@beehexa/hexasync-template-worker-flow 2608.15.1

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/routeGraph.d.ts

@@ -0,0 +1,41 @@
+import { type RoutableStep } from './routes.js';
+/** What a synthesised node is, so a renderer picks a shape without inspecting the label. */
+export type JunctionKind = 'if' | 'expression' | 'unknown';
+/** A node the document does not declare, produced because a route needs somewhere to branch. */
+export interface Junction {
+    /** Relative path from the owning step, e.g. `['next', 'if']`. The caller prefixes the step's address. */
+    readonly path: readonly string[];
+    readonly kind: JunctionKind;
+    /** The text a renderer draws in it: the condition, the expression, or the unresolved target. */
+    readonly label: string;
+    /** The step key that produced it. */
+    readonly owner: string;
+}
+/** An edge in the route graph. Ends are either a step key or a junction path, tagged so the caller can address it. */
+export interface GraphEdge {
+    readonly from: EdgeEnd;
+    readonly to: EdgeEnd;
+    readonly label?: string;
+}
+export type EdgeEnd = {
+    readonly kind: 'step';
+    readonly key: string;
+} | {
+    readonly kind: 'junction';
+    readonly owner: string;
+    readonly path: readonly string[];
+};
+export interface RouteGraph {
+    readonly junctions: readonly Junction[];
+    readonly edges: readonly GraphEdge[];
+}
+/**
+ * Every junction and every edge for the steps of ONE stage.
+ *
+ * Iterative over an explicit work list, never recursive — `then`/`else` nest without bound and a document is
+ * untrusted input. The work list carries the PATH, which is what makes the addressing positional-free.
+ */
+export declare function routeGraph(steps: readonly RoutableStep[]): RouteGraph;
+/** The address of a junction, given its owning step's address. AD-33 rule 4 / rule 5. */
+export declare function junctionAddress(ownerAddress: string, path: readonly string[]): string;
+//# sourceMappingURL=routeGraph.d.ts.map

package/dist/routeGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeGraph.d.ts","sourceRoot":"","sources":["../src/routeGraph.ts"],"names":[],"mappings":"AAqCA,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAErB,4FAA4F;AAC5F,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,YAAY,GAAG,SAAS,CAAC;AAE3D,gGAAgG;AAChG,MAAM,WAAW,QAAQ;IACvB,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sHAAsH;AACtH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/C;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC,CAAC;AAEN,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,UAAU,CAsMrE;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,CAOR"}

package/dist/routeGraph.js

