@invinite-org/chartlang-runtime 1.1.0 → 1.2.0

package/dist/runtimeContext.d.ts

@@ -2,6 +2,8 @@ import type { AlertConditionEmission, AlertEmission, Capabilities, DrawingEmissi
 import type { AlertConditionDefinition, Bar, DrawingBucket, DrawingCounts, DrawingKind, DrawingState, SecurityBar, Series } from "@invinite-org/chartlang-core";
 import type { DepOutputStore } from "./dep/DepOutputStore.js";
 import type { PersistentStateStore } from "./persistentStateStore.js";
+import type { SecurityExprRunner } from "./request/securityExprRunner.js";
+import type { SeriesSlot } from "./state/seriesSlot.js";
 import type { StateSlot } from "./state/stateSlot.js";
 import type { StateStore } from "./stateStore.js";
 import type { StreamState } from "./streamState.js";
@@ -11,9 +13,18 @@ import type { RuntimeViews } from "./views/index.js";
  * `slotId#subId` (compiler-injected callsite id + per-bar sub-id from
  * {@link nextSubId}). `state` holds the last full {@link DrawingState}
  * emitted for the handle; subsequent `update(patch)` calls merge into
- * it and re-emit the full payload per PLAN.md §10.3. `removed: true`
+ * it and re-emit the full payload. `removed: true`
  * is sticky — further `update` / `remove` on the handle no-op.
  *
+ * `z` is the presentation-only render-order key `handle.ts`'s `splitZ`
+ * lifted out of the drawing's `state.style` (default `0`). It is stored
+ * **beside** `state` — never inside `state` / `state.style` — because
+ * the wire carries it as the top-level {@link DrawingEmission.z} field,
+ * not as part of {@link DrawingState}. It persists across bars; an
+ * `update` that does not re-specify a non-zero `z` retains it, a
+ * re-specified non-zero `z` overrides, and a cross-bar re-entry
+ * re-specifies it from the new call.
+ *
  * @since 0.3
  * @stable
  * @example
@@ -21,6 +32,7 @@ import type { RuntimeViews } from "./views/index.js";
  *     //     handleId: "x.chart.ts:1:1#0",
  *     //     kind: "line",
  *     //     state: { kind: "line", anchors: [...], style: {} },
+ *     //     z: 0,
  *     //     removed: false,
  *     // };
  */
@@ -28,6 +40,7 @@ export type DrawingSlot = {
     readonly handleId: string;
     readonly kind: DrawingKind;
     state: DrawingState;
+    z: number;
     removed: boolean;
 };
 /**
@@ -100,8 +113,8 @@ export type RuntimeContext = {
      * Per-handle drawing slot store keyed by `slotId#subId`. Allocated
      * on first `op: "create"`; mutated by `update(patch)` to merge the
      * patch into the slot's `state`; flagged `removed: true` on
-     * `remove()`. Cleared on `dispose`. Persists across bars per
-     * PLAN.md §10.3. @since 0.3
+     * `remove()`. Cleared on `dispose`. Persists across bars.
+     * @since 0.3
      */
     readonly drawingSlots: Map<string, DrawingSlot>;
     /**
@@ -138,6 +151,15 @@ export type RuntimeContext = {
      * @since 0.4
      */
     readonly stateSlots: Map<string, StateSlot<unknown>>;
+    /**
+     * Runtime `state.series` slot store keyed by
+     * `${slotIdPrefix ?? ""}${slotId}:series`. Each holds a history ring +
+     * the identity-stable script-facing view + the last committed head.
+     * The ring advances once per close (script-invisible lockstep), so
+     * `s[1]` is always one committed bar back. Cleared on `dispose` after
+     * the final snapshot captures it. @since 0.9
+     */
+    readonly seriesSlots: Map<string, SeriesSlot>;
     /**
      * Secondary candle streams keyed by `IntervalDescriptor.value`.
      * Mutated only by `createScriptRunner` mount/restore/routing. @since 0.5
@@ -167,6 +189,32 @@ export type RuntimeContext = {
      * {@link requestSecurityAlignments}. @since 0.5
      */
     readonly requestSecurityAscendingBars: Map<StreamState, ReadonlyArray<Bar>>;
+    /**
+     * Mounted HTF expression runners keyed by `slotId`. One entry per
+     * `manifest.securityExpressions` callsite. `request.security(slotId,
+     * opts, expr)` dispatches the expression overload off this registry
+     * (rather than `expr !== undefined`) and captures the callback here.
+     * Absent on dep / sibling contexts and single-timeframe scripts.
+     * Cleared on `dispose`. @since 0.7
+     */
+    securityExprRunners?: Map<string, SecurityExprRunner>;
+    /**
+     * Per-interval index into {@link securityExprRunners}, keyed by
+     * `IntervalDescriptor.value`. `driveSecurityExpressions` fans a
+     * secondary close / tick out to every runner on that interval.
+     * Absent when no expression callsites are declared. Cleared on
+     * `dispose`. @since 0.7
+     */
+    securityExprRunnersByInterval?: ReadonlyMap<string, ReadonlyArray<SecurityExprRunner>>;
+    /**
+     * Per-compute aligned expression-output series cache keyed by
+     * `slotId|interval`. Holds the stable `Series<number>` Proxy each
+     * expression-form `request.security` returns; cleared each bar
+     * (alongside {@link requestSecurityAlignments}) so the proxy re-aligns
+     * the runner's output buffer against the latest secondary buffers.
+     * @since 0.7
+     */
+    requestSecurityExprSeries?: Map<string, Series<number>>;
     /**
      * Per-`request.lowerTf` slot cache keyed by `slotId|interval`. Values are
      * stable `Series<ReadonlyArray<Bar>>` proxies over the latest LTF bucket

package/dist/runtimeContext.d.ts.map

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

package/dist/runtimeContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtimeContext.js","sourceRoot":"","sources":["../src/runtimeContext.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AA2S/D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAuC;IACtE,OAAO,EAAE,IAAI;CAChB,CAAC"}
+{"version":3,"file":"runtimeContext.js","sourceRoot":"","sources":["../src/runtimeContext.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AA2V/D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAuC;IACtE,OAAO,EAAE,IAAI;CAChB,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 type {\n    AlertConditionEmission,\n    AlertEmission,\n    Capabilities,\n    DrawingEmission,\n    LogEmission,\n    PlotEmission,\n    PlotOverride,\n    RuntimeDiagnostic,\n} from \"@invinite-org/chartlang-adapter-kit\";\nimport type {\n    AlertConditionDefinition,\n    Bar,\n    DrawingBucket,\n    DrawingCounts,\n    DrawingKind,\n    DrawingState,\n    SecurityBar,\n    Series,\n} from \"@invinite-org/chartlang-core\";\n\nimport type { DepOutputStore } from \"./dep/DepOutputStore.js\";\nimport type { PersistentStateStore } from \"./persistentStateStore.js\";\nimport type { SecurityExprRunner } from \"./request/securityExprRunner.js\";\nimport type { SeriesSlot } from \"./state/seriesSlot.js\";\nimport type { StateSlot } from \"./state/stateSlot.js\";\nimport type { StateStore } from \"./stateStore.js\";\nimport type { StreamState } from \"./streamState.js\";\nimport type { RuntimeViews } from \"./views/index.js\";\n\n/**\n * Per-handle drawing slot the runtime persists across bars. The key is\n * `slotId#subId` (compiler-injected callsite id + per-bar sub-id from\n * {@link nextSubId}). `state` holds the last full {@link DrawingState}\n * emitted for the handle; subsequent `update(patch)` calls merge into\n * it and re-emit the full payload. `removed: true`\n * is sticky — further `update` / `remove` on the handle no-op.\n *\n * `z` is the presentation-only render-order key `handle.ts`'s `splitZ`\n * lifted out of the drawing's `state.style` (default `0`). It is stored\n * **beside** `state` — never inside `state` / `state.style` — because\n * the wire carries it as the top-level {@link DrawingEmission.z} field,\n * not as part of {@link DrawingState}. It persists across bars; an\n * `update` that does not re-specify a non-zero `z` retains it, a\n * re-specified non-zero `z` overrides, and a cross-bar re-entry\n * re-specifies it from the new call.\n *\n * @since 0.3\n * @stable\n * @example\n *     // const slot: DrawingSlot = {\n *     //     handleId: \"x.chart.ts:1:1#0\",\n *     //     kind: \"line\",\n *     //     state: { kind: \"line\", anchors: [...], style: {} },\n *     //     z: 0,\n *     //     removed: false,\n *     // };\n */\nexport type DrawingSlot = {\n    readonly handleId: string;\n    readonly kind: DrawingKind;\n    state: DrawingState;\n    z: number;\n    removed: boolean;\n};\n\n/**\n * Mutable counterpart of `RunnerEmissions` (from adapter-kit) that the\n * runtime accumulates into per bar. Task 6's execution loop pushes\n * here during `compute`; `drain()` snapshots into the readonly\n * `RunnerEmissions` shape the adapter receives.\n *\n * @since 0.1\n * @example\n *     // const emissions: MutableRunnerEmissions = {\n *     //     plots: [],\n *     //     drawings: [],\n *     //     alerts: [],\n *     //     diagnostics: [],\n *     //     fromBar: 0,\n *     //     toBar: 0,\n *     // };\n */\nexport type MutableRunnerEmissions = {\n    plots: PlotEmission[];\n    drawings: DrawingEmission[];\n    alerts: AlertEmission[];\n    alertConditions?: AlertConditionEmission[];\n    logs: LogEmission[];\n    diagnostics: RuntimeDiagnostic[];\n    fromBar: number;\n    toBar: number;\n};\n\n/**\n * The contract Task 6's execution loop hands to stateful primitives\n * (Tasks 7-8) inside a single `compute` step. Tasks 7-8 read this\n * through {@link ACTIVE_RUNTIME_CONTEXT} — the runtime sets `.current`\n * around `compute` in a `try/finally`, so primitives can find their\n * series, slot store, capability bag, emission destination, and bar\n * index without an explicit argument.\n *\n * `isTick` discriminates `onBarTick` calls (head-replace mode) from\n * `onBarClose` / `onHistory` (append mode). Stateful primitives in\n * Task 7 use it to swap append vs replace-head behaviour.\n *\n * `stateSlots` stores Phase-4 `state.*` / `state.tick.*` slots keyed by\n * `${slotId}:state`; values flush into `stateStore` at close/dispose.\n *\n * `views` is a mutable container whose fields are replaced with fresh frozen\n * `barstate.*`, `syminfo.*`, and `timeframe.*` snapshots as the runner\n * advances.\n *\n * `resolvedInputs` is the frozen bag handed to `compute({ inputs })`,\n * resolved once at mount from manifest defaults plus adapter overrides.\n *\n * @since 0.1\n * @example\n *     // const ctx: RuntimeContext = {\n *     //     stream, stateStore, capabilities, emissions,\n *     //     barIndex: () => 0,\n *     //     isTick: false,\n *     // };\n */\nexport type RuntimeContext = {\n    readonly stream: StreamState;\n    readonly stateStore: StateStore;\n    readonly persistentStateStore?: PersistentStateStore;\n    lastPersistTime: number;\n    readonly capabilities: Capabilities;\n    readonly emissions: MutableRunnerEmissions;\n    readonly barIndex: () => number;\n    isTick: boolean;\n    /**\n     * Per-handle drawing slot store keyed by `slotId#subId`. Allocated\n     * on first `op: \"create\"`; mutated by `update(patch)` to merge the\n     * patch into the slot's `state`; flagged `removed: true` on\n     * `remove()`. Cleared on `dispose`. Persists across bars.\n     * @since 0.3\n     */\n    readonly drawingSlots: Map<string, DrawingSlot>;\n    /**\n     * Per-callsite per-bar sub-id counter. Each `draw.<kind>(...)` call\n     * inside a bar reads `nextSubId(ctx, slotId)`; the counter resets\n     * at the top of each `onBarClose` / `onBarTick` so iteration `i` at\n     * the same callsite yields the same `slotId#i` across bars.\n     * Cleared on `dispose`. @since 0.3\n     */\n    readonly drawingSubIdCounters: Map<string, number>;\n    /**\n     * Live per-bucket allocation tally for the current script. Each\n     * `op: \"create\"` increments the relevant bucket; each\n     * `op: \"remove\"` decrements (clamped at 0). `op: \"update\"` is\n     * free. `pushDrawing` drops the emission with\n     * `drawing-budget-exceeded` once a bucket hits its effective\n     * budget (min of adapter cap + `scriptMaxDrawings`). Reset to\n     * zero on `dispose`. @since 0.3\n     */\n    readonly drawingBucketCounters: Record<DrawingBucket, number>;\n    /**\n     * The script's per-bucket cap from `defineIndicator({ maxDrawings:\n     * ... })` / `defineDrawing({ maxDrawings: ... })`. `null` when\n     * omitted — `pushDrawing` then enforces the adapter cap alone.\n     * Effective budget is `min(scriptMaxDrawings[b],\n     * capabilities.maxDrawingsPerScript[b])`. @since 0.3\n     */\n    readonly scriptMaxDrawings: DrawingCounts | null;\n    /**\n     * Runtime `state.*` / `state.tick.*` slot store keyed by\n     * `${slotIdPrefix ?? \"\"}${slotId}:state`. Non-tick slots keep\n     * committed/tentative values; tick slots commit writes immediately.\n     * Cleared on `dispose` after flushing snapshots to `stateStore`.\n     * @since 0.4\n     */\n    readonly stateSlots: Map<string, StateSlot<unknown>>;\n    /**\n     * Runtime `state.series` slot store keyed by\n     * `${slotIdPrefix ?? \"\"}${slotId}:series`. Each holds a history ring +\n     * the identity-stable script-facing view + the last committed head.\n     * The ring advances once per close (script-invisible lockstep), so\n     * `s[1]` is always one committed bar back. Cleared on `dispose` after\n     * the final snapshot captures it. @since 0.9\n     */\n    readonly seriesSlots: Map<string, SeriesSlot>;\n    /**\n     * Secondary candle streams keyed by `IntervalDescriptor.value`.\n     * Mutated only by `createScriptRunner` mount/restore/routing. @since 0.5\n     */\n    readonly secondaryStreams: Map<string, StreamState>;\n    /**\n     * Per-`request.security` slot cache keyed by `slotId|interval`. Phase 4\n     * stores NaN fallback bars here; Phase 5 replaces the value producer with\n     * aligned secondary stream series while preserving stable identity.\n     * @since 0.4\n     */\n    readonly requestSecurityBars: Map<string, SecurityBar>;\n    /**\n     * Per-compute aligned numeric arrays keyed by\n     * `slotId|interval|sourceKey`. Cleared on main-stream close/tick before\n     * `compute` so `request.security` re-aligns against the latest\n     * secondary buffers. @since 0.5\n     */\n    readonly requestSecurityAlignments: Map<string, ReadonlyArray<number>>;\n    /**\n     * Per-compute cache of ascending `Bar[]` materialisations keyed by the\n     * source `StreamState`. Shared by `request.security` and `request.lowerTf`\n     * (via `request/streamBars.ts:ascendingBarsFor`) so a stable bar-array\n     * identity is reused across every consumer in a bar — the `getOrAlign` /\n     * `getOrBucket` WeakMap caches actually hit and the same ring buffer is\n     * walked once per bar instead of 10×. Cleared alongside\n     * {@link requestSecurityAlignments}. @since 0.5\n     */\n    readonly requestSecurityAscendingBars: Map<StreamState, ReadonlyArray<Bar>>;\n    /**\n     * Mounted HTF expression runners keyed by `slotId`. One entry per\n     * `manifest.securityExpressions` callsite. `request.security(slotId,\n     * opts, expr)` dispatches the expression overload off this registry\n     * (rather than `expr !== undefined`) and captures the callback here.\n     * Absent on dep / sibling contexts and single-timeframe scripts.\n     * Cleared on `dispose`. @since 0.7\n     */\n    securityExprRunners?: Map<string, SecurityExprRunner>;\n    /**\n     * Per-interval index into {@link securityExprRunners}, keyed by\n     * `IntervalDescriptor.value`. `driveSecurityExpressions` fans a\n     * secondary close / tick out to every runner on that interval.\n     * Absent when no expression callsites are declared. Cleared on\n     * `dispose`. @since 0.7\n     */\n    securityExprRunnersByInterval?: ReadonlyMap<string, ReadonlyArray<SecurityExprRunner>>;\n    /**\n     * Per-compute aligned expression-output series cache keyed by\n     * `slotId|interval`. Holds the stable `Series<number>` Proxy each\n     * expression-form `request.security` returns; cleared each bar\n     * (alongside {@link requestSecurityAlignments}) so the proxy re-aligns\n     * the runner's output buffer against the latest secondary buffers.\n     * @since 0.7\n     */\n    requestSecurityExprSeries?: Map<string, Series<number>>;\n    /**\n     * Per-`request.lowerTf` slot cache keyed by `slotId|interval`. Values are\n     * stable `Series<ReadonlyArray<Bar>>` proxies over the latest LTF bucket\n     * materialisation. @since 0.6\n     */\n    readonly requestLowerTfViews: Map<string, Series<ReadonlyArray<Bar>>>;\n    /**\n     * Runtime diagnostic dedupe for `request.*` capability gates, keyed by\n     * `code|slotId|interval|kind`. Cleared on `dispose`. @since 0.4\n     */\n    readonly diagnosedRequestKeys: Set<string>;\n    /**\n     * Manifest-declared alert conditions keyed by condition id. Used by\n     * `signal(conditionId, fired)` to reject unknown ids without\n     * re-reading the manifest each bar. @since 0.5\n     */\n    readonly alertConditions?: ReadonlyMap<string, AlertConditionDefinition>;\n    /**\n     * Dedupe for alert-condition capability/unknown-id diagnostics, keyed\n     * by `code|conditionId`. Cleared on dispose. @since 0.5\n     */\n    readonly diagnosedAlertConditionKeys?: Set<string>;\n    /**\n     * Number of `runtime.log.*` emissions accepted in the active compute\n     * step. Reset at the start of each close/tick. @since 0.5\n     */\n    logBudget: number;\n    /**\n     * Per-step dedupe flag for `runtime-log-budget-exceeded`. Reset with\n     * `logBudget` at the start of each close/tick. @since 0.5\n     */\n    logBudgetExceededDiagnosed: boolean;\n    /**\n     * Frozen effective input values keyed by script input name. Resolved once\n     * at mount and reused by every compute step. @since 0.4\n     */\n    resolvedInputs: Readonly<Record<string, unknown>>;\n    /**\n     * Mount-time script pane default. The runner sets it from\n     * `manifest.overlay`:\n     *   - `overlay` absent / `true` → `\"overlay\"`.\n     *   - `overlay === false` → `\"script:<sanitised(manifest.name)>\"`.\n     * `resolvePane` reads this value when a `plot()` / `hline()` call\n     * has no explicit `pane` opt.\n     * @since 0.2\n     */\n    readonly defaultPane: string;\n    /**\n     * Stable non-overlay pane key for this script. Explicit\n     * `pane: \"new\"` resolves here even when `defaultPane === \"overlay\"`\n     * so every `\"new\"` plot in a script joins one script-owned subpane.\n     * @since 0.2\n     */\n    readonly scriptPane: string;\n    /**\n     * Host-supplied per-slot presentation overrides, keyed by\n     * `PlotEmission.slotId`. Applied at emit time by `applyPlotOverride`.\n     * Mutable — `setPlotOverrides` swaps it live (presentation-only, so\n     * it does not break the frozen-input determinism guarantee). Entries\n     * themselves are frozen. @since 0.8\n     */\n    plotOverrides: Readonly<Record<string, PlotOverride>>;\n    /**\n     * Runtime diagnostic dedupe for mount-time input override failures,\n     * keyed by manifest input key. Cleared on `dispose`. @since 0.4\n     */\n    readonly diagnosedInputKeys: Set<string>;\n    /**\n     * Runtime `barstate.*`, `syminfo.*`, and `timeframe.*` views. The\n     * container is mutable; each assigned view snapshot is frozen.\n     * @since 0.4\n     */\n    readonly views: RuntimeViews;\n    /**\n     * Prefix prepended when emissions from this context flow into the\n     * parent runner's queues, and mirrored into every `stateSlots` /\n     * `StateStore` key written by `state.*` / `state.tick.*` so each\n     * runner's persisted state is isolated. `\"dep:<localId>/\"` for\n     * private dep runners, `\"export:<exportName>/\"` for sibling\n     * runners, and `\"\"` (or absent) for primary single-script and\n     * bundle-primary runners.\n     *\n     * @since 0.7\n     */\n    slotIdPrefix?: string;\n    /**\n     * `true` when this context belongs to a private dep runner — its\n     * emissions are dropped (or captured into the dep output store) by\n     * `applyDepEmissionPolicy`. `false` / absent for primary and\n     * sibling runners.\n     *\n     * @since 0.7\n     */\n    isDep?: boolean;\n    /**\n     * Per-bar titled-output buffer shared by the primary and every\n     * sibling of a `CompiledScriptBundle`. Populated by\n     * `applyDepEmissionPolicy` after each dep/sibling's compute; read\n     * by `__chartlang_depOutput` during the consumer's compute. `null`\n     * / absent for single-script runners with no deps.\n     *\n     * @since 0.7\n     */\n    depOutputStore?: DepOutputStore | null;\n};\n\n/**\n * Process-wide context slot. Task 6's `createScriptRunner` mutates\n * `.current` inside `try { ... } finally { current = null }` around\n * every `compute` invocation; Tasks 7-8 read it inside primitive\n * implementations. JavaScript's single-threaded execution model\n * guarantees only one `compute` runs at a time, so this ambient\n * slot is safe.\n *\n * The export is intentionally just a holder — no class, no methods,\n * no validation. Responsibility for setting and clearing lives in\n * Task 6.\n *\n * @since 0.1\n * @example\n *     // import { ACTIVE_RUNTIME_CONTEXT }\n *     //     from \"@invinite-org/chartlang-runtime\";\n *     // ACTIVE_RUNTIME_CONTEXT.current; // null at module load\n */\nexport const ACTIVE_RUNTIME_CONTEXT: { current: RuntimeContext | null } = {\n    current: null,\n};\n"]}

package/dist/seriesView.d.ts

@@ -2,7 +2,7 @@ import type { Series } from "@invinite-org/chartlang-core";
 import type { RingBufferLike } from "./ringBuffer.js";
 /**
  * Wrap a `RingBufferLike<T>` in the user-facing `Series<T>` Proxy shape
- * from PLAN.md §6.6. The Proxy is created **once per backing buffer**
+ *. The Proxy is created **once per backing buffer**
  * at stream/slot construction time and re-used across every bar — its
  * identity is stable so script authors can keep `const ema = ta.ema(...)`
  * at the top of `compute` and reference `ema` the same way every bar.
@@ -10,6 +10,14 @@ import type { RingBufferLike } from "./ringBuffer.js";
  * Property reads dispatch as follows:
  * - `series.current` → `buf.at(0)`
  * - `series.length` → `buf.length`
+ * - `series.valueOf` / `series[Symbol.toPrimitive]` → a function returning
+ *   `buf.at(0)`, so a numeric series coerces to its **current** value in any
+ *   value context (`series * 2`, `series > x`, `` `${series}` ``,
+ *   `Math.max(series, …)`). This is what lets `bar.close` be used both as a
+ *   scalar and indexed as a series. Coercion is harmless for non-numeric
+ *   buffers — nothing coerces those. Note `Number.isFinite(series)` is still
+ *   `false` (it does not coerce) and `series === 42` is `false` (object vs
+ *   number); use `series.current` / `+series` there.
  * - `series[n]` (string coerces to a non-negative integer) → `buf.at(n)`
  * - any other key → `undefined`
  *
@@ -30,30 +38,47 @@ import type { RingBufferLike } from "./ringBuffer.js";
  */
 export declare function makeSeriesView<T>(buf: RingBufferLike<T>): Series<T>;
 /**
- * Offset-shifted variant of {@link makeSeriesView}. `offset === 0`
- * returns the same Proxy shape (and is the identity-preserving fast
- * path callers should special-case at the call site). For
- * `offset === k > 0`, `view.current === buf.at(k)` — i.e. the value
- * `k` bars ago, matching `lib/applyOffset`'s
- * `out[i] = values[i − offset]` semantics. For `offset === -k`,
- * `view.current === buf.at(-k)` — an OOR read returning the underlying
- * sentinel (NaN for `Float64RingBuffer`, `undefined` for object
- * `RingBuffer`).
+ * Offset-tagging variant of {@link makeSeriesView}. It returns the
+ * **unshifted** view (delegating to {@link makeSeriesView}) and, for a
+ * non-zero `offset`, records `view → offset` in a module-level
+ * `WeakMap` side-table read by `plot()` via {@link seriesOffsetOf}. The
+ * offset is **presentation-only** — `view.current` is `buf.at(0)`, not a
+ * value `offset` bars ago — so both shift directions are expressible and
+ * alerts / `state.*` see the unshifted value. `offset === 0` records
+ * nothing (byte-identical to a plain {@link makeSeriesView}).
  *
- * The shift is applied on every read — no allocation, no per-bar
- * work. Callers cache the returned Proxy per `(slot, offset)` pair so
- * the view's identity stays stable across bars.
+ * Callers cache the returned view per `(slot, offset)` pair so the
+ * view's identity — and therefore its recorded offset — stays stable
+ * across bars.
  *
  * @since 0.2
+ * @stable
  * @example
- *     // import { Float64RingBuffer, makeShiftedSeriesView }
+ *     // import { Float64RingBuffer, makeShiftedSeriesView, seriesOffsetOf }
  *     //     from "@invinite-org/chartlang-runtime";
  *     // const buf = new Float64RingBuffer(8);
  *     // buf.append(10); buf.append(20); buf.append(30);
- *     // const view = makeShiftedSeriesView<number>(buf, 1);
- *     // view.current; // 20 (one bar ago)
- *     // view[0];      // 20
- *     // view[1];      // 10
+ *     // const view = makeShiftedSeriesView<number>(buf, 5);
+ *     // view.current;          // 30 (unshifted — the offset does NOT lag the read)
+ *     // seriesOffsetOf(view);  // 5 (presentation x-shift carried to the emission)
  */
 export declare function makeShiftedSeriesView<T>(buf: RingBufferLike<T>, offset: number): Series<T>;
+/**
+ * Read the presentation x-shift recorded for `series` by
+ * {@link makeShiftedSeriesView}, or `0` when the series is untagged (a
+ * plain {@link makeSeriesView} view, an `offset === 0` view, or any
+ * non-runtime Series). `plot()` calls this to populate
+ * `PlotEmission.xShift`; a `0` result omits the field so a no-offset
+ * plot stays byte-identical to today.
+ *
+ * @since 0.2
+ * @stable
+ * @example
+ *     // import { Float64RingBuffer, makeShiftedSeriesView, seriesOffsetOf }
+ *     //     from "@invinite-org/chartlang-runtime";
+ *     // const buf = new Float64RingBuffer(8);
+ *     // const shifted = makeShiftedSeriesView<number>(buf, -3);
+ *     // seriesOffsetOf(shifted); // -3
+ */
+export declare function seriesOffsetOf(series: Series<unknown>): number;
 //# sourceMappingURL=seriesView.d.ts.map

package/dist/seriesView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seriesView.d.ts","sourceRoot":"","sources":["../src/seriesView.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAoBnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAqB1F"}
+{"version":3,"file":"seriesView.d.ts","sourceRoot":"","sources":["../src/seriesView.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAuBnE;AAcD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAI1F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAE9D"}

package/dist/seriesView.js

@@ -2,7 +2,7 @@
 // See the LICENSE file in the repo root for full license text.
 /**
  * Wrap a `RingBufferLike<T>` in the user-facing `Series<T>` Proxy shape
- * from PLAN.md §6.6. The Proxy is created **once per backing buffer**
+ *. The Proxy is created **once per backing buffer**
  * at stream/slot construction time and re-used across every bar — its
  * identity is stable so script authors can keep `const ema = ta.ema(...)`
  * at the top of `compute` and reference `ema` the same way every bar.
@@ -10,6 +10,14 @@
  * Property reads dispatch as follows:
  * - `series.current` → `buf.at(0)`
  * - `series.length` → `buf.length`
+ * - `series.valueOf` / `series[Symbol.toPrimitive]` → a function returning
+ *   `buf.at(0)`, so a numeric series coerces to its **current** value in any
+ *   value context (`series * 2`, `series > x`, `` `${series}` ``,
+ *   `Math.max(series, …)`). This is what lets `bar.close` be used both as a
+ *   scalar and indexed as a series. Coercion is harmless for non-numeric
+ *   buffers — nothing coerces those. Note `Number.isFinite(series)` is still
+ *   `false` (it does not coerce) and `series === 42` is `false` (object vs
+ *   number); use `series.current` / `+series` there.
  * - `series[n]` (string coerces to a non-negative integer) → `buf.at(n)`
  * - any other key → `undefined`
  *
@@ -35,6 +43,10 @@ export function makeSeriesView(buf) {
                 return buf.at(0);
             if (prop === "length")
                 return buf.length;
+            if (prop === "valueOf")
+                return () => buf.at(0);
+            if (prop === Symbol.toPrimitive)
+                return () => buf.at(0);
             if (typeof prop === "string") {
                 const n = Number(prop);
                 if (Number.isInteger(n) && n >= 0)
@@ -45,6 +57,8 @@ export function makeSeriesView(buf) {
         has(_target, prop) {
             if (prop === "current" || prop === "length")
                 return true;
+            if (prop === "valueOf" || prop === Symbol.toPrimitive)
+                return true;
             if (typeof prop === "string") {
                 const n = Number(prop);
                 return Number.isInteger(n) && n >= 0;
@@ -54,56 +68,65 @@ export function makeSeriesView(buf) {
     });
 }
 /**
- * Offset-shifted variant of {@link makeSeriesView}. `offset === 0`
- * returns the same Proxy shape (and is the identity-preserving fast
- * path callers should special-case at the call site). For
- * `offset === k > 0`, `view.current === buf.at(k)` — i.e. the value
- * `k` bars ago, matching `lib/applyOffset`'s
- * `out[i] = values[i − offset]` semantics. For `offset === -k`,
- * `view.current === buf.at(-k)` — an OOR read returning the underlying
- * sentinel (NaN for `Float64RingBuffer`, `undefined` for object
- * `RingBuffer`).
+ * Module-level side-table recording the **presentation x-shift** declared
+ * for an offset-tagged Series view. `offset` is no longer a value-read
+ * transform (Option A, bidirectional-plot-offset): the series value is
+ * always the unshifted `buf.at(0)`; the recorded offset rides the plot
+ * emission as `PlotEmission.xShift` so the adapter renders the series
+ * shifted (`+n` right / future, `−n` left / past) without changing the
+ * numbers alerts and `state.*` see. Keyed weakly on the view object so a
+ * dropped slot's tag is collected with it.
+ */
+const seriesOffsets = new WeakMap();
+/**
+ * Offset-tagging variant of {@link makeSeriesView}. It returns the
+ * **unshifted** view (delegating to {@link makeSeriesView}) and, for a
+ * non-zero `offset`, records `view → offset` in a module-level
+ * `WeakMap` side-table read by `plot()` via {@link seriesOffsetOf}. The
+ * offset is **presentation-only** — `view.current` is `buf.at(0)`, not a
+ * value `offset` bars ago — so both shift directions are expressible and
+ * alerts / `state.*` see the unshifted value. `offset === 0` records
+ * nothing (byte-identical to a plain {@link makeSeriesView}).
  *
- * The shift is applied on every read — no allocation, no per-bar
- * work. Callers cache the returned Proxy per `(slot, offset)` pair so
- * the view's identity stays stable across bars.
+ * Callers cache the returned view per `(slot, offset)` pair so the
+ * view's identity — and therefore its recorded offset — stays stable
+ * across bars.
  *
  * @since 0.2
+ * @stable
  * @example
- *     // import { Float64RingBuffer, makeShiftedSeriesView }
+ *     // import { Float64RingBuffer, makeShiftedSeriesView, seriesOffsetOf }
  *     //     from "@invinite-org/chartlang-runtime";
  *     // const buf = new Float64RingBuffer(8);
  *     // buf.append(10); buf.append(20); buf.append(30);
- *     // const view = makeShiftedSeriesView<number>(buf, 1);
- *     // view.current; // 20 (one bar ago)
- *     // view[0];      // 20
- *     // view[1];      // 10
+ *     // const view = makeShiftedSeriesView<number>(buf, 5);
+ *     // view.current;          // 30 (unshifted — the offset does NOT lag the read)
+ *     // seriesOffsetOf(view);  // 5 (presentation x-shift carried to the emission)
  */
 export function makeShiftedSeriesView(buf, offset) {
-    if (offset === 0)
-        return makeSeriesView(buf);
-    return new Proxy({}, {
-        get(_target, prop) {
-            if (prop === "current")
-                return buf.at(offset);
-            if (prop === "length")
-                return buf.length;
-            if (typeof prop === "string") {
-                const n = Number(prop);
-                if (Number.isInteger(n) && n >= 0)
-                    return buf.at(n + offset);
-            }
-            return undefined;
-        },
-        has(_target, prop) {
-            if (prop === "current" || prop === "length")
-                return true;
-            if (typeof prop === "string") {
-                const n = Number(prop);
-                return Number.isInteger(n) && n >= 0;
-            }
-            return false;
-        },
-    });
+    const view = makeSeriesView(buf);
+    if (offset !== 0)
+        seriesOffsets.set(view, offset);
+    return view;
+}
+/**
+ * Read the presentation x-shift recorded for `series` by
+ * {@link makeShiftedSeriesView}, or `0` when the series is untagged (a
+ * plain {@link makeSeriesView} view, an `offset === 0` view, or any
+ * non-runtime Series). `plot()` calls this to populate
+ * `PlotEmission.xShift`; a `0` result omits the field so a no-offset
+ * plot stays byte-identical to today.
+ *
+ * @since 0.2
+ * @stable
+ * @example
+ *     // import { Float64RingBuffer, makeShiftedSeriesView, seriesOffsetOf }
+ *     //     from "@invinite-org/chartlang-runtime";
+ *     // const buf = new Float64RingBuffer(8);
+ *     // const shifted = makeShiftedSeriesView<number>(buf, -3);
+ *     // seriesOffsetOf(shifted); // -3
+ */
+export function seriesOffsetOf(series) {
+    return seriesOffsets.get(series) ?? 0;
 }
 //# sourceMappingURL=seriesView.js.map

package/dist/seriesView.js.map

@@ -1 +1 @@
-{"version":3,"file":"seriesView.js","sourceRoot":"","sources":["../src/seriesView.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAM/D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,cAAc,CAAI,GAAsB;IACpD,OAAO,IAAI,KAAK,CAAC,EAAe,EAAE;QAC9B,GAAG,CAAC,OAAO,EAAE,IAAI;YACb,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACzC,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAO,GAAG,CAAC,MAAM,CAAC;YACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;gBACvB,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACxD,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,GAAG,CAAC,OAAO,EAAE,IAAI;YACb,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACzD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;gBACvB,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACzC,CAAC;YACD,OAAO,KAAK,CAAC;QACjB,CAAC;KACJ,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,qBAAqB,CAAI,GAAsB,EAAE,MAAc;IAC3E,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,cAAc,CAAI,GAAG,CAAC,CAAC;IAChD,OAAO,IAAI,KAAK,CAAC,EAAe,EAAE;QAC9B,GAAG,CAAC,OAAO,EAAE,IAAI;YACb,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAO,GAAG,CAAC,MAAM,CAAC;YACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;gBACvB,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;YACjE,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,GAAG,CAAC,OAAO,EAAE,IAAI;YACb,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACzD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;gBACvB,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACzC,CAAC;YACD,OAAO,KAAK,CAAC;QACjB,CAAC;KACJ,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"seriesView.js","sourceRoot":"","sources":["../src/seriesView.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAM/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,cAAc,CAAI,GAAsB;IACpD,OAAO,IAAI,KAAK,CAAC,EAAe,EAAE;QAC9B,GAAG,CAAC,OAAO,EAAE,IAAI;YACb,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACzC,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAO,GAAG,CAAC,MAAM,CAAC;YACzC,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAC/C,IAAI,IAAI,KAAK,MAAM,CAAC,WAAW;gBAAE,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACxD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;gBACvB,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACxD,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,GAAG,CAAC,OAAO,EAAE,IAAI;YACb,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACzD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,CAAC,WAAW;gBAAE,OAAO,IAAI,CAAC;YACnE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;gBACvB,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACzC,CAAC;YACD,OAAO,KAAK,CAAC;QACjB,CAAC;KACJ,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,aAAa,GAAG,IAAI,OAAO,EAA2B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,qBAAqB,CAAI,GAAsB,EAAE,MAAc;IAC3E,MAAM,IAAI,GAAG,cAAc,CAAI,GAAG,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,CAAC;QAAE,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,MAAuB;IAClD,OAAO,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC1C,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 type { Series } from \"@invinite-org/chartlang-core\";\n\nimport type { RingBufferLike } from \"./ringBuffer.js\";\n\n/**\n * Wrap a `RingBufferLike<T>` in the user-facing `Series<T>` Proxy shape\n *. The Proxy is created **once per backing buffer**\n * at stream/slot construction time and re-used across every bar — its\n * identity is stable so script authors can keep `const ema = ta.ema(...)`\n * at the top of `compute` and reference `ema` the same way every bar.\n *\n * Property reads dispatch as follows:\n * - `series.current` → `buf.at(0)`\n * - `series.length` → `buf.length`\n * - `series.valueOf` / `series[Symbol.toPrimitive]` → a function returning\n *   `buf.at(0)`, so a numeric series coerces to its **current** value in any\n *   value context (`series * 2`, `series > x`, `` `${series}` ``,\n *   `Math.max(series, …)`). This is what lets `bar.close` be used both as a\n *   scalar and indexed as a series. Coercion is harmless for non-numeric\n *   buffers — nothing coerces those. Note `Number.isFinite(series)` is still\n *   `false` (it does not coerce) and `series === 42` is `false` (object vs\n *   number); use `series.current` / `+series` there.\n * - `series[n]` (string coerces to a non-negative integer) → `buf.at(n)`\n * - any other key → `undefined`\n *\n * For numeric buffers (`Float64RingBuffer`) out-of-range reads return\n * `NaN`; for object buffers they return `undefined`. The Proxy passes\n * the underlying sentinel through verbatim.\n *\n * @since 0.1\n * @example\n *     // import { Float64RingBuffer, makeSeriesView }\n *     //     from \"@invinite-org/chartlang-runtime\";\n *     // const buf = new Float64RingBuffer(8);\n *     // const view = makeSeriesView<number>(buf);\n *     // buf.append(42);\n *     // view.current; // 42\n *     // view[0];      // 42\n *     // view.length;  // 1\n */\nexport function makeSeriesView<T>(buf: RingBufferLike<T>): Series<T> {\n    return new Proxy({} as Series<T>, {\n        get(_target, prop) {\n            if (prop === \"current\") return buf.at(0);\n            if (prop === \"length\") return buf.length;\n            if (prop === \"valueOf\") return () => buf.at(0);\n            if (prop === Symbol.toPrimitive) return () => buf.at(0);\n            if (typeof prop === \"string\") {\n                const n = Number(prop);\n                if (Number.isInteger(n) && n >= 0) return buf.at(n);\n            }\n            return undefined;\n        },\n        has(_target, prop) {\n            if (prop === \"current\" || prop === \"length\") return true;\n            if (prop === \"valueOf\" || prop === Symbol.toPrimitive) return true;\n            if (typeof prop === \"string\") {\n                const n = Number(prop);\n                return Number.isInteger(n) && n >= 0;\n            }\n            return false;\n        },\n    });\n}\n\n/**\n * Module-level side-table recording the **presentation x-shift** declared\n * for an offset-tagged Series view. `offset` is no longer a value-read\n * transform (Option A, bidirectional-plot-offset): the series value is\n * always the unshifted `buf.at(0)`; the recorded offset rides the plot\n * emission as `PlotEmission.xShift` so the adapter renders the series\n * shifted (`+n` right / future, `−n` left / past) without changing the\n * numbers alerts and `state.*` see. Keyed weakly on the view object so a\n * dropped slot's tag is collected with it.\n */\nconst seriesOffsets = new WeakMap<Series<unknown>, number>();\n\n/**\n * Offset-tagging variant of {@link makeSeriesView}. It returns the\n * **unshifted** view (delegating to {@link makeSeriesView}) and, for a\n * non-zero `offset`, records `view → offset` in a module-level\n * `WeakMap` side-table read by `plot()` via {@link seriesOffsetOf}. The\n * offset is **presentation-only** — `view.current` is `buf.at(0)`, not a\n * value `offset` bars ago — so both shift directions are expressible and\n * alerts / `state.*` see the unshifted value. `offset === 0` records\n * nothing (byte-identical to a plain {@link makeSeriesView}).\n *\n * Callers cache the returned view per `(slot, offset)` pair so the\n * view's identity — and therefore its recorded offset — stays stable\n * across bars.\n *\n * @since 0.2\n * @stable\n * @example\n *     // import { Float64RingBuffer, makeShiftedSeriesView, seriesOffsetOf }\n *     //     from \"@invinite-org/chartlang-runtime\";\n *     // const buf = new Float64RingBuffer(8);\n *     // buf.append(10); buf.append(20); buf.append(30);\n *     // const view = makeShiftedSeriesView<number>(buf, 5);\n *     // view.current;          // 30 (unshifted — the offset does NOT lag the read)\n *     // seriesOffsetOf(view);  // 5 (presentation x-shift carried to the emission)\n */\nexport function makeShiftedSeriesView<T>(buf: RingBufferLike<T>, offset: number): Series<T> {\n    const view = makeSeriesView<T>(buf);\n    if (offset !== 0) seriesOffsets.set(view, offset);\n    return view;\n}\n\n/**\n * Read the presentation x-shift recorded for `series` by\n * {@link makeShiftedSeriesView}, or `0` when the series is untagged (a\n * plain {@link makeSeriesView} view, an `offset === 0` view, or any\n * non-runtime Series). `plot()` calls this to populate\n * `PlotEmission.xShift`; a `0` result omits the field so a no-offset\n * plot stays byte-identical to today.\n *\n * @since 0.2\n * @stable\n * @example\n *     // import { Float64RingBuffer, makeShiftedSeriesView, seriesOffsetOf }\n *     //     from \"@invinite-org/chartlang-runtime\";\n *     // const buf = new Float64RingBuffer(8);\n *     // const shifted = makeShiftedSeriesView<number>(buf, -3);\n *     // seriesOffsetOf(shifted); // -3\n */\nexport function seriesOffsetOf(series: Series<unknown>): number {\n    return seriesOffsets.get(series) ?? 0;\n}\n"]}

package/dist/state/index.d.ts

@@ -1,5 +1,6 @@
-export { commitStateSlots, flushStateSlots, restoreStateSlots, resetTentativeStateSlots, serialiseStateSlots, } from "./lifecycle.js";
+export { advanceSeriesSlots, commitSeriesSlots, commitStateSlots, flushStateSlots, resetSeriesHeads, restoreStateSlots, resetTentativeStateSlots, serialiseStateSlots, } from "./lifecycle.js";
 export type { StateSlotSnapshot } from "./lifecycle.js";
+export { isSeriesSlotSnapshotKey, restoreSeriesSlots, serialiseSeriesSlots, } from "./seriesPersistence.js";
 export { buildStateNamespace } from "./stateNamespace.js";
 export type { StateSlotSerialisers } from "./stateSlot.js";
 export { asMutableSlot, StateSlot } from "./stateSlot.js";

package/dist/state/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,GACtB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,GACtB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACH,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,GACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/state/index.js

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Invinite. Licensed under the MIT License.
 // See the LICENSE file in the repo root for full license text.
-export { commitStateSlots, flushStateSlots, restoreStateSlots, resetTentativeStateSlots, serialiseStateSlots, } from "./lifecycle.js";
+export { advanceSeriesSlots, commitSeriesSlots, commitStateSlots, flushStateSlots, resetSeriesHeads, restoreStateSlots, resetTentativeStateSlots, serialiseStateSlots, } from "./lifecycle.js";
+export { isSeriesSlotSnapshotKey, restoreSeriesSlots, serialiseSeriesSlots, } from "./seriesPersistence.js";
 export { buildStateNamespace } from "./stateNamespace.js";
 export { asMutableSlot, StateSlot } from "./stateSlot.js";
 //# sourceMappingURL=index.js.map

package/dist/state/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAE/D,OAAO,EACH,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,GACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAE/D,OAAO,EACH,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,GACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACH,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,GACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,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\nexport {\n    advanceSeriesSlots,\n    commitSeriesSlots,\n    commitStateSlots,\n    flushStateSlots,\n    resetSeriesHeads,\n    restoreStateSlots,\n    resetTentativeStateSlots,\n    serialiseStateSlots,\n} from \"./lifecycle.js\";\nexport type { StateSlotSnapshot } from \"./lifecycle.js\";\nexport {\n    isSeriesSlotSnapshotKey,\n    restoreSeriesSlots,\n    serialiseSeriesSlots,\n} from \"./seriesPersistence.js\";\nexport { buildStateNamespace } from \"./stateNamespace.js\";\nexport type { StateSlotSerialisers } from \"./stateSlot.js\";\nexport { asMutableSlot, StateSlot } from \"./stateSlot.js\";\n"]}

