@beehexa/hexasync-template-worker-flow 2608.15.1 → 2608.20.18

package/dist/routes.js

@@ -1,155 +0,0 @@
-/**
- * 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

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

package/dist/stages.d.ts

@@ -1,112 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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"}

package/dist/stages.js

@@ -1,178 +0,0 @@
-/**
- * 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.
- */
-/**
- * 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 const WORKER_STAGES = {
-    pullers: [
-        { key: 'beforePullSteps', label: 'Before pull', phase: 'sequence' },
-        { key: 'pullSteps', label: 'Pull', phase: 'sequence' },
-        { key: 'afterPullSteps', label: 'After pull', phase: 'sequence' },
-        // The steps-based kind's main stage. Named `steps` outright, which is why both kinds can share one list.
-        { key: 'steps', label: 'Steps', phase: 'sequence' },
-        { key: 'onErrorSteps', label: 'On error', phase: 'error' },
-        { key: 'finalSteps', label: 'Final', phase: 'final' },
-    ],
-    pushers: [
-        { key: 'beforePushSteps', label: 'Before push', phase: 'sequence' },
-        { key: 'pushSteps', label: 'Push', phase: 'sequence' },
-        { key: 'afterPushSteps', label: 'After push', phase: 'sequence' },
-        /**
-         * ⛔ ABSENT until Story 4.5's review (H2), and the worker has always run it.
-         *
-         * `hexasync.api/Pushers/PushStepAccessor.cs:50` reads `$.finalSteps[*]` for `StepType.Final`, and the enum's own
-         * comment says *"`finalSteps` (StepType.Final) is shared with the old-kind puller and runs in the finally"* — shared
-         * with the PUSHER as well. The pullers list above has carried it since Story 4.1; this one did not, so a pusher
-         * declaring only `finalSteps` produced a model with ZERO nodes and the extension's preview drew no chart at all
-         * while still printing a Flow heading.
-         *
-         * Found by putting the two stage lists side by side, which is what this epic is for: the extension's own
-         * `STAGE_ORDER.pushers` had it right. Four other places were wrong the same way — `provenance.ts`'s `FLOW_PHASES`
-         * (so the composition report omitted the stage), `duplicates.ts` (duplicate keys there went unreported),
-         * `reference.ts` (references there went unvalidated) and `flow.ts` (routing rules never saw it) — plus
-         * `assets/pushers/pusher.json`, which did not declare the property at all.
-         *
-         * There is deliberately NO `onErrorSteps` here: `PushStepAccessor` has no `OnError` case, and `StepType.OnError` is
-         * the steps-based puller's. A stage a pusher cannot run must not be drawable.
-         */
-        { key: 'finalSteps', label: 'Final', phase: 'final' },
-    ],
-};
-const LEGACY_PULLER_STAGES = new Set([
-    'beforePullSteps',
-    'pullSteps',
-    'afterPullSteps',
-]);
-const STEPS_PULLER_STAGES = new Set(['steps', 'onErrorSteps', 'finalSteps']);
-/**
- * An array-valued key **with something in it** — which is what AC-1's *"actually present"* means.
- *
- * ⚠️ REVERSED by the Story 4.1 review (MEDIUM-1). This read `Array.isArray` alone, with a docblock arguing that
- * *"an empty array counts: it was declared"*. Measured against the corpus, that argument costs **4,519** empty
- * stage arrays — `afterPushSteps: []` is the common one — each of which drew a stage arrow into a stage containing
- * nothing. That is precisely what `stageEdges`' own docblock forbids two paragraphs later: *"an arrow into a stage
- * that is not drawn points at nothing."* Declared-and-empty is a fact about the document; it is not a stage a
- * reader can be sent to.
- *
- * `pullerKindOf` uses the same predicate deliberately: a puller whose only `steps` key is `[]` has not told us
- * which kind it is, and `unknown` is the honest answer.
- */
-function declaresStage(component, key) {
-    const value = component[key];
-    return Array.isArray(value) && value.length > 0;
-}
-export function pullerKindOf(component) {
-    const legacy = [...LEGACY_PULLER_STAGES].some((k) => declaresStage(component, k));
-    const steps = [...STEPS_PULLER_STAGES].some((k) => declaresStage(component, k));
-    // Both is possible in a malformed document. Reporting `steps` would hide the legacy stages a consumer can see, so
-    // `unknown` is the answer that does not assert something the document contradicts.
-    if (legacy && steps)
-        return 'unknown';
-    if (legacy)
-        return 'legacy';
-    if (steps)
-        return 'steps';
-    return 'unknown';
-}
-/** The stages a component actually declares, in run order. */
-export function stagesPresent(collection, component) {
-    return WORKER_STAGES[collection].filter((stage) => declaresStage(component, stage.key));
-}
-/**
- * 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 function stageEdges(collection, component) {
-    const present = stagesPresent(collection, component);
-    const sequence = present.filter((s) => s.phase === 'sequence');
-    const error = present.find((s) => s.phase === 'error');
-    const final = present.find((s) => s.phase === 'final');
-    const edges = [];
-    for (let i = 0; i < sequence.length - 1; i += 1) {
-        edges.push({ from: sequence[i].key, to: sequence[i + 1].key });
-    }
-    if (error) {
-        for (const stage of sequence) {
-            edges.push({ from: stage.key, to: error.key, label: 'on error' });
-        }
-    }
-    if (final) {
-        const last = sequence.at(-1);
-        if (last)
-            edges.push({ from: last.key, to: final.key, label: 'always' });
-        if (error)
-            edges.push({ from: error.key, to: final.key, label: 'always' });
-    }
-    return edges;
-}
-//# sourceMappingURL=stages.js.map

package/dist/stages.js.map

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