@beehexa/hexasync-template-context 2608.20.18 → 2608.20.31

package/dist/references.js

@@ -0,0 +1,217 @@
+import { ALLOWS_NESTING } from './position.js';
+/**
+ * Every context path an expression references, and whether the position can provide it — Story 8.6.
+ *
+ * ⛔ **The known-inert allowlist.** `puller.isInit` appears **79 times** in the corpus (**77** once deduplicated per
+ * step) and the string `isInit` appears NOWHERE in `core.api` or `hexasync.worker.proxy`. Every one of those guards
+ * is testing an always-falsy value. Whether that is intended is a question for the platform, not for this feature —
+ * and 77 findings about a pattern nobody intends to change is noise, not a finding. Decided by Jazz, 2026-08-09:
+ * ignore it.
+ *
+ * ⚠️ Both numbers are correct and they are NOT the same measurement: the corpus spec's `inertSkipped` counts raw
+ * occurrences (79), while a report would show one line per step (77). They were conflated in three places until the
+ * Epic 8 review separated them — the assertion below is on the string, so it silently accepted either.
+ *
+ * The allowlist needs a REASON written next to each entry, or it becomes a place findings go to disappear.
+ */
+export const KNOWN_INERT = {
+    'puller.isInit': 'Measured 2026-08-09: 79 corpus occurrences (77 deduplicated per step), and `isInit` exists in no runtime. Ignored by decision — the pattern is not one this feature is asking anyone to change.',
+};
+/**
+ * Pull every `$( )`, `$$( )` and `{{ }}` payload out of one authored value.
+ *
+ * ⛔ These were two lazy regexes — `/\{\{([\s\S]*?)\}\}/g` and `/\$\$?\(([\s\S]*?)\)/g` — and CodeQL was
+ * right about both (`js/polynomial-redos`, High). A lazy `[\s\S]*?` looking for a closer scans to the END OF
+ * THE VALUE from every opener that has no closer after it, so a value with many `{{` and no `}}` is quadratic.
+ * Authored values reach this from any project, and it runs per value while typing.
+ *
+ * Scanning for the delimiters is what the lazy quantifier meant: the payload of an opener is everything up to
+ * the FIRST closer after it. Once a closer cannot be found, no later opener can find one either — which is why
+ * the loop stops rather than continuing to search, and why this is one pass over the value.
+ */
+export function expressionsIn(value) {
+    return [...curlyPayloads(value), ...dollarPayloads(value)];
+}
+/** `{{ … }}` — payload up to the first `}}` after the opener. */
+function curlyPayloads(value) {
+    const out = [];
+    let at = value.indexOf('{{');
+    while (at !== -1) {
+        const close = value.indexOf('}}', at + 2);
+        // No closer after this opener means none after any later one — the lazy regex found nothing either.
+        if (close === -1)
+            break;
+        out.push(value.slice(at + 2, close));
+        at = value.indexOf('{{', close + 2);
+    }
+    return out;
+}
+/**
+ * `$( … )` and `$$( … )` — payload up to the first `)` after the opener.
+ *
+ * The opener is matched at the LAST possible `$`, which is what `\$\$?\(` does: in `$$$(`, the regex matches
+ * `$$(` starting at the second `$`, because the first attempt cannot reach the `(`. So a `$` that is not
+ * followed by `(` or by `$(` advances by one and is not part of anything.
+ */
+function dollarPayloads(value) {
+    const out = [];
+    let at = value.indexOf('$');
+    while (at !== -1) {
+        const opens = value.startsWith('$$(', at) ? 3 : value.startsWith('$(', at) ? 2 : 0;
+        if (opens === 0) {
+            at = value.indexOf('$', at + 1);
+            continue;
+        }
+        const close = value.indexOf(')', at + opens);
+        if (close === -1)
+            break;
+        out.push(value.slice(at + opens, close));
+        at = value.indexOf('$', close + 1);
+    }
+    return out;
+}
+/** The dotted paths inside one expression payload. */
+export function pathsIn(expression) {
+    return [
+        ...expression.matchAll(/\b([A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)+)/g),
+    ].map((match) => match[1]);
+}
+/**
+ * Check one path against one environment.
+ *
+ * ⚠️ Only the ROOT is checked, deliberately. A deeper segment can be legitimately dynamic — a step key composed at
+ * run time, an option whose name comes from a connection — and reporting those would bury the one finding that is
+ * always true: a root the position does not have cannot resolve, ever, under any composition.
+ */
+export function checkPath(path, environment) {
+    if (KNOWN_INERT[path] !== undefined)
+        return undefined;
+    const [root, second] = path.split('.');
+    if (!root)
+        return undefined;
+    if (!environment.roots.has(root)) {
+        // ⚠️ Unknown roots are NOT reported. An expression may reference a local variable, a loop binding or a helper,
+        // and this engine knows only the context — so "not a context root" is not evidence of "does not exist".
+        return undefined;
+    }
+    /**
+     * ⛔ `pusher.lastToken` — the handler gates that write on `root == "puller"`, so it does not exist on a pusher.
+     * Measured: **0 corpus occurrences**, so this reports nothing today and guards a mistake that reads exactly like
+     * the puller idiom an author has just come from.
+     */
+    const rootShape = environment.roots.get(root)?.shape;
+    if (second !== undefined &&
+        rootShape?.kind === 'object' &&
+        rootShape.fields &&
+        !rootShape.fields.has(second)) {
+        const siblings = [...rootShape.fields.keys()];
+        return {
+            path,
+            reason: `\`${root}\` has no \`${second}\`. It has: ${siblings.map((name) => `\`${name}\``).join(', ')}.`,
+            available: siblings,
+        };
+    }
+    return undefined;
+}
+/**
+ * Which phase's outputs a context segment addresses.
+ *
+ * ⛔ `history` and `lastToken` are **aliases, not stores** (§2.2): `LegacyStepContextHandler.UpdateContext` writes
+ * the phase's outputs to the phase key and then writes *the same object* to the alias. So a step key absent from
+ * `before` is absent from `history` too, and one absent from `current` is absent from `lastToken` — on every
+ * iteration, because there is only ever one object.
+ */
+export const SEGMENT_PHASE = {
+    before: 'before',
+    current: 'current',
+    after: 'after',
+    final: 'final',
+    history: 'before',
+    lastToken: 'current',
+};
+/**
+ * A step key that the addressed phase does not contain at all — a typo, or a step someone renamed (§2.3).
+ *
+ * ⛔ **NOT a forward-reference rule, though AC-2 asked for one.** A key declared LATER still resolves on every
+ * iteration after the first: `ExecuteSteps` runs afresh per page with an empty outputs dict, so at the top of page 2
+ * `puller.current` still holds page 1's values (§2.4). Measured 2026-08-14: **112** such references in the corpus,
+ * and every one is the pagination idiom. A rule with 112 false positives and no true ones does not get triaged, it
+ * gets switched off, taking the real class with it. AC-2 was amended to what the corpus supports.
+ *
+ * ⚠️ **112 and 199 are PRE-FIX figures — they no longer reproduce, and that is expected.** Both were measured before
+ * the harness's pusher-stage bug was corrected and before this rule was restricted to depth 1. Re-derived after both,
+ * the declared-later class counts ~116 under a phase's own name and ~213 across both arms. They are kept, dated, as
+ * the evidence the 2026-08-14 ruling was actually made on; they are not current measurements. The Epic 8 review
+ * flagged them as non-reproducing, which is correct and is why they now say so.
+ *
+ * ⛔ **The alias arm is reported too** (Jazz, 2026-08-14). The 199 → 112 narrowing moved along two axes at once and
+ * measured only one: *which key class* (declared-later vs absent-entirely) was evidenced, *which segment* (own name
+ * vs alias) never was. The first pass's 199 were suppressed for being declared-later reads, not for being alias
+ * reads. Applying this rule under the alias adds **67** occurrences across 12 distinct paths and no false positives
+ * — every one a renamed watermark step, e.g. `puller.history.GET_LAST_MODIFIED_DATE` in a component whose
+ * `beforePullSteps` declares only `GET_LAST_UPDATED`. Those guards fall to their `else` branch on every run and
+ * always have, which is precisely the harm this story was written to catch.
+ */
+/**
+ * The only roots that own phases. A phase word anywhere else is an ordinary field name.
+ *
+ * ⛔ Added by the Epic 8 review after TWO reviewers found the same defect independently. The first version scanned
+ * every segment from index 1 for a member of `SEGMENT_PHASE`, and the caller gated only on the ROOT existing — so any
+ * field called `after`, `before`, `current`, `final`, `history` or `lastToken` under a legitimate root was read as a
+ * phase. `__this.arguments.after.value` was reported `high` as *"`after` has no steps at all"*, and the corpus already
+ * carries **32** `__this.arguments.after` reads (an `after` pagination cursor) plus 2 of `before` — every one a single
+ * authored segment from firing. `item.history.status`, `dependencies.current.foo`, `_outputs.STEP.history.id` and
+ * `runStart.before.id` were all the same class.
+ *
+ * Widening the rule to the alias is what created the exposure: `history` and `lastToken` are ordinary English words,
+ * where `beforePullSteps` never collided with anything.
+ */
+const PHASE_OWNING_ROOTS = new Set(['puller', 'pusher']);
+export function unknownStepKey(path, keysByPhase) {
+    const segments = path.split('.');
+    const root = segments[0];
+    if (!root || !PHASE_OWNING_ROOTS.has(root))
+        return undefined;
+    /**
+     * ⛔ Depth 1, exactly. Per §2.1-§2.4 and §4 a phase is always addressed directly under its root —
+     * `puller.current.STEP`, `pusher.before.STEP`, `puller.history.STEP`. There is no shape in which a phase word is
+     * legitimately deeper, so scanning deeper only ever finds a field that happens to share the name.
+     */
+    const segment = segments[1];
+    if (segment === undefined)
+        return undefined;
+    const phase = SEGMENT_PHASE[segment];
+    if (phase === undefined)
+        return undefined;
+    /**
+     * ⛔ `lastToken` is written only when the root is `puller` — the handler gates that write on `root == "puller"`.
+     * On a pusher the whole root is wrong, which `checkPath` already reports as `pusher` having no `lastToken`;
+     * answering again here would name a phase for a path that never resolves at all.
+     */
+    if (segment === 'lastToken' && root !== 'puller')
+        return undefined;
+    const referenced = segments[2];
+    if (referenced === undefined)
+        return undefined;
+    const stepKeys = keysByPhase[phase] ?? [];
+    /**
+     * ⛔ Self-reference is NOT reported (§2.4). Each pagination iteration calls `ExecuteSteps` afresh, so
+     * `puller.lastToken.PULL_DATA.offset` read from inside `PULL_DATA` is the PREVIOUS page's value — the idiom the
+     * alias is named for, and 5,933 corpus uses of `puller.lastToken` are built on it. Membership is what keeps it
+     * out: the step is in its own phase, so it is never absent.
+     */
+    if (stepKeys.includes(referenced))
+        return undefined;
+    const named = segment === phase ? `\`${phase}\`` : `\`${segment}\` (\`${phase}\`)`;
+    return {
+        path,
+        reason: stepKeys.length === 0
+            ? `${named} has no steps at all, so \`${referenced}\` resolves to nothing — no error, an empty value.`
+            : `${named} has no step called \`${referenced}\`. It has: ${stepKeys.map((key) => `\`${key}\``).join(', ')}. ` +
+                'A step key that is not in the phase resolves to nothing — no error, an empty value.',
+        available: stepKeys,
+    };
+}
+/** Whether a position can carry a nested path at all — a validation's cannot. */
+export const nestingAllowed = (position) => ALLOWS_NESTING[position];
+//# sourceMappingURL=references.js.map

package/dist/references.js.map

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

package/dist/shape.d.ts

@@ -0,0 +1,68 @@
+/**
+ * What an author may legally reference at one caret — and nothing else.
+ *
+ * ### Why a shape rather than a list of strings
+ *
+ * Four surfaces answer *"what can this path be"* — completion, hover, diagnostics and the agent tool — and every one
+ * of them needs a different slice of the same answer: completion needs the keys, hover needs the provenance,
+ * diagnostics needs to know a path is absent, and the agent needs the whole thing as data. A list of strings serves
+ * the first and lies to the other three.
+ *
+ * ⛔ **`unknown` carries its reason.** G-8: an alphabet the engine could not enumerate is stated, never silently
+ * empty. The distinction is the whole difference between *"this transformation contributes no fields"* and *"this
+ * transformation is a `SELECT *` and its fields cannot be known from the document"* — the first invites an author to
+ * stop looking, the second tells them where to look. Measured: `SELECT *` is 4.3% of authored SQL (210 of 4,832
+ * blocks), so the unknown case is the exception that must be visible, not the default that can be ignored.
+ */
+export type ShapeKind = 'object' | 'array' | 'scalar' | 'unknown';
+/** Where a field came from, so hover can say it and an author can go read it. */
+export type Provenance = {
+    readonly kind: 'column';
+    readonly table?: string;
+    readonly dataType?: string;
+} | {
+    readonly kind: 'transformation';
+    readonly type: string;
+    readonly index: number;
+} | {
+    readonly kind: 'step';
+    readonly stepKey: string;
+    readonly phase?: string;
+} | {
+    readonly kind: 'hint';
+    readonly declaredOn?: string;
+} | {
+    readonly kind: 'builtin';
+    readonly note?: string;
+};
+export interface Shape {
+    readonly kind: ShapeKind;
+    /** Present on `object`: the fields, by name. */
+    readonly fields?: ReadonlyMap<string, Field>;
+    /** Present on `array`: the shape of one element, so `[0].` resolves. */
+    readonly element?: Shape;
+    /**
+     * Present on `unknown`, ALWAYS — G-8. A shape that cannot say why it is unknown is indistinguishable from a bug in
+     * the engine, and an author reading "unknown" with no reason learns nothing they did not already know.
+     */
+    readonly reason?: string;
+    /** Present on `scalar` where the document declares one: `string`, `number`, `boolean`, `date`… */
+    readonly scalarType?: string;
+}
+export interface Field {
+    readonly name: string;
+    readonly shape: Shape;
+    readonly provenance: Provenance;
+    /** The author-facing prose, where the document carries any — a column description, a step's own docs. */
+    readonly description?: string;
+}
+export declare const objectShape: (fields: Iterable<Field>) => Shape;
+export declare const arrayShape: (element: Shape) => Shape;
+export declare const scalarShape: (scalarType?: string) => Shape;
+/**
+ * ⛔ The reason is REQUIRED by the signature, not by a convention. An optional reason is one a caller forgets, and
+ * the forgetting is invisible: the shape still reads `unknown` and the surface still renders it.
+ */
+export declare const unknownShape: (reason: string) => Shape;
+export declare const field: (name: string, shape: Shape, provenance: Provenance, description?: string) => Field;
+//# sourceMappingURL=shape.d.ts.map

package/dist/shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.d.ts","sourceRoot":"","sources":["../src/shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElE,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAClB;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC7C,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kGAAkG;IAClG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,yGAAyG;IACzG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,WAAW,WAAY,QAAQ,CAAC,KAAK,CAAC,KAAG,KAGpD,CAAC;AAEH,eAAO,MAAM,UAAU,YAAa,KAAK,KAAG,KAG1C,CAAC;AAEH,eAAO,MAAM,WAAW,gBAAiB,MAAM,KAAG,KAGd,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,YAAY,WAAY,MAAM,KAAG,KAG5C,CAAC;AAEH,eAAO,MAAM,KAAK,SACV,MAAM,SACL,KAAK,cACA,UAAU,gBACR,MAAM,KACnB,KAG2C,CAAC"}

package/dist/shape.js

@@ -0,0 +1,23 @@
+export const objectShape = (fields) => ({
+    kind: 'object',
+    fields: new Map([...fields].map((field) => [field.name, field])),
+});
+export const arrayShape = (element) => ({
+    kind: 'array',
+    element,
+});
+export const scalarShape = (scalarType) => scalarType === undefined
+    ? { kind: 'scalar' }
+    : { kind: 'scalar', scalarType };
+/**
+ * ⛔ The reason is REQUIRED by the signature, not by a convention. An optional reason is one a caller forgets, and
+ * the forgetting is invisible: the shape still reads `unknown` and the surface still renders it.
+ */
+export const unknownShape = (reason) => ({
+    kind: 'unknown',
+    reason,
+});
+export const field = (name, shape, provenance, description) => description === undefined
+    ? { name, shape, provenance }
+    : { name, shape, provenance, description };
+//# sourceMappingURL=shape.js.map

package/dist/shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../src/shape.ts"],"names":[],"mappings":"AAyDA,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAuB,EAAS,EAAE,CAAC,CAAC;IAC9D,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;CACjE,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAc,EAAS,EAAE,CAAC,CAAC;IACpD,IAAI,EAAE,OAAO;IACb,OAAO;CACR,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,UAAmB,EAAS,EAAE,CACxD,UAAU,KAAK,SAAS;IACtB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE;IACpB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAc,EAAS,EAAE,CAAC,CAAC;IACtD,IAAI,EAAE,SAAS;IACf,MAAM;CACP,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,IAAY,EACZ,KAAY,EACZ,UAAsB,EACtB,WAAoB,EACb,EAAE,CACT,WAAW,KAAK,SAAS;IACvB,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE;IAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC"}

package/dist/stepOutputs.d.ts

@@ -0,0 +1,52 @@
+import { type Field, type Shape } from './shape.js';
+/**
+ * A step's own outputs are EXACTLY its response-filter keys — `CONTEXT-MODEL.md` §7.
+ *
+ * This is the fact that makes `puller.current.STEP_X.<field>` exact rather than heuristic:
+ * `ResponseFilterEngine.HandleResponse` merges every engine block's parsed output into one flat result, so the step's
+ * output key set is the union of the keys across its four engine blocks — written in the same file, twenty lines
+ * above the caret.
+ *
+ * ⛔ **Engine order is fixed and asymmetric.** Non-scriban engines run first, in declaration order, each merged into
+ * `filters.<engine>.<key>`; **scriban always runs last**. So a scriban expression may read `filters.jsonata.items` —
+ * the corpus does — while a jsonata expression may only read an engine declared before it. Getting this backwards
+ * would offer an author a `filters.*` path that is empty at the moment their expression runs.
+ */
+export declare const ENGINES: readonly ['jsonata', 'jsonpath', 'xpath', 'scriban'];
+export type Engine = (typeof ENGINES)[number];
+/** Scriban last, everything else in declaration order. The ordering rule, as data. */
+export declare function engineOrder(declared: readonly string[]): readonly string[];
+/**
+ * The literal keys of a JSONata object constructor, and whether it yields an array.
+ *
+ * Measured: **34 of 54** authored `Jsonata` blocks (62%) are object constructors with literal keys, and a trailing
+ * `[]` forces an array. So `$.{ "id": id, "order_id": orderId }[]` fully determines
+ * `…PULL_DATA.items[0].order_id` — the path the corpus actually uses.
+ *
+ * ⚠️ Deliberately shallow: it reads the literal keys of ONE constructor, and makes no attempt to evaluate the
+ * expressions behind them. A key whose value is itself a constructor resolves to `unknown` with its reason, which is
+ * the honest answer — the alternative is a parser for a language we do not own.
+ */
+export declare function jsonataShape(expression: string): Shape | undefined;
+export interface StepOutputs {
+    /** The step's own output keys, merged across engines — what `…current.STEP_X.` offers. */
+    readonly shape: Shape;
+    /** `filters.<engine>.<key>`, available only INSIDE a response filter. */
+    readonly filters: Field;
+    /** Keys declared in more than one engine block. Last writer wins, silently — §7. */
+    readonly collisions: readonly {
+        readonly key: string;
+        readonly engines: readonly string[];
+    }[];
+}
+/**
+ * Read one step's `responseFilters` into the shapes four surfaces need.
+ *
+ * ⛔ `collisions` is not a nicety. `results.Merge` is last-writer-wins, so a key declared in two engine blocks
+ * silently loses one of its two values — a diagnostic nobody has today (Story 8.6), and it can only be seen by
+ * comparing the blocks, which is what this does once for everyone.
+ */
+export declare function stepOutputs(step: unknown): StepOutputs;
+/** The response headers, a root available only inside a response filter. */
+export declare const HEADERS_ROOT: Field;
+//# sourceMappingURL=stepOutputs.d.ts.map

package/dist/stepOutputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepOutputs.d.ts","sourceRoot":"","sources":["../src/stepOutputs.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,KAAK,EACV,KAAK,KAAK,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO,YAAI,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAC5E,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAG1E;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CA2BlE;AAED,MAAM,WAAW,WAAW;IAC1B,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,SAAS;QAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;KACrC,EAAE,CAAC;CACL;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CA4EtD;AAED,4EAA4E;AAC5E,eAAO,MAAM,YAAY,OAMxB,CAAC"}

package/dist/stepOutputs.js

@@ -0,0 +1,102 @@
+import { arrayShape, field, objectShape, unknownShape, } from './shape.js';
+/**
+ * A step's own outputs are EXACTLY its response-filter keys — `CONTEXT-MODEL.md` §7.
+ *
+ * This is the fact that makes `puller.current.STEP_X.<field>` exact rather than heuristic:
+ * `ResponseFilterEngine.HandleResponse` merges every engine block's parsed output into one flat result, so the step's
+ * output key set is the union of the keys across its four engine blocks — written in the same file, twenty lines
+ * above the caret.
+ *
+ * ⛔ **Engine order is fixed and asymmetric.** Non-scriban engines run first, in declaration order, each merged into
+ * `filters.<engine>.<key>`; **scriban always runs last**. So a scriban expression may read `filters.jsonata.items` —
+ * the corpus does — while a jsonata expression may only read an engine declared before it. Getting this backwards
+ * would offer an author a `filters.*` path that is empty at the moment their expression runs.
+ */
+export const ENGINES = ['jsonata', 'jsonpath', 'xpath', 'scriban'];
+/** Scriban last, everything else in declaration order. The ordering rule, as data. */
+export function engineOrder(declared) {
+    const nonScriban = declared.filter((engine) => engine !== 'scriban');
+    return declared.includes('scriban') ? [...nonScriban, 'scriban'] : nonScriban;
+}
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * The literal keys of a JSONata object constructor, and whether it yields an array.
+ *
+ * Measured: **34 of 54** authored `Jsonata` blocks (62%) are object constructors with literal keys, and a trailing
+ * `[]` forces an array. So `$.{ "id": id, "order_id": orderId }[]` fully determines
+ * `…PULL_DATA.items[0].order_id` — the path the corpus actually uses.
+ *
+ * ⚠️ Deliberately shallow: it reads the literal keys of ONE constructor, and makes no attempt to evaluate the
+ * expressions behind them. A key whose value is itself a constructor resolves to `unknown` with its reason, which is
+ * the honest answer — the alternative is a parser for a language we do not own.
+ */
+export function jsonataShape(expression) {
+    const open = expression.indexOf('{');
+    if (open === -1)
+        return undefined;
+    const close = expression.lastIndexOf('}');
+    if (close <= open)
+        return undefined;
+    const body = expression.slice(open + 1, close);
+    const keys = [...body.matchAll(/"([^"]+)"\s*:/g)].map((match) => match[1]);
+    if (keys.length === 0)
+        return undefined;
+    const shape = objectShape(keys.map((key) => field(key, unknownShape('A JSONata expression — its key is declared here, its value is computed at run time.'), {
+        kind: 'builtin',
+    })));
+    // A trailing `[]` after the constructor forces an array, which is what gives the path its index.
+    return /\}\s*\[\s*\]\s*;?\s*$/.test(expression.trimEnd())
+        ? arrayShape(shape)
+        : shape;
+}
+/**
+ * Read one step's `responseFilters` into the shapes four surfaces need.
+ *
+ * ⛔ `collisions` is not a nicety. `results.Merge` is last-writer-wins, so a key declared in two engine blocks
+ * silently loses one of its two values — a diagnostic nobody has today (Story 8.6), and it can only be seen by
+ * comparing the blocks, which is what this does once for everyone.
+ */
+export function stepOutputs(step) {
+    const filters = record(record(step)?.['responseFilters']);
+    const declared = Object.keys(filters ?? {}).filter((name) => ENGINES.includes(name));
+    const perEngine = new Map();
+    const owners = new Map();
+    for (const engine of engineOrder(declared)) {
+        const block = record(filters?.[engine]);
+        const keys = new Map();
+        for (const [key, value] of Object.entries(block ?? {})) {
+            const expression = record(value)?.['expression'];
+            const shape = engine === 'jsonata' && typeof expression === 'string'
+                ? (jsonataShape(expression) ??
+                    unknownShape(`\`${key}\` is a JSONata expression that is not an object constructor, so its keys are computed at run time.`))
+                : unknownShape(`\`${key}\` is produced by a ${engine} expression, so its shape is not declared in this document.`);
+            keys.set(key, shape);
+            owners.set(key, [...(owners.get(key) ?? []), engine]);
+        }
+        perEngine.set(engine, keys);
+    }
+    const merged = [];
+    for (const [engine, keys] of perEngine) {
+        for (const [key, shape] of keys) {
+            merged.push(field(key, shape, { kind: 'step', stepKey: key }, `From the ${engine} block.`));
+        }
+    }
+    return {
+        shape: merged.length > 0
+            ? objectShape(merged)
+            : unknownShape('This step declares no response filters, so its output keys are not in this document.'),
+        filters: field('filters', objectShape([...perEngine].map(([engine, keys]) => field(engine, objectShape([...keys].map(([key, shape]) => field(key, shape, { kind: 'step', stepKey: key }))), { kind: 'builtin', note: `The ${engine} block's own results.` }))), {
+            kind: 'builtin',
+            note: 'Available only inside a response filter. Non-scriban engines run first in declaration order; scriban ' +
+                'always runs last, so only scriban can read every other engine.',
+        }),
+        collisions: [...owners]
+            .filter(([, engines]) => engines.length > 1)
+            .map(([key, engines]) => ({ key, engines })),
+    };
+}
+/** The response headers, a root available only inside a response filter. */
+export const HEADERS_ROOT = field('__headers', unknownShape("The response's headers, keyed as the source system returned them."), { kind: 'builtin' });
+//# sourceMappingURL=stepOutputs.js.map

