@invinite-org/chartlang-compiler 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,251 @@
 # @invinite-org/chartlang-compiler
 
+## 1.3.0
+
+### Minor Changes
+
+- 850ae21: Add `bar.point(offset, price)` — index authoring sugar for anchoring drawings
+  by bar offset instead of an absolute timestamp.
+
+  `bar.point` resolves the offset to the existing time-based `WorldPoint`
+  (`{ time, price }`) at compute time, so it composes directly with every
+  `draw.*` anchor argument and introduces no new wire format or anchor union:
+
+  - `bar.point(0, price)` — the current bar.
+  - `bar.point(-n, price)` — `n` bars back, using the real historical timestamp
+    from the runtime's time ring buffer (`NaN` time past retained history; never
+    throws).
+  - `bar.point(n, price)` — a future bar, with the time extrapolated from the
+    median recent bar spacing (falling back to the parsed bar interval when
+    fewer than two bars are retained).
+
+  The compiler's max-lookback analysis now counts a negative integer-literal
+  `bar.point(-n, …)` offset toward `maxLookback` exactly like a `series[n]`
+  lookback, so the runtime sizes the time buffer deeply enough; positive (future)
+  offsets and dynamic offsets contribute no extra depth. The recogniser peels
+  parentheses, so the converter's emitted form `bar.point(-(n), …)` is sized
+  identically to a hand-written `bar.point(-n, …)` (without it, a converted
+  historical tracking line sized its buffer to 0 and resolved to a NaN anchor).
+
+  The Pine v6 converter now lowers `bar_index` drawing anchors to
+  `bar.point(<signed offset>, <price>)` and drops the dead `__BAR_INTERVAL_MS`
+  sentinel and its `bar.time ± (N * __BAR_INTERVAL_MS)` arithmetic — future
+  anchors resolve at runtime instead of needing a host-supplied bar interval.
+
+- ca19e20: Bidirectional plot `offset` — negative offsets shift a plotted series left.
+
+  `offset` becomes a presentation-only **display shift** in bars with the
+  fixed sign convention `+n` = right (future), `−n` = left (past); the
+  numeric series value is unshifted. This replaces the old value-read model
+  (where a positive offset made `series.current` read the value N bars ago
+  and a negative offset resolved to `NaN`). The `*Opts` `offset` JSDoc (and
+  ALMA's `barShift`) now describe both directions and drop the old
+  "negative ⇒ NaN" wording (`AlmaOpts.offset`, the Gaussian-centre
+  position, is unchanged).
+
+  `PlotEmission` gains an optional presentation field `xShift?: number`
+  (signed integer bars; omitted/`0` ≡ no shift, so a no-shift emission is
+  byte-identical to today). `validateEmission` rejects a non-integer
+  `xShift`. The compiler no longer counts `offset` toward `maxLookback`
+  (the value is no longer read from a deeper slot). The runtime threads the
+  declared offset onto the emission as `xShift` (reading a
+  `WeakMap<Series, number>` offset tag set by `makeShiftedSeriesView`; ALMA
+  tags `opts.barShift`) and stops the old value-read shift so
+  `series.current` is unshifted; the reference adapter renders it by
+  projecting `xShift` onto the x-axis (extending the viewport for
+  future-shifted points).
+
+  The Pine converter now maps `plot(<ta.* call>, offset=N)` onto the
+  emitted `ta.*` call's `offset` opt (signed, both directions); a plot
+  whose value is not a direct `ta.*` call drops the offset and emits the
+  new `plot-offset-needs-ta-call` warning, and a plot-level offset
+  replacing the ta call's own `offset=` emits `plot-offset-overrides-ta-offset`.
+
+  The conformance harness's `plot-field` assertion gains an `xShift` field,
+  and a new scenario pins both shift directions plus the unshifted value
+  series.
+
+- 3541445: Size series-index buffers precisely for provably-bounded indices.
+
+  `extractMaxLookback` now resolves a series read at a literal, a
+  bounded-`for` induction variable (`for (let i = 0; i < N; i++) src[i]`),
+  a `const` numeric literal, or an affine combination of those
+  (`src[i + 1]`, `src[K - i]`, `src[2 * i]`) to its exact `maxLookback`
+  contribution via a new compile-time interval resolver
+  (`resolveIndexUpperBound`) sharing one `parseBoundedForLoop` helper with
+  `forbiddenConstructs`. These indices no longer emit the
+  `dynamic-series-index` warning or force the 5000-slot `dynamicFallback`
+  buffer — they size the ring buffer exactly like a literal lookback. The
+  resolver over-approximates (never under-sizes); genuinely dynamic indices
+  (unbounded variables, unsupported operators, non-terminating loops,
+  reassigned loop variables) keep the warning + fallback. A new
+  `loop-sma` conformance scenario pins a `for`-loop SMA as bar-for-bar
+  identical to `ta.sma(close, 5)`.
+
+- 6235ad7: Make the compute bar's OHLCV + derived fields directly indexable as a series.
+
+  `bar.close`, `bar.open`, `bar.high`, `bar.low`, `bar.volume`, and the derived
+  `bar.hl2` / `bar.hlc3` / `bar.ohlc4` / `bar.hlcc4` are now `PriceSeries` /
+  `VolumeSeries` (`number & Series<number>`) on the bar passed to `compute`
+  (`ComputeContext.bar`, typed as the new `BarSeries`). Each field is **both** a
+  scalar — `bar.close * 2`, `plot(bar.close)`, `ta.ema(bar.close, 20)` keep
+  working unchanged — **and** an indexable series, so a script can read prior
+  bars directly:
+
+  ```ts
+  const sma5 =
+    (bar.close[0] + bar.close[1] + bar.close[2] + bar.close[3] + bar.close[4]) /
+    5;
+  ```
+
+  This removes the `ta.ema(bar.close, 1)` identity-trick that scripts previously
+  needed to "republish" a scalar price as an indexable `Series`.
+
+  The adapter-supplied candle type `Bar` (and `request.lowerTf` intrabar bars) is
+  unchanged — it stays scalar OHLCV; only the streaming `compute` bar gains the
+  series shape. `request.security`'s higher-timeframe bar remains the separate
+  `SecurityBar`.
+
+  Migration note: because the field is now an object, `Number.isFinite(bar.close)`
+  is always `false` (it does not coerce) and `bar.close === 42` is `false` (object
+  vs number). Use `bar.close.current` or `+bar.close` in those raw-number
+  contexts. `bar.point(0, bar.close)` continues to work — the runtime coerces the
+  anchor price to a scalar.
+
+- 3bf391a: Add the `draw.fillBetween(edgeA, edgeB, opts?)` drawing primitive — a
+  native filled ribbon between two edges (the closed polygon `edgeA`
+  forward then `edgeB` reversed). It is the chartlang equivalent of Pine's
+  `linefill.new(line1, line2, color)` / `fill(plot1, plot2)`. The
+  pine-converter now lowers static two-line `linefill.new` to it instead of
+  approximating with `draw.rotatedRectangle`, retiring the
+  `linefill-rotatedrect-approximated` diagnostic.
+- 8086003: Add an optional presentation-only `z` (render-order / z-index) option to
+  `plot()` and every `draw.*` primitive. Default `0`; higher renders on
+  top, ties fall back to the existing group + declaration order. Finite
+  numbers only. Affects stacking only — values, alerts, and `state.*` are
+  unchanged.
+
+  Adapter kit: `PlotEmission` and `DrawingEmission` gain the matching
+  presentation-only `z?: number` wire field, validated by
+  `validateEmission` as a finite number (NaN / ±Infinity rejected;
+  fractional and negative allowed). Omitted/`0` stays byte-identical to a
+  pre-feature emission, so existing goldens and conformance hashes are
+  untouched.
+
+  Runtime: `plotImpl` reads `opts.z`, and the drawing-emit path
+  (`createDrawingHandle`) lifts `z` out of `state.style` — into a shallow
+  clone with `z` removed, where the per-kind `draw.*` impls fold the opts
+  bag — and threads it onto the top-level `PlotEmission.z` /
+  `DrawingEmission.z` with the same omit-when-`0` conditional spread used
+  for `xShift`. `z` is persisted **beside** the drawing slot's `state`
+  (never inside `DrawingState`), so an `update` retains the last value. A
+  no-`z` plot or drawing emits no `z` key — byte-identical to the
+  pre-feature baseline. `draw.table` / `draw.group` do not carry `z` in
+  v1.
+
+  Pine converter: `explicit_plot_zorder` is now a recognized no-op instead
+  of an unmapped warning. chartlang already layers marks by declaration
+  order within their group (the normative ordering contract), which is
+  exactly what Pine's `explicit_plot_zorder=true` makes authoritative — so
+  the flag is satisfied by default and needs no chartlang option.
+  `mapDeclarationArgs` no longer raises `indicator-arg-not-mapped` for it;
+  instead it emits a single `explicit-plot-zorder-default` info note
+  (covering both `explicit_plot_zorder=true` and the Pine-default
+  `=false`). The converter still never _emits_ a numeric `z` — Pine has no
+  per-element z source construct. Other unmapped `indicator(...)` args
+  (`timeframe`, etc.) keep warning.
+
+  Compiler: the ambient `@invinite-org/chartlang-core` `.d.ts` shim gains a
+  `ZOrdered { z?: number }` mixin intersected into `PlotOpts` and every
+  `draw.*` option type (mirroring core's `drawingStyle.ts`), so a compiled
+  script's `plot(value, { z })` **and** `draw.*(…, { z })` type-check (the
+  shim stays in lockstep with core).
+
+  Conformance: a new `z-order` scenario pins the plot `z` →
+  `PlotEmission.z` wire contract — a `plot(value, { z: -1 })` emits
+  `z: -1`, a no-`z` plot omits the field (omit-when-`0` byte-identity), and
+  a value-hash proves `z` never transforms the series. The `plot-field`
+  assertion's `field` union widens to also accept `"z"`.
+
+- 073f41b: Add the higher-timeframe expression/callback overload to `request.security`.
+  Alongside the existing data form `request.security({ interval })` →
+  `SecurityBar`, scripts can now write `request.security({ interval }, (bar) =>
+…)` → `Series<number>`, where the callback runs on the **higher-timeframe
+  clock** — `request.security({ interval: "1W" }, (bar) => ta.ema(bar.close, 20))`
+  is a true weekly EMA(20) (20 weekly bars), not 20 main bars of a weekly-stepped
+  series. The result is aligned no-lookahead down to the main timeline.
+
+  - **core** — the `SecurityExpr` callback type (re-exported from the package
+    root), the second `security` overload, and the shared `statefulPrimitives`
+    entry annotated as covering both arities.
+  - **compiler** — records one `SecurityExpressionDescriptor { slotId, interval,
+paramName }` per expression callsite in `manifest.securityExpressions`
+    (sorted by `slotId`, omitted for the data-only form), and validates each
+    callback against the allowed subset — its `bar` parameter and body locals,
+    the ambient `ta` / `inputs`, safe `Math.*` globals, and literals — rejecting
+    any captured outer binding with the new
+    `request-security-expr-captures-local` diagnostic.
+  - **runtime** — mounts one `SecurityExprRunner` per manifest entry: the
+    callback is captured lazily on the first main compute, driven once per HTF bar
+    close through a dedicated fold `StreamState` so `ta.*` accumulate on the HTF
+    clock, and one sampled value per HTF bar feeds a per-slot output buffer that
+    `request.security(opts, expr)` returns aligned no-lookahead to the main
+    timeline. Capability / interval / stream fallbacks return an all-NaN series
+    with a deduped diagnostic.
+  - **host-worker / host-quickjs** — boot the expression form unchanged; the
+    `__manifest` sidecar already carries `securityExpressions`.
+  - **pine-converter** — Pine's `request.security(sym, "D", ta.ema(close, 9))`
+    now lowers to the chartlang callback form
+    `request.security({ interval: "1d" }, (bar) => ta.ema(bar.close, 9))` (a bare
+    OHLCV third arg keeps lowering to the data form).
+  - **conformance** — new scenarios prove the weekly expression value differs
+    from a same-length main-timeframe EMA, plus the `multiTimeframe: false` NaN
+    fallback.
+
+- 5a9c24d: Add `state.series(init)` — a writable, indexable user series. Store an
+  arbitrary value each bar (`s.value = expr`) and read its history N bars
+  back (`s[1]`). Number-coercible (`+s`, `s.current`) and usable as a `ta.*`
+  source. The Pine converter lowers a history-indexed `var` to it.
+- 08c536c: Add the `ta.highestbars` / `ta.lowestbars` primitives plus the cross-package
+  wiring that makes them usable as drawing anchors and Pine-converter targets.
+
+  - **core / runtime:** `ta.highestbars(source, length, opts?)` and
+    `ta.lowestbars(source, length, opts?)` return the bar OFFSET (≤ 0) to the
+    highest / lowest `source` value over the trailing `length` bars (window
+    INCLUDES the current bar). `0` → current bar is the extreme; `-k` → the
+    extreme occurred `k` bars ago. Ties resolve to the most recent bar; NaN
+    inputs are skipped; warmup is `length − 1` bars; tick-mode replays the
+    in-progress head as the offset-0 candidate. Registered in
+    `STATEFUL_PRIMITIVES` (now 174 entries) and `TA_REGISTRY` (now 96 entries).
+  - **compiler:** a literal-length `ta.highestbars` / `ta.lowestbars` call
+    contributes `length − 1` toward `maxLookback`, so the runtime sizes the time
+    ring buffer deep enough for a `bar.point(<that offset>, …)` anchor to resolve.
+    A non-literal length contributes 0.
+  - **pine-converter:** `ta.highestbars` / `ta.lowestbars` now map to the real
+    chartlang primitives (previously lossy passthroughs to `ta.highest` /
+    `ta.lowest`). **Behavior change:** a DYNAMIC `bar_index + <non-literal>`
+    drawing-x anchor no longer raises the hard `requires-bar-interval` error —
+    the offset is resolved by `bar.point` at runtime sign-agnostically (a
+    negative runtime offset, e.g. what `ta.highestbars` returns, resolves to the
+    historical timestamp via the time buffer). Only the literal `bar_index + N`
+    future case still requires a bar interval.
+  - **conformance:** new `TA_HIGHEST_LOWEST_BARS_SCENARIO` export pins both
+    primitives end-to-end through the compiler + runtime over the bundled
+    `goldenBars.json` fixture, and is added to `ALL_SCENARIOS`.
+
+### Patch Changes
+
+- Updated dependencies [850ae21]
+- Updated dependencies [ca19e20]
+- Updated dependencies [6235ad7]
+- Updated dependencies [3bf391a]
+- Updated dependencies [8086003]
+- Updated dependencies [850ae21]
+- Updated dependencies [073f41b]
+- Updated dependencies [5a9c24d]
+- Updated dependencies [08c536c]
+  - @invinite-org/chartlang-core@1.2.0
+
 ## 1.2.1
 
 ### Patch Changes

package/dist/analysis/extractMaxLookback.d.ts

@@ -24,7 +24,8 @@ export type ExtractMaxLookbackResult = Readonly<{
  * Walk the source file's `ElementAccessExpression` nodes and infer
  * `maxLookback` plus any `dynamicFallback` capacity from non-literal index
  * reads on Phase-1 series shapes: `bar.<ohlcv>[N]`, `ta.<name>(...)[N]`,
- * and identifier-bound series variables (`const e = ta.ema(...); e[N];`).
+ * and identifier-bound series variables (`const e = ta.ema(...); e[N];` or
+ * `const s = state.series(...); s[N];`).
  *
  * The optional `scope` parameter narrows both the series-variable
  * collection and the lookback walk to a single AST subtree (typically

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

@@ -1 +1 @@
-{"version":3,"file":"extractMaxLookback.d.ts","sourceRoot":"","sources":["../../src/analysis/extractMaxLookback.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,KAAK,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAK7E;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,WAAW,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACjD,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAC9B,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,EAAE,CAAC,IAAiB,GAC5B,wBAAwB,CAuC1B"}
+{"version":3,"file":"extractMaxLookback.d.ts","sourceRoot":"","sources":["../../src/analysis/extractMaxLookback.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,KAAK,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAO7E;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,WAAW,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACjD,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAC9B,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,EAAE,CAAC,IAAiB,GAC5B,wBAAwB,CAmD1B"}

package/dist/analysis/extractMaxLookback.js

@@ -3,12 +3,15 @@
 import ts from "typescript";
 import { createDiagnostic } from "../diagnostics.js";
 import { resolveCalleeName } from "../transformers/resolveCallee.js";
+import { unwrapParens } from "./loopBounds.js";
+import { collectConstNumberEnv, resolveIndexUpperBound } from "./resolveIndexBound.js";
 const OHLCV_FIELDS = new Set(["close", "open", "high", "low", "volume", "time"]);
 /**
  * Walk the source file's `ElementAccessExpression` nodes and infer
  * `maxLookback` plus any `dynamicFallback` capacity from non-literal index
  * reads on Phase-1 series shapes: `bar.<ohlcv>[N]`, `ta.<name>(...)[N]`,
- * and identifier-bound series variables (`const e = ta.ema(...); e[N];`).
+ * and identifier-bound series variables (`const e = ta.ema(...); e[N];` or
+ * `const s = state.series(...); s[N];`).
  *
  * The optional `scope` parameter narrows both the series-variable
  * collection and the lookback walk to a single AST subtree (typically
@@ -28,13 +31,27 @@ export function extractMaxLookback(sourceFile, checker, sourcePath, scope = sour
     const diagnostics = [];
     const seriesVarNames = collectSeriesVarNames(scope, checker);
     const visit = (node) => {
+        if (ts.isCallExpression(node)) {
+            const calleeName = resolveCalleeName(node, checker);
+            if (calleeName?.startsWith("ta.")) {
+                const barsDepth = readHighestLowestBarsDepth(calleeName, node);
+                if (barsDepth > maxLookback)
+                    maxLookback = barsDepth;
+            }
+            if (isBarPointCall(node)) {
+                const depth = readBarPointLookback(node);
+                if (depth > maxLookback)
+                    maxLookback = depth;
+            }
+        }
         if (ts.isElementAccessExpression(node)) {
             if (isSeriesShapedAccess(node, checker, seriesVarNames)) {
                 const argument = node.argumentExpression;
-                if (ts.isNumericLiteral(argument)) {
-                    const n = Number(argument.text);
-                    if (Number.isFinite(n) && n > maxLookback)
-                        maxLookback = n;
+                const constEnv = collectConstNumberEnv(argument, scope);
+                const bound = resolveIndexUpperBound(argument, node, { constEnv, checker });
+                if (bound !== null) {
+                    if (bound > maxLookback)
+                        maxLookback = bound;
                 }
                 else {
                     diagnostics.push(createDiagnostic({
@@ -58,6 +75,46 @@ export function extractMaxLookback(sourceFile, checker, sourcePath, scope = sour
         diagnostics: Object.freeze(diagnostics.slice()),
     });
 }
+/**
+ * Whether a call is a `bar.point(…)` invocation. Matched textually on the
+ * `bar.point` property-access shape — the same OHLCV-style textual recognition
+ * `isSeriesShapedAccess` uses — so it fires for both the destructured
+ * `compute({ bar })` binding and a `declare const bar: Bar` test fixture.
+ */
+function isBarPointCall(call) {
+    const expression = call.expression;
+    return (ts.isPropertyAccessExpression(expression) &&
+        expression.name.text === "point" &&
+        ts.isIdentifier(expression.expression) &&
+        expression.expression.text === "bar");
+}
+/**
+ * The historical-lookback depth a `bar.point(offset, …)` call contributes,
+ * or `0` when it reads the current / a future bar. A negative integer-literal
+ * first argument (`bar.point(-N, …)` — or the converter's parenthesised
+ * `bar.point(-(N), …)`) anchors `N` bars back, so the runtime's time ring
+ * buffer must retain `N` extra slots — exactly like a `series[N]` lookback.
+ * `bar.point(0, …)` (current) and positive offsets (future, extrapolated, no
+ * buffer depth) contribute `0`; a non-literal / dynamic offset (e.g. a bound
+ * `-k` or a computed `-(2 + 3)`) cannot be sized at compile time and also
+ * contributes `0` (reads past retention degrade to a NaN time at runtime, per
+ * `bar.point`'s contract).
+ */
+function readBarPointLookback(call) {
+    const first = call.arguments[0];
+    if (first === undefined)
+        return 0;
+    const expr = unwrapParens(first);
+    if (ts.isPrefixUnaryExpression(expr) && expr.operator === ts.SyntaxKind.MinusToken) {
+        const operand = unwrapParens(expr.operand);
+        if (ts.isNumericLiteral(operand)) {
+            const n = Number(operand.text);
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+    }
+    return 0;
+}
 function collectSeriesVarNames(scope, checker) {
     const names = new Set();
     const visit = (node) => {
@@ -65,7 +122,14 @@ function collectSeriesVarNames(scope, checker) {
             const initializer = node.initializer;
             if (initializer && ts.isCallExpression(initializer)) {
                 const calleeName = resolveCalleeName(initializer, checker);
-                if (calleeName?.startsWith("ta.")) {
+                // A `state.series(...)`-bound variable is series-shaped just
+                // like a `ta.*`-bound one: `s[N]` reads the slot's ring buffer,
+                // so its literal index must fold into `maxLookback`. Matched on
+                // the resolved callee name (the slot-injection path) so an
+                // element-access form like `state["series"](...)` is not
+                // recognised — that form is rejected upstream as
+                // `stateful-call-element-access`.
+                if (calleeName?.startsWith("ta.") || calleeName === "state.series") {
                     names.add(node.name.text);
                 }
             }
@@ -75,6 +139,26 @@ function collectSeriesVarNames(scope, checker) {
     visit(scope);
     return names;
 }
+/**
+ * The historical-lookback depth a `ta.highestbars` / `ta.lowestbars` call
+ * contributes. Both primitives return the bar OFFSET (≤ 0) to the extreme
+ * over the trailing `length`-bar window, so the deepest offset they can
+ * return is `-(length − 1)`. A downstream `bar.point(<that offset>, …)`
+ * anchor reads `time.at(length − 1)`, so the runtime's time ring buffer
+ * must retain `length − 1` slots. Only a LITERAL second positional `length`
+ * arg can be sized at compile time; a non-literal length contributes `0`.
+ */
+function readHighestLowestBarsDepth(calleeName, call) {
+    if (calleeName !== "ta.highestbars" && calleeName !== "ta.lowestbars")
+        return 0;
+    const lengthArg = call.arguments[1];
+    if (lengthArg === undefined || !ts.isNumericLiteral(lengthArg))
+        return 0;
+    const length = Number(lengthArg.text);
+    if (!Number.isFinite(length) || length <= 1)
+        return 0;
+    return length - 1;
+}
 function isSeriesShapedAccess(node, checker, seriesVarNames) {
     const expression = node.expression;
     if (ts.isPropertyAccessExpression(expression)) {

package/dist/analysis/extractMaxLookback.js.map

@@ -1 +1 @@
-{"version":3,"file":"extractMaxLookback.js","sourceRoot":"","sources":["../../src/analysis/extractMaxLookback.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 { type CompileDiagnostic, createDiagnostic } from \"../diagnostics.js\";\nimport { resolveCalleeName } from \"../transformers/resolveCallee.js\";\n\nconst OHLCV_FIELDS = new Set([\"close\", \"open\", \"high\", \"low\", \"volume\", \"time\"]);\n\n/**\n * Maximum literal lookback `N` discovered across every series read in the\n * source plus the inferred `seriesCapacities` record. `dynamicFallback`\n * captures the §6.6 contract: any non-literal series index contributes\n * `5000` so the runtime can size its ring buffers safely.\n *\n * @since 0.1\n * @example\n *     const r: ExtractMaxLookbackResult = {\n *         maxLookback: 20,\n *         seriesCapacities: {},\n *         diagnostics: [],\n *     };\n *     void r;\n */\nexport type ExtractMaxLookbackResult = Readonly<{\n    maxLookback: number;\n    seriesCapacities: Readonly<Record<string, number>>;\n    diagnostics: ReadonlyArray<CompileDiagnostic>;\n}>;\n\n/**\n * Walk the source file's `ElementAccessExpression` nodes and infer\n * `maxLookback` plus any `dynamicFallback` capacity from non-literal index\n * reads on Phase-1 series shapes: `bar.<ohlcv>[N]`, `ta.<name>(...)[N]`,\n * and identifier-bound series variables (`const e = ta.ema(...); e[N];`).\n *\n * The optional `scope` parameter narrows both the series-variable\n * collection and the lookback walk to a single AST subtree (typically\n * one binding's `defineCall`) so multi-export files derive per-binding\n * `maxLookback` values. Defaults to the whole `sourceFile`.\n *\n * @since 0.1\n * @example\n *     // const { maxLookback, seriesCapacities, diagnostics } =\n *     //     extractMaxLookback(sourceFile, checker, \"demo.chart.ts\");\n *     const fn: typeof extractMaxLookback = extractMaxLookback;\n *     void fn;\n */\nexport function extractMaxLookback(\n    sourceFile: ts.SourceFile,\n    checker: ts.TypeChecker,\n    sourcePath: string,\n    scope: ts.Node = sourceFile,\n): ExtractMaxLookbackResult {\n    let maxLookback = 0;\n    const seriesCapacities: Record<string, number> = {};\n    const diagnostics: CompileDiagnostic[] = [];\n\n    const seriesVarNames = collectSeriesVarNames(scope, checker);\n\n    const visit = (node: ts.Node): void => {\n        if (ts.isElementAccessExpression(node)) {\n            if (isSeriesShapedAccess(node, checker, seriesVarNames)) {\n                const argument = node.argumentExpression;\n                if (ts.isNumericLiteral(argument)) {\n                    const n = Number(argument.text);\n                    if (Number.isFinite(n) && n > maxLookback) maxLookback = n;\n                } else {\n                    diagnostics.push(\n                        createDiagnostic({\n                            severity: \"warning\",\n                            code: \"dynamic-series-index\",\n                            message:\n                                \"Non-literal series index — runtime will use the 5000-slot dynamic fallback buffer.\",\n                            file: sourcePath,\n                            node: argument,\n                            sourceFile,\n                        }),\n                    );\n                    seriesCapacities.dynamicFallback = 5000;\n                }\n            }\n        }\n        ts.forEachChild(node, visit);\n    };\n    visit(scope);\n\n    return Object.freeze({\n        maxLookback,\n        seriesCapacities: Object.freeze({ ...seriesCapacities }),\n        diagnostics: Object.freeze(diagnostics.slice()),\n    });\n}\n\nfunction collectSeriesVarNames(scope: ts.Node, checker: ts.TypeChecker): ReadonlySet<string> {\n    const names = new Set<string>();\n    const visit = (node: ts.Node): void => {\n        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {\n            const initializer = node.initializer;\n            if (initializer && ts.isCallExpression(initializer)) {\n                const calleeName = resolveCalleeName(initializer, checker);\n                if (calleeName?.startsWith(\"ta.\")) {\n                    names.add(node.name.text);\n                }\n            }\n        }\n        ts.forEachChild(node, visit);\n    };\n    visit(scope);\n    return names;\n}\n\nfunction isSeriesShapedAccess(\n    node: ts.ElementAccessExpression,\n    checker: ts.TypeChecker,\n    seriesVarNames: ReadonlySet<string>,\n): boolean {\n    const expression = node.expression;\n    if (ts.isPropertyAccessExpression(expression)) {\n        if (OHLCV_FIELDS.has(expression.name.text)) return true;\n    }\n    if (ts.isCallExpression(expression)) {\n        const calleeName = resolveCalleeName(expression, checker);\n        if (calleeName?.startsWith(\"ta.\")) return true;\n    }\n    if (ts.isIdentifier(expression)) {\n        if (seriesVarNames.has(expression.text)) return true;\n    }\n    return false;\n}\n"]}
+{"version":3,"file":"extractMaxLookback.js","sourceRoot":"","sources":["../../src/analysis/extractMaxLookback.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 { type CompileDiagnostic, createDiagnostic } from \"../diagnostics.js\";\nimport { resolveCalleeName } from \"../transformers/resolveCallee.js\";\nimport { unwrapParens } from \"./loopBounds.js\";\nimport { collectConstNumberEnv, resolveIndexUpperBound } from \"./resolveIndexBound.js\";\n\nconst OHLCV_FIELDS = new Set([\"close\", \"open\", \"high\", \"low\", \"volume\", \"time\"]);\n\n/**\n * Maximum literal lookback `N` discovered across every series read in the\n * source plus the inferred `seriesCapacities` record. `dynamicFallback`\n * captures the §6.6 contract: any non-literal series index contributes\n * `5000` so the runtime can size its ring buffers safely.\n *\n * @since 0.1\n * @example\n *     const r: ExtractMaxLookbackResult = {\n *         maxLookback: 20,\n *         seriesCapacities: {},\n *         diagnostics: [],\n *     };\n *     void r;\n */\nexport type ExtractMaxLookbackResult = Readonly<{\n    maxLookback: number;\n    seriesCapacities: Readonly<Record<string, number>>;\n    diagnostics: ReadonlyArray<CompileDiagnostic>;\n}>;\n\n/**\n * Walk the source file's `ElementAccessExpression` nodes and infer\n * `maxLookback` plus any `dynamicFallback` capacity from non-literal index\n * reads on Phase-1 series shapes: `bar.<ohlcv>[N]`, `ta.<name>(...)[N]`,\n * and identifier-bound series variables (`const e = ta.ema(...); e[N];` or\n * `const s = state.series(...); s[N];`).\n *\n * The optional `scope` parameter narrows both the series-variable\n * collection and the lookback walk to a single AST subtree (typically\n * one binding's `defineCall`) so multi-export files derive per-binding\n * `maxLookback` values. Defaults to the whole `sourceFile`.\n *\n * @since 0.1\n * @example\n *     // const { maxLookback, seriesCapacities, diagnostics } =\n *     //     extractMaxLookback(sourceFile, checker, \"demo.chart.ts\");\n *     const fn: typeof extractMaxLookback = extractMaxLookback;\n *     void fn;\n */\nexport function extractMaxLookback(\n    sourceFile: ts.SourceFile,\n    checker: ts.TypeChecker,\n    sourcePath: string,\n    scope: ts.Node = sourceFile,\n): ExtractMaxLookbackResult {\n    let maxLookback = 0;\n    const seriesCapacities: Record<string, number> = {};\n    const diagnostics: CompileDiagnostic[] = [];\n\n    const seriesVarNames = collectSeriesVarNames(scope, checker);\n\n    const visit = (node: ts.Node): void => {\n        if (ts.isCallExpression(node)) {\n            const calleeName = resolveCalleeName(node, checker);\n            if (calleeName?.startsWith(\"ta.\")) {\n                const barsDepth = readHighestLowestBarsDepth(calleeName, node);\n                if (barsDepth > maxLookback) maxLookback = barsDepth;\n            }\n            if (isBarPointCall(node)) {\n                const depth = readBarPointLookback(node);\n                if (depth > maxLookback) maxLookback = depth;\n            }\n        }\n        if (ts.isElementAccessExpression(node)) {\n            if (isSeriesShapedAccess(node, checker, seriesVarNames)) {\n                const argument = node.argumentExpression;\n                const constEnv = collectConstNumberEnv(argument, scope);\n                const bound = resolveIndexUpperBound(argument, node, { constEnv, checker });\n                if (bound !== null) {\n                    if (bound > maxLookback) maxLookback = bound;\n                } else {\n                    diagnostics.push(\n                        createDiagnostic({\n                            severity: \"warning\",\n                            code: \"dynamic-series-index\",\n                            message:\n                                \"Non-literal series index — runtime will use the 5000-slot dynamic fallback buffer.\",\n                            file: sourcePath,\n                            node: argument,\n                            sourceFile,\n                        }),\n                    );\n                    seriesCapacities.dynamicFallback = 5000;\n                }\n            }\n        }\n        ts.forEachChild(node, visit);\n    };\n    visit(scope);\n\n    return Object.freeze({\n        maxLookback,\n        seriesCapacities: Object.freeze({ ...seriesCapacities }),\n        diagnostics: Object.freeze(diagnostics.slice()),\n    });\n}\n\n/**\n * Whether a call is a `bar.point(…)` invocation. Matched textually on the\n * `bar.point` property-access shape — the same OHLCV-style textual recognition\n * `isSeriesShapedAccess` uses — so it fires for both the destructured\n * `compute({ bar })` binding and a `declare const bar: Bar` test fixture.\n */\nfunction isBarPointCall(call: ts.CallExpression): boolean {\n    const expression = call.expression;\n    return (\n        ts.isPropertyAccessExpression(expression) &&\n        expression.name.text === \"point\" &&\n        ts.isIdentifier(expression.expression) &&\n        expression.expression.text === \"bar\"\n    );\n}\n\n/**\n * The historical-lookback depth a `bar.point(offset, …)` call contributes,\n * or `0` when it reads the current / a future bar. A negative integer-literal\n * first argument (`bar.point(-N, …)` — or the converter's parenthesised\n * `bar.point(-(N), …)`) anchors `N` bars back, so the runtime's time ring\n * buffer must retain `N` extra slots — exactly like a `series[N]` lookback.\n * `bar.point(0, …)` (current) and positive offsets (future, extrapolated, no\n * buffer depth) contribute `0`; a non-literal / dynamic offset (e.g. a bound\n * `-k` or a computed `-(2 + 3)`) cannot be sized at compile time and also\n * contributes `0` (reads past retention degrade to a NaN time at runtime, per\n * `bar.point`'s contract).\n */\nfunction readBarPointLookback(call: ts.CallExpression): number {\n    const first = call.arguments[0];\n    if (first === undefined) return 0;\n    const expr = unwrapParens(first);\n    if (ts.isPrefixUnaryExpression(expr) && expr.operator === ts.SyntaxKind.MinusToken) {\n        const operand = unwrapParens(expr.operand);\n        if (ts.isNumericLiteral(operand)) {\n            const n = Number(operand.text);\n            if (Number.isFinite(n) && n > 0) return n;\n        }\n    }\n    return 0;\n}\n\nfunction collectSeriesVarNames(scope: ts.Node, checker: ts.TypeChecker): ReadonlySet<string> {\n    const names = new Set<string>();\n    const visit = (node: ts.Node): void => {\n        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {\n            const initializer = node.initializer;\n            if (initializer && ts.isCallExpression(initializer)) {\n                const calleeName = resolveCalleeName(initializer, checker);\n                // A `state.series(...)`-bound variable is series-shaped just\n                // like a `ta.*`-bound one: `s[N]` reads the slot's ring buffer,\n                // so its literal index must fold into `maxLookback`. Matched on\n                // the resolved callee name (the slot-injection path) so an\n                // element-access form like `state[\"series\"](...)` is not\n                // recognised — that form is rejected upstream as\n                // `stateful-call-element-access`.\n                if (calleeName?.startsWith(\"ta.\") || calleeName === \"state.series\") {\n                    names.add(node.name.text);\n                }\n            }\n        }\n        ts.forEachChild(node, visit);\n    };\n    visit(scope);\n    return names;\n}\n\n/**\n * The historical-lookback depth a `ta.highestbars` / `ta.lowestbars` call\n * contributes. Both primitives return the bar OFFSET (≤ 0) to the extreme\n * over the trailing `length`-bar window, so the deepest offset they can\n * return is `-(length − 1)`. A downstream `bar.point(<that offset>, …)`\n * anchor reads `time.at(length − 1)`, so the runtime's time ring buffer\n * must retain `length − 1` slots. Only a LITERAL second positional `length`\n * arg can be sized at compile time; a non-literal length contributes `0`.\n */\nfunction readHighestLowestBarsDepth(calleeName: string, call: ts.CallExpression): number {\n    if (calleeName !== \"ta.highestbars\" && calleeName !== \"ta.lowestbars\") return 0;\n    const lengthArg = call.arguments[1];\n    if (lengthArg === undefined || !ts.isNumericLiteral(lengthArg)) return 0;\n    const length = Number(lengthArg.text);\n    if (!Number.isFinite(length) || length <= 1) return 0;\n    return length - 1;\n}\n\nfunction isSeriesShapedAccess(\n    node: ts.ElementAccessExpression,\n    checker: ts.TypeChecker,\n    seriesVarNames: ReadonlySet<string>,\n): boolean {\n    const expression = node.expression;\n    if (ts.isPropertyAccessExpression(expression)) {\n        if (OHLCV_FIELDS.has(expression.name.text)) return true;\n    }\n    if (ts.isCallExpression(expression)) {\n        const calleeName = resolveCalleeName(expression, checker);\n        if (calleeName?.startsWith(\"ta.\")) return true;\n    }\n    if (ts.isIdentifier(expression)) {\n        if (seriesVarNames.has(expression.text)) return true;\n    }\n    return false;\n}\n"]}

package/dist/analysis/extractRequestedIntervals.d.ts

@@ -1,12 +1,54 @@
+import type { SecurityExpressionDescriptor } from "@invinite-org/chartlang-core";
 import ts from "typescript";
 import { type CompileDiagnostic } from "../diagnostics.js";
 import type { ExtractedDescriptor } from "./extractInputs.js";
+/**
+ * Combined result of the `request.*` analysis pass: the sorted, deduped list
+ * of requested intervals plus one {@link SecurityExpressionDescriptor} per
+ * `request.security({ interval }, (bar) => …)` expression callsite (sorted by
+ * `slotId`).
+ *
+ * @since 0.7
+ * @stable
+ * @example
+ *     const r: RequestAnalysis = { intervals: ["1W"], securityExpressions: [] };
+ *     void r;
+ */
+export type RequestAnalysis = Readonly<{
+    intervals: ReadonlyArray<string>;
+    securityExpressions: ReadonlyArray<SecurityExpressionDescriptor>;
+}>;
+/**
+ * Walk a script's AST and collect every static `interval` argument to
+ * `request.security({ interval: ... })` and `request.lowerTf(...)`, plus every
+ * `request.security` *expression* callsite (a second arrow/function argument).
+ * Dynamic intervals emit `request-security-interval-not-literal` (for
+ * `request.security`) or `request-lower-tf-interval-not-literal` (for
+ * `request.lowerTf`) and are excluded.
+ *
+ * Each expression callsite is recorded as a {@link SecurityExpressionDescriptor}
+ * keyed by the same `slotId` the callsite-id transformer injects (via the
+ * shared `callsiteIdFor` helper) so the runtime can match the manifest entry
+ * to the inlined callback. When `validateExpressions` is `true`, each callback
+ * is also run through {@link validateSecurityExpr}, pushing
+ * `request-security-expr-captures-local` for any out-of-subset reference.
+ *
+ * @since 0.7
+ * @stable
+ * @example
+ *     // const { intervals, securityExpressions } =
+ *     //     extractRequestAnalysis(sf, checker, inputs, diagnostics, path, true);
+ *     const fn: typeof extractRequestAnalysis = extractRequestAnalysis;
+ *     void fn;
+ */
+export declare function extractRequestAnalysis(sourceFile: ts.SourceFile, checker: ts.TypeChecker, inputs: Readonly<Record<string, ExtractedDescriptor>>, diagnostics: CompileDiagnostic[], sourcePath?: string, validateExpressions?: boolean): RequestAnalysis;
 /**
  * Walk a script's AST and collect every static `interval` argument to
  * `request.security({ interval: ... })` and `request.lowerTf(...)`. Dynamic
  * arguments emit `request-security-interval-not-literal` (for `request.security`)
  * or `request-lower-tf-interval-not-literal` (for `request.lowerTf`) and are
- * excluded.
+ * excluded. Thin delegate over {@link extractRequestAnalysis} kept for callers
+ * that only need the interval list.
  *
  * @since 0.4
  * @example

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

@@ -1 +1 @@
-{"version":3,"file":"extractRequestedIntervals.d.ts","sourceRoot":"","sources":["../../src/analysis/extractRequestedIntervals.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,KAAK,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAE7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACrC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,EACrD,WAAW,EAAE,iBAAiB,EAAE,EAChC,UAAU,GAAE,MAA4B,GACzC,aAAa,CAAC,MAAM,CAAC,CAuBvB"}
+{"version":3,"file":"extractRequestedIntervals.d.ts","sourceRoot":"","sources":["../../src/analysis/extractRequestedIntervals.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AACjF,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,KAAK,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAG7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAG9D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACnC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACjC,mBAAmB,EAAE,aAAa,CAAC,4BAA4B,CAAC,CAAC;CACpE,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAClC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,EACrD,WAAW,EAAE,iBAAiB,EAAE,EAChC,UAAU,GAAE,MAA4B,EACxC,mBAAmB,UAAQ,GAC5B,eAAe,CAuCjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACrC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,EACrD,WAAW,EAAE,iBAAiB,EAAE,EAChC,UAAU,GAAE,MAA4B,GACzC,aAAa,CAAC,MAAM,CAAC,CAEvB"}