@invinite-org/chartlang-compiler 1.2.1 → 1.3.0

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

package/dist/analysis/resolveIndexBound.js.map

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

package/dist/analysis/validateSecurityExpr.d.ts

@@ -0,0 +1,25 @@
+import ts from "typescript";
+import { type CompileDiagnostic } from "../diagnostics.js";
+/**
+ * Validate that a `request.security({ interval }, (bar) => …)` expression
+ * callback references only its `bar` parameter (and locals derived from it),
+ * the ambient `ta` namespace, `inputs`, safe `Math.*` globals, and literal
+ * constants. Any other free identifier is a captured outer binding — it would
+ * smuggle the main-timeline clock into the higher-timeframe expression — and
+ * is rejected with `request-security-expr-captures-local`.
+ *
+ * Function / arrow expressions nested deeper inside the callback are out of
+ * the v1 subset and rejected too (keeps the expression unit flat), as is a
+ * `this` reference. Parameter default initialisers are walked alongside the
+ * body so a default that captures an outer binding is flagged too.
+ *
+ * @since 0.7
+ * @stable
+ * @example
+ *     // Inside extractRequestAnalysis, once per expression callsite:
+ *     //   validateSecurityExpr(callback, checker, diagnostics, sourcePath);
+ *     const fn: typeof validateSecurityExpr = validateSecurityExpr;
+ *     void fn;
+ */
+export declare function validateSecurityExpr(callback: ts.ArrowFunction | ts.FunctionExpression, checker: ts.TypeChecker, diagnostics: CompileDiagnostic[], sourcePath: string): void;
+//# sourceMappingURL=validateSecurityExpr.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validateSecurityExpr.d.ts","sourceRoot":"","sources":["../../src/analysis/validateSecurityExpr.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,KAAK,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAG7E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,EAAE,CAAC,aAAa,GAAG,EAAE,CAAC,kBAAkB,EAClD,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,WAAW,EAAE,iBAAiB,EAAE,EAChC,UAAU,EAAE,MAAM,GACnB,IAAI,CA2DN"}

package/dist/analysis/validateSecurityExpr.js