package/dist/stepOutputs.js.map

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

package/dist/survival.d.ts

@@ -0,0 +1,47 @@
+import type { Shape } from './shape.js';
+/**
+ * Fields that will not survive the pull — Story 8.7.
+ *
+ * A puller can produce a field the task has no column for. It is written into the raw payload and it is readable
+ * there, so nothing fails — until someone tries to reference it as a column, or a customer asks why it is missing
+ * from the destination. The author learns this the slow way today.
+ *
+ * ⚠️ The finding is *"this survives only inside the raw payload"*, not *"this is wrong"*. Pulling a field you do not
+ * store is a legitimate choice — it may exist to be read by a transformation in the same run. What is never
+ * legitimate is believing it became a column.
+ */
+export interface SurvivalFinding {
+    readonly field: string;
+    readonly reason: string;
+    /** The fix an editor can offer: the column this field would need. */
+    readonly addColumn?: {
+        readonly table: string;
+        readonly name: string;
+        readonly dataType: string;
+    };
+}
+/**
+ * Compare what a puller produces against the columns its task declares.
+ *
+ * `produced` is the union of the puller's step output keys — Story 8.3 derives it — and `columns` is what
+ * `tables[*].columns` declares. A produced key with no column survives only in `__raw`.
+ */
+export declare function fieldsThatWillNotSurvive(input: {
+    readonly produced: readonly string[];
+    readonly columns: readonly string[];
+    readonly table?: string;
+}): readonly SurvivalFinding[];
+/**
+ * A validation naming a field that is HINTED rather than declared — Story 8.7 AC-3.
+ *
+ * ⛔ A validation cannot address a non-column at all. `BuildConditionsAsync` interpolates the field name directly
+ * into SQL against the task's table, so a hinted field produces a query naming a column that does not exist; and
+ * `ValidateAsync` does a flat `TryGetValue`, which reports *"the field is missing from the item"*. Two halves, two
+ * different failures, neither of them a message that points at the real cause.
+ */
+export declare function validationAgainstNonColumn(input: {
+    readonly fieldName: string;
+    readonly columns: readonly string[];
+    readonly item?: Shape;
+}): SurvivalFinding | undefined;
+//# sourceMappingURL=survival.d.ts.map

