@beehexa/hexasync-template-context 2608.15.1

package/dist/item.d.ts

@@ -0,0 +1,87 @@
+import { type Field, type Shape } from './shape.js';
+/**
+ * The item, in three labelled layers — `CONTEXT-MODEL.md` §4.1.
+ *
+ * ```
+ * row → BuildResolvedOriginalAsync → ItemTransformerIterator.Transform → item
+ *       = { ...decode(__raw), ...columns }   = ordered transformation pipeline
+ *         columns WIN
+ * ```
+ *
+ * | layer | declared where | static knowledge |
+ * | --- | --- | --- |
+ * | 1. columns | `tables[*].columns` | **complete**, with types and prose for free |
+ * | 2. decoded `__raw` | nowhere — it is the source system's payload | **none**; this is the hole `dataHints` fills |
+ * | 3. transformations | `transformations[taskId][]`, ordered by `index` | **derivable** |
+ *
+ * The labelling is the feature. An author looking at a flat list cannot tell a column they may validate against from
+ * a `tf_*` field that exists only at push time — and a validation referencing the second one fails at run time with
+ * "the field is missing from the item".
+ */
+/**
+ * The system columns, always present, in their own group.
+ *
+ * Measured against the corpus on 2026-08-14: `item.__destination_id` **4,659 uses** — far ahead of every business
+ * field — then `__hashed_keys` 309, `__id` 102, `__status` 41, `__source_id` 36. An author references these
+ * constantly and no `tables[*].columns` block declares them, so a list built from the document alone would omit the
+ * single most-used path in the corpus.
+ */
+export declare const SYSTEM_COLUMNS: readonly Field[];
+export interface ColumnFacts {
+    readonly name: string;
+    readonly dataType?: string;
+    readonly description?: string;
+    readonly table?: string;
+}
+export interface TransformationFacts {
+    readonly index: number;
+    readonly type: string;
+    /** `$.metadata` — ⚠️ NOT `data`, which is what every step type uses. */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * The aliases of a SQL select list, or `undefined` where it selects everything.
+ *
+ * Measured: 4,832 authored `sql:` blocks, **210** containing `SELECT *` (4.3%), and 18,339 `AS <alias>`
+ * occurrences. So the honest statement is the inverse of the intuition — **95.7% of authored SQL names its output
+ * fields**, and `SELECT *` is the visible exception rather than a reason to give up on the whole layer.
+ */
+export declare function selectAliases(sql: string): readonly string[] | undefined;
+/**
+ * Whether a transformation REPLACES the whole item rather than merging into it — §5.1.
+ *
+ * `SQL.is_replacement`, `QUERY_SINGLE.isReplacement` and `RESOLVE_RAW_DATA.replace` reset the environment, and a
+ * `true` here invalidates every path an earlier transformation established. Propagating past one of these as though
+ * it merged is how completion offers a field that no longer exists by the time the author's expression runs.
+ */
+export declare function isReplacement(transformation: TransformationFacts): boolean;
+/** Apply one transformation to the accumulated fields. Exported so a diagnostic can ask what a step discarded. */
+export declare function applyTransformation(fields: Map<string, Field>, transformation: TransformationFacts): {
+    readonly fields: Map<string, Field>;
+    readonly reset: boolean;
+    readonly unknownReason?: string;
+};
+export interface ItemRequest {
+    readonly columns?: readonly ColumnFacts[];
+    readonly transformations?: readonly TransformationFacts[];
+    /** Everything at an index STRICTLY BELOW this has run; the caret is inside the transformation at this index. */
+    readonly upToIndex?: number;
+    /** A task's declared payload shape (Story 8.8), filling the layer the document otherwise cannot describe. */
+    readonly hints?: Shape;
+}
+export interface ResolvedItem {
+    readonly shape: Shape;
+    /** Stated where a transformation could not be enumerated — never silently dropped. */
+    readonly unknownReasons: readonly string[];
+    /** Fields an earlier transformation established and a replacement discarded — Story 8.6 reports references to them. */
+    readonly discarded: readonly string[];
+}
+/**
+ * Build the item as it stands at one point in the pipeline.
+ *
+ * ⛔ **The alphabet inside transformation *i* is the key set after *i−1*.** `ItemTransformerIterator.Transform` runs
+ * the pipeline ordered by `index`, so a field produced at index 5 does not exist inside the transformation at index
+ * 3 — offering it there is offering a path that resolves to nothing.
+ */
+export declare function resolveItem(request: ItemRequest): ResolvedItem;
+//# sourceMappingURL=item.d.ts.map

package/dist/item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item.d.ts","sourceRoot":"","sources":["../src/item.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,KAAK,EACV,KAAK,KAAK,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,KAAK,EA+B1C,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAKD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAMxE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,mBAAmB,GAAG,OAAO,CAO1E;AAED,kHAAkH;AAClH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,EAC1B,cAAc,EAAE,mBAAmB,GAClC;IACD,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,CAgIA;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1D,gHAAgH;IAChH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,6GAA6G;IAC7G,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,sFAAsF;IACtF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,uHAAuH;IACvH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,YAAY,CAqD9D"}

package/dist/item.js

@@ -0,0 +1,222 @@
+import { arrayShape, field, objectShape, scalarShape, unknownShape, } from './shape.js';
+/**
+ * The item, in three labelled layers — `CONTEXT-MODEL.md` §4.1.
+ *
+ * ```
+ * row → BuildResolvedOriginalAsync → ItemTransformerIterator.Transform → item
+ *       = { ...decode(__raw), ...columns }   = ordered transformation pipeline
+ *         columns WIN
+ * ```
+ *
+ * | layer | declared where | static knowledge |
+ * | --- | --- | --- |
+ * | 1. columns | `tables[*].columns` | **complete**, with types and prose for free |
+ * | 2. decoded `__raw` | nowhere — it is the source system's payload | **none**; this is the hole `dataHints` fills |
+ * | 3. transformations | `transformations[taskId][]`, ordered by `index` | **derivable** |
+ *
+ * The labelling is the feature. An author looking at a flat list cannot tell a column they may validate against from
+ * a `tf_*` field that exists only at push time — and a validation referencing the second one fails at run time with
+ * "the field is missing from the item".
+ */
+/**
+ * The system columns, always present, in their own group.
+ *
+ * Measured against the corpus on 2026-08-14: `item.__destination_id` **4,659 uses** — far ahead of every business
+ * field — then `__hashed_keys` 309, `__id` 102, `__status` 41, `__source_id` 36. An author references these
+ * constantly and no `tables[*].columns` block declares them, so a list built from the document alone would omit the
+ * single most-used path in the corpus.
+ */
+export const SYSTEM_COLUMNS = [
+    field('__destination_id', scalarShape('string'), { kind: 'builtin' }, 'The id this item has in the DESTINATION system. Empty until the item has been pushed once.'),
+    field('__id', scalarShape('string'), { kind: 'builtin' }, "HexaSync's own id for this item."),
+    field('__source_id', scalarShape('string'), { kind: 'builtin' }, 'The id this item has in the SOURCE system.'),
+    field('__status', scalarShape('string'), { kind: 'builtin' }, "The item's sync status."),
+    field('__hashed_keys', scalarShape('string'), { kind: 'builtin' }, 'The hash used to detect a change since the last pull.'),
+];
+const asString = (value) => typeof value === 'string' && value !== '' ? value : undefined;
+/**
+ * The aliases of a SQL select list, or `undefined` where it selects everything.
+ *
+ * Measured: 4,832 authored `sql:` blocks, **210** containing `SELECT *` (4.3%), and 18,339 `AS <alias>`
+ * occurrences. So the honest statement is the inverse of the intuition — **95.7% of authored SQL names its output
+ * fields**, and `SELECT *` is the visible exception rather than a reason to give up on the whole layer.
+ */
+export function selectAliases(sql) {
+    if (/select\s+\*/i.test(sql))
+        return undefined;
+    const aliases = [...sql.matchAll(/\bas\s+"?([A-Za-z_][\w]*)"?/gi)].map((match) => match[1]);
+    return aliases.length > 0 ? aliases : undefined;
+}
+/**
+ * Whether a transformation REPLACES the whole item rather than merging into it — §5.1.
+ *
+ * `SQL.is_replacement`, `QUERY_SINGLE.isReplacement` and `RESOLVE_RAW_DATA.replace` reset the environment, and a
+ * `true` here invalidates every path an earlier transformation established. Propagating past one of these as though
+ * it merged is how completion offers a field that no longer exists by the time the author's expression runs.
+ */
+export function isReplacement(transformation) {
+    const metadata = transformation.metadata ?? {};
+    return (metadata['is_replacement'] === true ||
+        metadata['isReplacement'] === true ||
+        metadata['replace'] === true);
+}
+/** Apply one transformation to the accumulated fields. Exported so a diagnostic can ask what a step discarded. */
+export function applyTransformation(fields, transformation) {
+    const metadata = transformation.metadata ?? {};
+    const provenance = {
+        kind: 'transformation',
+        type: transformation.type,
+        index: transformation.index,
+    };
+    const next = isReplacement(transformation)
+        ? new Map()
+        : new Map(fields);
+    const reset = isReplacement(transformation);
+    const add = (name, shape = unknownShape(`Produced by the ${transformation.type} transformation at index ${transformation.index}.`)) => next.set(name, field(name, shape, provenance));
+    switch (transformation.type) {
+        case 'Rename': {
+            const from = asString(metadata['old_name']);
+            const to = asString(metadata['new_name']);
+            if (from && to) {
+                const existing = next.get(from);
+                next.delete(from);
+                add(to, existing?.shape);
+            }
+            break;
+        }
+        case 'BulkRename': {
+            const map = metadata['renames'] ?? metadata['fields'];
+            for (const [from, to] of Object.entries(map ?? {})) {
+                const target = asString(to);
+                if (!target)
+                    continue;
+                const existing = next.get(from);
+                next.delete(from);
+                add(target, existing?.shape);
+            }
+            break;
+        }
+        case 'Clone':
+        case 'BulkClone': {
+            const from = asString(metadata['field_name']);
+            const targets = Array.isArray(metadata['new_names'])
+                ? metadata['new_names']
+                : [];
+            for (const target of targets) {
+                const name = asString(target);
+                if (name)
+                    add(name, from ? next.get(from)?.shape : undefined);
+            }
+            break;
+        }
+        case 'Scriban': {
+            // The key is exact; the value is text, and opaque.
+            const name = asString(metadata['field_name']);
+            if (name)
+                add(name, scalarShape('string'));
+            break;
+        }
+        case 'Jsonata': {
+            const name = asString(metadata['field_name']);
+            if (name)
+                add(name);
+            break;
+        }
+        case 'Nested_SQL':
+        case 'QUERY_MANY': {
+            const name = asString(metadata['field_name']) ?? asString(metadata['fieldName']);
+            const sql = asString(metadata['sql']);
+            const aliases = sql ? selectAliases(sql) : undefined;
+            if (name) {
+                add(name, arrayShape(aliases
+                    ? objectShape(aliases.map((alias) => field(alias, unknownShape('A selected column.'), provenance)))
+                    : unknownShape('The select list does not name its columns, so the element shape is not in this document.')));
+            }
+            break;
+        }
+        case 'SQL':
+        case 'QUERY_SINGLE': {
+            const sql = asString(metadata['sql']);
+            const aliases = sql ? selectAliases(sql) : undefined;
+            if (aliases) {
+                for (const alias of aliases)
+                    add(alias);
+            }
+            else {
+                /**
+                 * ⛔ `SELECT *` contributes an EXPLICITLY UNKNOWN key set, stated with its reason — G-8, and Story 8.4's own
+                 * AC. Treating it as "no keys" would tell an author their transformation contributes nothing, when what is
+                 * true is that the document does not say what it contributes.
+                 */
+                return {
+                    fields: next,
+                    reset,
+                    unknownReason: `The ${transformation.type} transformation at index ${transformation.index} selects every column, so the ` +
+                        'fields it contributes are not in this document. Name them with `AS` aliases, or declare them as data hints.',
+                };
+            }
+            break;
+        }
+        case 'RESOLVE_RAW_DATA': {
+            const name = asString(metadata['fieldName']) ?? asString(metadata['field_name']);
+            const shape = unknownShape('The decoded raw payload. Its shape comes from the source system, so declare it as data hints to complete against it.');
+            if (name)
+                add(name, shape);
+            break;
+        }
+        default:
+            break;
+    }
+    return { fields: next, reset };
+}
+/**
+ * Build the item as it stands at one point in the pipeline.
+ *
+ * ⛔ **The alphabet inside transformation *i* is the key set after *i−1*.** `ItemTransformerIterator.Transform` runs
+ * the pipeline ordered by `index`, so a field produced at index 5 does not exist inside the transformation at index
+ * 3 — offering it there is offering a path that resolves to nothing.
+ */
+export function resolveItem(request) {
+    const fields = new Map();
+    // Layer 2 first, then layer 1 — COLUMNS WIN, matching `BuildResolvedOriginalAsync`'s own precedence.
+    if (request.hints?.kind === 'object' && request.hints.fields) {
+        for (const [name, each] of request.hints.fields)
+            fields.set(name, each);
+    }
+    for (const column of request.columns ?? []) {
+        fields.set(column.name, field(column.name, scalarShape(column.dataType), {
+            kind: 'column',
+            ...(column.table === undefined ? {} : { table: column.table }),
+            ...(column.dataType === undefined
+                ? {}
+                : { dataType: column.dataType }),
+        }, column.description));
+    }
+    for (const system of SYSTEM_COLUMNS)
+        fields.set(system.name, system);
+    const unknownReasons = [];
+    const discarded = new Set();
+    const ordered = [...(request.transformations ?? [])].sort((a, b) => a.index - b.index);
+    for (const transformation of ordered) {
+        if (request.upToIndex !== undefined &&
+            transformation.index >= request.upToIndex)
+            break;
+        const before = new Set(fields.keys());
+        const result = applyTransformation(fields, transformation);
+        if (result.unknownReason)
+            unknownReasons.push(result.unknownReason);
+        if (result.reset)
+            for (const name of before)
+                if (!result.fields.has(name))
+                    discarded.add(name);
+        fields.clear();
+        for (const [name, each] of result.fields)
+            fields.set(name, each);
+    }
+    return {
+        shape: objectShape(fields.values()),
+        unknownReasons,
+        discarded: [...discarded],
+    };
+}
+//# sourceMappingURL=item.js.map

package/dist/item.js.map

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

package/dist/position.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The five authoring positions, which are five different alphabets — not one context with local variations.
+ *
+ * From `CONTEXT-MODEL.md` §1, verified against the executing code on 2026-08-09:
+ *
+ * | position | roots | nesting |
+ * | --- | --- | --- |
+ * | `legacy-puller-step` | `puller.*`, `env`, `_outputs`, `__this`, `runStart`, `filters.*`, `__headers` | yes |
+ * | `new-kind-puller-step` | `_inputs`, `_outputs`, `__this`, `_env`, `_history`, `runStart` — **no `puller.*`** | yes |
+ * | `pusher-step` | `item`, `task`, `dependencies`, `pusher.*`, `env`, `_outputs`, `__this`, `runStart` | yes |
+ * | `transformation-expression` | the item's fields **bare** — no `item.` prefix | yes |
+ * | `validation-field` | task **columns** only | **no** |
+ *
+ * ⛔ Positions 3 and 4 are the dangerous pair: `{{ item.sku }}` is right in a pusher step and **silently wrong** in a
+ * transformation, where the context object IS the item and the path is `{{ sku }}`. Position 5 looks like 4 and
+ * rejects both nesting and every transformation-produced field. Nothing in the editor tells an author which one they
+ * are in today, which is the whole reason this engine exists.
+ *
+ * The two puller kinds share NO context root. Copying a step between them carries paths that resolve to nothing — no
+ * error, no diagnostic, an empty string in a URL. So the kind must be resolved BEFORE a single root is offered, and
+ * it is decided by one thing: a non-empty `steps` array (`PullStepAccessor.IsNewKind`).
+ */
+export type Position = 'legacy-puller-step' | 'new-kind-puller-step' | 'pusher-step' | 'transformation-expression' | 'validation-field';
+/** Every position, in the order `CONTEXT-MODEL.md` numbers them — the order every surface should list them in. */
+export declare const POSITIONS: readonly Position[];
+/** What to call a position in a sentence an author reads. */
+export declare const POSITION_LABEL: Readonly<Record<Position, string>>;
+/**
+ * Whether the position allows a nested path at all.
+ *
+ * ⚠️ `validation-field` does not, and it is the one case where offering a nested path is worse than offering nothing:
+ * the value is interpolated into SQL, so `item.address.city` is not "unresolved", it is a column name that does not
+ * exist and a query that fails at run time.
+ */
+export declare const ALLOWS_NESTING: Readonly<Record<Position, boolean>>;
+//# sourceMappingURL=position.d.ts.map

package/dist/position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../src/position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,QAAQ,GAChB,oBAAoB,GACpB,sBAAsB,GACtB,aAAa,GACb,2BAA2B,GAC3B,kBAAkB,CAAC;AAEvB,kHAAkH;AAClH,eAAO,MAAM,SAAS,EAAE,SAAS,QAAQ,EAMxC,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAM7D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAM9D,CAAC"}

package/dist/position.js

@@ -0,0 +1,31 @@
+/** Every position, in the order `CONTEXT-MODEL.md` numbers them — the order every surface should list them in. */
+export const POSITIONS = [
+    'legacy-puller-step',
+    'new-kind-puller-step',
+    'pusher-step',
+    'transformation-expression',
+    'validation-field',
+];
+/** What to call a position in a sentence an author reads. */
+export const POSITION_LABEL = {
+    'legacy-puller-step': 'a legacy puller step',
+    'new-kind-puller-step': 'a new-kind puller step',
+    'pusher-step': 'a pusher step',
+    'transformation-expression': 'a transformation expression',
+    'validation-field': "a validation's field",
+};
+/**
+ * Whether the position allows a nested path at all.
+ *
+ * ⚠️ `validation-field` does not, and it is the one case where offering a nested path is worse than offering nothing:
+ * the value is interpolated into SQL, so `item.address.city` is not "unresolved", it is a column name that does not
+ * exist and a query that fails at run time.
+ */
+export const ALLOWS_NESTING = {
+    'legacy-puller-step': true,
+    'new-kind-puller-step': true,
+    'pusher-step': true,
+    'transformation-expression': true,
+    'validation-field': false,
+};
+//# sourceMappingURL=position.js.map

package/dist/position.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"position.js","sourceRoot":"","sources":["../src/position.ts"],"names":[],"mappings":"AA6BA,kHAAkH;AAClH,MAAM,CAAC,MAAM,SAAS,GAAwB;IAC5C,oBAAoB;IACpB,sBAAsB;IACtB,aAAa;IACb,2BAA2B;IAC3B,kBAAkB;CACnB,CAAC;AAEF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,cAAc,GAAuC;IAChE,oBAAoB,EAAE,sBAAsB;IAC5C,sBAAsB,EAAE,wBAAwB;IAChD,aAAa,EAAE,eAAe;IAC9B,2BAA2B,EAAE,6BAA6B;IAC1D,kBAAkB,EAAE,sBAAsB;CAC3C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwC;IACjE,oBAAoB,EAAE,IAAI;IAC1B,sBAAsB,EAAE,IAAI;IAC5B,aAAa,EAAE,IAAI;IACnB,2BAA2B,EAAE,IAAI;IACjC,kBAAkB,EAAE,KAAK;CAC1B,CAAC"}