package/dist/state/lifecycle.d.ts

@@ -72,4 +72,44 @@ export declare function serialiseStateSlots(ctx: RuntimeContext): Readonly<Recor
  *     void restored;
  */
 export declare function restoreStateSlots(ctx: RuntimeContext, slots: Readonly<Record<string, unknown>>): void;
+/**
+ * Advance every `state.series` ring once for a new close bar — append a
+ * fresh `NaN` head so the prior committed head slides to index 1. Runs
+ * BEFORE compute on close, so a slot first allocated mid-compute (already
+ * holding its seeded head) is not present here and is not double-advanced.
+ *
+ * @since 0.9
+ * @stable
+ * @example
+ *     // advanceSeriesSlots(ctx);
+ *     const advanced = true;
+ *     void advanced;
+ */
+export declare function advanceSeriesSlots(ctx: RuntimeContext): void;
+/**
+ * Commit every `state.series` live head as its bar-close value after
+ * close compute, so the next advance retains it and a tick can reset to
+ * it.
+ *
+ * @since 0.9
+ * @stable
+ * @example
+ *     // commitSeriesSlots(ctx);
+ *     const committed = true;
+ *     void committed;
+ */
+export declare function commitSeriesSlots(ctx: RuntimeContext): void;
+/**
+ * Reset every `state.series` live head to its last committed value before
+ * tick compute, so a re-write refines from the committed baseline and a
+ * tick without a write reads the committed head. Does NOT advance length.
+ *
+ * @since 0.9
+ * @stable
+ * @example
+ *     // resetSeriesHeads(ctx);
+ *     const reset = true;
+ *     void reset;
+ */
+export declare function resetSeriesHeads(ctx: RuntimeContext): void;
 //# sourceMappingURL=lifecycle.d.ts.map

