@invinite-org/chartlang-compiler 1.2.1 → 1.4.0

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/stateArrayCapacity.d.ts

@@ -0,0 +1,58 @@
+import ts from "typescript";
+import { type CompileDiagnostic } from "../diagnostics.js";
+/**
+ * The largest `capacity` a `state.array<T>(capacity)` allocation may request.
+ * The collection is bounded-execution-safe only because its size is fixed at
+ * compile time: a hard ceiling caps memory, caps the JSON snapshot size, and —
+ * crucially — caps the per-tick two-ring `Float64Array` copy the runtime does
+ * on every tick rollback. `100_000` is generous (the dominant rolling-window /
+ * event-log cases are ≤ a few hundred) while still keeping the snapshot and
+ * the per-tick copy bounded.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // state.array<number>(20)        → 20 <= MAX_STATE_ARRAY_CAPACITY  (OK)
+ *     // state.array<number>(1_000_000) → exceeds the cap                 (error)
+ *     const cap: number = MAX_STATE_ARRAY_CAPACITY;
+ *     void cap;
+ */
+export declare const MAX_STATE_ARRAY_CAPACITY = 100000;
+/**
+ * Walk the source file and flag every `state.array<T>(capacity)` allocation
+ * whose `capacity` argument is not a compile-time-resolvable positive integer
+ * within `MAX_STATE_ARRAY_CAPACITY`. This pins the bounded-execution +
+ * bounded-snapshot invariant at the compiler boundary: a non-literal capacity
+ * would make the backing ring's size — and therefore its snapshot size and
+ * per-tick rollback cost — non-deterministic.
+ *
+ * Capacity resolution reuses `resolveIndexUpperBound` + `collectConstNumberEnv`
+ * (the same machinery that sizes a series index), so a bare numeric literal,
+ * a parenthesised / unary-`±` literal, and a `const` numeric-literal binding
+ * (`const K = 20; state.array(K)`) are all accepted; a `let`, an input, or any
+ * runtime expression resolves to `null` and is rejected.
+ *
+ * Two error codes:
+ * - `state-array-capacity-not-literal` — the capacity is missing or does not
+ *   resolve to a compile-time number.
+ * - `state-array-capacity-exceeds-max` — the capacity resolves but is `<= 0`,
+ *   non-integer, or `> MAX_STATE_ARRAY_CAPACITY`.
+ *
+ * The walk runs on the **original** AST (positions match the user's source,
+ * and — running pre-injection — the capacity is `node.arguments[0]`, before
+ * the slot-id literal is injected as the leading argument). The element-access
+ * form `state["array"](cap)` is rejected upstream as
+ * `stateful-call-element-access` and never matches `"state.array"` here, so it
+ * is not double-reported. A `state.array(...)` inside a loop additionally
+ * errors `stateful-call-inside-loop`; both passes are independent.
+ *
+ * @since 1.3
+ * @example
+ *     // const diagnostics = runStateArrayCapacity(
+ *     //     sourceFile, checker, "demo.chart.ts",
+ *     // );
+ *     const fn: typeof runStateArrayCapacity = runStateArrayCapacity;
+ *     void fn;
+ */
+export declare function runStateArrayCapacity(sourceFile: ts.SourceFile, checker: ts.TypeChecker, sourcePath: string): ReadonlyArray<CompileDiagnostic>;
+//# sourceMappingURL=stateArrayCapacity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stateArrayCapacity.d.ts","sourceRoot":"","sources":["../../src/analysis/stateArrayCapacity.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,KAAK,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAI7E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,qBAAqB,CACjC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,UAAU,EAAE,MAAM,GACnB,aAAa,CAAC,iBAAiB,CAAC,CAwDlC"}

package/dist/analysis/stateArrayCapacity.js

