@invinite-org/chartlang-runtime 1.0.2

package/dist/runtimeContext.d.ts

@@ -0,0 +1,238 @@
+import type { AlertConditionEmission, AlertEmission, Capabilities, DrawingEmission, LogEmission, PlotEmission, RuntimeDiagnostic } from "@invinite-org/chartlang-adapter-kit";
+import type { AlertConditionDefinition, Bar, DrawingBucket, DrawingCounts, DrawingKind, DrawingState, SecurityBar, Series } from "@invinite-org/chartlang-core";
+import type { PersistentStateStore } from "./persistentStateStore.js";
+import type { StateSlot } from "./state/stateSlot.js";
+import type { StateStore } from "./stateStore.js";
+import type { StreamState } from "./streamState.js";
+import type { RuntimeViews } from "./views/index.js";
+/**
+ * Per-handle drawing slot the runtime persists across bars. The key is
+ * `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`
+ * is sticky — further `update` / `remove` on the handle no-op.
+ *
+ * @since 0.3
+ * @stable
+ * @example
+ *     // const slot: DrawingSlot = {
+ *     //     handleId: "x.chart.ts:1:1#0",
+ *     //     kind: "line",
+ *     //     state: { kind: "line", anchors: [...], style: {} },
+ *     //     removed: false,
+ *     // };
+ */
+export type DrawingSlot = {
+    readonly handleId: string;
+    readonly kind: DrawingKind;
+    state: DrawingState;
+    removed: boolean;
+};
+/**
+ * Mutable counterpart of `RunnerEmissions` (from adapter-kit) that the
+ * runtime accumulates into per bar. Task 6's execution loop pushes
+ * here during `compute`; `drain()` snapshots into the readonly
+ * `RunnerEmissions` shape the adapter receives.
+ *
+ * @since 0.1
+ * @example
+ *     // const emissions: MutableRunnerEmissions = {
+ *     //     plots: [],
+ *     //     drawings: [],
+ *     //     alerts: [],
+ *     //     diagnostics: [],
+ *     //     fromBar: 0,
+ *     //     toBar: 0,
+ *     // };
+ */
+export type MutableRunnerEmissions = {
+    plots: PlotEmission[];
+    drawings: DrawingEmission[];
+    alerts: AlertEmission[];
+    alertConditions?: AlertConditionEmission[];
+    logs: LogEmission[];
+    diagnostics: RuntimeDiagnostic[];
+    fromBar: number;
+    toBar: number;
+};
+/**
+ * The contract Task 6's execution loop hands to stateful primitives
+ * (Tasks 7-8) inside a single `compute` step. Tasks 7-8 read this
+ * through {@link ACTIVE_RUNTIME_CONTEXT} — the runtime sets `.current`
+ * around `compute` in a `try/finally`, so primitives can find their
+ * series, slot store, capability bag, emission destination, and bar
+ * index without an explicit argument.
+ *
+ * `isTick` discriminates `onBarTick` calls (head-replace mode) from
+ * `onBarClose` / `onHistory` (append mode). Stateful primitives in
+ * Task 7 use it to swap append vs replace-head behaviour.
+ *
+ * `stateSlots` stores Phase-4 `state.*` / `state.tick.*` slots keyed by
+ * `${slotId}:state`; values flush into `stateStore` at close/dispose.
+ *
+ * `views` is a mutable container whose fields are replaced with fresh frozen
+ * `barstate.*`, `syminfo.*`, and `timeframe.*` snapshots as the runner
+ * advances.
+ *
+ * `resolvedInputs` is the frozen bag handed to `compute({ inputs })`,
+ * resolved once at mount from manifest defaults plus adapter overrides.
+ *
+ * @since 0.1
+ * @example
+ *     // const ctx: RuntimeContext = {
+ *     //     stream, stateStore, capabilities, emissions,
+ *     //     barIndex: () => 0,
+ *     //     isTick: false,
+ *     // };
+ */
+export type RuntimeContext = {
+    readonly stream: StreamState;
+    readonly stateStore: StateStore;
+    readonly persistentStateStore?: PersistentStateStore;
+    lastPersistTime: number;
+    readonly capabilities: Capabilities;
+    readonly emissions: MutableRunnerEmissions;
+    readonly barIndex: () => number;
+    isTick: boolean;
+    /**
+     * 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
+     */
+    readonly drawingSlots: Map<string, DrawingSlot>;
+    /**
+     * Per-callsite per-bar sub-id counter. Each `draw.<kind>(...)` call
+     * inside a bar reads `nextSubId(ctx, slotId)`; the counter resets
+     * at the top of each `onBarClose` / `onBarTick` so iteration `i` at
+     * the same callsite yields the same `slotId#i` across bars.
+     * Cleared on `dispose`. @since 0.3
+     */
+    readonly drawingSubIdCounters: Map<string, number>;
+    /**
+     * Live per-bucket allocation tally for the current script. Each
+     * `op: "create"` increments the relevant bucket; each
+     * `op: "remove"` decrements (clamped at 0). `op: "update"` is
+     * free. `pushDrawing` drops the emission with
+     * `drawing-budget-exceeded` once a bucket hits its effective
+     * budget (min of adapter cap + `scriptMaxDrawings`). Reset to
+     * zero on `dispose`. @since 0.3
+     */
+    readonly drawingBucketCounters: Record<DrawingBucket, number>;
+    /**
+     * The script's per-bucket cap from `defineIndicator({ maxDrawings:
+     * ... })` / `defineDrawing({ maxDrawings: ... })`. `null` when
+     * omitted — `pushDrawing` then enforces the adapter cap alone.
+     * Effective budget is `min(scriptMaxDrawings[b],
+     * capabilities.maxDrawingsPerScript[b])`. @since 0.3
+     */
+    readonly scriptMaxDrawings: DrawingCounts | null;
+    /**
+     * Runtime `state.*` / `state.tick.*` slot store keyed by
+     * `${slotId}:state`. Non-tick slots keep committed/tentative values;
+     * tick slots commit writes immediately. Cleared on `dispose` after
+     * flushing snapshots to `stateStore`. @since 0.4
+     */
+    readonly stateSlots: Map<string, StateSlot<unknown>>;
+    /**
+     * Secondary candle streams keyed by `IntervalDescriptor.value`.
+     * Mutated only by `createScriptRunner` mount/restore/routing. @since 0.5
+     */
+    readonly secondaryStreams: Map<string, StreamState>;
+    /**
+     * Per-`request.security` slot cache keyed by `slotId|interval`. Phase 4
+     * stores NaN fallback bars here; Phase 5 replaces the value producer with
+     * aligned secondary stream series while preserving stable identity.
+     * @since 0.4
+     */
+    readonly requestSecurityBars: Map<string, SecurityBar>;
+    /**
+     * Per-compute aligned numeric arrays keyed by
+     * `slotId|interval|sourceKey`. Cleared on main-stream close/tick before
+     * `compute` so `request.security` re-aligns against the latest
+     * secondary buffers. @since 0.5
+     */
+    readonly requestSecurityAlignments: Map<string, ReadonlyArray<number>>;
+    /**
+     * Per-compute cache of ascending `Bar[]` materialisations keyed by the
+     * source `StreamState`. Shared by `request.security` and `request.lowerTf`
+     * (via `request/streamBars.ts:ascendingBarsFor`) so a stable bar-array
+     * identity is reused across every consumer in a bar — the `getOrAlign` /
+     * `getOrBucket` WeakMap caches actually hit and the same ring buffer is
+     * walked once per bar instead of 10×. Cleared alongside
+     * {@link requestSecurityAlignments}. @since 0.5
+     */
+    readonly requestSecurityAscendingBars: Map<StreamState, ReadonlyArray<Bar>>;
+    /**
+     * Per-`request.lowerTf` slot cache keyed by `slotId|interval`. Values are
+     * stable `Series<ReadonlyArray<Bar>>` proxies over the latest LTF bucket
+     * materialisation. @since 0.6
+     */
+    readonly requestLowerTfViews: Map<string, Series<ReadonlyArray<Bar>>>;
+    /**
+     * Runtime diagnostic dedupe for `request.*` capability gates, keyed by
+     * `code|slotId|interval|kind`. Cleared on `dispose`. @since 0.4
+     */
+    readonly diagnosedRequestKeys: Set<string>;
+    /**
+     * Manifest-declared alert conditions keyed by condition id. Used by
+     * `signal(conditionId, fired)` to reject unknown ids without
+     * re-reading the manifest each bar. @since 0.5
+     */
+    readonly alertConditions?: ReadonlyMap<string, AlertConditionDefinition>;
+    /**
+     * Dedupe for alert-condition capability/unknown-id diagnostics, keyed
+     * by `code|conditionId`. Cleared on dispose. @since 0.5
+     */
+    readonly diagnosedAlertConditionKeys?: Set<string>;
+    /**
+     * Number of `runtime.log.*` emissions accepted in the active compute
+     * step. Reset at the start of each close/tick. @since 0.5
+     */
+    logBudget: number;
+    /**
+     * Per-step dedupe flag for `runtime-log-budget-exceeded`. Reset with
+     * `logBudget` at the start of each close/tick. @since 0.5
+     */
+    logBudgetExceededDiagnosed: boolean;
+    /**
+     * Frozen effective input values keyed by script input name. Resolved once
+     * at mount and reused by every compute step. @since 0.4
+     */
+    resolvedInputs: Readonly<Record<string, unknown>>;
+    /**
+     * Runtime diagnostic dedupe for mount-time input override failures,
+     * keyed by manifest input key. Cleared on `dispose`. @since 0.4
+     */
+    readonly diagnosedInputKeys: Set<string>;
+    /**
+     * Runtime `barstate.*`, `syminfo.*`, and `timeframe.*` views. The
+     * container is mutable; each assigned view snapshot is frozen.
+     * @since 0.4
+     */
+    readonly views: RuntimeViews;
+};
+/**
+ * Process-wide context slot. Task 6's `createScriptRunner` mutates
+ * `.current` inside `try { ... } finally { current = null }` around
+ * every `compute` invocation; Tasks 7-8 read it inside primitive
+ * implementations. JavaScript's single-threaded execution model
+ * guarantees only one `compute` runs at a time, so this ambient
+ * slot is safe.
+ *
+ * The export is intentionally just a holder — no class, no methods,
+ * no validation. Responsibility for setting and clearing lives in
+ * Task 6.
+ *
+ * @since 0.1
+ * @example
+ *     // import { ACTIVE_RUNTIME_CONTEXT }
+ *     //     from "@invinite-org/chartlang-runtime";
+ *     // ACTIVE_RUNTIME_CONTEXT.current; // null at module load
+ */
+export declare const ACTIVE_RUNTIME_CONTEXT: {
+    current: RuntimeContext | null;
+};
+//# sourceMappingURL=runtimeContext.d.ts.map

