@beehexa/hexasync-template-context 2608.20.18 → 2608.20.32

package/dist/completion.d.ts

@@ -0,0 +1,80 @@
+import type { Environment } from './environment.js';
+/**
+ * One offer, as any surface can render it — a completion item in the editor, a line in a CLI answer, an entry in the
+ * agent's environment. It carries no editor type, which is what lets all four read it.
+ */
+export interface Offer {
+    readonly label: string;
+    /** What to insert. Differs from the label when accepting has to finish a thought (Story 8.5). */
+    readonly insert: string;
+    readonly detail: string;
+    readonly documentation?: string;
+    /**
+     * A correction that outranks every plain offer.
+     *
+     * ⛔ Story 8.2 AC-4: an author who types `item.` inside a transformation has made the single most common mistake
+     * this engine exists to catch, and the honest response is not an empty list — an empty list reads as "there is
+     * nothing here", which is the opposite of true. The bare fields are offered AND the prefix removal is offered
+     * above them.
+     */
+    readonly fix?: {
+        readonly removePrefix: string;
+        readonly why: string;
+    };
+    /**
+     * A second field this choice determines — Story 8.5 AC-1.
+     *
+     * ⛔ Accepting a validation's `fieldName` determines its `dataType`: the column already declares one, and
+     * `metadata.dataType` selects the SQL form (`DateTime` → `hexasync_datetime_equal(…)`). Leaving the author to
+     * remember it is leaving them to get it wrong in a way that only shows up as a validation that quietly never
+     * matches.
+     */
+    readonly coFill?: {
+        readonly field: string;
+        readonly value: string;
+    };
+    /** True where `insert` is a whole expression rather than a bare path — see `wrapFor`. */
+    readonly wrapped?: boolean;
+}
+/**
+ * The dialect wrapper a position requires — Story 8.5 AC-2.
+ *
+ * The three dialects are not interchangeable: `$( )` JSONata and `$$( )` JSONPath return STRUCTURE, `{{ }}` Scriban
+ * returns TEXT. Inserting a bare `item.lines` where the field needs a structured value produces the string
+ * "item.lines", which is the failure mode this fills in against.
+ */
+export type Dialect = 'scriban' | 'jsonata' | 'jsonpath' | 'none';
+export declare function wrapFor(dialect: Dialect, path: string): string;
+/** What a surface says about where the caret is. Story 8.2 AC-6 — the position is stated, never guessed at. */
+export declare const positionBanner: (environment: Environment) => string;
+/**
+ * The offers at one caret, given what the author has typed so far.
+ *
+ * `typed` is the text before the caret on this expression — `''` at a fresh caret, `'item.'` for the mistake AC-4
+ * names, `'puller.current.'` for a nested walk.
+ */
+export interface OfferOptions {
+    /** Wrap the inserted path for this dialect, where the position needs a whole expression, not a fragment. */
+    readonly dialect?: Dialect;
+    /** More candidates than a list should carry — escalate through the surface's existing picker (AC-4). */
+    readonly listCeiling?: number;
+}
+/** The sentinel every surface already uses to escalate a long list into its picker. Not a second mechanism. */
+export declare const MORE_SENTINEL = "__hexasync_more__";
+export declare function offersFor(environment: Environment, typed?: string, options?: OfferOptions): readonly Offer[];
+/**
+ * The trailing run of path characters, scanned BACKWARDS from the end.
+ *
+ * ⛔ This was `/([\w.[\]]*)$/.exec(trimmed)`, and CodeQL was right (`js/polynomial-redos`, High). With `$`
+ * anchored and `*` unbounded, the engine retries the class from every position in the string, so a value of N
+ * dots costs O(N²) — and this runs on the line under the caret on every keystroke, which is the worst place in
+ * the extension to put a quadratic.
+ *
+ * A backward scan is what the regex was describing anyway: the longest suffix made only of word characters,
+ * `.`, `[` and `]`. One pass, no backtracking, byte-identical result for every input.
+ *
+ * Exported for `__tests__/redos.spec.ts`, which pins both halves: the same answer the regex gave, and a bound
+ * on the time it takes.
+ */
+export declare function trailingPathToken(text: string): string;
+//# sourceMappingURL=completion.d.ts.map

