@beehexa/hexasync-template-context 2608.20.18 → 2608.20.32

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,60 @@
+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.
+ *
+ * ⛔ 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 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;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE9D;AAyCD,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,aAAc,QAAQ,KAAG,OAC1B,CAAC"}