A machine that arrives as a value can still be commanded, so a name may name its state (#58)

Set state and State branch derived their ports from the graph, so a machine
that came out of a variable or a list had no ports at all: nothing to set,
nowhere to branch. It could be passed around but not operated.

stateByName() resolves id first, then name; a name two states carry answers
with nothing, the same rule transitionTo already follows for two transitions
of one name — without something in the graph that decides between them, any
pick would be a guess.

Set state by name takes the machine and a text, and has a second exec output
not found, so a typo is not swallowed in silence. State branch gains a
derived else that fires whenever no state output matches — no state set, a
state of another machine, or a machine that arrives as a value and therefore
has no state outputs at all. A flow that enters State branch now always
leaves it somewhere.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/core/graph/nodes/flow/SetStateByName.ts

@@ -0,0 +1,29 @@
+import type { NodeDef } from '../../NodeRegistry';
+import { setState } from '../../sharedState';
+import { machinePort, stateByName } from '../../stateMachine';
+import { asString } from '../../values';
+import { exec, str } from '../shared';
+
+/**
+ * What `Set state` cannot do: a machine that arrives as a value. Ports are derived from the graph,
+ * so a machine coming from a variable or a list item has no state inputs at all – this node names
+ * the state instead of wiring it. Nothing is found is a way out of its own, not silence.
+ */
+export const SetStateByName: NodeDef = {
+  type: 'SetStateByName',
+  label: 'Set state by name',
+  category: 'action',
+  description:
+    'Puts the machine into the state of that id or name, then continues along "exec". A name no ' +
+    'state answers to – or two states share – continues along "not found" and moves nothing.',
+  inputs: [exec(), machinePort(), str('state')],
+  outputs: [exec(), exec('notFound', 'not found')],
+  params: [],
+  run: (ctx, inputs, _params, _def, _entry, lookup) => {
+    const machineId = asString(inputs.machine);
+    const state = stateByName(machineId ? lookup.machine(machineId) : null, asString(inputs.state));
+    if (!state) return { next: 'notFound' };
+    setState(ctx, machineId, state);
+    return { next: 'exec' };
+  },
+};

src/core/graph/nodes/flow/StateBranch.ts

@@ -4,20 +4,33 @@ import { machineOf, machinePort, statePorts } from '../../stateMachine';
 import { asString } from '../../values';
 import { exec } from '../shared';
 
-/** No state set yet, or a state of another machine: the flow ends here, along no output. */
+/** The way out for everything no state output covers. A state id is ten characters, so no state
+ *  can claim this key – the guard below is what makes that true rather than likely. */
+const ELSE = 'else';
+
+/**
+ * No state set yet, a state of another machine, or a machine that arrived as a value and therefore
+ * has no state outputs at all: the flow leaves along `else`. A branch nobody can see taken is the
+ * hardest kind to debug, so this node always continues somewhere.
+ */
 export const StateBranch: NodeDef = {
   type: 'StateBranch',
   label: 'State branch',
   category: 'flow',
   description:
-    'Continues along the output of the state the machine is in. A machine with no start state is ' +
-    'in no state until "Set state" has run, and nothing continues.',
+    'Continues along the output of the state the machine is in, and along "else" while it is in ' +
+    'none – or while the machine comes from a value, where the states are unknown to the graph.',
   inputs: [exec(), machinePort()],
+  // Derived rather than fixed, so it sits below the states instead of above them – the way out of a
+  // branch belongs under what it is an exception to, as it does on `Branch`.
   outputs: [],
   params: [],
-  derivePorts: (source) => ({ outputs: statePorts(machineOf(source)) }),
+  derivePorts: (source) => {
+    const states = statePorts(machineOf(source));
+    return { outputs: [...states, ...(states.some((p) => p.key === ELSE) ? [] : [exec(ELSE, ELSE)])] };
+  },
   run: (ctx, inputs, _params, def) => {
     const current = currentState(ctx, asString(inputs.machine));
-    return def.outputs.some((p) => p.key === current) ? { next: current } : {};
+    return { next: def.outputs.some((p) => p.key === current) ? current : ELSE };
   },
 };