package/dist/runtimeContext.d.ts.map

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

package/dist/runtimeContext.js

@@ -0,0 +1,24 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+/**
+ * Process-wide context slot. Task 6's `createScriptRunner` mutates
+ * `.current` inside `try { ... } finally { current = null }` around
+ * every `compute` invocation; Tasks 7-8 read it inside primitive
+ * implementations. JavaScript's single-threaded execution model
+ * guarantees only one `compute` runs at a time, so this ambient
+ * slot is safe.
+ *
+ * The export is intentionally just a holder — no class, no methods,
+ * no validation. Responsibility for setting and clearing lives in
+ * Task 6.
+ *
+ * @since 0.1
+ * @example
+ *     // import { ACTIVE_RUNTIME_CONTEXT }
+ *     //     from "@invinite-org/chartlang-runtime";
+ *     // ACTIVE_RUNTIME_CONTEXT.current; // null at module load
+ */
+export const ACTIVE_RUNTIME_CONTEXT = {
+    current: null,
+};
+//# sourceMappingURL=runtimeContext.js.map

package/dist/runtimeContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeContext.js","sourceRoot":"","sources":["../src/runtimeContext.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAgP/D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAuC;IACtE,OAAO,EAAE,IAAI;CAChB,CAAC"}

package/dist/seriesView.d.ts