package/dist/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,yFAAyF;IACzF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAElE,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAW9D;AAED,+GAA+G;AAC/G,eAAO,MAAM,cAAc,gBAAiB,WAAW,KAAG,MACO,CAAC;AAiClE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,4GAA4G;IAC5G,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,wGAAwG;IACxG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,+GAA+G;AAC/G,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAEjD,wBAAgB,SAAS,CACvB,WAAW,EAAE,WAAW,EACxB,KAAK,SAAK,EACV,OAAO,GAAE,YAAiB,GACzB,SAAS,KAAK,EAAE,CAuHlB;AA0CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAItD"}

package/dist/completion.js

@@ -0,0 +1,202 @@
+import { ALLOWS_NESTING, POSITION_LABEL } from './position.js';
+export function wrapFor(dialect, path) {
+    switch (dialect) {
+        case 'scriban':
+            return `{{ ${path} }}`;
+        case 'jsonata':
+            return `$( ${path} )`;
+        case 'jsonpath':
+            return `$$( ${path} )`;
+        default:
+            return path;
+    }
+}
+/** What a surface says about where the caret is. Story 8.2 AC-6 — the position is stated, never guessed at. */
+export const positionBanner = (environment) => `${POSITION_LABEL[environment.position]} — ${environment.note}`;
+const offerFor = (field, insert) => ({
+    label: field.name,
+    insert: insert ?? field.name,
+    detail: detailOf(field),
+    ...(field.description === undefined
+        ? {}
+        : { documentation: field.description }),
+});
+function detailOf(field) {
+    const shape = field.shape;
+    const kind = shape.kind === 'scalar'
+        ? (shape.scalarType ?? 'scalar')
+        : shape.kind === 'unknown'
+            ? 'unknown'
+            : shape.kind;
+    switch (field.provenance.kind) {
+        case 'column':
+            return `${kind} · column${field.provenance.dataType ? ` (${field.provenance.dataType})` : ''}`;
+        case 'transformation':
+            return `${kind} · from ${field.provenance.type} at index ${field.provenance.index}`;
+        case 'step':
+            return `${kind} · output of ${field.provenance.stepKey}`;
+        case 'hint':
+            return `${kind} · declared hint`;
+        default:
+            return `${kind} · built in`;
+    }
+}
+/** The sentinel every surface already uses to escalate a long list into its picker. Not a second mechanism. */
+export const MORE_SENTINEL = '__hexasync_more__';
+export function offersFor(environment, typed = '', options = {}) {
+    const trimmed = typed.trim();
+    /**
+     * ⛔ The `item.` correction. In a transformation the context object IS the item, so `item.sku` resolves to nothing
+     * — silently, at run time, in a value that ends up empty. It is right one position away, in a pusher step, which
+     * is why authors write it here.
+     */
+    if (environment.position === 'transformation-expression' &&
+        /(^|[^\w.])item\.$/.test(trimmed)) {
+        const bare = [...environment.roots.values()]
+            .filter((field) => field.name !== '__this')
+            .map((field) => offerFor(field));
+        return [
+            {
+                label: 'Remove the `item.` prefix',
+                insert: '',
+                detail: 'the context object IS the item here',
+                documentation: 'A transformation expression is evaluated with the item as its context, so its fields are referenced ' +
+                    'bare — `sku`, not `item.sku`. The prefixed form resolves to nothing at run time, with no error.',
+                fix: {
+                    removePrefix: 'item.',
+                    why: 'A transformation is evaluated with the item as its context.',
+                },
+            },
+            ...bare,
+        ];
+    }
+    /**
+     * ⛔ The trailing PATH TOKEN, not the whole expression.
+     *
+     * `{{ puller.current.` splits on `.` into `['{{ puller', 'current', '']`, and `{{ puller` is a root that exists
+     * nowhere — so every nested walk inside a real template returned an empty list while the unit fixtures, which pass
+     * bare paths, all passed. The dialect opener and any preceding text are not part of the path.
+     */
+    const token = trailingPathToken(trimmed);
+    const segments = token.split('.').filter((segment) => segment !== '');
+    // A path is walked only where the position allows nesting. ⚠️ A validation's field is interpolated into SQL, so a
+    // nested path there is a column name that does not exist, not a deeper lookup.
+    if (segments.length === 0 || !ALLOWS_NESTING[environment.position]) {
+        return finish([...environment.roots.values()].map((field) => offerFor(field)), environment, options);
+    }
+    /**
+     * ⛔ A segment may carry an index — `lines[0]` — and the index is not part of the field's NAME.
+     *
+     * The first version looked up a field literally called `lines[0]`, found nothing, and returned an empty list for
+     * the exact path this engine had just told the author to insert: Story 8.4 makes an array offer insert its index
+     * precisely so the next completion resolves the element. Offering a path and then failing to walk it is worse than
+     * not offering it.
+     */
+    const step = (shape, segment) => {
+        const match = /^([^[\]]+)((?:\[\d*\])*)$/.exec(segment);
+        if (!match)
+            return undefined;
+        let next = shape?.fields?.get(match[1])?.shape;
+        // One `element` hop per `[…]` written, so `matrix[0][0]` resolves as far as the shape actually goes.
+        for (let index = 0; index < (match[2]?.match(/\[/g)?.length ?? 0); index += 1) {
+            next = next?.kind === 'array' ? next.element : undefined;
+        }
+        return next;
+    };
+    const first = /^([^[\]]+)/.exec(segments[0])?.[1] ?? segments[0];
+    let shape = environment.roots.get(first)?.shape;
+    for (let index = 0; index < (segments[0].match(/\[/g)?.length ?? 0); index += 1) {
+        shape = shape?.kind === 'array' ? shape.element : undefined;
+    }
+    /**
+     * ⛔ AC-3 — an already-complete path RE-OPENS at its own level.
+     *
+     * An author who has typed `item.sku` and asks again is asking *"what else is here"*, not *"is this valid"*. The
+     * walk therefore remembers the last level that had fields: landing on a scalar offers its SIBLINGS rather than the
+     * empty list a leaf would otherwise produce.
+     */
+    let parent;
+    for (const segment of segments.slice(1)) {
+        if (shape?.kind === 'object' && shape.fields)
+            parent = shape;
+        shape = step(shape, segment);
+    }
+    if (shape?.kind === 'array')
+        shape = shape.element;
+    const level = shape?.kind === 'object' && shape.fields
+        ? shape
+        : parent?.kind === 'object' && parent.fields
+            ? parent
+            : undefined;
+    if (!level?.fields)
+        return [];
+    return finish([...level.fields.values()].map((field) => 
+    // Story 8.4: an array field inserts its index, so the NEXT completion resolves the element rather than the array.
+    offerFor(field, field.shape.kind === 'array' ? `${field.name}[0]` : field.name)), environment, options);
+}
+/**
+ * What acceptance has to finish: the co-filled field, the dialect wrapper, and the escalation.
+ *
+ * ⚠️ ONE place, applied to every return path. A first draft wrapped at one of the two returns only, so a root-level
+ * completion inserted a bare fragment while a nested one inserted a whole expression — the same list behaving two
+ * ways depending on how far the author had already typed.
+ */
+function finish(offers, environment, options) {
+    const withExtras = offers.map((offer) => {
+        const source = environment.roots.get(offer.label);
+        const dataType = environment.position === 'validation-field' &&
+            source?.provenance.kind === 'column'
+            ? source.provenance.dataType
+            : undefined;
+        return {
+            ...offer,
+            ...(options.dialect && options.dialect !== 'none'
+                ? { insert: wrapFor(options.dialect, offer.insert), wrapped: true }
+                : {}),
+            ...(dataType ? { coFill: { field: 'dataType', value: dataType } } : {}),
+        };
+    });
+    const ceiling = options.listCeiling;
+    if (ceiling === undefined || withExtras.length <= ceiling)
+        return withExtras;
+    return [
+        ...withExtras.slice(0, ceiling),
+        {
+            label: `${withExtras.length - ceiling} more…`,
+            insert: MORE_SENTINEL,
+            detail: 'Open the picker to search all of them',
+        },
+    ];
+}
+/**
+ * The trailing run of path characters, scanned BACKWARDS from the end.
+ *
+ * ⛔ This was `/([\w.[\]]*)$/.exec(trimmed)`, and CodeQL was right (`js/polynomial-redos`, High). With `$`
+ * anchored and `*` unbounded, the engine retries the class from every position in the string, so a value of N
+ * dots costs O(N²) — and this runs on the line under the caret on every keystroke, which is the worst place in
+ * the extension to put a quadratic.
+ *
+ * A backward scan is what the regex was describing anyway: the longest suffix made only of word characters,
+ * `.`, `[` and `]`. One pass, no backtracking, byte-identical result for every input.
+ *
+ * Exported for `__tests__/redos.spec.ts`, which pins both halves: the same answer the regex gave, and a bound
+ * on the time it takes.
+ */
+export function trailingPathToken(text) {
+    let at = text.length;
+    while (at > 0 && isPathChar(text.charCodeAt(at - 1)))
+        at -= 1;
+    return text.slice(at);
+}
+/** `[\w.[\]]` — a word character, a dot, or a bracket. `\w` is `[A-Za-z0-9_]`, ASCII only, as the regex was. */
+function isPathChar(code) {
+    return ((code >= 48 && code <= 57) || // 0-9
+        (code >= 65 && code <= 90) || // A-Z
+        (code >= 97 && code <= 122) || // a-z
+        code === 95 || // _
+        code === 46 || // .
+        code === 91 || // [
+        code === 93 // ]
+    );
+}
+//# sourceMappingURL=completion.js.map

package/dist/completion.js.map

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

package/dist/detect.d.ts

@@ -0,0 +1,38 @@
+import type { Position } from './position.js';
+/**
+ * Which of the five alphabets a caret is in.
+ *
+ * ⛔ The classification is here, not in a surface, because getting it wrong is invisible: every position produces a
+ * plausible-looking list, and the author only finds out at run time when the path resolved to an empty string. Two
+ * surfaces classifying independently is two chances to be differently wrong.
+ *
+ * The rules, in the order they must be applied:
+ *
+ * | test | position |
+ * | --- | --- |
+ * | the path runs through `transformations` | `transformation-expression` |
+ * | the path runs through `validations` | `validation-field` |
+ * | the component is a pusher | `pusher-step` |
+ * | the puller declares a non-empty `steps` array | `new-kind-puller-step` |
+ * | otherwise | `legacy-puller-step` |
+ *
+ * ⚠️ Order matters. A transformation is declared under a task, which is reached through the same document as a
+ * puller's steps — so testing "is this a puller" first would classify every transformation expression in a puller's
+ * project as a puller step and offer `puller.*` where the context object is the item.
+ */
+export interface DetectRequest {
+    /** The component being edited, as authored. */
+    readonly component?: unknown;
+    /** The caret's path through the document, e.g. `['pullers', 0, 'pullSteps', 2, 'data', 'url']`. */
+    readonly yamlPath?: readonly (string | number)[];
+}
+/**
+ * ⛔ A non-empty `steps` array is the ONLY thing that decides the puller kind — `PullStepAccessor.IsNewKind`.
+ *
+ * Not the presence of the key, and not a `kind` field: a puller carrying `steps: []` is legacy, because the accessor
+ * tests the array's length. Reading the key alone would flip every such puller onto an alphabet that shares no root
+ * with the one it is written in.
+ */
+export declare function isNewKindPuller(component: unknown): boolean;
+export declare function detectPosition(request: DetectRequest): Position | undefined;
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAClD;AAOD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAG3D;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,QAAQ,GAAG,SAAS,CAsB3E"}

package/dist/detect.js

@@ -0,0 +1,35 @@
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * ⛔ A non-empty `steps` array is the ONLY thing that decides the puller kind — `PullStepAccessor.IsNewKind`.
+ *
+ * Not the presence of the key, and not a `kind` field: a puller carrying `steps: []` is legacy, because the accessor
+ * tests the array's length. Reading the key alone would flip every such puller onto an alphabet that shares no root
+ * with the one it is written in.
+ */
+export function isNewKindPuller(component) {
+    const steps = record(component)?.['steps'];
+    return Array.isArray(steps) && steps.length > 0;
+}
+export function detectPosition(request) {
+    const path = request.yamlPath ?? [];
+    if (path.length === 0)
+        return undefined;
+    if (path.includes('transformations'))
+        return 'transformation-expression';
+    if (path.includes('validations'))
+        return 'validation-field';
+    const component = record(record(request.component)?.['value'] ?? request.component);
+    if (path.includes('pushers') ||
+        record(component)?.['pushSteps'] !== undefined) {
+        return 'pusher-step';
+    }
+    if (path.includes('pullers') || component !== undefined) {
+        return isNewKindPuller(component)
+            ? 'new-kind-puller-step'
+            : 'legacy-puller-step';
+    }
+    return undefined;
+}
+//# sourceMappingURL=detect.js.map

package/dist/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AA8BA,MAAM,MAAM,GAAG,CAAC,KAAc,EAAuC,EAAE,CACrE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;IAClE,CAAC,CAAE,KAAiC;IACpC,CAAC,CAAC,SAAS,CAAC;AAEhB;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,SAAkB;IAChD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC3C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,OAAsB;IACnD,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAExC,IAAI,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAAE,OAAO,2BAA2B,CAAC;IACzE,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC;QAAE,OAAO,kBAAkB,CAAC;IAE5D,MAAM,SAAS,GAAG,MAAM,CACtB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,SAAS,CAC1D,CAAC;IACF,IACE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QACxB,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,SAAS,EAC9C,CAAC;QACD,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACxD,OAAO,eAAe,CAAC,SAAS,CAAC;YAC/B,CAAC,CAAC,sBAAsB;YACxB,CAAC,CAAC,oBAAoB,CAAC;IAC3B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/environment.d.ts

@@ -0,0 +1,79 @@
+import { type Position } from './position.js';
+import { type Field, type Shape } from './shape.js';
+/**
+ * The resolved environment: a map from context path to the shape at that path, and nothing else (Story 8.1 AC-1).
+ *
+ * "Nothing else" is the constraint that makes four surfaces possible. The moment this carried a completion item, a
+ * diagnostic range or a markdown string, it would belong to whichever surface that shape came from and the other three
+ * would each need their own pass.
+ */
+export interface Environment {
+    /** Which of the five alphabets this is — stated, because a surface must be able to say it (Story 8.2 AC-6). */
+    readonly position: Position;
+    /** The roots available here, by name. A root absent from this map does not exist at this caret. */
+    readonly roots: ReadonlyMap<string, Field>;
+    /**
+     * Why the environment is what it is, in one sentence an author can read. Not decoration: the two puller kinds are
+     * disjoint and look identical in the file, so "this puller declares a `steps` array, so it is a new-kind puller"
+     * is the difference between a confusing empty list and an understood one.
+     */
+    readonly note: string;
+}
+/** What the caller must tell the engine about one step, so nothing here reads a file. */
+export interface StepFacts {
+    readonly key: string;
+    /** The union of the step's `responseFilters` engine keys, where the document declares them. */
+    readonly outputs?: Shape;
+}
+/**
+ * Read a step's facts straight from the authored step, so a caller never has to derive the output shape itself.
+ *
+ * ⚠️ The whole point of `stepOutputs` living beside this is that `…current.STEP_X.<field>` is EXACT — the union of
+ * the step's response-filter keys, written twenty lines above the caret — rather than a guess. A caller that built
+ * `StepFacts` by hand would be re-deriving that, which is how two surfaces start disagreeing.
+ */
+export declare function stepFactsFrom(step: unknown): StepFacts;
+/** What the caller must tell the engine about the component being edited. */
+export interface ComponentFacts {
+    readonly collection: 'pullers' | 'pushers';
+    /** ⛔ A non-empty `steps` array is the ONLY thing that decides the puller kind (`PullStepAccessor.IsNewKind`). */
+    readonly hasStepsArray: boolean;
+    readonly optionKeys?: readonly string[];
+    readonly argumentKeys?: readonly string[];
+    /** The steps of each phase, in declaration order — the order IS the rule (§2.3). */
+    readonly phases?: Readonly<Record<string, readonly StepFacts[]>>;
+}
+export interface ResolveRequest {
+    readonly position: Position;
+    readonly component?: ComponentFacts;
+    /** The phase the caret is in, and how far along it — everything after this index is a forward reference. */
+    readonly phase?: string;
+    readonly stepIndex?: number;
+    /** The item as the caller has resolved it — columns, transformation output and hints, already layered. */
+    readonly item?: Shape;
+    /** The task's declared columns, flat, for the one position that takes nothing else. */
+    readonly columns?: readonly Field[];
+    readonly ownArguments?: readonly Field[];
+}
+/**
+ * ⛔ **Earlier steps in the phase, plus the step itself.**
+ *
+ * `StepIterator` calls the context handler in each step's success path with the accumulated outputs, so after
+ * `STEP_A` the phase holds `{STEP_A}` and after `STEP_B` it holds `{STEP_A, STEP_B}`. A forward reference resolves
+ * to nothing — no error, no diagnostic, an empty string in a URL or a body.
+ *
+ * The step ITSELF is included, and that is not an off-by-one: each pagination iteration calls `ExecuteSteps` afresh
+ * with an empty outputs dict, so at the top of page 2 `puller.current` still holds page 1's values. Reading
+ * `puller.lastToken.PULL_DATA.offset` from inside `PULL_DATA` is the pagination idiom, not a mistake — it is why the
+ * alias is called `lastToken`.
+ */
+export declare function visibleSteps(steps: readonly StepFacts[], stepIndex: number | undefined): readonly StepFacts[];
+/**
+ * Resolve one caret into one environment.
+ *
+ * ⛔ Pure. It reads no file, spawns nothing and imports nothing from an editor — Story 8.1 AC-5, and the reason the
+ * CLI and the extension cannot disagree: there is one function and they both call it. A test asserting "the editor
+ * and the CLI produce the same environment" is only worth writing because it could otherwise have been two engines.
+ */
+export declare function resolveEnvironment(request: ResolveRequest): Environment;
+//# sourceMappingURL=environment.d.ts.map

package/dist/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,eAAe,CAAC;AAE9D,OAAO,EAML,KAAK,KAAK,EACV,KAAK,KAAK,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,+GAA+G;IAC/G,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,mGAAmG;IACnG,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAoHD,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAGtD;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,GAAG,SAAS,CAAC;IAC3C,iHAAiH;IACjH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;IACpC,4GAA4G;IAC5G,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0GAA0G;IAC1G,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,SAAS,SAAS,EAAE,CAGtB;AA2KD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,WAAW,CAmIvE"}