@@ -0,0 +1,154 @@
+// 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 { createDiagnostic } from "../diagnostics.js";
+import { resolveCoreSymbolName } from "../transformers/resolveCallee.js";
+/**
+ * Validate that a `request.security({ interval }, (bar) => …)` expression
+ * callback references only its `bar` parameter (and locals derived from it),
+ * the ambient `ta` namespace, `inputs`, safe `Math.*` globals, and literal
+ * constants. Any other free identifier is a captured outer binding — it would
+ * smuggle the main-timeline clock into the higher-timeframe expression — and
+ * is rejected with `request-security-expr-captures-local`.
+ *
+ * Function / arrow expressions nested deeper inside the callback are out of
+ * the v1 subset and rejected too (keeps the expression unit flat), as is a
+ * `this` reference. Parameter default initialisers are walked alongside the
+ * body so a default that captures an outer binding is flagged too.
+ *
+ * @since 0.7
+ * @stable
+ * @example
+ *     // Inside extractRequestAnalysis, once per expression callsite:
+ *     //   validateSecurityExpr(callback, checker, diagnostics, sourcePath);
+ *     const fn: typeof validateSecurityExpr = validateSecurityExpr;
+ *     void fn;
+ */
+export function validateSecurityExpr(callback, checker, diagnostics, sourcePath) {
+    const sourceFile = callback.getSourceFile();
+    const bound = collectBoundNames(callback);
+    const visit = (node) => {
+        // Nested functions/arrows are out of the flat v1 subset.
+        if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+            diagnostics.push(createDiagnostic({
+                severity: "error",
+                code: "request-security-expr-captures-local",
+                message: "A request.security expression callback may not contain a nested function. Keep the expression flat.",
+                file: sourcePath,
+                node,
+                sourceFile,
+            }));
+            return;
+        }
+        // `this` is not a value the flat expression subset may read — in a
+        // function-expression callback it would be `undefined` under the
+        // module's strict mode and throw at runtime.
+        if (node.kind === ts.SyntaxKind.ThisKeyword) {
+            diagnostics.push(createDiagnostic({
+                severity: "error",
+                code: "request-security-expr-captures-local",
+                message: "A request.security expression callback may not use `this`.",
+                file: sourcePath,
+                node,
+                sourceFile,
+            }));
+            return;
+        }
+        if (ts.isIdentifier(node) && isFreeReference(node)) {
+            if (!isAllowedReference(node, bound, checker)) {
+                diagnostics.push(createDiagnostic({
+                    severity: "error",
+                    code: "request-security-expr-captures-local",
+                    message: `A request.security expression callback may not capture the outer binding \`${node.text}\`. Inline it as a literal or read it from \`inputs\`.`,
+                    file: sourcePath,
+                    node,
+                    sourceFile,
+                }));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    // A parameter default (`(bar = outer) => …`) is a value read of whatever it
+    // initialises to, so it must be checked for captures alongside the body.
+    for (const parameter of callback.parameters) {
+        if (parameter.initializer !== undefined)
+            visit(parameter.initializer);
+    }
+    visit(callback.body);
+}
+/**
+ * Collect every name bound *inside* the callback: the parameter identifiers
+ * plus any `const` / `let` / `var` declared in the body. A binding's
+ * initialiser is still walked by the caller, so an initialiser that captures
+ * an outer name is still flagged.
+ */
+function collectBoundNames(callback) {
+    const names = new Set();
+    for (const parameter of callback.parameters) {
+        addBindingNames(parameter.name, names);
+    }
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node)) {
+            addBindingNames(node.name, names);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(callback.body);
+    return names;
+}
+function addBindingNames(name, into) {
+    if (ts.isIdentifier(name)) {
+        into.add(name.text);
+        return;
+    }
+    for (const element of name.elements) {
+        if (ts.isBindingElement(element))
+            addBindingNames(element.name, into);
+    }
+}
+/**
+ * Whether an identifier is a *free reference* — an actual value read, not a
+ * property name (`bar.close` → `close`), a property-assignment key, or a
+ * binding/declaration name (handled by `collectBoundNames`).
+ *
+ * A shorthand property (`{ offset }`) is deliberately NOT excluded: the
+ * identifier there is both the key and the value read, so `{ outerLength }`
+ * inside an opts object must still be checked against the allowed subset.
+ */
+function isFreeReference(node) {
+    const parent = node.parent;
+    if (ts.isPropertyAccessExpression(parent) && parent.name === node)
+        return false;
+    if (ts.isPropertyAssignment(parent) && parent.name === node)
+        return false;
+    if (ts.isBindingElement(parent) && parent.propertyName === node)
+        return false;
+    if (ts.isVariableDeclaration(parent) && parent.name === node)
+        return false;
+    return true;
+}
+/**
+ * Pure value globals that carry no main-timeline data and are morally literals.
+ * They cannot smuggle the outer clock in, so they are allowed alongside `Math`.
+ * Genuinely hostile globals (`Date`, `fetch`, …) are rejected separately by the
+ * file-level `forbiddenConstructs` pass, which also covers the inline callback.
+ */
+const SAFE_VALUE_GLOBALS = new Set(["undefined", "NaN", "Infinity"]);
+/**
+ * Whether a free identifier is in the allowed subset: a name bound inside the
+ * callback (`bar` + locals), a {@link SAFE_VALUE_GLOBALS} constant, the ambient
+ * `ta` / `inputs` namespaces, or the `Math` global (individual hostile members
+ * such as `Math.random` are rejected by the separate hostile-global pass, not
+ * here).
+ */
+function isAllowedReference(node, bound, checker) {
+    if (bound.has(node.text))
+        return true;
+    if (node.text === "Math")
+        return true;
+    if (SAFE_VALUE_GLOBALS.has(node.text))
+        return true;
+    const canonical = resolveCoreSymbolName(checker, node);
+    return canonical === "ta" || canonical === "inputs";
+}
+//# sourceMappingURL=validateSecurityExpr.js.map