@@ -0,0 +1,59 @@
+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**
+ * 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.
+ *
+ * Property reads dispatch as follows:
+ * - `series.current` → `buf.at(0)`
+ * - `series.length` → `buf.length`
+ * - `series[n]` (string coerces to a non-negative integer) → `buf.at(n)`
+ * - any other key → `undefined`
+ *
+ * For numeric buffers (`Float64RingBuffer`) out-of-range reads return
+ * `NaN`; for object buffers they return `undefined`. The Proxy passes
+ * the underlying sentinel through verbatim.
+ *
+ * @since 0.1
+ * @example
+ *     // import { Float64RingBuffer, makeSeriesView }
+ *     //     from "@invinite-org/chartlang-runtime";
+ *     // const buf = new Float64RingBuffer(8);
+ *     // const view = makeSeriesView<number>(buf);
+ *     // buf.append(42);
+ *     // view.current; // 42
+ *     // view[0];      // 42
+ *     // view.length;  // 1
+ */
+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`).
+ *
+ * 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.
+ *
+ * @since 0.2
+ * @example
+ *     // import { Float64RingBuffer, makeShiftedSeriesView }
+ *     //     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
+ */
+export declare function makeShiftedSeriesView<T>(buf: RingBufferLike<T>, offset: number): Series<T>;
+//# sourceMappingURL=seriesView.d.ts.map

package/dist/seriesView.d.ts.map

@@ -0,0 +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"}

package/dist/seriesView.js

@@ -0,0 +1,109 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// 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**
+ * 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.
+ *
+ * Property reads dispatch as follows:
+ * - `series.current` → `buf.at(0)`
+ * - `series.length` → `buf.length`
+ * - `series[n]` (string coerces to a non-negative integer) → `buf.at(n)`
+ * - any other key → `undefined`
+ *
+ * For numeric buffers (`Float64RingBuffer`) out-of-range reads return
+ * `NaN`; for object buffers they return `undefined`. The Proxy passes
+ * the underlying sentinel through verbatim.
+ *
+ * @since 0.1
+ * @example
+ *     // import { Float64RingBuffer, makeSeriesView }
+ *     //     from "@invinite-org/chartlang-runtime";
+ *     // const buf = new Float64RingBuffer(8);
+ *     // const view = makeSeriesView<number>(buf);
+ *     // buf.append(42);
+ *     // view.current; // 42
+ *     // view[0];      // 42
+ *     // view.length;  // 1
+ */
+export function makeSeriesView(buf) {
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (prop === "current")
+                return buf.at(0);
+            if (prop === "length")
+                return buf.length;
+            if (typeof prop === "string") {
+                const n = Number(prop);
+                if (Number.isInteger(n) && n >= 0)
+                    return buf.at(n);
+            }
+            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;
+        },
+    });
+}
+/**
+ * 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`).
+ *
+ * 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.
+ *
+ * @since 0.2
+ * @example
+ *     // import { Float64RingBuffer, makeShiftedSeriesView }
+ *     //     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
+ */
+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;
+        },
+    });
+}
+//# sourceMappingURL=seriesView.js.map