package/dist/survival.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"survival.d.ts","sourceRoot":"","sources":["../src/survival.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,SAAS,eAAe,EAAE,CAiB7B;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;CACvB,GAAG,eAAe,GAAG,SAAS,CAsB9B"}

package/dist/survival.js

@@ -0,0 +1,50 @@
+/**
+ * Compare what a puller produces against the columns its task declares.
+ *
+ * `produced` is the union of the puller's step output keys — Story 8.3 derives it — and `columns` is what
+ * `tables[*].columns` declares. A produced key with no column survives only in `__raw`.
+ */
+export function fieldsThatWillNotSurvive(input) {
+    const declared = new Set(input.columns);
+    return (input.produced
+        // ⛔ A `__`-prefixed key is the platform's own — `__raw`, `__headers`, `__last_seen`. Reporting those would fire
+        // on every puller in the corpus and teach an author to ignore the whole class.
+        .filter((name) => !declared.has(name) && !name.startsWith('__'))
+        .map((name) => ({
+        field: name,
+        reason: `\`${name}\` is pulled but has no column on this task, so it survives only inside the raw payload. A ` +
+            'transformation in the same run can read it; a validation cannot, and it will never reach the destination.',
+        ...(input.table === undefined
+            ? {}
+            : { addColumn: { table: input.table, name, dataType: 'text' } }),
+    })));
+}
+/**
+ * A validation naming a field that is HINTED rather than declared — Story 8.7 AC-3.
+ *
+ * ⛔ A validation cannot address a non-column at all. `BuildConditionsAsync` interpolates the field name directly
+ * into SQL against the task's table, so a hinted field produces a query naming a column that does not exist; and
+ * `ValidateAsync` does a flat `TryGetValue`, which reports *"the field is missing from the item"*. Two halves, two
+ * different failures, neither of them a message that points at the real cause.
+ */
+export function validationAgainstNonColumn(input) {
+    if (input.columns.includes(input.fieldName))
+        return undefined;
+    const known = input.item?.kind === 'object'
+        ? input.item.fields?.get(input.fieldName)
+        : undefined;
+    if (!known)
+        return undefined; // Not a column and not on the item either — Story 8.6's rule owns that case.
+    const source = known.provenance.kind === 'hint'
+        ? 'declared as a data hint'
+        : known.provenance.kind === 'transformation'
+            ? `produced by the ${known.provenance.type} transformation at index ${known.provenance.index}`
+            : 'not a column';
+    return {
+        field: input.fieldName,
+        reason: `\`${input.fieldName}\` is ${source}, not a column on this task. A validation's field is interpolated ` +
+            'directly into SQL against the table, so this names a column that does not exist — and the item lookup is ' +
+            'flat, so it reports "the field is missing" rather than pointing here.',
+    };
+}
+//# sourceMappingURL=survival.js.map