package/dist/state/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/state/lifecycle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IAC/B,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAIlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAI1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAOzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAS1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC7B,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzC,IAAI,CAKN"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/state/lifecycle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IAC/B,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAIlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAI1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAOzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAS1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC7B,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzC,IAAI,CAKN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAI5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAI3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAI1D"}

package/dist/state/lifecycle.js

@@ -1,5 +1,6 @@
 // Copyright (c) 2026 Invinite. Licensed under the MIT License.
 // See the LICENSE file in the repo root for full license text.
+import { advanceSeriesSlot, commitSeriesSlot, resetSeriesSlotHead } from "./seriesSlot.js";
 /**
  * Reset all non-`state.tick.*` tentative values before tick compute.
  *
@@ -84,4 +85,56 @@ export function restoreStateSlots(ctx, slots) {
         ctx.stateStore.set(key, value);
     }
 }
+/**
+ * Advance every `state.series` ring once for a new close bar — append a
+ * fresh `NaN` head so the prior committed head slides to index 1. Runs
+ * BEFORE compute on close, so a slot first allocated mid-compute (already
+ * holding its seeded head) is not present here and is not double-advanced.
+ *
+ * @since 0.9
+ * @stable
+ * @example
+ *     // advanceSeriesSlots(ctx);
+ *     const advanced = true;
+ *     void advanced;
+ */
+export function advanceSeriesSlots(ctx) {
+    for (const slot of ctx.seriesSlots.values()) {
+        advanceSeriesSlot(slot);
+    }
+}
+/**
+ * Commit every `state.series` live head as its bar-close value after
+ * close compute, so the next advance retains it and a tick can reset to
+ * it.
+ *
+ * @since 0.9
+ * @stable
+ * @example
+ *     // commitSeriesSlots(ctx);
+ *     const committed = true;
+ *     void committed;
+ */
+export function commitSeriesSlots(ctx) {
+    for (const slot of ctx.seriesSlots.values()) {
+        commitSeriesSlot(slot);
+    }
+}
+/**
+ * Reset every `state.series` live head to its last committed value before
+ * tick compute, so a re-write refines from the committed baseline and a
+ * tick without a write reads the committed head. Does NOT advance length.
+ *
+ * @since 0.9
+ * @stable
+ * @example
+ *     // resetSeriesHeads(ctx);
+ *     const reset = true;
+ *     void reset;
+ */
+export function resetSeriesHeads(ctx) {
+    for (const slot of ctx.seriesSlots.values()) {
+        resetSeriesSlotHead(slot);
+    }
+}
 //# sourceMappingURL=lifecycle.js.map

