@invinite-org/chartlang-compiler 1.2.0 → 1.3.0

package/dist/analysis/loopBounds.d.ts

@@ -0,0 +1,91 @@
+import ts from "typescript";
+/**
+ * The comparison operators a legal chartlang `for` condition may use.
+ * Shared by `parseBoundedForLoop` (which captures the operator so a sizer
+ * can derive the loop's max index) and `forbiddenConstructs` (which rejects
+ * any other condition shape) so the two passes recognise the same set.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     COMPARISON_OPS.has(ts.SyntaxKind.LessThanToken); // → true
+ */
+export declare const COMPARISON_OPS: ReadonlySet<ts.SyntaxKind>;
+/**
+ * The parsed shape of a legal chartlang `for` loop.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     const loop: BoundedForLoop = {
+ *         varName: "i",
+ *         start: 0,
+ *         op: ts.SyntaxKind.LessThanToken,
+ *         limit: 5,
+ *     };
+ *     void loop;
+ */
+export type BoundedForLoop = Readonly<{
+    /** The induction variable name (the `i` in `for (let i = …)`). */
+    varName: string;
+    /** The literal initial value (`for (let i = <start>; …)`). */
+    start: number;
+    /** The comparison operator token used in the condition. */
+    op: ts.SyntaxKind;
+    /** The literal right-hand bound (`… i <op> <limit>; …`). */
+    limit: number;
+}>;
+/**
+ * Parse a `ts.ForStatement` into its `BoundedForLoop` shape, or `null`
+ * when it is not the one legal chartlang loop form
+ * (`for (let i = <numLit>; i <comparison> <numLit>; i++)` — single
+ * `let` init, id-on-left/literal-on-right condition, postfix `i++`).
+ * The single source of truth for "what is a bounded loop"; both
+ * `forbiddenConstructs` (reject everything else) and
+ * `resolveIndexUpperBound` (size the index range) call it so the two
+ * passes can never disagree.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // for (let i = 0; i < 5; i++) → { varName: "i", start: 0,
+ *     //                                  op: LessThanToken, limit: 5 }
+ *     const fn: typeof parseBoundedForLoop = parseBoundedForLoop;
+ *     void fn;
+ */
+export declare function parseBoundedForLoop(node: ts.ForStatement): BoundedForLoop | null;
+/**
+ * The induction variable's **declaration** identifier of the single legal
+ * chartlang loop *initializer* shape, or `null` otherwise. A sizer calls
+ * this directly when it needs the declaration node (not just the `varName`
+ * text) to ask the type checker whether an index use resolves to this
+ * loop's own binding rather than a nested shadow of the same name. Shares
+ * `parseBoundedForLoop`'s initializer acceptance via `parseLoopInit`.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // for (let i = 0; i < 5; i++) → the `i` declaration identifier
+ *     const fn: typeof boundedLoopVarId = boundedLoopVarId;
+ *     void fn;
+ */
+export declare function boundedLoopVarId(node: ts.ForStatement): ts.Identifier | null;
+/**
+ * Unwrap any number of nested parentheses around an expression. The Pine
+ * converter emits a historical bar offset as the parenthesised form
+ * `bar.point(-(N), …)` (see the converter's `anchorToWorldPoint`), so the
+ * lookback recogniser must peel the parens before matching the literal;
+ * the index-bound resolver does the same before matching a numeric leaf.
+ * Housed here — a leaf module with no analysis-package imports — so both
+ * `extractMaxLookback` and `resolveIndexBound` can share it without a
+ * circular import.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // unwrapParens of `((7))` → the `7` numeric-literal node
+ *     const fn: typeof unwrapParens = unwrapParens;
+ *     void fn;
+ */
+export declare function unwrapParens(node: ts.Expression): ts.Expression;
+//# sourceMappingURL=loopBounds.d.ts.map

package/dist/analysis/loopBounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopBounds.d.ts","sourceRoot":"","sources":["../../src/analysis/loopBounds.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,EAAE,CAAC,UAAU,CAKpD,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IAClC,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC;IAClB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,GAAG,cAAc,GAAG,IAAI,CAoBhF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,GAAG,EAAE,CAAC,UAAU,GAAG,IAAI,CAE5E;AAsBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,UAAU,CAI/D"}