package/dist/references.d.ts

@@ -0,0 +1,49 @@
+import { type Position } from './position.js';
+import type { Environment } from './environment.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 declare const KNOWN_INERT: Readonly<Record<string, string>>;
+export interface ReferenceFinding {
+    readonly path: string;
+    readonly reason: string;
+    /** The roots this position actually has, so the message can name them rather than only refusing. */
+    readonly available: readonly string[];
+}
+/** Pull every `$( )`, `$$( )` and `{{ }}` payload out of one authored value. */
+export declare function expressionsIn(value: string): readonly string[];
+/** The dotted paths inside one expression payload. */
+export declare function pathsIn(expression: string): readonly string[];
+/**
+ * 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 declare function checkPath(path: string, environment: Environment): ReferenceFinding | 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 declare const SEGMENT_PHASE: Readonly<Record<string, string>>;
+export declare function unknownStepKey(path: string, keysByPhase: Readonly<Record<string, readonly string[]>>): ReferenceFinding | undefined;
+/** Whether a position can carry a nested path at all — a validation's cannot. */
+export declare const nestingAllowed: (position: Position) => boolean;
+//# sourceMappingURL=references.d.ts.map

package/dist/references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGxD,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oGAAoG;IACpG,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAK9D;AAED,sDAAsD;AACtD,wBAAgB,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAI7D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,WAAW,GACvB,gBAAgB,GAAG,SAAS,CA+B9B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO1D,CAAC;AAyCF,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,GACvD,gBAAgB,GAAG,SAAS,CA6C9B;AAED,iFAAiF;AACjF,eAAO,MAAM,cAAc,GAAI,UAAU,QAAQ,KAAG,OAC1B,CAAC"}

package/dist/references.js

@@ -0,0 +1,171 @@
+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. */
+export function expressionsIn(value) {
+    return [
+        ...[...value.matchAll(/\{\{([\s\S]*?)\}\}/g)].map((match) => match[1]),
+        ...[...value.matchAll(/\$\$?\(([\s\S]*?)\)/g)].map((match) => match[1]),
+    ];
+}
+/** 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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"}