package/dist/seriesView.js.map

@@ -0,0 +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"}

package/dist/state/index.d.ts

@@ -0,0 +1,6 @@
+export { commitStateSlots, flushStateSlots, restoreStateSlots, resetTentativeStateSlots, serialiseStateSlots, } from "./lifecycle.js";
+export type { StateSlotSnapshot } from "./lifecycle.js";
+export { buildStateNamespace } from "./stateNamespace.js";
+export type { StateSlotSerialisers } from "./stateSlot.js";
+export { asMutableSlot, StateSlot } from "./stateSlot.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/state/index.js

@@ -0,0 +1,6 @@
+// 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 { buildStateNamespace } from "./stateNamespace.js";
+export { asMutableSlot, StateSlot } from "./stateSlot.js";
+//# sourceMappingURL=index.js.map

package/dist/state/index.js.map

@@ -0,0 +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"}

package/dist/state/lifecycle.d.ts

@@ -0,0 +1,75 @@
+import type { RuntimeContext } from "../runtimeContext.js";
+/**
+ * Persisted representation for a runtime state slot. Keys use
+ * `${slotId}:state`, matching the compiler-injected slot id plus the
+ * state namespace suffix.
+ *
+ * @since 0.4
+ * @stable
+ * @example
+ *     const snapshot: StateSlotSnapshot<number> = {
+ *         committed: 1,
+ *         tentative: 2,
+ *     };
+ *     void snapshot;
+ */
+export type StateSlotSnapshot<T> = {
+    readonly committed: T;
+    readonly tentative: T;
+};
+/**
+ * Reset all non-`state.tick.*` tentative values before tick compute.
+ *
+ * @since 0.4
+ * @stable
+ * @example
+ *     // resetTentativeStateSlots(ctx);
+ *     const called = true;
+ *     void called;
+ */
+export declare function resetTentativeStateSlots(ctx: RuntimeContext): void;
+/**
+ * Commit all non-`state.tick.*` tentative values after close compute.
+ *
+ * @since 0.4
+ * @stable
+ * @example
+ *     // commitStateSlots(ctx);
+ *     const called = true;
+ *     void called;
+ */
+export declare function commitStateSlots(ctx: RuntimeContext): void;
+/**
+ * Flush runtime state slots into the backing {@link StateStore}.
+ *
+ * @since 0.4
+ * @stable
+ * @example
+ *     // flushStateSlots(ctx);
+ *     const called = true;
+ *     void called;
+ */
+export declare function flushStateSlots(ctx: RuntimeContext): void;
+/**
+ * Serialise runtime state slots into a snapshot payload.
+ *
+ * @since 0.5
+ * @stable
+ * @example
+ *     // const slots = serialiseStateSlots(ctx);
+ *     const slots = {};
+ *     void slots;
+ */
+export declare function serialiseStateSlots(ctx: RuntimeContext): Readonly<Record<string, unknown>>;
+/**
+ * Seed restored state-slot payloads into the backing slot store.
+ *
+ * @since 0.5
+ * @stable
+ * @example
+ *     // restoreStateSlots(ctx, snapshot.slots);
+ *     const restored = true;
+ *     void restored;
+ */
+export declare function restoreStateSlots(ctx: RuntimeContext, slots: Readonly<Record<string, unknown>>): void;
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +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"}