package/dist/analysis/loopBounds.js

@@ -0,0 +1,132 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+import ts from "typescript";
+/**
+ * The comparison operators a legal chartlang `for` condition may use.
+ * Shared by `parseBoundedForLoop` (which captures the operator so a sizer
+ * can derive the loop's max index) and `forbiddenConstructs` (which rejects
+ * any other condition shape) so the two passes recognise the same set.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     COMPARISON_OPS.has(ts.SyntaxKind.LessThanToken); // → true
+ */
+export const COMPARISON_OPS = new Set([
+    ts.SyntaxKind.LessThanToken,
+    ts.SyntaxKind.LessThanEqualsToken,
+    ts.SyntaxKind.GreaterThanToken,
+    ts.SyntaxKind.GreaterThanEqualsToken,
+]);
+/**
+ * Parse a `ts.ForStatement` into its `BoundedForLoop` shape, or `null`
+ * when it is not the one legal chartlang loop form
+ * (`for (let i = <numLit>; i <comparison> <numLit>; i++)` — single
+ * `let` init, id-on-left/literal-on-right condition, postfix `i++`).
+ * The single source of truth for "what is a bounded loop"; both
+ * `forbiddenConstructs` (reject everything else) and
+ * `resolveIndexUpperBound` (size the index range) call it so the two
+ * passes can never disagree.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // for (let i = 0; i < 5; i++) → { varName: "i", start: 0,
+ *     //                                  op: LessThanToken, limit: 5 }
+ *     const fn: typeof parseBoundedForLoop = parseBoundedForLoop;
+ *     void fn;
+ */
+export function parseBoundedForLoop(node) {
+    const init = parseLoopInit(node);
+    if (init === null)
+        return null;
+    const condition = node.condition;
+    const incrementor = node.incrementor;
+    if (!condition || !incrementor)
+        return null;
+    if (!ts.isBinaryExpression(condition))
+        return null;
+    if (!COMPARISON_OPS.has(condition.operatorToken.kind))
+        return null;
+    if (!ts.isNumericLiteral(condition.right))
+        return null;
+    if (!ts.isIdentifier(condition.left))
+        return null;
+    if (condition.left.text !== init.varId.text)
+        return null;
+    if (!ts.isPostfixUnaryExpression(incrementor))
+        return null;
+    if (!ts.isIdentifier(incrementor.operand))
+        return null;
+    if (incrementor.operand.text !== init.varId.text)
+        return null;
+    return {
+        varName: init.varId.text,
+        start: Number(init.start.text),
+        op: condition.operatorToken.kind,
+        limit: Number(condition.right.text),
+    };
+}
+/**
+ * The induction variable's **declaration** identifier of the single legal
+ * chartlang loop *initializer* shape, or `null` otherwise. A sizer calls
+ * this directly when it needs the declaration node (not just the `varName`
+ * text) to ask the type checker whether an index use resolves to this
+ * loop's own binding rather than a nested shadow of the same name. Shares
+ * `parseBoundedForLoop`'s initializer acceptance via `parseLoopInit`.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // for (let i = 0; i < 5; i++) → the `i` declaration identifier
+ *     const fn: typeof boundedLoopVarId = boundedLoopVarId;
+ *     void fn;
+ */
+export function boundedLoopVarId(node) {
+    return parseLoopInit(node)?.varId ?? null;
+}
+/**
+ * The accepted `for (let i = <numLit>; …)` initializer — a single-
+ * declaration `let`/`const` list whose name is an identifier with a
+ * numeric-literal start value — captured as both nodes, or `null`. The one
+ * place the initializer shape is recognised; `parseBoundedForLoop` and
+ * `boundedLoopVarId` both build on it (no narrowing casts in either).
+ */
+function parseLoopInit(node) {
+    const init = node.initializer;
+    if (!init || !ts.isVariableDeclarationList(init))
+        return null;
+    if (init.declarations.length !== 1)
+        return null;
+    const declaration = init.declarations[0];
+    if (!declaration || !ts.isIdentifier(declaration.name))
+        return null;
+    const start = declaration.initializer;
+    if (!start || !ts.isNumericLiteral(start))
+        return null;
+    return { varId: declaration.name, start };
+}
+/**
+ * Unwrap any number of nested parentheses around an expression. The Pine
+ * converter emits a historical bar offset as the parenthesised form
+ * `bar.point(-(N), …)` (see the converter's `anchorToWorldPoint`), so the
+ * lookback recogniser must peel the parens before matching the literal;
+ * the index-bound resolver does the same before matching a numeric leaf.
+ * Housed here — a leaf module with no analysis-package imports — so both
+ * `extractMaxLookback` and `resolveIndexBound` can share it without a
+ * circular import.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // unwrapParens of `((7))` → the `7` numeric-literal node
+ *     const fn: typeof unwrapParens = unwrapParens;
+ *     void fn;
+ */
+export function unwrapParens(node) {
+    let current = node;
+    while (ts.isParenthesizedExpression(current))
+        current = current.expression;
+    return current;
+}
+//# sourceMappingURL=loopBounds.js.map

