automategraph 1.5.1 → 1.5.3

package/CHANGELOG.md

@@ -3,12 +3,25 @@
 All notable changes to the AutomateGraph Execution Engine.
 Format follows [Keep a Changelog](https://keepachangelog.com/); the project uses semver.
 
-## [1.5.1] — First registry publish
+## [1.5.3] — The complete project on npm
 
-No code changes. The 1.5.0 upload was accepted by the registry but held by the account's
-publish policy (granular tokens with 2FA bypass are being restricted for direct publishing,
-which routes to staged approval), so the version never became installable. 1.5.1 carries the
-identical tarball through the same policy.
+No code changes. The tarball now ships the WHOLE project instead of the library subset: the
+282-test suite with its fixtures, the examples, the report tooling, the docs and the build
+configuration, alongside the engine sources and the compiled output. `files` is gone in favour
+of a short `.npmignore` deny-list, so anything added to the repository travels to npm by
+default; `npm test` and every example run from an installed copy.
+
+Lineage of this release: 1.5.0 was consumed by the registry without ever becoming installable
+(held by the account's publish policy), 1.5.1 went live with the library-only tarball, 1.5.2
+was staged but could not be approved and never shipped. 1.5.3 is the complete project.
+
+## [1.5.2] — First registry publish
+
+No code changes. The 1.5.0 and 1.5.1 uploads were accepted by the registry but held by the
+account's publish policy — bypass-2FA granular tokens are being restricted for direct
+publishing (see https://gh.io/npm-gat-bypass2fa-deprecation), and a directly submitted version
+can no longer be staged either, so those two numbers are consumed. 1.5.2 carries the identical
+tarball through the supported path: `npm stage publish` + approval.
 
 ## [1.5.0] — Script loading
 

package/UPGRADE-PROPOSAL.md

@@ -0,0 +1,141 @@
+# AutomateGraph — Upgrade Proposal
+
+**From "a well-tested single-file engine" to "a durable, observable workflow engine you could actually run in production — with proof."**
+
+Current state: 140/140 tests passing, 18 documented semantics/findings, a self-contained web
+dashboard, zero dependencies. Everything below builds on that baseline without throwing it away.
+
+---
+
+## 0. North star
+
+Three properties separate a tested engine from a production-grade one:
+
+| Property | Today | Target |
+|---|---|---|
+| **Durability** — survives process death, resumes mid-graph, supports long waits | Checkpoints are *written* but never *read*; `StoragePlugin.load()` is dead code in the engine | `resume(executionId)` reconstructs the scheduler frontier and continues; durable timers & external signals |
+| **Predictability** — policies are explicit, never "deferred" | 18 findings: silent dropped work, asymmetric FAIL_FAST, inert FALLBACK, unbounded concurrency, ambiguous cancellation | Every policy is a documented, configurable, tested contract — findings become specs, not surprises |
+| **Provability** — confidence scales beyond hand-written cases | 140 curated tests | Property-based fuzzing over random graphs + mutation testing (proves the suite can *catch* bugs) + deterministic clock |
+
+The single highest-leverage move: **checkpointing already exists but is write-only.** Turning it
+into real resume/replay upgrades the product category, not just the code.
+
+---
+
+## Track A — Engine correctness (turn the 18 findings into specs)
+
+| # | Upgrade | Why (evidence from the suite) | Scope |
+|---|---|---|---|
+| A1 | **Cancellation symmetry** — in `executeActivation`'s catch, re-check `cancellationRequested` before recording: settle `CANCELLED`, mark the `GRAPH_CANCELLED` record as handled | A-10 proved a callback that *rejects* on abort is recorded `FAILED` + unhandled error while one that *resolves* is `CANCELLED` | S |
+| A2 | **Use `cancellationTimeoutMs` for the drain** — it is documented as "Cancellation timeout" but is only applied to plugin shutdown (line 644). After the deadline, remaining in-flight work is recorded `ABANDONED` and the report says `drainTimedOut: true` | The `cancel()` contract is explicitly "deferred" today; work that ignores the signal can hang `run()` forever | M |
+| A3 | **Explicit completion policy** — `completionPolicy: "FIRST_TERMINAL" \| "ALL_TERMINALS" \| "DRAIN"`. FIRST_TERMINAL must emit `activation.dropped` for cleared work instead of silently discarding ONTHROW recovery paths whose errors are already `handled: true` | C-15/C-19: recovery nodes never run yet the run reports COMPLETED | M |
+| A4 | **Persistent FAIL_FAST** — node-level `FAIL_FAST` currently empties the queue once (no-op under unbounded concurrency); make any FAIL_FAST set a sticky stop. Node-level `CONTINUE` can't shield branches from a graph-level stop — document or drop the override | C-16: three-way asymmetry | S |
+| A5 | **Real FALLBACK or delete it** — `errorPolicy: "FALLBACK"` is accepted and treated as CONTINUE. Either add `fallback: { node, when }` routing or remove the enum value so the API stops lying | C-12 | S |
+| A6 | **Fix `NodeResult.error`** — the field exists but is never assigned; attach the `GraphError` record (and the `TimeoutError` for `TIMED_OUT`) to the result | Dead field; consumers can't correlate result→error without array scanning | S |
+| A7 | **Join semantics primitive** — `join: { mode: "ALL" \| "ANY", of: [...] }` on a node so convergence is deterministic and runs once; keep current per-edge behavior as `join: "NONE"`. Fix last-writer-wins `outputs[nodeId]` with per-activation results (`outputsByActivation`) | C-05: diamond fan-in executes the join 2× by design-that-isn't-documented | M |
+| A8 | **Bounded concurrency + backpressure** — replace `maxConcurrency = Number.MAX_SAFE_INTEGER // Provisional` with `maxConcurrency`, `queuePolicy: "FIFO" \| "PRIORITY"`, per-node `concurrency`, and a `maxActivations` step budget (kills runaway cycles with a typed `STEP_BUDGET_EXCEEDED` error instead of hanging) | C-07 proved unbounded; cycles are legal and unbounded (C-06) | M |
+| A9 | **Static graph lint** — `lintGraph()` returns warnings: unreachable nodes, terminals that no edge can reach, duplicate entries, non-terminating cycles, nodes never referenced by `next`/`onThrow` | C-15 scenario 1 only fails at *runtime* after burning work | S |
+| A10 | **Kill dead weight** — `resolveRun` (declared, never used), `NodeStatus: "PENDING"` (never assigned), `activeControllers` leaking after settle (assert empty at drain) | Hygiene; every dead symbol weakens the type contract | S |
+
+**Payoff:** the finding count drops from 18 "surprises" to ~6 documented-by-design behaviors, each
+with regression tests named after its finding (A1–A10 → ~25 new assertions).
+
+---
+
+## Track B — Durability & workflow capabilities (the big unlock)
+
+| # | Upgrade | What it enables | Scope |
+|---|---|---|---|
+| B1 | **Snapshot v2 + real resume** — snapshot gains the scheduler frontier (`pending: Activation[]`), `phase`, `graphHash`, `input`, `activationSeq`, `idempotencyKeys`; `GraphExecutionEngine.resume(id)` loads, validates graph-version compatibility, re-marks in-flight work per policy (`RETRY` \| `FAIL` \| `ABANDON`), continues | Crash-safe executions: kill the process mid-graph, restart, it finishes. `StoragePlugin.load()` finally means something | L |
+| B2 | **Durable timers & external signals** — a node returns `suspend({ until })` or `awaitSignal("approval")`; the activation is parked in the snapshot; `engine.signal(executionId, name, payload)` wakes it. Timers survive restarts | Human-in-the-loop approvals, webhooks, SLA deadlines — the features that make people choose a workflow engine | L |
+| B3 | **Deterministic replay** — activation ids derived from `hash(executionId, path, seq)`; identical inputs + seeded clock ⇒ identical event stream, so a run can be replayed step-by-step for debugging | Time-travel debugging; also makes property tests reproducible | M |
+| B4 | **Saga / compensation** — `compensate: nodeId` per node; on failure the engine walks completed activations in reverse and runs their compensations, recording a compensation journal | Multi-step transactions (charge → reserve → ship) with rollback, the #1 enterprise workflow pattern | M |
+| B5 | **Map / fan-out primitive** — `map: { over: (ctx) => iterable, concurrency }` with per-item child executions, results aggregated at the join | Replaces 250 hand-wired nodes with one declarative node | M |
+| B6 | **Idempotency & exactly-once** — `idempotencyKey` per activation handed to node code, checkpoint-before-effect ordering option (outbox), dedupe of replayed activations | Prevents the classic "retry charged the customer twice" bug | M |
+| B7 | **Middleware / interceptors** — `engine.use(async (activation, next) => …)` around node execution: tracing, metrics, caching, auth context, dry-run mode | Extensibility without forking the engine | S |
+| B8 | **Retry upgrades** — exponential backoff + jitter + maxDelay, `retryOn: (error) => boolean`, per-attempt timeout, budget-aware retries | Production retry semantics instead of fixed `delayMs` | S |
+
+---
+
+## Track C — Observability & developer experience
+
+| # | Upgrade | What it looks like | Scope |
+|---|---|---|---|
+| C1 | **Live execution stream** — the existing `tools/server.mjs` gains `GET /events/:executionId` (SSE) fed by an engine event hook; the dashboard gains a *live* mode showing nodes lighting up as they run | Watch a graph execute in the browser instead of reading JSON after the fact | M |
+| C2 | **Trace viewer / waterfall** — per-activation timeline (start, attempts, retries, timeout marks, path tree), driven by the recorded event stream; scrub through checkpoints | Debugging a 250-node fan-out becomes visual | M |
+| C3 | **Graph visualization** — `toMermaid(graph)` / `toDot(graph)` + an SVG renderer in the report; node states colored by status (pending/running/failed/skipped/abandoned) | Onboarding: see the graph, not just the list | S |
+| C4 | **Structured logs + trace context** — replace free-form `onLog` calls with `{ level, event, executionId, nodeId, activationId, path, attempt, durationMs }`; OpenTelemetry-compatible span events (zero-dep core, adapter optional) | Plugs into existing observability stacks | M |
+| C5 | **CLI** — `automategraph validate graph.ts`, `run graph.ts --input in.json --watch`, `resume <executionId>`, `export --mermaid`, `bench` | One command from file to running graph | M |
+| C6 | **Interactive playground** — define nodes in a browser sandbox (engine already has zero deps → runs in a Web Worker), wire them visually, run and inspect | The demo that sells the library | L |
+
+---
+
+## Track D — Testing to the next level (proof, not just coverage)
+
+| # | Upgrade | Why it's the real step up | Scope |
+|---|---|---|---|
+| D1 | **Property-based fuzzing** — a random graph generator (DAG + cycles, random failures/timeouts/retries/policies/cancellation) plus invariants asserted on every run: `COMPLETED ⇒ logicallyCompleted`; no output for non-SUCCEEDED results; `finishedAt ≥ startedAt`; unique activation ids; no unhandled rejections; no work scheduled after cancel; `activeControllers`/`activeTasks` empty at settle. Thousands of cases per run, counterexample-minimizing | Curated tests check what *you thought of*; invariants check everything. A-10-class asymmetries get found automatically | L |
+| D2 | **Mutation testing** — a zero-dep mutation runner that patches the engine (`>=`→`>`, drop `handled = true`, swap settle precedence, remove `pending.length = 0`) and re-runs the suite; **kill rate ≥ 95%** gated in CI, score shown in the dashboard | Answers the only question that matters: *can the suite catch bugs?* 140 green tests prove nothing without this | M |
+| D3 | **Deterministic clock + seeded scheduler** — inject `now()`, `setTimeout`, `delay`, and id generation; timeout tests stop using wall-clock sleeps | Removes CI flakiness; makes D1 replayable | M |
+| D4 | **Burn-in & leak checks** — `--repeat 50` stress mode; heap-delta assertions; `activeTasks.size === 0` after every run; 10k-node soak | Catches the O(n²) snapshot growth (every checkpoint copies all results/errors) before users do | S |
+| D5 | **Chaos storage/listener faults** — extend `SpyStorage` into a fault matrix: latency, partial write, duplicate save, out-of-order resolve, close-timeout; assert the sticky-checkpoint-failure invariants still hold | Our C-09/C-14 already probe this; make it systematic | S |
+| D6 | **Coverage gate + badge** in the dashboard (c8, statements/branches thresholds); **CI matrix** (Node 18/20/22, Linux/macOS), published report to GitHub Pages, `npm pack` smoke test | Turns the suite into infrastructure | M |
+| D7 | **Differential testing** — a trivially-correct sequential reference interpreter for small graphs; random graphs run on both; any divergence is a scheduler bug | Finds scheduler semantics bugs no hand-written test anticipates | M |
+
+---
+
+## Track E — Productization
+
+| # | Upgrade | Notes | Scope |
+|---|---|---|---|
+| E1 | **Package** — `@automategraph/core` with dual ESM/CJS builds, `.d.ts`, browser + worker builds (already dependency-free), semver major for the breaking policy changes in Track A | 30 minutes of tooling, changes who can use it | S |
+| E2 | **Storage adapters** — SQLite (single file, `BEGIN IMMEDIATE` for atomicity), Postgres (JSONB + `FOR UPDATE`), Redis (Lua CAS); conformance test suite that every adapter must pass | `InMemoryStorage` already defines the contract; adapters are how durability becomes real | M–L |
+| E3 | **Server mode** — `POST /executions`, `GET /executions/:id`, `GET /events/:id` (SSE), `POST /executions/:id/signals`, `POST /executions/:id/cancel`; execution registry, retention, auth hook | The engine becomes a service; the dashboard becomes an ops console | L |
+| E4 | **Docs** — typedoc API reference, 5 runnable guides (ETL, order pipeline, approval flow, saga, map/reduce), migration guide for v2 semantics, published benchmark numbers (nodes/sec, snapshot overhead per checkpoint) | Adoption is proportional to documentation | M |
+
+---
+
+## Sequencing — five waves
+
+Each wave ends with a numeric acceptance criterion, so progress is provable, not vibes.
+
+| Wave | Content | Acceptance criterion |
+|---|---|---|
+| **1. Correctness** (1–2 days) | A1–A10 + regression tests named per finding; README "findings" section rewritten as "guaranteed semantics" | Findings 18 → ≤6; suite 140 → ~170; all green ×5 runs |
+| **2. Durability** (3–5 days) | B1 snapshot v2 + `resume()`, B2 suspends/signals, B8 retry upgrades; SQLite adapter; kill-and-resume integration test that SIGKILLs a child process mid-graph | Kill a run at 50%, restart, execution completes with identical outputs; new tests cover resume matrix |
+| **3. Trust** (2–3 days) | D1 property fuzzing, D2 mutation ≥95%, D3 deterministic clock, D4 burn-in; dashboard cards for mutation score + fuzz cases + coverage | 10k fuzz cases clean; mutation score ≥95% displayed in the report |
+| **4. Capabilities** (3–5 days) | B3 replay, B4 saga, B5 map/fan-out, B7 middleware, A7 joins in anger; C1 live SSE stream + C2 waterfall in the dashboard | A saga demo (charge→reserve→ship→rollback) and a live-updating trace view |
+| **5. Product** (3–5 days) | E1 package, E3 server, E2 Postgres adapter, E4 docs, C5 CLI | `npx automategraph run examples/approval-flow.ts` works; docs site live |
+
+Deliberate omissions (still worth doing *later*): distributed workers with leases (needs E2/E3
+first), conditional/edge-level policies as first-class objects, subgraph composition, JSON/YAML
+declarative graph specs, secrets plugin, multi-tenant isolation.
+
+---
+
+## My recommendation — start here
+
+If you only do three things, do these:
+
+1. **Wave 1 (A1–A10)** — cheap, and it converts the audit into guarantees. The cancellation
+   asymmetry (A1) and the silently-dropped recovery work (A3) are the two behaviors most likely to
+   bite a real user, and both are ~1 hour fixes plus tests.
+2. **B1 — snapshot v2 + `resume()`.** This is the category change: "automation library" → "durable
+   workflow engine". Everything else in Track B is optional; this one is not.
+3. **D1 + D2 — property fuzzing and mutation testing.** These change how you *feel* about the code:
+   "140 tests pass" becomes "the suite kills 97% of injected bugs and 10,000 random graphs violate
+   no invariants". That is the difference between a test suite and proof.
+
+Nice-to-have that pays for itself immediately: **C3** (Mermaid/SVG export — one afternoon, makes
+every future conversation about the engine visual) and **C1/C2** (live trace view — makes the
+dashboard a selling point instead of a report).
+
+### Decisions I need from you before Wave 1
+
+1. **Breaking-change budget** — Track A changes observable semantics (completion policy default,
+   FAIL_FAST stickiness, cancellation status). Do we ship v2.0 with clean semantics, or v1.1 with
+   opt-in flags defaulting to today's behavior?
+2. **Runtime target** — Node-only (child-process workers for hard isolation), or keep it
+   isomorphic for the browser playground?
+3. **Where durability lands** — in-repo SQLite via `node:sqlite` (zero deps, ships with Node 22+)
+   or a pluggable adapter interface you implement later?

package/docs/diagrams/c19-resilience-scenario.md

@@ -0,0 +1,61 @@
+```mermaid
+%% C-19 · Resilience scenario — timeout routed to a fallback (AutomateGraph v1.1)
+%% Solid = next (normal transition) · dashed red = onThrow (error transition, NOT a retry)
+%% Dotted violet = fixture-only synchronisation gate
+flowchart TD
+    start["<b>start</b><br/><i>sync · run: () =&gt; 1</i><br/>next: [slow-vendor, fast-vendor]"]
+    slow["<b>slow-vendor</b><br/><i>async · await sleep(80)</i><br/>timeoutMs: 25 · onThrow ↓"]
+    fast["<b>fast-vendor</b><br/><i>async · await race(fallbackDone, 2000ms)</i><br/>next: [decide]"]
+    fb["<b>vendor-fallback</b><br/><i>sync · releaseFast()</i><br/>next: [decide]"]
+    decide["<b>decide</b><br/><i>async · emit(pricing.decided)</i><br/>reads outputs[vendor-fallback]<br/>next: [finish]"]
+    finish(["<b>finish ★</b><br/><i>const · 'DONE'</i><br/>terminal node"])
+
+    start -->|next| slow
+    start -->|next · fan-out| fast
+    slow -.->|onThrow · NODE_TIMEOUT · handled| fb
+    fb -->|next| decide
+    fast -->|next| decide
+    decide -->|next| finish
+    fb -.->|test gate: releaseFast resolves fallbackDone| fast
+
+    classDef done fill:#0f3627,stroke:#31c48d,color:#e7ecf7
+    classDef failed fill:#3a1620,stroke:#f4645f,color:#e7ecf7
+    classDef terminalNode fill:#1b2a55,stroke:#6ea8fe,color:#e7ecf7
+    classDef hot fill:#3a2b0d,stroke:#f0b429,color:#e7ecf7
+
+    class start,fb,fast done
+    class slow failed
+    class decide hot
+    class finish terminalNode
+```
+
+### Observed execution (verified, not illustrative)
+
+| t | what happens |
+|---|---|
+| 8 ms | `start` succeeds → fan-out seeds **both** vendors |
+| 9 ms | `slow-vendor` begins (25 ms budget, 80 ms of work); `fast-vendor` begins awaiting the gate |
+| 25 ms | `timeoutMs: 25` deadline passes |
+| 36 ms | `slow-vendor` → **TIMED_OUT**, `NODE_TIMEOUT` recorded (handled) → `onThrow` → `vendor-fallback` |
+| 37 ms | `vendor-fallback` runs `releaseFast()` → `"cached-price"`; `fast-vendor` released → `"fresh-price"` |
+| 38 ms | `decide` starts **twice** (two activations, both read `outputs["vendor-fallback"] = "cached-price"`) |
+| 39 ms | `pricing.decided` emitted ×2 · `decide` ×2 SUCCEEDED · `finish` ×2 start + SUCCEEDED |
+| 40 ms | `graph.logicallyCompleted` (`terminalNodeId: finish`) → **COMPLETED** |
+| 89 ms | `slow-vendor`'s abandoned work resolves — **discarded**, never appears in `outputs` |
+
+### What the diagram shows that the code doesn't
+
+1. **`onThrow` is an error *transition*, not a retry** — `slow-vendor` has `maxAttempts = 1`, so there is
+   exactly one attempt; the dashed edge is taken instead of a second run.
+2. **The timeout is cooperative** — `run()` settles at 40 ms while the 80 ms callback keeps running and
+   finishes at 89 ms. The `⚠` in the legend; its output is never adopted.
+3. **Fan-in has no join** — the two `next` edges into `decide` produce two activations, so `decide`
+   *and* `finish` each run twice (last-write-wins on `outputs[nodeId]`).
+4. **The gate is test-only** — `releaseFast()` / `fallbackDone` don't belong to the engine; they exist so
+   the *fast* branch waits for the *fallback* branch, keeping the C-19 assertions deterministic. Without
+   it, `fast-vendor` would have waited the full 2000 ms race timeout.
+5. **The dead edge** — `slow-vendor`'s success path is unreachable because 25 ms < 80 ms: the graph's
+   "happy path" for that node can never fire in this fixture.
+6. **Since v1.2 this graph is a lint error** — `lintGraph()` reports
+   `SUCCESS_DEAD_END` for `slow-vendor` (non-terminal node, no `next` target, only `onThrow`).
+   Adding `next: ["decide"]` clears it; see `tests/lint.test.ts`.

package/docs/diagrams/c19-resilience-scenario.mmd

@@ -0,0 +1,28 @@
+%% C-19 · Resilience scenario — timeout routed to a fallback (AutomateGraph v1.1)
+%% Solid = next (normal transition) · dashed red = onThrow (error transition, NOT a retry)
+%% Dotted violet = fixture-only synchronisation gate
+flowchart TD
+    start["<b>start</b><br/><i>sync · run: () =&gt; 1</i><br/>next: [slow-vendor, fast-vendor]"]
+    slow["<b>slow-vendor</b><br/><i>async · await sleep(80)</i><br/>timeoutMs: 25 · onThrow ↓"]
+    fast["<b>fast-vendor</b><br/><i>async · await race(fallbackDone, 2000ms)</i><br/>next: [decide]"]
+    fb["<b>vendor-fallback</b><br/><i>sync · releaseFast()</i><br/>next: [decide]"]
+    decide["<b>decide</b><br/><i>async · emit(pricing.decided)</i><br/>reads outputs[vendor-fallback]<br/>next: [finish]"]
+    finish(["<b>finish ★</b><br/><i>const · 'DONE'</i><br/>terminal node"])
+
+    start -->|next| slow
+    start -->|next · fan-out| fast
+    slow -.->|onThrow · NODE_TIMEOUT · handled| fb
+    fb -->|next| decide
+    fast -->|next| decide
+    decide -->|next| finish
+    fb -.->|test gate: releaseFast resolves fallbackDone| fast
+
+    classDef done fill:#0f3627,stroke:#31c48d,color:#e7ecf7
+    classDef failed fill:#3a1620,stroke:#f4645f,color:#e7ecf7
+    classDef terminalNode fill:#1b2a55,stroke:#6ea8fe,color:#e7ecf7
+    classDef hot fill:#3a2b0d,stroke:#f0b429,color:#e7ecf7
+
+    class start,fb,fast done
+    class slow failed
+    class decide hot
+    class finish terminalNode

package/docs/diagrams/c19-resilience-scenario.svg

@@ -0,0 +1,181 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1120 900" width="1120" height="900"
+     font-family="ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
+  <defs>
+    <radialGradient id="bg" cx="15%" cy="-10%" r="120%">
+      <stop offset="0%" stop-color="#16224a"/>
+      <stop offset="55%" stop-color="#0b1020"/>
+      <stop offset="100%" stop-color="#0b1020"/>
+    </radialGradient>
+    <marker id="aNext" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#31c48d"/>
+    </marker>
+    <marker id="aErr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#f4645f"/>
+    </marker>
+    <marker id="aGate" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#c084fc"/>
+    </marker>
+    <marker id="aDead" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#4a5670"/>
+    </marker>
+  </defs>
+
+  <rect width="1120" height="900" fill="url(#bg)"/>
+
+  <!-- ============ header ============ -->
+  <text x="40" y="52" font-size="26" font-weight="700" fill="#e7ecf7" letter-spacing="-0.4">C-19 · Resilience scenario — node timeout routed to a fallback</text>
+  <text x="40" y="78" font-size="13" fill="#94a3c4">GraphExecutionEngine v1.1 · observed run: COMPLETED, logicallyCompleted = true, 40 ms, 1 handled NODE_TIMEOUT · no retries, no joins</text>
+
+  <!-- ============ edges (drawn first, under the boxes) ============ -->
+
+  <!-- start -> slow-vendor -->
+  <path d="M 490 196 C 490 240, 260 216, 260 254" fill="none" stroke="#31c48d" stroke-width="2" marker-end="url(#aNext)"/>
+  <text x="306" y="238" font-size="11.5" fill="#31c48d">next</text>
+
+  <!-- start -> fast-vendor -->
+  <path d="M 630 196 C 630 240, 860 216, 860 254" fill="none" stroke="#31c48d" stroke-width="2" marker-end="url(#aNext)"/>
+  <text x="776" y="238" font-size="11.5" fill="#31c48d">next</text>
+
+  <!-- slow-vendor -> vendor-fallback : ONTHROW (error transition) -->
+  <path d="M 260 346 L 260 416" fill="none" stroke="#f4645f" stroke-width="2" stroke-dasharray="7 5" marker-end="url(#aErr)"/>
+  <text x="274" y="374" font-size="12" font-weight="700" fill="#f4645f">onThrow</text>
+  <text x="274" y="391" font-size="11" fill="#f4645f">NODE_TIMEOUT · recorded handled</text>
+
+  <!-- slow-vendor success path : never taken -->
+  <path d="M 380 303 L 452 303" fill="none" stroke="#4a5670" stroke-width="1.6" stroke-dasharray="4 4" marker-end="url(#aDead)"/>
+  <text x="462" y="307" font-size="11" fill="#8b96ae">success path never reached (25 ms &lt; 80 ms work)</text>
+
+  <!-- test gate : vendor-fallback resolves the promise fast-vendor awaits -->
+  <path d="M 384 430 C 480 398, 620 368, 744 338" fill="none" stroke="#c084fc" stroke-width="1.8" stroke-dasharray="2 5" marker-end="url(#aGate)"/>
+  <text x="500" y="428" font-size="11" fill="#c084fc">test gate: releaseFast() resolves fallbackDone</text>
+
+  <!-- vendor-fallback -> decide -->
+  <path d="M 340 506 C 400 556, 468 552, 500 570" fill="none" stroke="#31c48d" stroke-width="2" marker-end="url(#aNext)"/>
+  <text x="350" y="540" font-size="11.5" fill="#31c48d">next</text>
+
+  <!-- fast-vendor -> decide -->
+  <path d="M 900 346 C 900 480, 690 500, 640 570" fill="none" stroke="#31c48d" stroke-width="2" marker-end="url(#aNext)"/>
+  <text x="828" y="470" font-size="11.5" fill="#31c48d">next</text>
+
+  <!-- decide -> finish -->
+  <path d="M 560 656 L 560 694" fill="none" stroke="#31c48d" stroke-width="2" marker-end="url(#aNext)"/>
+  <text x="572" y="680" font-size="11.5" fill="#31c48d">next</text>
+
+  <!-- ============ nodes ============ -->
+
+  <!-- start -->
+  <g>
+    <rect x="440" y="110" width="240" height="86" rx="12" fill="#121a33" stroke="#31c48d" stroke-width="1.6"/>
+    <text x="456" y="140" font-size="15" font-weight="700" fill="#e7ecf7">start</text>
+    <text x="664" y="140" font-size="10.5" font-weight="700" fill="#31c48d" text-anchor="end">SUCCEEDED</text>
+    <text x="456" y="166" font-size="11.5" fill="#c8d3ec">run: () =&gt; 1</text>
+    <text x="456" y="186" font-size="11.5" fill="#94a3c4">next: [slow-vendor, fast-vendor]</text>
+  </g>
+
+  <!-- slow-vendor -->
+  <g>
+    <rect x="140" y="260" width="240" height="86" rx="12" fill="#121a33" stroke="#f4645f" stroke-width="1.8"/>
+    <text x="156" y="290" font-size="15" font-weight="700" fill="#e7ecf7">slow-vendor</text>
+    <text x="364" y="290" font-size="10.5" font-weight="700" fill="#f4645f" text-anchor="end">TIMED_OUT</text>
+    <text x="156" y="316" font-size="11.5" fill="#c8d3ec">await sleep(80) → "vendor-result"</text>
+    <text x="156" y="336" font-size="11.5" fill="#f0b429">timeoutMs: 25 · onThrow ↓</text>
+  </g>
+
+  <!-- vendor-fallback -->
+  <g>
+    <rect x="140" y="430" width="240" height="86" rx="12" fill="#121a33" stroke="#31c48d" stroke-width="1.6"/>
+    <text x="156" y="460" font-size="15" font-weight="700" fill="#e7ecf7">vendor-fallback</text>
+    <text x="364" y="460" font-size="10.5" font-weight="700" fill="#31c48d" text-anchor="end">SUCCEEDED</text>
+    <text x="156" y="486" font-size="11.5" fill="#c8d3ec">releaseFast() → "cached-price"</text>
+    <text x="156" y="506" font-size="11.5" fill="#94a3c4">next: [decide]</text>
+  </g>
+
+  <!-- fast-vendor -->
+  <g>
+    <rect x="740" y="260" width="240" height="86" rx="12" fill="#121a33" stroke="#31c48d" stroke-width="1.6"/>
+    <text x="756" y="290" font-size="15" font-weight="700" fill="#e7ecf7">fast-vendor</text>
+    <text x="964" y="290" font-size="10.5" font-weight="700" fill="#31c48d" text-anchor="end">SUCCEEDED</text>
+    <text x="756" y="316" font-size="11.5" fill="#c8d3ec">await race(fallbackDone, 2000 ms)</text>
+    <text x="756" y="336" font-size="11.5" fill="#94a3c4">"fresh-price" · next: [decide]</text>
+  </g>
+
+  <!-- decide -->
+  <g>
+    <rect x="440" y="570" width="240" height="86" rx="12" fill="#121a33" stroke="#f0b429" stroke-width="1.8"/>
+    <text x="456" y="600" font-size="15" font-weight="700" fill="#e7ecf7">decide</text>
+    <text x="664" y="600" font-size="10.5" font-weight="700" fill="#f0b429" text-anchor="end">SUCCEEDED ×2</text>
+    <text x="456" y="626" font-size="11.5" fill="#c8d3ec">emit("pricing.decided", …)</text>
+    <text x="456" y="646" font-size="11.5" fill="#94a3c4">"decided" · next: [finish]</text>
+  </g>
+
+  <!-- finish -->
+  <g>
+    <rect x="440" y="700" width="240" height="86" rx="12" fill="#121a33" stroke="#6ea8fe" stroke-width="1.8"/>
+    <text x="456" y="730" font-size="15" font-weight="700" fill="#e7ecf7">finish ★</text>
+    <text x="664" y="730" font-size="10.5" font-weight="700" fill="#f0b429" text-anchor="end">SUCCEEDED ×2</text>
+    <text x="456" y="756" font-size="11.5" fill="#c8d3ec">"DONE"</text>
+    <text x="456" y="776" font-size="11.5" fill="#6ea8fe">terminal node → latches completion</text>
+  </g>
+
+  <!-- ============ legend ============ -->
+  <g>
+    <rect x="740" y="100" width="340" height="140" rx="12" fill="#101a38" stroke="#24304f"/>
+    <text x="756" y="122" font-size="10.5" font-weight="700" fill="#94a3c4" letter-spacing="0.08em">LEGEND</text>
+
+    <line x1="756" y1="142" x2="778" y2="142" stroke="#31c48d" stroke-width="2" marker-end="url(#aNext)"/>
+    <text x="788" y="146" font-size="11.5" fill="#c8d3ec">next — normal transition</text>
+
+    <line x1="756" y1="162" x2="778" y2="162" stroke="#f4645f" stroke-width="2" stroke-dasharray="7 5" marker-end="url(#aErr)"/>
+    <text x="788" y="166" font-size="11.5" fill="#c8d3ec">onThrow — error transition (no retry)</text>
+
+    <line x1="756" y1="182" x2="778" y2="182" stroke="#c084fc" stroke-width="1.8" stroke-dasharray="2 5" marker-end="url(#aGate)"/>
+    <text x="788" y="186" font-size="11.5" fill="#c8d3ec">test gate — fixture-only synchronisation</text>
+
+    <text x="756" y="206" font-size="11.5" fill="#c8d3ec">★ terminal · ⚠ abandoned work keeps running</text>
+    <text x="756" y="226" font-size="11.5" fill="#94a3c4">even after the run has already settled</text>
+  </g>
+
+  <!-- ============ fan-in note ============ -->
+  <g>
+    <rect x="700" y="546" width="396" height="132" rx="12" fill="#101a38" stroke="#f0b429" stroke-width="1.2"/>
+    <text x="716" y="572" font-size="11" font-weight="700" fill="#f0b429" letter-spacing="0.06em">FAN-IN · NO JOIN</text>
+    <text x="716" y="596" font-size="11.5" fill="#c8d3ec">decide is activated once per incoming edge</text>
+    <text x="716" y="614" font-size="11.5" fill="#c8d3ec">→ 2 activations · it ran twice · emit fired twice</text>
+    <text x="716" y="636" font-size="11.5" fill="#c8d3ec">each activation also schedules finish</text>
+    <text x="716" y="654" font-size="11.5" fill="#c8d3ec">→ finish ran twice · outputs[nodeId] last-write-wins</text>
+    <text x="716" y="672" font-size="11" fill="#94a3c4">(finding C-05 / C-19 · workaround: DRAIN or a join primitive)</text>
+  </g>
+
+  <!-- ============ timeline ============ -->
+  <g>
+    <text x="140" y="804" font-size="10.5" font-weight="700" fill="#94a3c4" letter-spacing="0.08em">OBSERVED TIMELINE (ms)</text>
+
+    <line x1="140" y1="838" x2="1010" y2="838" stroke="#24304f" stroke-width="2"/>
+    <rect x="449" y="830" width="46" height="16" rx="4" fill="#f0b429" opacity="0.18"/>
+
+    <!-- t = 8 -->
+    <line x1="210" y1="830" x2="210" y2="846" stroke="#4a5670" stroke-width="1.5"/>
+    <circle cx="210" cy="838" r="3.5" fill="#31c48d"/>
+    <text x="220" y="824" font-size="11" fill="#31c48d">8 · fan-out: both vendors start</text>
+
+    <!-- t = 25 -->
+    <line x1="358" y1="830" x2="358" y2="846" stroke="#4a5670" stroke-width="1.5"/>
+    <circle cx="358" cy="838" r="3.5" fill="#f0b429"/>
+    <text x="358" y="864" font-size="11" fill="#f0b429" text-anchor="middle">25 · timeoutMs deadline</text>
+
+    <!-- burst 36..40 -->
+    <line x1="453" y1="830" x2="453" y2="846" stroke="#4a5670" stroke-width="1.5"/>
+    <line x1="488" y1="830" x2="488" y2="846" stroke="#4a5670" stroke-width="1.5"/>
+    <circle cx="453" cy="838" r="3.5" fill="#f4645f"/>
+    <circle cx="462" cy="838" r="3" fill="#c084fc"/>
+    <circle cx="479" cy="838" r="3" fill="#31c48d"/>
+    <circle cx="488" cy="838" r="3.5" fill="#6ea8fe"/>
+
+    <!-- t = 89 -->
+    <line x1="914" y1="830" x2="914" y2="846" stroke="#4a5670" stroke-width="1.5"/>
+    <circle cx="914" cy="838" r="3.5" fill="#f4645f"/>
+    <text x="904" y="824" font-size="11" fill="#f4645f" text-anchor="end">89 · abandoned work ends — result discarded</text>
+
+    <text x="140" y="886" font-size="11.5" fill="#c8d3ec">t = 36–40 ms: NODE_TIMEOUT → onThrow → vendor-fallback → releaseFast → fast-vendor released → decide ×2 → finish ×2 → COMPLETED</text>
+  </g>
+</svg>