Split & Merge — Nodes That Carry Policies

Fan-out and join already work, and are invisible: N plain out-edges IS a fan, in-degree > 1 IS a wait-all join. split and merge add no topology — they are the cards a POLICY hangs on, and they ship with their first two: run the arms one at a time, and release on the first arm home.

1 · What already ships, and why nobody can see it

Four rules, all live, all load-bearing for everything below.

The legibility problem is concrete, not aesthetic: every unlabelled out-edge leaves the same single port dot — one Handle for all of them (GovernedCanvas.tsx:193). A three-way fan and a one-step chain draw identically, and a join is readable only by counting arrowheads.

2 · Nodes, not edge annotations

The same semantics could be a field on the fanning node (fanout: {mode}) and a field on the joining node (join: {mode}) — zero new kinds, zero node-cap cost. Rejected on three grounds:

1. An unseen policy is ungoverned. PD003's thesis is that a governed workflow is legible on the canvas. "These arms run one at a time" buried in a config panel is a rule reviewers never read.public/designs/003-governed-workflows/
2. Ordering needs ports. Sequential order is per-arm, and an arm's home on a card is a port. The card-growth machinery already exists for exactly this.canvas/metrics/port-geometry.ts:64
3. The mode flip must not be a rewire. With the node present, parallel → sequential is one config change; with annotations, adding a policy later means editing the node upstream of the shape it governs.

The cost is honest: merge · wait_all becomes a second way to spell the implicit join. That is deliberate, not an oversight — implicit stays the default and stays legal, and the explicit node exists so that arriving at a non-default policy needs no rewire.

The compile-down, explicitly

Two of the four modes ARE the shipped behaviour wearing a card, so half this surface carries no decider risk at all.

3 · split

config: { mode: "parallel" | "sequential" }. The mode words are loop_over_items's own z.enum(["sequential", "parallel"]) (graph.ts:152) — not "serial". A second vocabulary for one concept is the drift worth refusing up front.

What sequential reuses — and what it does not

The claim that sequential rides loop_over_items' machinery is half true, and the half that is false matters:

What "one at a time" means: the region question

If arm A is a three-node chain, does arm B start when A's first node finishes, or when A is done? Only the second is what an author means, so an arm is a REGION, not a node.