package/dist/analysis/loopBounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopBounds.js","sourceRoot":"","sources":["../../src/analysis/loopBounds.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Invinite. Licensed under the MIT License.\n// See the LICENSE file in the repo root for full license text.\n\nimport ts from \"typescript\";\n\n/**\n * The comparison operators a legal chartlang `for` condition may use.\n * Shared by `parseBoundedForLoop` (which captures the operator so a sizer\n * can derive the loop's max index) and `forbiddenConstructs` (which rejects\n * any other condition shape) so the two passes recognise the same set.\n *\n * @since 0.1\n * @stable\n * @example\n *     COMPARISON_OPS.has(ts.SyntaxKind.LessThanToken); // → true\n */\nexport const COMPARISON_OPS: ReadonlySet<ts.SyntaxKind> = new Set<ts.SyntaxKind>([\n    ts.SyntaxKind.LessThanToken,\n    ts.SyntaxKind.LessThanEqualsToken,\n    ts.SyntaxKind.GreaterThanToken,\n    ts.SyntaxKind.GreaterThanEqualsToken,\n]);\n\n/**\n * The parsed shape of a legal chartlang `for` loop.\n *\n * @since 0.1\n * @stable\n * @example\n *     const loop: BoundedForLoop = {\n *         varName: \"i\",\n *         start: 0,\n *         op: ts.SyntaxKind.LessThanToken,\n *         limit: 5,\n *     };\n *     void loop;\n */\nexport type BoundedForLoop = Readonly<{\n    /** The induction variable name (the `i` in `for (let i = …)`). */\n    varName: string;\n    /** The literal initial value (`for (let i = <start>; …)`). */\n    start: number;\n    /** The comparison operator token used in the condition. */\n    op: ts.SyntaxKind;\n    /** The literal right-hand bound (`… i <op> <limit>; …`). */\n    limit: number;\n}>;\n\n/**\n * Parse a `ts.ForStatement` into its `BoundedForLoop` shape, or `null`\n * when it is not the one legal chartlang loop form\n * (`for (let i = <numLit>; i <comparison> <numLit>; i++)` — single\n * `let` init, id-on-left/literal-on-right condition, postfix `i++`).\n * The single source of truth for \"what is a bounded loop\"; both\n * `forbiddenConstructs` (reject everything else) and\n * `resolveIndexUpperBound` (size the index range) call it so the two\n * passes can never disagree.\n *\n * @since 0.1\n * @stable\n * @example\n *     // for (let i = 0; i < 5; i++) → { varName: \"i\", start: 0,\n *     //                                  op: LessThanToken, limit: 5 }\n *     const fn: typeof parseBoundedForLoop = parseBoundedForLoop;\n *     void fn;\n */\nexport function parseBoundedForLoop(node: ts.ForStatement): BoundedForLoop | null {\n    const init = parseLoopInit(node);\n    if (init === null) return null;\n    const condition = node.condition;\n    const incrementor = node.incrementor;\n    if (!condition || !incrementor) return null;\n    if (!ts.isBinaryExpression(condition)) return null;\n    if (!COMPARISON_OPS.has(condition.operatorToken.kind)) return null;\n    if (!ts.isNumericLiteral(condition.right)) return null;\n    if (!ts.isIdentifier(condition.left)) return null;\n    if (condition.left.text !== init.varId.text) return null;\n    if (!ts.isPostfixUnaryExpression(incrementor)) return null;\n    if (!ts.isIdentifier(incrementor.operand)) return null;\n    if (incrementor.operand.text !== init.varId.text) return null;\n    return {\n        varName: init.varId.text,\n        start: Number(init.start.text),\n        op: condition.operatorToken.kind,\n        limit: Number(condition.right.text),\n    };\n}\n\n/**\n * The induction variable's **declaration** identifier of the single legal\n * chartlang loop *initializer* shape, or `null` otherwise. A sizer calls\n * this directly when it needs the declaration node (not just the `varName`\n * text) to ask the type checker whether an index use resolves to this\n * loop's own binding rather than a nested shadow of the same name. Shares\n * `parseBoundedForLoop`'s initializer acceptance via `parseLoopInit`.\n *\n * @since 0.1\n * @stable\n * @example\n *     // for (let i = 0; i < 5; i++) → the `i` declaration identifier\n *     const fn: typeof boundedLoopVarId = boundedLoopVarId;\n *     void fn;\n */\nexport function boundedLoopVarId(node: ts.ForStatement): ts.Identifier | null {\n    return parseLoopInit(node)?.varId ?? null;\n}\n\n/**\n * The accepted `for (let i = <numLit>; …)` initializer — a single-\n * declaration `let`/`const` list whose name is an identifier with a\n * numeric-literal start value — captured as both nodes, or `null`. The one\n * place the initializer shape is recognised; `parseBoundedForLoop` and\n * `boundedLoopVarId` both build on it (no narrowing casts in either).\n */\nfunction parseLoopInit(\n    node: ts.ForStatement,\n): Readonly<{ varId: ts.Identifier; start: ts.NumericLiteral }> | null {\n    const init = node.initializer;\n    if (!init || !ts.isVariableDeclarationList(init)) return null;\n    if (init.declarations.length !== 1) return null;\n    const declaration = init.declarations[0];\n    if (!declaration || !ts.isIdentifier(declaration.name)) return null;\n    const start = declaration.initializer;\n    if (!start || !ts.isNumericLiteral(start)) return null;\n    return { varId: declaration.name, start };\n}\n\n/**\n * Unwrap any number of nested parentheses around an expression. The Pine\n * converter emits a historical bar offset as the parenthesised form\n * `bar.point(-(N), …)` (see the converter's `anchorToWorldPoint`), so the\n * lookback recogniser must peel the parens before matching the literal;\n * the index-bound resolver does the same before matching a numeric leaf.\n * Housed here — a leaf module with no analysis-package imports — so both\n * `extractMaxLookback` and `resolveIndexBound` can share it without a\n * circular import.\n *\n * @since 0.1\n * @stable\n * @example\n *     // unwrapParens of `((7))` → the `7` numeric-literal node\n *     const fn: typeof unwrapParens = unwrapParens;\n *     void fn;\n */\nexport function unwrapParens(node: ts.Expression): ts.Expression {\n    let current = node;\n    while (ts.isParenthesizedExpression(current)) current = current.expression;\n    return current;\n}\n"]}