package/dist/survival.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"survival.js","sourceRoot":"","sources":["../src/survival.ts"],"names":[],"mappings":"AAwBA;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAIxC;IACC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,CACL,KAAK,CAAC,QAAQ;QACZ,gHAAgH;QAChH,+EAA+E;SAC9E,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;SAC/D,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACd,KAAK,EAAE,IAAI;QACX,MAAM,EACJ,KAAK,IAAI,6FAA6F;YACtG,2GAA2G;QAC7G,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS;YAC3B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;KACnE,CAAC,CAAC,CACN,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAI1C;IACC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IAE9D,MAAM,KAAK,GACT,KAAK,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ;QAC3B,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC;QACzC,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC,CAAC,6EAA6E;IAE3G,MAAM,MAAM,GACV,KAAK,CAAC,UAAU,CAAC,IAAI,KAAK,MAAM;QAC9B,CAAC,CAAC,yBAAyB;QAC3B,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,KAAK,gBAAgB;YAC1C,CAAC,CAAC,mBAAmB,KAAK,CAAC,UAAU,CAAC,IAAI,4BAA4B,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE;YAC9F,CAAC,CAAC,cAAc,CAAC;IACvB,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,SAAS;QACtB,MAAM,EACJ,KAAK,KAAK,CAAC,SAAS,SAAS,MAAM,oEAAoE;YACvG,2GAA2G;YAC3G,uEAAuE;KAC1E,CAAC;AACJ,CAAC"}