@@ -0,0 +1,214 @@
+/**
+ * The route GRAPH — edges that pass THROUGH the nodes a branch synthesises.
+ *
+ * ### Why this exists alongside `routeEdges`, which is flat
+ *
+ * ⛔ The first version of this package had `routeEdges` only, and `flow.ts` synthesised a decision node beside it
+ * without connecting the two. The Story 4.1 review measured what that produced: a diamond with **zero** edges
+ * touching it, while the YES/NO arms left the step — so the diamond was unreachable and undrawable, and the step
+ * carried arms it does not have. Worse, it synthesised for the ~22 corpus steps with an object-valued `next` and
+ * produced **no** node for the **3,480** with an expression-valued one, which is exactly where both shipped
+ * surfaces DO synthesise (`_EXPR_<n>` in `flowChart.ts:145-155`, in the golden baseline for fixture 01).
+ *
+ * `routeEdges` is kept because it answers a genuinely different question — *"what routes where"*, flat, which is
+ * what `flowEdges` answers and what `routeParity.spec.ts` compares. This answers *"how is it drawn"*, and
+ * `routeGraph.spec.ts` asserts the two agree about reachability so they cannot drift.
+ *
+ * ### The three synthesised kinds, from the shipped baseline
+ *
+ * | kind | when | drawn as | label |
+ * | --- | --- | --- | --- |
+ * | `if` | an object route `{ if, then, else }` | diamond | the `if` text, or `?` |
+ * | `expression` | a Scriban route naming ≥1 real step | diamond | the expression |
+ * | `unknown` | a route naming no step at all | stadium | the route text |
+ *
+ * ### Addressed by PATH, per AD-33 rule 4
+ *
+ * A structural node is *"named by the keys that reach it"*. So the junction for a step's object `next` is
+ * `<step>:next:if` — AD-33's own example — a nested arm is `<step>:next:then:if`, an `IF` branching through `data`
+ * is `<step>:data:if`, and an expression is `<step>:next:expression`. No counter anywhere, so inserting a step above
+ * renumbers nothing. The path also disambiguates naturally: two dead ends leaving one step reach it by different
+ * keys (`:next:unknown` and `:onError:unknown`), so neither needs an index.
+ */
+import { keySegment, entrySegment, nodeAddress, } from '@beehexa/hexasync-template-model';
+import { looksLikeExpression, quotedKeys, } from './routes.js';
+const step_ = (key) => ({ kind: 'step', key });
+/**
+ * Every junction and every edge for the steps of ONE stage.
+ *
+ * Iterative over an explicit work list, never recursive — `then`/`else` nest without bound and a document is
+ * untrusted input. The work list carries the PATH, which is what makes the addressing positional-free.
+ */
+export function routeGraph(steps) {
+    const known = new Set(steps.map((s) => String(s.key)));
+    const junctions = [];
+    const edges = [];
+    /** Junctions already created, so two routes reaching the same path share one node. */
+    const seen = new Set();
+    const junction = (owner, path, kind, label) => {
+        const id = `${owner} ${path.join(' ')}`;
+        if (!seen.has(id)) {
+            seen.add(id);
+            junctions.push({ owner, path, kind, label });
+        }
+        return { kind: 'junction', owner, path };
+    };
+    for (const step of steps) {
+        const owner = String(step.key);
+        const type = String(step.stepType ?? '').toUpperCase();
+        const isBranchObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+        /**
+         * Branch objects already entered on THIS step's walk — the cycle guard.
+         *
+         * ⛔ Without it a cyclic branch does not merely loop, it **kills the process**. Found by the Story 4.2 review and
+         * confirmed here: `const a = {}; a.then = a; routeGraph([{ key: 'A', next: a }])` exits **134**, `FATAL ERROR:
+         * heap out of memory`, in a few seconds. The `path` grows by two segments per iteration, `seen` is keyed by that
+         * path so it never repeats, and both `junctions` and the work list grow without bound.
+         *
+         * This module's own docblock argued *"iterative, never recursive — a document is untrusted input"*. Iteration was
+         * the right call and it removed the only thing that had been bounding this: the reference implementation recurses
+         * and throws a **catchable** `RangeError`. An uncatchable V8 fatal is strictly worse, and this package is bundled
+         * into the VS Code extension host, so the blast radius is the editor process.
+         *
+         * REACHABLE FROM YAML with the parser the CLI already uses — a recursive anchor is all it takes:
+         *
+         * ```yaml
+         * next: &loop
+         *   if: "x"
+         *   then: *loop
+         * ```
+         *
+         * Identity, not path: the same object reached twice is the cycle, however long the path to it.
+         */
+        const entered = new WeakSet();
+        /** Work list of routes still to place: where the arrow leaves, the value, the path, the label. */
+        const pending = [];
+        // ── Which route(s) this step declares, and under which key ──
+        //
+        // An IF whose `data` is an object but declares NEITHER `then` NOR `else` falls back to `next`. Without the
+        // fallback a partly-written IF loses its only edge and its target is orphaned in the diagram — `data:
+        // { expression: '…' }` with `next: 'DONE'` drew `CHECK → <diamond>` and nothing else, leaving `DONE` floating.
+        //
+        // This mirrors `routes.ts`, the flat twin, which has always had the fallback and says why in the same words. The
+        // two disagreed until Story 4.7's review measured it; this module's own docblock claimed the case "routed
+        // correctly through its `next`", which was aspiration rather than behaviour. `type` comes from `displayType`
+        // first, and every UI-served step carries one, so the divergence was reachable from a real surface.
+        const branching = (type === 'IF' || type === 'SWITCH') && isBranchObject(step.data);
+        const ifWithoutBranch = type === 'IF' &&
+            branching &&
+            step.data.then == null &&
+            step.data.else == null;
+        if (branching && !ifWithoutBranch) {
+            pending.push({ from: step_(owner), value: step.data, path: ['data'] });
+        }
+        else {
+            pending.push({ from: step_(owner), value: step.next, path: ['next'] });
+        }
+        if (step.onError !== null && step.onError !== undefined) {
+            pending.push({
+                from: step_(owner),
+                value: step.onError,
+                path: ['onError'],
+                label: 'onError',
+            });
+        }
+        while (pending.length > 0) {
+            const { from, value, path, label } = pending.pop();
+            if (value === null || value === undefined || value === '')
+                continue;
+            const labelled = label !== undefined ? { label } : {};
+            // ── An object route: a diamond, and its arms leave the DIAMOND, not the step ──
+            if (isBranchObject(value)) {
+                const branch = value;
+                if (entered.has(branch)) {
+                    /**
+                     * A cycle. Reported as a dead end labelled for what it is, rather than dropped: a route that loops back on
+                     * itself is a real document defect, and a diagram that simply stops there tells the reader nothing.
+                     */
+                    const point = junction(owner, [...path, 'cycle'], 'unknown', 'cycle: this branch refers to itself');
+                    edges.push({ from, to: point, ...labelled });
+                    continue;
+                }
+                entered.add(branch);
+                const isSwitch = type === 'SWITCH' && path.length === 1 && path[0] === 'data';
+                if (isSwitch) {
+                    // A SWITCH's arms are its data KEYS. The junction is the switch point itself.
+                    const point = junction(owner, [...path, 'switch'], 'if', 'SWITCH');
+                    edges.push({ from, to: point, ...labelled });
+                    for (const arm of Object.keys(branch)) {
+                        pending.push({
+                            from: point,
+                            value: arm,
+                            path: [...path, arm],
+                            label: arm,
+                        });
+                    }
+                    continue;
+                }
+                const condition = branch.if === null || branch.if === undefined
+                    ? '?'
+                    : String(branch.if);
+                const point = junction(owner, [...path, 'if'], 'if', condition);
+                edges.push({ from, to: point, ...labelled });
+                // `else` first so `then` is placed first — a reader expects YES before NO.
+                pending.push({
+                    from: point,
+                    value: branch.else,
+                    path: [...path, 'else'],
+                    label: 'NO',
+                });
+                pending.push({
+                    from: point,
+                    value: branch.then,
+                    path: [...path, 'then'],
+                    label: 'YES',
+                });
+                continue;
+            }
+            const text = String(value);
+            // ── A direct step key: a plain edge, no synthesis ──
+            if (known.has(text)) {
+                edges.push({ from, to: step_(text), ...labelled });
+                continue;
+            }
+            // ── An expression naming real steps: a diamond, then one arrow per target ──
+            if (looksLikeExpression(text)) {
+                const targets = quotedKeys(text).filter((k) => known.has(k));
+                if (targets.length > 0) {
+                    const point = junction(owner, [...path, 'expression'], 'expression', text);
+                    edges.push({ from, to: point, ...labelled });
+                    // Unlabelled, as the baseline draws them: which target it takes is a run-time fact.
+                    for (const target of targets) {
+                        edges.push({ from: point, to: step_(target) });
+                    }
+                    continue;
+                }
+            }
+            // ── Naming nothing: a terminal, kept so the reader sees the dead end ──
+            const point = junction(owner, [...path, 'unknown'], 'unknown', text);
+            edges.push({ from, to: point, ...labelled });
+        }
+        /**
+         * The exception BACK-REFERENCE, which is reversed: an edge INTO this step from the one that threw. No junction —
+         * it is a direct edge between two authored steps.
+         */
+        if (step.fromStep && known.has(step.fromStep)) {
+            edges.push({
+                from: step_(step.fromStep),
+                to: step_(owner),
+                label: 'Exception',
+            });
+        }
+    }
+    return { junctions, edges };
+}
+/** The address of a junction, given its owning step's address. AD-33 rule 4 / rule 5. */
+export function junctionAddress(ownerAddress, path) {
+    return nodeAddress([
+        keySegment(ownerAddress),
+        // A path element is a document key where it is one (`next`, `then`, `if`) and a dictionary tail where it is a
+        // SWITCH arm — `entrySegment` normalises both and refuses a `!`-prefixed one.
+        ...path.map((element) => entrySegment(element) ?? keySegment(element)),
+    ]);
+}
+//# sourceMappingURL=routeGraph.js.map

