Module 3, Lesson 220 min

Nodes, edges, and Command routing

A node is a function of state that returns a partial update. Edges wire the flow. START and END are the sentinels.

A basic graph with static edges

const graph = new StateGraph(State)
  .addNode("sense", senseNode)
  .addNode("modulate", modulateNode)
  .addNode("roll", rollNode)
  .addEdge(START, "sense")
  .addEdge("sense", "modulate")
  .addEdge("modulate", "roll")
  .compile();

Command lets a node decide where to go next and what to write, together, instead of a static edge.

Command: update and route in one return

const roll: GraphNode<typeof State, "continueNode" | "wildNode" | "personalNode" | "restNode"> =
  (state) => {
    const face = rollDice(state.weights, state.random);
    return new Command({ update: { face }, goto: `${face}Node` });
  };

In your codebase

The whole cold-mode path lives in Impulse (~/dev/lumiere/apps/impulse): src/strategy/dice.ts has DEFAULT_WEIGHTS { continue: 0.65, personal: 0.15, wild: 0.15, rest: 0.05 }, and rollDice(weights, random) is a cumulative weighted walk with injectable random for tests. modulateWeights(base, quotaLevel, temperatureLevel) shifts weights: quota warning is continue -0.10 / rest +0.10; temperature hot is continue -0.15, personal -0.05, wild -0.05, rest +0.25; warm is continue -0.05 / rest +0.05. Sensors: DiscordTemperatureSensor (exponential decay from last Rai message, half-life 20 min; hot >= 0.7, warm 0.3-0.7, cold < 0.3) and AnthropicQuotaSensor (healthy < 70%, warning 70-90%, critical > 90% blocks before the dice), both in src/sensors/. src/heartbeat/cold-mode.ts gates on temperature.level === 'cold' plus a 5-minute cooldown; rest is a recorded no-op, other faces route through faceToWhisperRequest in src/actuators/ark-whisper.ts.

Your graph: a sense node (read the two sensor levels), a modulate node (modulateWeights), a roll node (rollDice returning a Command that goes to the face node), and four terminal nodes: continue, wild, personal, rest. The injectable random is your parity hook.

Practice

Try it yourself

Recall

Why injectable random matters

The point is the parity test against src/strategy/dice.ts, not general testability.

What would break about testing your graph's roll node if it called Math.random() directly instead of taking an injected random function?

Quiz

Command vs addConditionalEdges for the roll node

Both Command and addConditionalEdges can route dynamically. Why is Command the better fit specifically for the roll node?

Port Impulse's cold-mode path into a StateGraph

Port the sense -> modulateWeights -> rollDice -> route path into an explicit, parity-tested StateGraph.

Create the build under ~/dev/groundschool/builds/m3-impulse-graph.
Build a sense node that reads the two sensor levels (temperature, quota).
Build a modulate node that calls modulateWeights exactly as src/strategy/dice.ts does.
Build a roll node that calls rollDice with an injectable random and returns a Command routing to the matching face node.
Add four terminal nodes: continue, wild, personal, rest.
Write a parity test: the same injected random seeds must produce the same faces as src/strategy/dice.ts.
Assert the modulated weight vectors match exactly for a quota-warning case and for hot/warm temperature cases.
Render the graph structure (mermaid or LangGraph Studio) and save it.

Tick every step to confirm you did it.

Check

Dice roll parity confirmed

Confirm the ported graph reproduces the original dice logic exactly.

You should see

Same injected random seeds produce the same faces as src/strategy/dice.ts, and quota-warning / hot / warm modulation matches the original weight vectors exactly.