@beehexa/hexasync-template-worker-flow 2608.15.1

package/dist/stages.js

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

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

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@beehexa/hexasync-template-worker-flow",
+  "version": "2608.15.1",
+  "description": "The flow model for a worker component — pullers and pushers, computed once for every consumer.",
+  "license": "SEE LICENSE IN ../../LICENSE",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@beehexa/hexasync-template-model": "2608.15.1"
+  },
+  "hexasync": {
+    "layer": "core"
+  },
+  "devDependencies": {
+    "yaml": "^2.8.0"
+  }
+}