package/dist/routeGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeGraph.js","sourceRoot":"","sources":["../src/routeGraph.ts"],"names":[],"mappings":"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"}

package/dist/routes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Where a step goes next — Story 4.1 AC-2, all five kinds, in the MODEL rather than in a renderer.
+ *
+ * The semantics are the runtime's: `core.api/hexasync.steps/Execution/NextStepBuilder.cs` and `IfStepExecutor`.
+ * This package does not invent them; NFR-1 says the editor invents no semantics the runtime lacks.
+ *
+ * | kind | where it is declared | who drew it before |
+ * | --- | --- | --- |
+ * | by step TYPE | `IF` / `SWITCH` read their `data` | CLI only — dashboard reads only `step.next` |
+ * | by step DATA | `{ if, then, else }` on `next` or `data` | CLI |
+ * | an EXPRESSION | a Scriban `next` naming keys in quotes | CLI |
+ * | an ERROR route | `onError` | CLI |
+ * | an exception BACK-REFERENCE | `fromStep` → this step | **nobody** — see below |
+ *
+ * ### The back-reference is why routing has to live here
+ *
+ * `fromStep` produces an edge *into* the exception step from the step that threw. It exists **only in the CLI's
+ * drawing path** (`flowChart.ts:199-201` emits `fromStep --|"Exception"|-> this`) and **not** in the shared
+ * `flowEdges`. The VS Code extension imports `flowEdges`, so it has never drawn that edge at all — a whole route
+ * kind missing from one surface because the renderer, not the model, owned it. Moving routing into the model is what
+ * makes AC-2's last clause true everywhere, and it is the concrete argument for this package existing.
+ *
+ * ### An unresolvable route is REPORTED, not dropped
+ *
+ * A route naming no step in the stage yields an edge with `raw` and no `to`. A reader needs to see the dead end:
+ * silently dropping it draws a flow that terminates where the document does not say it terminates, which is the
+ * more expensive error. Same for an expression whose quoted keys match nothing.
+ */
+/** A step as routing needs to see it. Deliberately structural — this package reads no schema and no file. */
+export interface RoutableStep {
+    readonly key: string;
+    /** Raw `next`: a step key, a `{ if, then, else }` branch, a Scriban expression, or absent. */
+    readonly next?: unknown;
+    /** The step's declared type, e.g. `IF`, `SWITCH`. Compared case-insensitively. */
+    readonly stepType?: string;
+    /** For `IF`/`SWITCH`, the runtime passes `data` to the route builder. */
+    readonly data?: unknown;
+    /** A recovery target. */
+    readonly onError?: unknown;
+    /** An Exception step's back-reference: the step whose failure reaches this one. */
+    readonly fromStep?: string;
+}
+/** One arrow between two steps. */
+export interface RouteEdge {
+    /** The step the arrow leaves. */
+    readonly from: string;
+    /** The step it reaches, when that step exists in this stage. */
+    readonly to?: string;
+    /** `YES`, `NO`, a SWITCH branch name, `onError`, `Exception`. */
+    readonly label?: string;
+    /**
+     * The route text when it does not name a known step — an expression, or a dead end.
+     *
+     * Carried alongside `to` for an expression that DOES resolve, because which branch it takes at run time is a fact
+     * a static view cannot know, and showing the expression is how the reader learns that.
+     */
+    readonly raw?: string;
+}
+/** Every `"QUOTED_KEY"` in an expression. */
+export declare function quotedKeys(expression: string): readonly string[];
+/** Is this route text an expression rather than a step key? */
+export declare function looksLikeExpression(text: string): boolean;
+/**
+ * Every edge the steps of ONE stage declare.
+ *
+ * Iterative, never recursive: `then`/`else` nest without bound and a document is untrusted input, so a deep branch
+ * must not be able to exhaust the stack. (The same rule the puller step standards state: *no recursion — stack or
+ * loop*.)
+ */
+export declare function routeEdges(steps: readonly RoutableStep[]): readonly RouteEdge[];
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,6GAA6G;AAC7G,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,6CAA6C;AAC7C,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,SAAS,SAAS,EAAE,CAmHtB"}