package/dist/analysis/resolveIndexBound.d.ts

@@ -0,0 +1,73 @@
+import ts from "typescript";
+/**
+ * Compile-time context for resolving a series index's upper bound.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     const ctx: IndexBoundContext = {
+ *         constEnv: new Map([["k", 3]]),
+ *         checker, // ts.TypeChecker
+ *     };
+ *     void ctx;
+ */
+export type IndexBoundContext = Readonly<{
+    /** `const <id> = <numeric literal>` bindings visible at the index use site. */
+    constEnv: ReadonlyMap<string, number>;
+    /** Checker used to avoid resolving loop variables through a shadowed name. */
+    checker: ts.TypeChecker;
+}>;
+/**
+ * The provable maximum non-negative integer a series-index expression
+ * can reach at runtime, or `null` when no sound upper bound exists.
+ * Over-approximates: a result is always `>=` the true max index, so the
+ * runtime buffer (sized `maxLookback + 1`) never under-sizes. `null`
+ * signals the caller to fall back to the 5000-slot dynamic buffer.
+ *
+ * Resolves any expression built from numeric literals, `const`
+ * numeric-literal bindings (`ctx.constEnv`), bounded-loop induction
+ * variables (resolved to their full range), the binary operators `+`,
+ * `−`, `*`, unary `±`, and parentheses, by computing its integer
+ * interval and returning the **upper** endpoint. Any other node (another
+ * identifier, a call, `/`, `%`, `**`, a bitwise op, a non-numeric
+ * literal) collapses the containing interval — and thus the whole
+ * index — to `null`.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // for (let i = 0; i < 5; i++) { series[i + 1]; }
+ *     // resolveIndexUpperBound(<the `i + 1` arg>, <access node>, ctx) → 5
+ *     const fn: typeof resolveIndexUpperBound = resolveIndexUpperBound;
+ *     void fn;
+ */
+export declare function resolveIndexUpperBound(argument: ts.Expression, node: ts.Node, ctx: IndexBoundContext): number | null;
+/**
+ * The `const <id> = <numeric literal>` bindings lexically visible at a
+ * specific series-index expression. Only `const` initialised with a
+ * numeric literal — or a unary `+`/`-` on one — is included (mirroring
+ * `extractInputs.readLiteral`'s numeric handling); a binary initialiser
+ * is left for Task 2's interval evaluator and is simply omitted. The walk
+ * runs from `useSite` outward through its lexical containers up to
+ * `scopeRoot`, collecting only declarations that occur before
+ * `useSite.pos` within each container, so it never sees a declaration
+ * after the read, inside a sibling block, or in a nested function/class
+ * that does not contain `useSite`. The innermost visible binding for a
+ * name wins (normal shadowing) — including binders that are not
+ * `var`/`let`/`const` statements: a `for`-init induction variable and a
+ * function parameter shadow an outer numeric `const` of the same name
+ * (`markContainerBinders`), so a reassigned `for (let i …)` index or a
+ * `request.security((k) => series[k])` callback parameter can never leak
+ * an unrelated outer `const k`'s value into the bound (which would
+ * under-size the buffer).
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // const k = 3; series[k];
+ *     // collectConstNumberEnv(<the `k` arg>, scope).get("k") → 3
+ *     const fn: typeof collectConstNumberEnv = collectConstNumberEnv;
+ *     void fn;
+ */
+export declare function collectConstNumberEnv(useSite: ts.Node, scopeRoot: ts.Node): ReadonlyMap<string, number>;
+//# sourceMappingURL=resolveIndexBound.d.ts.map