@@ -0,0 +1,108 @@
+// 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 { resolveCalleeName } from "../transformers/resolveCallee.js";
+import { collectConstNumberEnv, resolveIndexUpperBound } from "./resolveIndexBound.js";
+/**
+ * The largest `capacity` a `state.array<T>(capacity)` allocation may request.
+ * The collection is bounded-execution-safe only because its size is fixed at
+ * compile time: a hard ceiling caps memory, caps the JSON snapshot size, and —
+ * crucially — caps the per-tick two-ring `Float64Array` copy the runtime does
+ * on every tick rollback. `100_000` is generous (the dominant rolling-window /
+ * event-log cases are ≤ a few hundred) while still keeping the snapshot and
+ * the per-tick copy bounded.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // state.array<number>(20)        → 20 <= MAX_STATE_ARRAY_CAPACITY  (OK)
+ *     // state.array<number>(1_000_000) → exceeds the cap                 (error)
+ *     const cap: number = MAX_STATE_ARRAY_CAPACITY;
+ *     void cap;
+ */
+export const MAX_STATE_ARRAY_CAPACITY = 100_000;
+/**
+ * Walk the source file and flag every `state.array<T>(capacity)` allocation
+ * whose `capacity` argument is not a compile-time-resolvable positive integer
+ * within `MAX_STATE_ARRAY_CAPACITY`. This pins the bounded-execution +
+ * bounded-snapshot invariant at the compiler boundary: a non-literal capacity
+ * would make the backing ring's size — and therefore its snapshot size and
+ * per-tick rollback cost — non-deterministic.
+ *
+ * Capacity resolution reuses `resolveIndexUpperBound` + `collectConstNumberEnv`
+ * (the same machinery that sizes a series index), so a bare numeric literal,
+ * a parenthesised / unary-`±` literal, and a `const` numeric-literal binding
+ * (`const K = 20; state.array(K)`) are all accepted; a `let`, an input, or any
+ * runtime expression resolves to `null` and is rejected.
+ *
+ * Two error codes:
+ * - `state-array-capacity-not-literal` — the capacity is missing or does not
+ *   resolve to a compile-time number.
+ * - `state-array-capacity-exceeds-max` — the capacity resolves but is `<= 0`,
+ *   non-integer, or `> MAX_STATE_ARRAY_CAPACITY`.
+ *
+ * The walk runs on the **original** AST (positions match the user's source,
+ * and — running pre-injection — the capacity is `node.arguments[0]`, before
+ * the slot-id literal is injected as the leading argument). The element-access
+ * form `state["array"](cap)` is rejected upstream as
+ * `stateful-call-element-access` and never matches `"state.array"` here, so it
+ * is not double-reported. A `state.array(...)` inside a loop additionally
+ * errors `stateful-call-inside-loop`; both passes are independent.
+ *
+ * @since 1.3
+ * @example
+ *     // const diagnostics = runStateArrayCapacity(
+ *     //     sourceFile, checker, "demo.chart.ts",
+ *     // );
+ *     const fn: typeof runStateArrayCapacity = runStateArrayCapacity;
+ *     void fn;
+ */
+export function runStateArrayCapacity(sourceFile, checker, sourcePath) {
+    const diagnostics = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && resolveCalleeName(node, checker) === "state.array") {
+            const capacity = node.arguments[0];
+            if (capacity === undefined) {
+                diagnostics.push(createDiagnostic({
+                    severity: "error",
+                    code: "state-array-capacity-not-literal",
+                    message: "`state.array` requires a numeric-literal capacity (a `const` numeric binding is accepted).",
+                    file: sourcePath,
+                    node,
+                    sourceFile,
+                }));
+            }
+            else {
+                const constEnv = collectConstNumberEnv(capacity, sourceFile);
+                const bound = resolveIndexUpperBound(capacity, node, { constEnv, checker });
+                if (bound === null) {
+                    diagnostics.push(createDiagnostic({
+                        severity: "error",
+                        code: "state-array-capacity-not-literal",
+                        message: "`state.array` capacity must be a numeric literal (a `const` numeric binding is accepted), not a runtime value.",
+                        file: sourcePath,
+                        node: capacity,
+                        sourceFile,
+                    }));
+                }
+                else if (bound <= 0 ||
+                    !Number.isInteger(bound) ||
+                    bound > MAX_STATE_ARRAY_CAPACITY) {
+                    diagnostics.push(createDiagnostic({
+                        severity: "error",
+                        code: "state-array-capacity-exceeds-max",
+                        message: `\`state.array\` capacity must be a positive integer in 1..${MAX_STATE_ARRAY_CAPACITY}; got ${bound}.`,
+                        file: sourcePath,
+                        node: capacity,
+                        sourceFile,
+                    }));
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sourceFile, visit);
+    return Object.freeze(diagnostics.slice());
+}
+//# sourceMappingURL=stateArrayCapacity.js.map

package/dist/analysis/stateArrayCapacity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateArrayCapacity.js","sourceRoot":"","sources":["../../src/analysis/stateArrayCapacity.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAE/D,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAA0B,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEvF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,qBAAqB,CACjC,UAAyB,EACzB,OAAuB,EACvB,UAAkB;IAElB,MAAM,WAAW,GAAwB,EAAE,CAAC;IAE5C,MAAM,KAAK,GAAG,CAAC,IAAa,EAAQ,EAAE;QAClC,IAAI,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,aAAa,EAAE,CAAC;YAClF,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YACnC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACzB,WAAW,CAAC,IAAI,CACZ,gBAAgB,CAAC;oBACb,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,kCAAkC;oBACxC,OAAO,EACH,4FAA4F;oBAChG,IAAI,EAAE,UAAU;oBAChB,IAAI;oBACJ,UAAU;iBACb,CAAC,CACL,CAAC;YACN,CAAC;iBAAM,CAAC;gBACJ,MAAM,QAAQ,GAAG,qBAAqB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;gBAC7D,MAAM,KAAK,GAAG,sBAAsB,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;gBAC5E,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;oBACjB,WAAW,CAAC,IAAI,CACZ,gBAAgB,CAAC;wBACb,QAAQ,EAAE,OAAO;wBACjB,IAAI,EAAE,kCAAkC;wBACxC,OAAO,EACH,gHAAgH;wBACpH,IAAI,EAAE,UAAU;wBAChB,IAAI,EAAE,QAAQ;wBACd,UAAU;qBACb,CAAC,CACL,CAAC;gBACN,CAAC;qBAAM,IACH,KAAK,IAAI,CAAC;oBACV,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;oBACxB,KAAK,GAAG,wBAAwB,EAClC,CAAC;oBACC,WAAW,CAAC,IAAI,CACZ,gBAAgB,CAAC;wBACb,QAAQ,EAAE,OAAO;wBACjB,IAAI,EAAE,kCAAkC;wBACxC,OAAO,EAAE,6DAA6D,wBAAwB,SAAS,KAAK,GAAG;wBAC/G,IAAI,EAAE,UAAU;wBAChB,IAAI,EAAE,QAAQ;wBACd,UAAU;qBACb,CAAC,CACL,CAAC;gBACN,CAAC;YACL,CAAC;QACL,CAAC;QACD,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC,CAAC;IAEF,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC;AAC9C,CAAC","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 { type CompileDiagnostic, createDiagnostic } from \"../diagnostics.js\";\nimport { resolveCalleeName } from \"../transformers/resolveCallee.js\";\nimport { collectConstNumberEnv, resolveIndexUpperBound } from \"./resolveIndexBound.js\";\n\n/**\n * The largest `capacity` a `state.array<T>(capacity)` allocation may request.\n * The collection is bounded-execution-safe only because its size is fixed at\n * compile time: a hard ceiling caps memory, caps the JSON snapshot size, and —\n * crucially — caps the per-tick two-ring `Float64Array` copy the runtime does\n * on every tick rollback. `100_000` is generous (the dominant rolling-window /\n * event-log cases are ≤ a few hundred) while still keeping the snapshot and\n * the per-tick copy bounded.\n *\n * @since 1.3\n * @stable\n * @example\n *     // state.array<number>(20)        → 20 <= MAX_STATE_ARRAY_CAPACITY  (OK)\n *     // state.array<number>(1_000_000) → exceeds the cap                 (error)\n *     const cap: number = MAX_STATE_ARRAY_CAPACITY;\n *     void cap;\n */\nexport const MAX_STATE_ARRAY_CAPACITY = 100_000;\n\n/**\n * Walk the source file and flag every `state.array<T>(capacity)` allocation\n * whose `capacity` argument is not a compile-time-resolvable positive integer\n * within `MAX_STATE_ARRAY_CAPACITY`. This pins the bounded-execution +\n * bounded-snapshot invariant at the compiler boundary: a non-literal capacity\n * would make the backing ring's size — and therefore its snapshot size and\n * per-tick rollback cost — non-deterministic.\n *\n * Capacity resolution reuses `resolveIndexUpperBound` + `collectConstNumberEnv`\n * (the same machinery that sizes a series index), so a bare numeric literal,\n * a parenthesised / unary-`±` literal, and a `const` numeric-literal binding\n * (`const K = 20; state.array(K)`) are all accepted; a `let`, an input, or any\n * runtime expression resolves to `null` and is rejected.\n *\n * Two error codes:\n * - `state-array-capacity-not-literal` — the capacity is missing or does not\n *   resolve to a compile-time number.\n * - `state-array-capacity-exceeds-max` — the capacity resolves but is `<= 0`,\n *   non-integer, or `> MAX_STATE_ARRAY_CAPACITY`.\n *\n * The walk runs on the **original** AST (positions match the user's source,\n * and — running pre-injection — the capacity is `node.arguments[0]`, before\n * the slot-id literal is injected as the leading argument). The element-access\n * form `state[\"array\"](cap)` is rejected upstream as\n * `stateful-call-element-access` and never matches `\"state.array\"` here, so it\n * is not double-reported. A `state.array(...)` inside a loop additionally\n * errors `stateful-call-inside-loop`; both passes are independent.\n *\n * @since 1.3\n * @example\n *     // const diagnostics = runStateArrayCapacity(\n *     //     sourceFile, checker, \"demo.chart.ts\",\n *     // );\n *     const fn: typeof runStateArrayCapacity = runStateArrayCapacity;\n *     void fn;\n */\nexport function runStateArrayCapacity(\n    sourceFile: ts.SourceFile,\n    checker: ts.TypeChecker,\n    sourcePath: string,\n): ReadonlyArray<CompileDiagnostic> {\n    const diagnostics: CompileDiagnostic[] = [];\n\n    const visit = (node: ts.Node): void => {\n        if (ts.isCallExpression(node) && resolveCalleeName(node, checker) === \"state.array\") {\n            const capacity = node.arguments[0];\n            if (capacity === undefined) {\n                diagnostics.push(\n                    createDiagnostic({\n                        severity: \"error\",\n                        code: \"state-array-capacity-not-literal\",\n                        message:\n                            \"`state.array` requires a numeric-literal capacity (a `const` numeric binding is accepted).\",\n                        file: sourcePath,\n                        node,\n                        sourceFile,\n                    }),\n                );\n            } else {\n                const constEnv = collectConstNumberEnv(capacity, sourceFile);\n                const bound = resolveIndexUpperBound(capacity, node, { constEnv, checker });\n                if (bound === null) {\n                    diagnostics.push(\n                        createDiagnostic({\n                            severity: \"error\",\n                            code: \"state-array-capacity-not-literal\",\n                            message:\n                                \"`state.array` capacity must be a numeric literal (a `const` numeric binding is accepted), not a runtime value.\",\n                            file: sourcePath,\n                            node: capacity,\n                            sourceFile,\n                        }),\n                    );\n                } else if (\n                    bound <= 0 ||\n                    !Number.isInteger(bound) ||\n                    bound > MAX_STATE_ARRAY_CAPACITY\n                ) {\n                    diagnostics.push(\n                        createDiagnostic({\n                            severity: \"error\",\n                            code: \"state-array-capacity-exceeds-max\",\n                            message: `\\`state.array\\` capacity must be a positive integer in 1..${MAX_STATE_ARRAY_CAPACITY}; got ${bound}.`,\n                            file: sourcePath,\n                            node: capacity,\n                            sourceFile,\n                        }),\n                    );\n                }\n            }\n        }\n        ts.forEachChild(node, visit);\n    };\n\n    ts.forEachChild(sourceFile, visit);\n    return Object.freeze(diagnostics.slice());\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"}