package/dist/routes.js

@@ -0,0 +1,155 @@
+/**
+ * Where a step goes next — Story 4.1 AC-2, all five kinds, in the MODEL rather than in a renderer.
+ *
+ * The semantics are the runtime's: `core.api/hexasync.steps/Execution/NextStepBuilder.cs` and `IfStepExecutor`.
+ * This package does not invent them; NFR-1 says the editor invents no semantics the runtime lacks.
+ *
+ * | kind | where it is declared | who drew it before |
+ * | --- | --- | --- |
+ * | by step TYPE | `IF` / `SWITCH` read their `data` | CLI only — dashboard reads only `step.next` |
+ * | by step DATA | `{ if, then, else }` on `next` or `data` | CLI |
+ * | an EXPRESSION | a Scriban `next` naming keys in quotes | CLI |
+ * | an ERROR route | `onError` | CLI |
+ * | an exception BACK-REFERENCE | `fromStep` → this step | **nobody** — see below |
+ *
+ * ### The back-reference is why routing has to live here
+ *
+ * `fromStep` produces an edge *into* the exception step from the step that threw. It exists **only in the CLI's
+ * drawing path** (`flowChart.ts:199-201` emits `fromStep --|"Exception"|-> this`) and **not** in the shared
+ * `flowEdges`. The VS Code extension imports `flowEdges`, so it has never drawn that edge at all — a whole route
+ * kind missing from one surface because the renderer, not the model, owned it. Moving routing into the model is what
+ * makes AC-2's last clause true everywhere, and it is the concrete argument for this package existing.
+ *
+ * ### An unresolvable route is REPORTED, not dropped
+ *
+ * A route naming no step in the stage yields an edge with `raw` and no `to`. A reader needs to see the dead end:
+ * silently dropping it draws a flow that terminates where the document does not say it terminates, which is the
+ * more expensive error. Same for an expression whose quoted keys match nothing.
+ */
+/** Every `"QUOTED_KEY"` in an expression. */
+export function quotedKeys(expression) {
+    return [...expression.matchAll(/"([A-Za-z0-9_]+)"/g)].map((m) => m[1]);
+}
+/** Is this route text an expression rather than a step key? */
+export function looksLikeExpression(text) {
+    return (text.includes('{{') || text.includes('}}') || /"[A-Za-z0-9_]+"/.test(text));
+}
+/**
+ * Every edge the steps of ONE stage declare.
+ *
+ * Iterative, never recursive: `then`/`else` nest without bound and a document is untrusted input, so a deep branch
+ * must not be able to exhaust the stack. (The same rule the puller step standards state: *no recursion — stack or
+ * loop*.)
+ */
+export function routeEdges(steps) {
+    // `String`, because the exported function is callable with a non-string `key` (Story 4.1 review, LOW-3): the raw
+    // value leaked into `RouteEdge.from`, typed `string`, and a route to step `5` was reported as a dead end because
+    // `known` held the number while the route text was `'5'`. `workerFlow` filters these out; a direct caller cannot.
+    const known = new Set(steps.map((s) => String(s.key)));
+    const edges = [];
+    const walk = (from, value, label) => {
+        /**
+         * Branch objects already entered on THIS step's walk — the cycle guard.
+         *
+         * ⛔ Added at the Epic 4 close (2026-08-12). `routeGraph.ts` and the frontend twin both carry this guard, with the
+         * reason recorded: a cyclic branch does not loop, it **kills the process** with an uncatchable V8 fatal, and this
+         * code is bundled into the VS Code extension host. This walker never received it, and it is the one the
+         * extension's fallback SVG still consumes on every preview — so the guarded packages closed the hole on the new
+         * path and left it open on the shipped one.
+         *
+         * Measured: `const a = {}; a.then = a;` walked through here under `--max-old-space-size=200` gives
+         * `FATAL ERROR: … heap out of memory`, process aborted. A `try/catch` around the preview does not help.
+         *
+         * REACHABLE FROM YAML with the parser the CLI already uses — a recursive anchor is all it takes:
+         *
+         * ```yaml
+         * next: &loop
+         *   if: "x"
+         *   then: *loop
+         * ```
+         *
+         * Identity, not path: the same object reached twice is the cycle, however long the path to it.
+         */
+        const entered = new WeakSet();
+        const stack = [
+            { value, ...(label !== undefined ? { label } : {}) },
+        ];
+        while (stack.length > 0) {
+            const { value: node, label: current } = stack.pop();
+            if (node === null || node === undefined || node === '')
+                continue;
+            const labelled = current !== undefined ? { label: current } : {};
+            if (typeof node === 'object' && !Array.isArray(node)) {
+                if (entered.has(node))
+                    continue;
+                entered.add(node);
+                const branch = node;
+                // `else` pushed first so `then` is walked first — a reader expects YES before NO.
+                stack.push({ value: branch.else, label: 'NO' });
+                stack.push({ value: branch.then, label: 'YES' });
+                continue;
+            }
+            const text = String(node);
+            if (known.has(text)) {
+                edges.push({ from, to: text, ...labelled });
+                continue;
+            }
+            if (looksLikeExpression(text)) {
+                const targets = quotedKeys(text).filter((k) => known.has(k));
+                for (const target of targets) {
+                    edges.push({ from, to: target, raw: text, ...labelled });
+                }
+                // Resolving to nothing is still a route, and the expression is the only thing that can be shown about it.
+                if (targets.length === 0)
+                    edges.push({ from, raw: text, ...labelled });
+                continue;
+            }
+            // Names no step in this stage. Kept so the reader sees the dead end.
+            edges.push({ from, raw: text, ...labelled });
+        }
+    };
+    for (const rawStep of steps) {
+        const step = { ...rawStep, key: String(rawStep.key) };
+        const type = String(step.stepType ?? '').toUpperCase();
+        const data = step.data && typeof step.data === 'object' && !Array.isArray(step.data)
+            ? step.data
+            : undefined;
+        if (type === 'IF' && data) {
+            // `IfStepExecutor` passes `StepData` to the builder, so an IF routes from its `data`.
+            if (data.then !== null && data.then !== undefined) {
+                walk(step.key, data.then, 'YES');
+            }
+            if (data.else !== null && data.else !== undefined) {
+                walk(step.key, data.else, 'NO');
+            }
+            // An IF declaring neither branch falls back to `next` — otherwise a partly-written IF loses its only edge.
+            if ((data.then === null || data.then === undefined) &&
+                (data.else === null || data.else === undefined)) {
+                walk(step.key, step.next);
+            }
+        }
+        else if (type === 'SWITCH' && data) {
+            // A SWITCH's branches are its `data` KEYS, each labelled with itself.
+            for (const branch of Object.keys(data))
+                walk(step.key, branch, branch);
+        }
+        else {
+            walk(step.key, step.next);
+        }
+        if (step.onError !== null && step.onError !== undefined) {
+            walk(step.key, step.onError, 'onError');
+        }
+        /**
+         * The exception BACK-REFERENCE — an edge INTO this step, from the one that threw.
+         *
+         * Reversed relative to every other kind, which is why a renderer that owned routing kept forgetting it. Only
+         * drawn when `fromStep` names a step in this stage: an exception handler pointing outside its own stage is a
+         * document error, and inventing a node for it would draw a step the stage does not contain.
+         */
+        if (step.fromStep && known.has(step.fromStep)) {
+            edges.push({ from: step.fromStep, to: step.key, label: 'Exception' });
+        }
+    }
+    return edges;
+}
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAkCH,6CAA6C;AAC7C,MAAM,UAAU,UAAU,CAAC,UAAkB;IAC3C,OAAO,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;AAC1E,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,CACL,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAC3E,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,KAA8B;IAE9B,iHAAiH;IACjH,iHAAiH;IACjH,kHAAkH;IAClH,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACvD,MAAM,KAAK,GAAgB,EAAE,CAAC;IAE9B,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,KAAc,EAAE,KAAc,EAAQ,EAAE;QAClE;;;;;;;;;;;;;;;;;;;;;WAqBG;QACH,MAAM,OAAO,GAAG,IAAI,OAAO,EAAU,CAAC;QACtC,MAAM,KAAK,GAAyC;YAClD,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;SACrD,CAAC;QACF,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;YACrD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE;gBAAE,SAAS;YACjE,MAAM,QAAQ,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAEjE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAc,CAAC;oBAAE,SAAS;gBAC1C,OAAO,CAAC,GAAG,CAAC,IAAc,CAAC,CAAC;gBAC5B,MAAM,MAAM,GAAG,IAA0C,CAAC;gBAC1D,kFAAkF;gBAClF,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAChD,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;gBACjD,SAAS;YACX,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1B,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;gBAC5C,SAAS;YACX,CAAC;YACD,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC7D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;gBAC3D,CAAC;gBACD,0GAA0G;gBAC1G,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;oBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;gBACvE,SAAS;YACX,CAAC;YACD,qEAAqE;YACrE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACvD,MAAM,IAAI,GACR,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YACrE,CAAC,CAAE,IAAI,CAAC,IAAgC;YACxC,CAAC,CAAC,SAAS,CAAC;QAEhB,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,EAAE,CAAC;YAC1B,sFAAsF;YACtF,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAClD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAClD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAClC,CAAC;YACD,2GAA2G;YAC3G,IACE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC;gBAC/C,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,EAC/C,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;aAAM,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,EAAE,CAAC;YACrC,sEAAsE;YACtE,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACzE,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACxD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1C,CAAC;QAED;;;;;;WAMG;QACH,IAAI,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/stages.d.ts