package/dist/state/lifecycle.js

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+/**
+ * Reset all non-`state.tick.*` tentative values before tick compute.
+ *
+ * @since 0.4
+ * @stable
+ * @example
+ *     // resetTentativeStateSlots(ctx);
+ *     const called = true;
+ *     void called;
+ */
+export function resetTentativeStateSlots(ctx) {
+    for (const slot of ctx.stateSlots.values()) {
+        slot.onBarTick();
+    }
+}
+/**
+ * Commit all non-`state.tick.*` tentative values after close compute.
+ *
+ * @since 0.4
+ * @stable
+ * @example
+ *     // commitStateSlots(ctx);
+ *     const called = true;
+ *     void called;
+ */
+export function commitStateSlots(ctx) {
+    for (const slot of ctx.stateSlots.values()) {
+        slot.onBarClose();
+    }
+}
+/**
+ * Flush runtime state slots into the backing {@link StateStore}.
+ *
+ * @since 0.4
+ * @stable
+ * @example
+ *     // flushStateSlots(ctx);
+ *     const called = true;
+ *     void called;
+ */
+export function flushStateSlots(ctx) {
+    for (const [key, slot] of ctx.stateSlots.entries()) {
+        ctx.stateStore.set(key, {
+            committed: slot.committed,
+            tentative: slot.tentative,
+        });
+    }
+}
+/**
+ * Serialise runtime state slots into a snapshot payload.
+ *
+ * @since 0.5
+ * @stable
+ * @example
+ *     // const slots = serialiseStateSlots(ctx);
+ *     const slots = {};
+ *     void slots;
+ */
+export function serialiseStateSlots(ctx) {
+    const out = {};
+    for (const [key, slot] of ctx.stateSlots.entries()) {
+        out[key] = {
+            committed: slot.serialise(slot.committed),
+            tentative: slot.serialise(slot.tentative),
+        };
+    }
+    return Object.freeze(out);
+}
+/**
+ * Seed restored state-slot payloads into the backing slot store.
+ *
+ * @since 0.5
+ * @stable
+ * @example
+ *     // restoreStateSlots(ctx, snapshot.slots);
+ *     const restored = true;
+ *     void restored;
+ */
+export function restoreStateSlots(ctx, slots) {
+    ctx.stateSlots.clear();
+    for (const [key, value] of Object.entries(slots)) {
+        ctx.stateStore.set(key, value);
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/state/lifecycle.js.map

@@ -0,0 +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"}

package/dist/state/stateNamespace.d.ts

@@ -0,0 +1,14 @@
+import type { StateNamespace } from "@invinite-org/chartlang-core";
+/**
+ * Build the runtime `state` namespace installed on `ComputeContext`.
+ * Each function accepts the compiler-injected `slotId` as its first
+ * parameter, then the script-facing init value.
+ *
+ * @since 0.4
+ * @stable
+ * @example
+ *     const ns = buildStateNamespace();
+ *     void ns.float;
+ */
+export declare function buildStateNamespace(): StateNamespace;
+//# sourceMappingURL=stateNamespace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stateNamespace.d.ts","sourceRoot":"","sources":["../../src/state/stateNamespace.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,8BAA8B,CAAC;AA0ChF;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAwBpD"}