package/dist/analysis/resolveIndexBound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveIndexBound.d.ts","sourceRoot":"","sources":["../../src/analysis/resolveIndexBound.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,YAAY,CAAC;AAS5B;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACrC,+EAA+E;IAC/E,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,8EAA8E;IAC9E,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC;CAC3B,CAAC,CAAC;AAUH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CAClC,QAAQ,EAAE,EAAE,CAAC,UAAU,EACvB,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,GAAG,EAAE,iBAAiB,GACvB,MAAM,GAAG,IAAI,CAGf;AAqLD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,EAAE,CAAC,IAAI,EAChB,SAAS,EAAE,EAAE,CAAC,IAAI,GACnB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CA+B7B"}

package/dist/analysis/resolveIndexBound.js

@@ -0,0 +1,336 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+import ts from "typescript";
+import { boundedLoopVarId, parseBoundedForLoop, unwrapParens, } from "./loopBounds.js";
+/**
+ * The provable maximum non-negative integer a series-index expression
+ * can reach at runtime, or `null` when no sound upper bound exists.
+ * Over-approximates: a result is always `>=` the true max index, so the
+ * runtime buffer (sized `maxLookback + 1`) never under-sizes. `null`
+ * signals the caller to fall back to the 5000-slot dynamic buffer.
+ *
+ * Resolves any expression built from numeric literals, `const`
+ * numeric-literal bindings (`ctx.constEnv`), bounded-loop induction
+ * variables (resolved to their full range), the binary operators `+`,
+ * `−`, `*`, unary `±`, and parentheses, by computing its integer
+ * interval and returning the **upper** endpoint. Any other node (another
+ * identifier, a call, `/`, `%`, `**`, a bitwise op, a non-numeric
+ * literal) collapses the containing interval — and thus the whole
+ * index — to `null`.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // for (let i = 0; i < 5; i++) { series[i + 1]; }
+ *     // resolveIndexUpperBound(<the `i + 1` arg>, <access node>, ctx) → 5
+ *     const fn: typeof resolveIndexUpperBound = resolveIndexUpperBound;
+ *     void fn;
+ */
+export function resolveIndexUpperBound(argument, node, ctx) {
+    const interval = evalInterval(argument, node, ctx);
+    return interval === null ? null : interval.hi;
+}
+/**
+ * The integer interval an index sub-expression spans, or `null` when any
+ * leaf or operator cannot be soundly bounded. The single evaluator that
+ * subsumes the leaf cases (literal / bounded-loop var / `const` number)
+ * and their affine combinations (`+`, `−`, `*`, unary `±`, parens).
+ */
+function evalInterval(expr, node, ctx) {
+    const inner = unwrapParens(expr);
+    if (ts.isNumericLiteral(inner)) {
+        const value = Number(inner.text);
+        return finiteInterval(value, value);
+    }
+    if (ts.isIdentifier(inner)) {
+        const loopInterval = resolveLoopVarInterval(inner, node, ctx.checker);
+        if (loopInterval !== null)
+            return loopInterval;
+        const constValue = ctx.constEnv.get(inner.text);
+        return constValue === undefined ? null : finiteInterval(constValue, constValue);
+    }
+    if (ts.isPrefixUnaryExpression(inner)) {
+        if (inner.operator === ts.SyntaxKind.PlusToken) {
+            return evalInterval(inner.operand, node, ctx);
+        }
+        if (inner.operator === ts.SyntaxKind.MinusToken) {
+            const operand = evalInterval(inner.operand, node, ctx);
+            return operand === null ? null : finiteInterval(-operand.hi, -operand.lo);
+        }
+        return null;
+    }
+    if (ts.isBinaryExpression(inner)) {
+        return evalBinaryInterval(inner, node, ctx);
+    }
+    return null;
+}
+/**
+ * The interval of a `+`/`−`/`*` over two sub-intervals, or `null` when
+ * either operand is unbounded or the operator is unsupported (`/`, `%`,
+ * `**`, bitwise, …). Multiplication takes the min/max of the four
+ * endpoint products so the bound is correct for any sign combination.
+ */
+function evalBinaryInterval(expr, node, ctx) {
+    const left = evalInterval(expr.left, node, ctx);
+    if (left === null)
+        return null;
+    const right = evalInterval(expr.right, node, ctx);
+    if (right === null)
+        return null;
+    switch (expr.operatorToken.kind) {
+        case ts.SyntaxKind.PlusToken:
+            return finiteInterval(left.lo + right.lo, left.hi + right.hi);
+        case ts.SyntaxKind.MinusToken:
+            return finiteInterval(left.lo - right.hi, left.hi - right.lo);
+        case ts.SyntaxKind.AsteriskToken: {
+            const products = [
+                left.lo * right.lo,
+                left.lo * right.hi,
+                left.hi * right.lo,
+                left.hi * right.hi,
+            ];
+            return finiteInterval(Math.min(...products), Math.max(...products));
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * An interval with finite endpoints, or `null` when either endpoint is
+ * non-finite. A defensive guard against a pathological literal
+ * (`1e400` → `Infinity`) or an overflow product feeding a non-finite
+ * `hi` into `maxLookback`; integer-ness needs no check (see `Interval`).
+ */
+function finiteInterval(lo, hi) {
+    if (!Number.isFinite(lo) || !Number.isFinite(hi))
+        return null;
+    // Normalise `-0` (e.g. `-2 * 0`) to `0` so a resolved bound is never the
+    // negative zero a downstream `Object.is`/strict consumer would distinguish.
+    return { lo: lo + 0, hi: hi + 0 };
+}
+/**
+ * The index range a bare bounded-loop induction variable can span, or
+ * `null` when the identifier is not the induction variable of an
+ * enclosing legal `for`, is reassigned in the body, runs a
+ * non-terminating `>`/`>=` loop, or is a shadowed name that does not
+ * resolve to the loop's own declaration. Affine forms need the full
+ * range (`K - i` is largest when `i` is smallest); a bare loop-var read
+ * still takes `interval.hi`, identical to the leaf max.
+ */
+function resolveLoopVarInterval(id, node, checker) {
+    const idSymbol = checker.getSymbolAtLocation(id);
+    let current = node;
+    while (current) {
+        if (ts.isForStatement(current)) {
+            const loopVarId = boundedLoopVarId(current);
+            if (loopVarId && loopVarId.text === id.text) {
+                // Confirm the use refers to THIS loop's induction variable
+                // and not a nested binding that shadows the same text.
+                const loopSymbol = checker.getSymbolAtLocation(loopVarId);
+                if (!idSymbol || !loopSymbol || idSymbol !== loopSymbol)
+                    return null;
+                const loop = parseBoundedForLoop(current);
+                if (loop === null)
+                    return null;
+                if (isLoopVarReassigned(current, loop.varName))
+                    return null;
+                return loopVarInterval(loop);
+            }
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * The full index range a terminating `for` reaches (`[start, max]`), or
+ * `null` for a non-terminating (`>`/`>=` with `i++`) header the resolver
+ * cannot bound. `<` reaches `limit - 1`; `<=` reaches `limit`.
+ */
+function loopVarInterval(loop) {
+    if (loop.op === ts.SyntaxKind.LessThanToken) {
+        return finiteInterval(loop.start, loop.limit - 1);
+    }
+    if (loop.op === ts.SyntaxKind.LessThanEqualsToken) {
+        return finiteInterval(loop.start, loop.limit);
+    }
+    return null;
+}
+/**
+ * Whether the loop body reassigns `varName` beyond the header `i++`
+ * incrementor (a plain `=`, a compound assignment, or an extra `++`/`--`
+ * whose target is the induction variable). Such a body breaks the
+ * `limit`-based bound, so the resolver refuses to size the read.
+ */
+function isLoopVarReassigned(loop, varName) {
+    const body = loop.statement;
+    let reassigned = false;
+    const visit = (node) => {
+        if (reassigned)
+            return;
+        if (ts.isBinaryExpression(node) &&
+            isAssignmentOperator(node.operatorToken.kind) &&
+            ts.isIdentifier(node.left) &&
+            node.left.text === varName) {
+            reassigned = true;
+            return;
+        }
+        if ((ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node)) &&
+            (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                node.operator === ts.SyntaxKind.MinusMinusToken) &&
+            ts.isIdentifier(node.operand) &&
+            node.operand.text === varName) {
+            reassigned = true;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+    return reassigned;
+}
+/** Whether a binary operator token writes to its left operand. */
+function isAssignmentOperator(kind) {
+    return kind >= ts.SyntaxKind.FirstAssignment && kind <= ts.SyntaxKind.LastAssignment;
+}
+/**
+ * The `const <id> = <numeric literal>` bindings lexically visible at a
+ * specific series-index expression. Only `const` initialised with a
+ * numeric literal — or a unary `+`/`-` on one — is included (mirroring
+ * `extractInputs.readLiteral`'s numeric handling); a binary initialiser
+ * is left for Task 2's interval evaluator and is simply omitted. The walk
+ * runs from `useSite` outward through its lexical containers up to
+ * `scopeRoot`, collecting only declarations that occur before
+ * `useSite.pos` within each container, so it never sees a declaration
+ * after the read, inside a sibling block, or in a nested function/class
+ * that does not contain `useSite`. The innermost visible binding for a
+ * name wins (normal shadowing) — including binders that are not
+ * `var`/`let`/`const` statements: a `for`-init induction variable and a
+ * function parameter shadow an outer numeric `const` of the same name
+ * (`markContainerBinders`), so a reassigned `for (let i …)` index or a
+ * `request.security((k) => series[k])` callback parameter can never leak
+ * an unrelated outer `const k`'s value into the bound (which would
+ * under-size the buffer).
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     // const k = 3; series[k];
+ *     // collectConstNumberEnv(<the `k` arg>, scope).get("k") → 3
+ *     const fn: typeof collectConstNumberEnv = collectConstNumberEnv;
+ *     void fn;
+ */
+export function collectConstNumberEnv(useSite, scopeRoot) {
+    const env = new Map();
+    // Every `var`/`let`/`const` name bound at or inside a nearer container,
+    // numeric or not. A nearer binding shadows an outer one even when it is
+    // a `let` or a non-numeric `const`, so an outer `const k = 5` must not
+    // leak through it — once a name is `seen`, no outer container can set it.
+    const seen = new Set();
+    let container = useSite.parent;
+    while (container) {
+        // A `for`-init variable / function parameter introduced by this
+        // container shadows any same-named outer `const`, even though it is
+        // not a `var`/`let`/`const` statement `variableDeclarationsIn` scans.
+        markContainerBinders(container, seen);
+        for (const declaration of variableDeclarationsIn(container)) {
+            if (declaration.pos >= useSite.pos)
+                continue;
+            if (!ts.isIdentifier(declaration.name))
+                continue;
+            const name = declaration.name.text;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            const list = declaration.parent;
+            if (ts.isVariableDeclarationList(list) && (list.flags & ts.NodeFlags.Const) !== 0) {
+                const value = readNumericLiteralInit(declaration);
+                if (value !== null)
+                    env.set(name, value);
+            }
+        }
+        if (container === scopeRoot)
+            break;
+        container = container.parent;
+    }
+    return env;
+}
+/**
+ * Mark every binding name a container introduces at its OWN level — a
+ * `for` initializer's induction variable and a function-like's parameters
+ * — as `seen`, so an outer numeric `const` of the same name cannot leak
+ * past it. These binders are never numeric `const`s the resolver trusts,
+ * so marking them only blocks unsound shadow leaks: a reassigned
+ * `for (let i …)` index or a callback parameter (`(k) => series[k]`) that
+ * collides with an outer `const i`/`const k`. Only identifier binders
+ * matter here (a numeric series index is an identifier); destructured
+ * parameter/loop patterns bind no numeric index and are skipped.
+ */
+function markContainerBinders(container, seen) {
+    if (ts.isForStatement(container)) {
+        const init = container.initializer;
+        if (init && ts.isVariableDeclarationList(init)) {
+            for (const declaration of init.declarations) {
+                if (ts.isIdentifier(declaration.name))
+                    seen.add(declaration.name.text);
+            }
+        }
+        return;
+    }
+    if (ts.isFunctionLike(container)) {
+        for (const parameter of container.parameters) {
+            if (ts.isIdentifier(parameter.name))
+                seen.add(parameter.name.text);
+        }
+    }
+}
+/**
+ * The direct `var`/`let`/`const` `VariableDeclaration`s of a container —
+ * of every declaration kind, so the caller can detect a nearer binding
+ * that shadows an outer numeric `const` — without descending into nested
+ * functions, classes, or blocks (those are handled by their own
+ * enclosing-container pass when they actually contain the use site).
+ * `Block`, `SourceFile`, function bodies, and case clauses hold their
+ * declarations as `statements`/`clauses` we scan directly.
+ */
+function variableDeclarationsIn(container) {
+    const declarations = [];
+    const statements = statementsOf(container);
+    for (const statement of statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            declarations.push(declaration);
+        }
+    }
+    return declarations;
+}
+/** The lexical statement list a container exposes, or `[]` when it holds none. */
+function statementsOf(container) {
+    if (ts.isSourceFile(container) || ts.isBlock(container) || ts.isModuleBlock(container)) {
+        return container.statements;
+    }
+    if (ts.isCaseClause(container) || ts.isDefaultClause(container)) {
+        return container.statements;
+    }
+    return [];
+}
+/**
+ * The numeric value of a `const k = <numeric literal>` /
+ * `const k = <unary ± numeric literal>` initialiser, or `null` for any
+ * other initialiser (no binary folding here — that is Task 2).
+ */
+function readNumericLiteralInit(declaration) {
+    const initializer = declaration.initializer;
+    if (!initializer)
+        return null;
+    const expr = unwrapParens(initializer);
+    if (ts.isNumericLiteral(expr))
+        return Number(expr.text);
+    if (ts.isPrefixUnaryExpression(expr) &&
+        (expr.operator === ts.SyntaxKind.MinusToken || expr.operator === ts.SyntaxKind.PlusToken) &&
+        ts.isNumericLiteral(expr.operand)) {
+        const value = Number(expr.operand.text);
+        return expr.operator === ts.SyntaxKind.MinusToken ? -value : value;
+    }
+    return null;
+}
+//# sourceMappingURL=resolveIndexBound.js.map