flowchart LR
  S{{"split · sequential
order: a1, b1"}}
  S -->|1| a1[a1 draft]
  a1 --> a2[a2 send]
  S -->|2| b1[b1 draft]
  b1 --> b2[b2 send]
  a2 --> M(("merge"))
  b2 --> M
  subgraph RA["region 1 — must fully settle first"]
    a1
    a2
  end
  subgraph RB["region 2 — starts after region 1"]
    b1
    b2
  end
  

Arm k's region = the nodes reachable from arm k's head that arm k's head dominates — every path from the trigger to them passes through that head. A node reachable from two arms is by definition below both, so it belongs to neither region; it is the merge's business. This is a pure, publish-time structural property of an immutable graph, so the decider stays a pure replay function.

Order lives in config.order — a list of the split's immediate successor node ids. It is deliberately NOT edge labels: labels are the exactly-one-of-N arm mechanism, and NEP-0006 rule 4b refuses any label no kind claims. Ordinal labels would need "all arms taken, one at a time", which is the opposite of what a label means everywhere else.

No failure policy — and why that is the answer

Both halves of a stop/continue knob are already spoken for:

So v1 adds no failure config. Consistency with parallel holds vacuously: parallel does not cancel a dispatched sibling because siblings are in flight; sequential has none in flight.

4 · merge

config: { mode: "wait_all" | "wait_any", on_loss?: "prune" | "continue" } — the second field is wait_any-only and defaults to prune (§6).

wait_all restates the shipped rule: not ready while any inbound edge is unresolved; skip if none resolved taken; otherwise run (decider.ts:201-209).

wait_any: the first live arm to settle releases the merge. Two precisions the phrase hides:

• A failed arm cannot win. A failed source's plain out-edge resolves to skip (decider.ts:130), so failure never counts as arriving. If every arm skips, the merge skips — exactly like today.
• A merge fed only by arms of ONE exclusive source (a switch's arms, an approval's outcomes) has exactly one live arm ever. There is no race; see §6.

Replay determinism needs no new event

The winner is the live arm with the earliest settle index in history, ties broken by topo seq. That is already durable and already deterministic: history is append-only, so a later poll sees a strict superset with no reordering — once an arm is earliest, it is earliest on every replay forever. No RecordSideEffect, no new column.

Settle index for a node with no event of its own (a branch, a switch) = the max over its live inbound sources' settle indices. Total, pure, defined for every node.

One deliberate departure from NEP-0006 v1.6's "no merged-output shape": a wait_any merge's own output is { won: "<armNodeId>" }. It is the first node whose output describes its INBOUND edges — needed because "which arm won" is the one fact a reader, a downstream reference, and the run canvas all want, and deriving it in three places is how mirrors drift.

5 · The losing arms — the analysis behind the default

Decided (§6): both semantics ship, selectable per merge. This section is left as written, because it is now the argument for which one is the DEFAULT — the reasoning has to stay visible for the default to be reviewable.

Framed as (a) cancel via the stop cascade, (b) run to completion and discard the results. Checking (a) against the code changes the question: the stop cascade (run-stop.ts) stops descendant RUNS. A losing arm is not a run — it is activities inside this one, and nothing in this system cancels a claimed activity (builder-surface.ts:187-189). So (a) as written is only partly buildable, and the real third option is the one to pick.

1. Stop scheduling. Every unstarted node in a losing region resolves to skip. Pure decider, zero new spend — this is the whole budget win.decider.ts:206-209
2. Stop the losers' child runs. A losing arm's live sub_workflow/loop_over_items children ARE runs, so the shipped cascade reaches them — invoked from an activity, never the pure decider.run-stop.ts:70-107
3. Accept the in-flight tail. An already-claimed activity finishes uncancellably. Its result records and is never read — precisely today's fatal-sibling rule.NEP-0006 §Fan-out

flowchart LR
  S{{"split"}} -->|1| F["fast arm"]
  S -->|2| L["slow arm
claimed — finishes, unread"]
  F -->|"first home · wins"| M(("merge
wait_any"))
  L -.-> L2["l2 send email
never scheduled"]
  L2 -.->|"pruned · skip"| M
  M --> D["downstream"]
  

Recommendation, now the default: prune. The reason is governance, not cost.

Option (b) discards results, but a losing arm keeps acting — a capability node sends the email, files the ticket, moves the money, and its output is dropped afterwards. "Results discarded" and "effects discarded" are not the same sentence, and a governed-workflow product cannot ship the first while implying the second. The budget argument is real too and points the same way — orphaned losers burning descendant runs contradicts the 200-run descendant cap (run-start.ts:33) — but it is the second reason, not the first.

The deadlock-freedom invariant, restated for pruning

This is the one place pruning could break the system, so it is the load-bearing paragraph.

• A pruned node resolves to skip, not notReady. Left notReady, allSettled never holds and the run never completes (decider.ts:293-296).
• Skip propagates through a losing region exactly as an untaken branch arm's skip does today. The by-construction argument survives untouched: every node still resolves to skip or done in finitely many topological steps, so nothing waits on an arm that will never settle.
• Re-convergence is safe: a node fed by a pruned arm (skip) AND the merge (taken) still runs — one taken inbound edge is sufficient (decider.ts:206). A node fed only by pruned arms skips, and so does its subtree.

6 · Owner decision — both semantics ship, one setting

Decided 2026-08-09. "For the losing arms, make both options available via a setting on the merge box." So §5's analysis no longer selects the only behaviour — it selects the DEFAULT.

Vocabulary: snake_case key with short lowercase values, matching collect: all|last|none and mode: sequential|parallel (graph.ts:152). on_loss names the event — an arm lost the race — rather than the mechanism, so a future third policy has somewhere to live.

The default is a design position, not a coin toss. A default that keeps spending and keeps ACTING is the wrong default for a governed product: the safe behaviour must be the one an author gets by not thinking about it, and the dangerous one must be chosen on purpose. That is the whole argument of §5, relocated to where defaults are decided.

continue — the mode with teeth

Losing arms run to completion. Their outputs are RECORDED in history and under their own node ids exactly as any step's are (collectNodeOutputs) — the merge simply never reads them. What must not be softened anywhere in the product: their side effects still happen. A losing capability node still sends the email, files the ticket, moves the money.

Note what does NOT change: prune's three layers from §5 still hold exactly as written — stop scheduling, stop the losers' child runs, accept the uncancellable in-flight tail. continue keeps all three off, which is why it needs no new decider machinery beyond not pruning; its cost is entirely in the canvas and in the refusals that keep it honest.

The setting's copy — the whole reason it is dangerous mislabelled

A non-engineer picking this in the node config panel must be able to see the effects-versus-results distinction without being told it separately.

7 · Publish-time refusals

House style: every refusal names its remediation (validate.ts:311, 545).

That last one is genuinely new territory: the existing ancestor rule permits it, because a losing arm IS a graph ancestor of anything below the merge. Only the wait_any semantics make it unsound, and an unresolved reference substitutes the empty string rather than failing — exactly the silent-blank class this document refuses everywhere else.

Labelled arms into a merge are otherwise legal and unchanged: a switch arm or an approval's denied arm entering a merge already works, because the untaken arms skip and a wait-all waits only on live ones.

8 · Canvas

The run overlay is the real gap, and it is bigger than a colour. WorkflowNodeStatus is done | running | failed | stopped | idle (types.ts:16) — there is no skipped state at all today; a never-reached node is dim idle. Worse, a mid-flight node is only rewritten to stopped when the whole RUN goes terminal (run-status.ts:454-459). A wait_any run continues after the win, so a pruned loser would spin forever on a live canvas.

Because both semantics now ship, the overlay needs two new marks, not one — and continue's is the one that prevents a NEW lie rather than fixing an old one:

The merge card itself reads won · <armId> in both modes.

And the structural risk to name: there is no server-side per-node state — no workflow_steps table. The UI re-derives every node's state client-side from the raw engine event log, deliberately mirroring the decider (run-status.ts:106). A new readiness rule shipped without its mirror does not throw; the canvas just silently lies. Every phase below therefore lands decider and mirror together.

Builder-agent prompt, one sentence: "split (mode parallel|sequential) and merge (mode wait_all|wait_any) are OPTIONAL policy nodes over the fan-out and join you already get from edge count — add one only to run arms one at a time, or to release a join on the first arm home; a wait_any merge outputs {{ node.<id>.won }} and, by default, prunes the arms that lost — set on_loss to "continue" only when a losing arm's work should finish anyway, remembering its side effects still happen."

9 · Compat and the spec bump

• Graph doc: two new kind values with configs. No edge-schema change — order lives in config, so rule 4b's closed label world stays closed.
• Migration: none. A published v1.8 graph contains no split or merge, so it replays identically — the same argument v1.6 made for v1–v1.5.
• NEP-0006 → v1.9: node-kinds rows for both, including on_loss and its wait_any-only rule; a "split and merge policies" subsection under Fan-out and join; the new validation rules; the pruned-arm skip rule folded into the deadlock-freedom paragraph as an extension, not an exception; and the statement that a continue loser's recorded output is never an input to its merge.
• Documentation debt to clear in the same bump: v1.8's node-kinds table is missing transform, http_request, wait, and loop_over_items — four SHIPPED kinds (zero occurrences of the first two anywhere in the spec). Adding two more kinds on top of that drift is how a spec stops being the reference.

10 · Out of scope, stated

• Weighted / probabilistic routing — a switch-family follow-up, not a split policy.
• N-of-M quorum joins — a future merge mode. wait_any is quorum at N = 1, so the config keeps room: mode now, a quorum: { n } later, no rename.
• Trigger-catalog strategy — its own PD.
• Cancelling an in-flight activity — needs an engine primitive that does not exist; out of scope by construction, which is exactly what §5's third step concedes.
• Merged-output shapes beyond won. Arms keep publishing under their own node ids; a downstream node still reads each independently.

11 · Phases

1. The no-op pair — split · parallel + merge · wait_all (~2 sessions). Kinds, configs, refusals, tokens, icons, palette, per-arm split ports and card growth, spec bump including the four undocumented kinds. Zero decider change — the whole surface lands before any execution risk does.
2. split · sequential (~2 sessions). The readiness rule, the dominator region computation, the interleave refusal, ordinal ports, and the UI mirror.
3. merge · wait_any + on_loss, both values (~4 sessions, up from 3 — §6 grew this phase). Earliest-settle-index winner, the won output, the prune path (prune-to-skip plus the stop activity for losing child runs), the continue path (leave the arms alone, and prove a late loser completion cannot alter won), and three refusals: the degenerate race, on_loss on wait_all, and the arm-reference rule.
4. Run overlay — both loser states (~2 sessions, up from 1–2). The pruned state, the done · unread mark, the winner mark on the merge card, the config-panel copy from §6, and the "N of M" tally correction so neither loser state reads as pending.

Total ~10–11 sessions, up from ~8–9. The growth is real and worth naming: shipping both semantics roughly doubles phase 3's decider surface and turns phase 4 from one canvas state into two plus the copy that makes the setting safe to choose.

12 · Acceptance

• Eight publish refusals, each with its own test and its remediation sentence asserted verbatim: split < 2 arms; merge < 2 inbound; label or error edge on either; order mismatch; interleaved sequential regions; degenerate wait_any; on_loss on a wait_all merge; a reference to a wait_any merge's arm from below it.
• The default is prune — asserted as BEHAVIOUR, not as a string. A graph omitting on_loss must produce the pruning command sequence; a mutation flipping the default to continue must fail this test. Asserting only that the zod default equals "prune" would survive the mutation that matters.
• Mutation-tested decider rules — each must FAIL when the rule is inverted: region-serial mutated to node-serial; the winner's tie-break; and pruned-resolves-to-skip mutated to notReady (which must surface as a run that never completes, not as a green suite).
• Compile-down equivalence: a graph with split · parallel and merge · wait_all emits the same command batches, in the same order, as the same graph with the nodes deleted and the edges wired directly.
• Live gate-walk — sequential: a 3-arm sequential split of notify arms, where arm 2 has no ActivityScheduled before arm 1's ActivityCompleted, proving ordering rather than asserting it.
• Live gate-walk — wait_any · prune: a fast and a slow arm, proving first-wins, the merge's won naming the fast arm, the slow arm's child run STOPPED, its unstarted nodes resolving to skip (no ActivityScheduled for them), and its card rendering pruned rather than spinning while the run continues.
• Live gate-walk — wait_any · continue: the same graph with on_loss: "continue", where the losing arm's step provably still executes its EFFECT — a notify whose message is present in the channel after the merge already released — while the merge still emits the fast arm as won and the loser's card reads done · unread. Proving the effect happened is the point; asserting the node reached done would not.
• Mirror parity: a test pinning the UI's derived node states against the decider's own outcomes for a split/merge graph — the drift class run-status.ts invites.