@@ -0,0 +1,112 @@
+/**
+ * A worker component's stages, and the arrows between the ones it actually has — Story 4.1 AC-1.
+ *
+ * ### Three shapes, one vocabulary
+ *
+ * A pusher, a **legacy** puller (`beforePullSteps`/`pullSteps`/`afterPullSteps`) and a **steps-based** puller
+ * (`steps`/`onErrorSteps`/`finalSteps`). Two vocabularies existed before this and they disagreed three ways; each
+ * disagreement is settled below by evidence rather than preference.
+ *
+ * **1. PRESENCE decides the shape, not a flag.** The CLI's `provenance.ts` picks between two stage lists using a
+ * `newKind` boolean. AC-1 says stage edges come from *"the stages actually present"*, and a boolean is a second
+ * source of truth for something the document already states by having the key. The extension's structure — one list
+ * per collection, presence deciding — is adopted. It also lets both puller kinds be listed together, which only
+ * works because the new kind's main stage is named `steps` outright and so cannot collide with the legacy three.
+ *
+ * **2. ⛔ A pusher DOES have `finalSteps` — this decision was WRONG and is reversed.** The original reasoning is kept
+ * below because the way it failed is instructive:
+ *
+ * > *"`assets/pushers/pusher.json` declares exactly `beforePushSteps`, `pushSteps`, `afterPushSteps`. The extension's
+ * > `STAGE_ORDER` lists a fourth, so it carries a stage that can never populate — a third vocabulary disagreeing with
+ * > the one authority. Dropped. Measured, so the drop costs nothing: 0 authored corpus pushers declare `finalSteps`."*
+ *
+ * The schema was treated as the authority, and the schema was itself wrong. **`PushStepAccessor` reads
+ * `$.finalSteps[*]` → `StepType.Final`** — the RUNTIME runs the stage. So the "third vocabulary" was the only one
+ * telling the truth, and the corpus count of 0 measured what authors could express through tooling that denied the
+ * stage, not what the platform supports. `WORKER_STAGES.pushers` declares it (Story 4.5 review, H2), and by Story 4.7
+ * the same omission had been found in **five** independent places, dashboard's `pusherPhases()` last.
+ *
+ * The transferable rule: **when a schema and the runtime disagree, the runtime is the authority.** A schema is a claim
+ * about the runtime and can be stale; `PushStepAccessor` is the thing that actually runs.
+ *
+ * **3. `label` and `phase` are carried.** A renderer needs a human label, and `phase` is what tells an error stage
+ * from a sequence stage without string-matching the key. The CLI has neither and its report is poorer for it.
+ *
+ * ### ⚠️ The steps-based puller is exercised by NOTHING real
+ *
+ * Measured over the authored corpus (`output.yaml` excluded), counting array-valued stage keys on every `pullers[]`
+ * and `pushers[]` entry:
+ *
+ * | stage | authored occurrences |
+ * | --- | --- |
+ * | `pullSteps` / `beforePullSteps` / `afterPullSteps` | 970 / 715 / 509 |
+ * | `pushSteps` / `beforePushSteps` / `afterPushSteps` | 925 / 756 / 767 |
+ * | `steps` / `onErrorSteps` / `finalSteps` | **0 / 0 / 0** |
+ *
+ * Story 4.1 says `onErrorSteps` and `finalSteps` appear in zero corpus files. That is true and it understates the
+ * position: **the whole steps-based kind has no authored instance anywhere**, so the shape is supported by the
+ * tooling and exercised by nothing. Fixture `03` is the only exercise it gets, which makes it the fixture most
+ * likely to drift and the one to treat as load-bearing rather than as an afterthought.
+ */
+/** What a stage is FOR, so a renderer never has to string-match a key to find out. */
+export type StagePhase = 'sequence' | 'error' | 'final';
+/** One stage a component may declare. */
+export interface StageDefinition {
+    /** The document key: `pullSteps`, `onErrorSteps`. */
+    readonly key: string;
+    /** For a human: `Before pull`. */
+    readonly label: string;
+    readonly phase: StagePhase;
+}
+/** The collections this package models. A frontend workflow is Story 4.2's, deliberately separate (AD-21). */
+export type WorkerCollection = 'pullers' | 'pushers';
+/**
+ * Every stage each collection may declare, in run order.
+ *
+ * ⛔ These keys mirror `assets/pullers/puller.json` and `assets/pushers/pusher.json`, which are the authority.
+ *
+ * ⚠️ **Mirrored, not DERIVED, and Task 2 asked for derived** (Story 4.1 review, M5). Deriving would mean reading a
+ * schema file, which AD-3 forbids this package from doing and NFR-4 forbids in the extension's host — so the schemas
+ * are the authority for a *test*, not for the runtime value. `stageSchemaParity.spec.ts` asserts this table against
+ * them in both directions, which is arguably stronger than derivation (it catches a stage the schema drops as well as
+ * one the table invents); it is nonetheless a deviation from the task as written, and it is skippable when the
+ * sibling repo is absent — which is why that spec also hardcodes the pusher expectation so something always runs.
+ */
+export declare const WORKER_STAGES: Readonly<Record<WorkerCollection, readonly StageDefinition[]>>;
+/**
+ * Which kind of puller a component is — reported, never used to CHOOSE the stage list.
+ *
+ * Worth having because a consumer may want to say so, and worth computing from presence: `legacy` and `steps` are
+ * observations about the document, and `unknown` is the honest answer for a puller declaring no stage at all rather
+ * than a guess at which kind it meant to be.
+ */
+export type PullerKind = 'legacy' | 'steps' | 'unknown';
+export declare function pullerKindOf(component: Record<string, unknown>): PullerKind;
+/** The stages a component actually declares, in run order. */
+export declare function stagesPresent(collection: WorkerCollection, component: Record<string, unknown>): readonly StageDefinition[];
+/** One arrow between two stages. */
+export interface StageEdge {
+    readonly from: string;
+    readonly to: string;
+    /** Absent for a plain sequence arrow; a renderer draws the label only where there is one. */
+    readonly label?: string;
+}
+/**
+ * The arrows between the stages a component HAS.
+ *
+ * Three rules, and the second and third are why this is not a `zip` of the ordered list:
+ *
+ * 1. **Sequence stages chain in order.** Computed from what is present, so a puller declaring only `pullSteps` has
+ *    **no stage edges at all** — which fixture 02's baseline records verbatim as *"stage edges: none"*. An arrow
+ *    into a stage that is not drawn points at nothing.
+ * 2. **An `error` stage is reachable from EVERY sequence stage**, labelled, because that is what an error stage
+ *    means: any of them can fail into it. Drawing it as one more link in the chain would say the opposite — that it
+ *    runs after the last sequence stage, on success.
+ * 3. **A `final` stage runs always**, from the last sequence stage and from the error stage, labelled `always`. It
+ *    is the one stage a component reaches whichever way the run ends.
+ *
+ * The labels are the extension's, which is the only implementation that has stage *semantics* rather than only
+ * geometry.
+ */
+export declare function stageEdges(collection: WorkerCollection, component: Record<string, unknown>): readonly StageEdge[];
+//# sourceMappingURL=stages.d.ts.map

package/dist/stages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stages.d.ts","sourceRoot":"","sources":["../src/stages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,sFAAsF;AACtF,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;AAExD,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,8GAA8G;AAC9G,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAClC,MAAM,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC,CAmCrD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AA8BxD,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAa3E;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAC3B,UAAU,EAAE,gBAAgB,EAC5B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,SAAS,eAAe,EAAE,CAI5B;AAED,oCAAoC;AACpC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,gBAAgB,EAC5B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,SAAS,SAAS,EAAE,CAqBtB"}