package/dist/state/lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/state/lifecycle.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAuB/D;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAmB;IACxD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC,SAAS,EAAE,CAAC;IACrB,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAmB;IAChD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC,UAAU,EAAE,CAAC;IACtB,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,GAAmB;IAC/C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,GAAG,CAAC,UAAU,CAAC,GAAG,CAA6B,GAAG,EAAE;YAChD,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC5B,CAAC,CAAC;IACP,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAmB;IACnD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,GAAG,CAAC,GAAG,CAAC,GAAG;YACP,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC;YACzC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC;SAC5C,CAAC;IACN,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC7B,GAAmB,EACnB,KAAwC;IAExC,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;AACL,CAAC"}
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/state/lifecycle.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAG/D,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAqB3F;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAmB;IACxD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC,SAAS,EAAE,CAAC;IACrB,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAmB;IAChD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC,UAAU,EAAE,CAAC;IACtB,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,GAAmB;IAC/C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,GAAG,CAAC,UAAU,CAAC,GAAG,CAA6B,GAAG,EAAE;YAChD,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC5B,CAAC,CAAC;IACP,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAmB;IACnD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,GAAG,CAAC,GAAG,CAAC,GAAG;YACP,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC;YACzC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC;SAC5C,CAAC;IACN,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC7B,GAAmB,EACnB,KAAwC;IAExC,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAmB;IAClD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1C,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAmB;IACjD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1C,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAmB;IAChD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1C,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;AACL,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 type { RuntimeContext } from \"../runtimeContext.js\";\nimport { advanceSeriesSlot, commitSeriesSlot, resetSeriesSlotHead } from \"./seriesSlot.js\";\n\n/**\n * Persisted representation for a runtime state slot. Keys use\n * `${slotId}:state`, matching the compiler-injected slot id plus the\n * state namespace suffix.\n *\n * @since 0.4\n * @stable\n * @example\n *     const snapshot: StateSlotSnapshot<number> = {\n *         committed: 1,\n *         tentative: 2,\n *     };\n *     void snapshot;\n */\nexport type StateSlotSnapshot<T> = {\n    readonly committed: T;\n    readonly tentative: T;\n};\n\n/**\n * Reset all non-`state.tick.*` tentative values before tick compute.\n *\n * @since 0.4\n * @stable\n * @example\n *     // resetTentativeStateSlots(ctx);\n *     const called = true;\n *     void called;\n */\nexport function resetTentativeStateSlots(ctx: RuntimeContext): void {\n    for (const slot of ctx.stateSlots.values()) {\n        slot.onBarTick();\n    }\n}\n\n/**\n * Commit all non-`state.tick.*` tentative values after close compute.\n *\n * @since 0.4\n * @stable\n * @example\n *     // commitStateSlots(ctx);\n *     const called = true;\n *     void called;\n */\nexport function commitStateSlots(ctx: RuntimeContext): void {\n    for (const slot of ctx.stateSlots.values()) {\n        slot.onBarClose();\n    }\n}\n\n/**\n * Flush runtime state slots into the backing {@link StateStore}.\n *\n * @since 0.4\n * @stable\n * @example\n *     // flushStateSlots(ctx);\n *     const called = true;\n *     void called;\n */\nexport function flushStateSlots(ctx: RuntimeContext): void {\n    for (const [key, slot] of ctx.stateSlots.entries()) {\n        ctx.stateStore.set<StateSlotSnapshot<unknown>>(key, {\n            committed: slot.committed,\n            tentative: slot.tentative,\n        });\n    }\n}\n\n/**\n * Serialise runtime state slots into a snapshot payload.\n *\n * @since 0.5\n * @stable\n * @example\n *     // const slots = serialiseStateSlots(ctx);\n *     const slots = {};\n *     void slots;\n */\nexport function serialiseStateSlots(ctx: RuntimeContext): Readonly<Record<string, unknown>> {\n    const out: Record<string, unknown> = {};\n    for (const [key, slot] of ctx.stateSlots.entries()) {\n        out[key] = {\n            committed: slot.serialise(slot.committed),\n            tentative: slot.serialise(slot.tentative),\n        };\n    }\n    return Object.freeze(out);\n}\n\n/**\n * Seed restored state-slot payloads into the backing slot store.\n *\n * @since 0.5\n * @stable\n * @example\n *     // restoreStateSlots(ctx, snapshot.slots);\n *     const restored = true;\n *     void restored;\n */\nexport function restoreStateSlots(\n    ctx: RuntimeContext,\n    slots: Readonly<Record<string, unknown>>,\n): void {\n    ctx.stateSlots.clear();\n    for (const [key, value] of Object.entries(slots)) {\n        ctx.stateStore.set(key, value);\n    }\n}\n\n/**\n * Advance every `state.series` ring once for a new close bar — append a\n * fresh `NaN` head so the prior committed head slides to index 1. Runs\n * BEFORE compute on close, so a slot first allocated mid-compute (already\n * holding its seeded head) is not present here and is not double-advanced.\n *\n * @since 0.9\n * @stable\n * @example\n *     // advanceSeriesSlots(ctx);\n *     const advanced = true;\n *     void advanced;\n */\nexport function advanceSeriesSlots(ctx: RuntimeContext): void {\n    for (const slot of ctx.seriesSlots.values()) {\n        advanceSeriesSlot(slot);\n    }\n}\n\n/**\n * Commit every `state.series` live head as its bar-close value after\n * close compute, so the next advance retains it and a tick can reset to\n * it.\n *\n * @since 0.9\n * @stable\n * @example\n *     // commitSeriesSlots(ctx);\n *     const committed = true;\n *     void committed;\n */\nexport function commitSeriesSlots(ctx: RuntimeContext): void {\n    for (const slot of ctx.seriesSlots.values()) {\n        commitSeriesSlot(slot);\n    }\n}\n\n/**\n * Reset every `state.series` live head to its last committed value before\n * tick compute, so a re-write refines from the committed baseline and a\n * tick without a write reads the committed head. Does NOT advance length.\n *\n * @since 0.9\n * @stable\n * @example\n *     // resetSeriesHeads(ctx);\n *     const reset = true;\n *     void reset;\n */\nexport function resetSeriesHeads(ctx: RuntimeContext): void {\n    for (const slot of ctx.seriesSlots.values()) {\n        resetSeriesSlotHead(slot);\n    }\n}\n"]}