@invinite-org/chartlang-runtime 1.1.1 → 1.3.0

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","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[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 (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 (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 * Offset-shifted variant of {@link makeSeriesView}. `offset === 0`\n * returns the same Proxy shape (and is the identity-preserving fast\n * path callers should special-case at the call site). For\n * `offset === k > 0`, `view.current === buf.at(k)` — i.e. the value\n * `k` bars ago, matching `lib/applyOffset`'s\n * `out[i] = values[i − offset]` semantics. For `offset === -k`,\n * `view.current === buf.at(-k)` — an OOR read returning the underlying\n * sentinel (NaN for `Float64RingBuffer`, `undefined` for object\n * `RingBuffer`).\n *\n * The shift is applied on every read — no allocation, no per-bar\n * work. Callers cache the returned Proxy per `(slot, offset)` pair so\n * the view's identity stays stable across bars.\n *\n * @since 0.2\n * @example\n *     // import { Float64RingBuffer, makeShiftedSeriesView }\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, 1);\n *     // view.current; // 20 (one bar ago)\n *     // view[0];      // 20\n *     // view[1];      // 10\n */\nexport function makeShiftedSeriesView<T>(buf: RingBufferLike<T>, offset: number): Series<T> {\n    if (offset === 0) return makeSeriesView<T>(buf);\n    return new Proxy({} as Series<T>, {\n        get(_target, prop) {\n            if (prop === \"current\") return buf.at(offset);\n            if (prop === \"length\") return buf.length;\n            if (typeof prop === \"string\") {\n                const n = Number(prop);\n                if (Number.isInteger(n) && n >= 0) return buf.at(n + offset);\n            }\n            return undefined;\n        },\n        has(_target, prop) {\n            if (prop === \"current\" || prop === \"length\") 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"]}
+{"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/arrayPersistence.d.ts

@@ -0,0 +1,48 @@
+import type { JsonValue } from "@invinite-org/chartlang-core";
+import type { RuntimeContext } from "../runtimeContext.js";
+/**
+ * Return whether a snapshot slot key belongs to the `state.array` namespace
+ * (a `${slotIdPrefix}${slotId}:array` key). Lets the restore router separate
+ * array slots from scalar `state.*` (`:state`), `state.series` (`:series`), and
+ * `ta.*` (`ta:`) slots, all of which share one `slots` record.
+ *
+ * @since 1.3
+ * @internal
+ * @stable
+ * @example
+ *     isArraySlotSnapshotKey("x.chart.ts:1:1:array"); // true
+ */
+export declare function isArraySlotSnapshotKey(key: string): boolean;
+/**
+ * Serialise the runner's `state.array` slots into JSON-clean snapshot entries
+ * keyed by the same `${prefix}${slotId}:array` key the slot store uses. Both
+ * rings ride {@link Float64RingBuffer.serialiseSnapshotBuffer}; `capacity` is
+ * recorded so restore can detect a script-edited capacity and degrade.
+ *
+ * @since 1.3
+ * @internal
+ * @stable
+ * @example
+ *     // const entries = serialiseArraySlots(ctx);
+ *     const entries = {};
+ *     void entries;
+ */
+export declare function serialiseArraySlots(ctx: RuntimeContext): Readonly<Record<string, JsonValue>>;
+/**
+ * Restore `state.array` slots from namespaced snapshot entries into
+ * `ctx.arraySlots`, rebuilding each ring at the *persisted* `capacity`. Non-array
+ * keys are ignored; a malformed snapshot — or one whose ring shape no longer
+ * matches its recorded `capacity` — is skipped so the slot starts fresh (a
+ * script-edited `state.array(cap)` literal degrades, it does not throw). The
+ * handle identity is recreated on restore (acceptable — same as `state.series`).
+ *
+ * @since 1.3
+ * @internal
+ * @stable
+ * @example
+ *     // restoreArraySlots(ctx, snapshot.slots);
+ *     const restored = true;
+ *     void restored;
+ */
+export declare function restoreArraySlots(ctx: RuntimeContext, slots: Readonly<Record<string, unknown>>): void;
+//# sourceMappingURL=arrayPersistence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arrayPersistence.d.ts","sourceRoot":"","sources":["../../src/state/arrayPersistence.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAS9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAM3D;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAW5F;AAaD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC7B,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzC,IAAI,CASN"}

package/dist/state/arrayPersistence.js

@@ -0,0 +1,88 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+import { isBufferSnapshot, isInteger, isRecord, restoreBuffer, serialiseBuffer, } from "../bufferSnapshot.js";
+import { restoreArrayStateSlot } from "./arrayStateSlot.js";
+const ARRAY_SLOT_SUFFIX = ":array";
+/**
+ * Return whether a snapshot slot key belongs to the `state.array` namespace
+ * (a `${slotIdPrefix}${slotId}:array` key). Lets the restore router separate
+ * array slots from scalar `state.*` (`:state`), `state.series` (`:series`), and
+ * `ta.*` (`ta:`) slots, all of which share one `slots` record.
+ *
+ * @since 1.3
+ * @internal
+ * @stable
+ * @example
+ *     isArraySlotSnapshotKey("x.chart.ts:1:1:array"); // true
+ */
+export function isArraySlotSnapshotKey(key) {
+    return key.endsWith(ARRAY_SLOT_SUFFIX);
+}
+/**
+ * Serialise the runner's `state.array` slots into JSON-clean snapshot entries
+ * keyed by the same `${prefix}${slotId}:array` key the slot store uses. Both
+ * rings ride {@link Float64RingBuffer.serialiseSnapshotBuffer}; `capacity` is
+ * recorded so restore can detect a script-edited capacity and degrade.
+ *
+ * @since 1.3
+ * @internal
+ * @stable
+ * @example
+ *     // const entries = serialiseArraySlots(ctx);
+ *     const entries = {};
+ *     void entries;
+ */
+export function serialiseArraySlots(ctx) {
+    const out = {};
+    for (const [key, slot] of ctx.arraySlots.entries()) {
+        out[key] = {
+            kind: "state.array",
+            capacity: slot.capacity,
+            committed: serialiseBuffer(slot.committedRing),
+            tentative: serialiseBuffer(slot.tentativeRing),
+        };
+    }
+    return Object.freeze(out);
+}
+function restoreArraySlotSnapshot(snapshot) {
+    if (!isRecord(snapshot) || snapshot.kind !== "state.array")
+        return null;
+    if (!isInteger(snapshot.capacity) || snapshot.capacity <= 0)
+        return null;
+    const { committed, tentative } = snapshot;
+    if (!isBufferSnapshot(committed) || !isBufferSnapshot(tentative))
+        return null;
+    const committedRing = restoreBuffer(committed, snapshot.capacity);
+    const tentativeRing = restoreBuffer(tentative, snapshot.capacity);
+    if (committedRing === null || tentativeRing === null)
+        return null;
+    return restoreArrayStateSlot(committedRing, tentativeRing);
+}
+/**
+ * Restore `state.array` slots from namespaced snapshot entries into
+ * `ctx.arraySlots`, rebuilding each ring at the *persisted* `capacity`. Non-array
+ * keys are ignored; a malformed snapshot — or one whose ring shape no longer
+ * matches its recorded `capacity` — is skipped so the slot starts fresh (a
+ * script-edited `state.array(cap)` literal degrades, it does not throw). The
+ * handle identity is recreated on restore (acceptable — same as `state.series`).
+ *
+ * @since 1.3
+ * @internal
+ * @stable
+ * @example
+ *     // restoreArraySlots(ctx, snapshot.slots);
+ *     const restored = true;
+ *     void restored;
+ */
+export function restoreArraySlots(ctx, slots) {
+    ctx.arraySlots.clear();
+    for (const [key, value] of Object.entries(slots)) {
+        if (!isArraySlotSnapshotKey(key))
+            continue;
+        const slot = restoreArraySlotSnapshot(value);
+        if (slot !== null) {
+            ctx.arraySlots.set(key, slot);
+        }
+    }
+}
+//# sourceMappingURL=arrayPersistence.js.map

package/dist/state/arrayPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayPersistence.js","sourceRoot":"","sources":["../../src/state/arrayPersistence.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAI/D,OAAO,EACH,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,aAAa,EACb,eAAe,GAClB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAEnC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAC9C,OAAO,GAAG,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAmB;IACnD,MAAM,GAAG,GAA8B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,GAAG,CAAC,GAAG,CAAC,GAAG;YACP,IAAI,EAAE,aAAa;YACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,SAAS,EAAE,eAAe,CAAC,IAAI,CAAC,aAAa,CAAC;YAC9C,SAAS,EAAE,eAAe,CAAC,IAAI,CAAC,aAAa,CAAC;SACjD,CAAC;IACN,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,wBAAwB,CAAC,QAAiB;IAC/C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,IAAI,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IACxE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,QAAQ,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACzE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC;IAC1C,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9E,MAAM,aAAa,GAAG,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClE,MAAM,aAAa,GAAG,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClE,IAAI,aAAa,KAAK,IAAI,IAAI,aAAa,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClE,OAAO,qBAAqB,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;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,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC;YAAE,SAAS;QAC3C,MAAM,IAAI,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAChB,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,CAAC;IACL,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 { JsonValue } from \"@invinite-org/chartlang-core\";\n\nimport {\n    isBufferSnapshot,\n    isInteger,\n    isRecord,\n    restoreBuffer,\n    serialiseBuffer,\n} from \"../bufferSnapshot.js\";\nimport type { RuntimeContext } from \"../runtimeContext.js\";\nimport type { ArrayStateSlot } from \"./arrayStateSlot.js\";\nimport { restoreArrayStateSlot } from \"./arrayStateSlot.js\";\n\nconst ARRAY_SLOT_SUFFIX = \":array\";\n\n/**\n * Return whether a snapshot slot key belongs to the `state.array` namespace\n * (a `${slotIdPrefix}${slotId}:array` key). Lets the restore router separate\n * array slots from scalar `state.*` (`:state`), `state.series` (`:series`), and\n * `ta.*` (`ta:`) slots, all of which share one `slots` record.\n *\n * @since 1.3\n * @internal\n * @stable\n * @example\n *     isArraySlotSnapshotKey(\"x.chart.ts:1:1:array\"); // true\n */\nexport function isArraySlotSnapshotKey(key: string): boolean {\n    return key.endsWith(ARRAY_SLOT_SUFFIX);\n}\n\n/**\n * Serialise the runner's `state.array` slots into JSON-clean snapshot entries\n * keyed by the same `${prefix}${slotId}:array` key the slot store uses. Both\n * rings ride {@link Float64RingBuffer.serialiseSnapshotBuffer}; `capacity` is\n * recorded so restore can detect a script-edited capacity and degrade.\n *\n * @since 1.3\n * @internal\n * @stable\n * @example\n *     // const entries = serialiseArraySlots(ctx);\n *     const entries = {};\n *     void entries;\n */\nexport function serialiseArraySlots(ctx: RuntimeContext): Readonly<Record<string, JsonValue>> {\n    const out: Record<string, JsonValue> = {};\n    for (const [key, slot] of ctx.arraySlots.entries()) {\n        out[key] = {\n            kind: \"state.array\",\n            capacity: slot.capacity,\n            committed: serialiseBuffer(slot.committedRing),\n            tentative: serialiseBuffer(slot.tentativeRing),\n        };\n    }\n    return Object.freeze(out);\n}\n\nfunction restoreArraySlotSnapshot(snapshot: unknown): ArrayStateSlot | null {\n    if (!isRecord(snapshot) || snapshot.kind !== \"state.array\") return null;\n    if (!isInteger(snapshot.capacity) || snapshot.capacity <= 0) return null;\n    const { committed, tentative } = snapshot;\n    if (!isBufferSnapshot(committed) || !isBufferSnapshot(tentative)) return null;\n    const committedRing = restoreBuffer(committed, snapshot.capacity);\n    const tentativeRing = restoreBuffer(tentative, snapshot.capacity);\n    if (committedRing === null || tentativeRing === null) return null;\n    return restoreArrayStateSlot(committedRing, tentativeRing);\n}\n\n/**\n * Restore `state.array` slots from namespaced snapshot entries into\n * `ctx.arraySlots`, rebuilding each ring at the *persisted* `capacity`. Non-array\n * keys are ignored; a malformed snapshot — or one whose ring shape no longer\n * matches its recorded `capacity` — is skipped so the slot starts fresh (a\n * script-edited `state.array(cap)` literal degrades, it does not throw). The\n * handle identity is recreated on restore (acceptable — same as `state.series`).\n *\n * @since 1.3\n * @internal\n * @stable\n * @example\n *     // restoreArraySlots(ctx, snapshot.slots);\n *     const restored = true;\n *     void restored;\n */\nexport function restoreArraySlots(\n    ctx: RuntimeContext,\n    slots: Readonly<Record<string, unknown>>,\n): void {\n    ctx.arraySlots.clear();\n    for (const [key, value] of Object.entries(slots)) {\n        if (!isArraySlotSnapshotKey(key)) continue;\n        const slot = restoreArraySlotSnapshot(value);\n        if (slot !== null) {\n            ctx.arraySlots.set(key, slot);\n        }\n    }\n}\n"]}

package/dist/state/arrayStateSlot.d.ts

@@ -0,0 +1,78 @@
+import type { MutableArraySlot } from "@invinite-org/chartlang-core";
+import { Float64RingBuffer } from "../ringBuffer.js";
+/**
+ * Runtime slot behind a script-facing `state.array(capacity)` handle. Unlike
+ * the scalar `StateSlot` (one committed/tentative *value*) or the `SeriesSlot`
+ * (one ring advanced once per bar), this is a **bounded FIFO collection** with
+ * two `Float64RingBuffer`s: `tentativeRing` holds the live, author-facing
+ * pushes; `committedRing` is the bar-close snapshot a tick rolls back to.
+ *
+ * The committed/tentative discipline mirrors `StateSlot`: pushes during a tick
+ * mutate the tentative ring; a head-bar-replacing tick resets it from committed
+ * (in-progress pushes discarded); a bar close commits tentative into committed.
+ * The two-ring copy is `O(capacity)` per tick via a typed-array
+ * {@link Float64RingBuffer.copyFrom} memcpy — bounded because `capacity` is a
+ * required compile-time literal (see `tasks/future/state-array/README.md`
+ * Architecture Decisions: "Tick rollback = a two-ring buffer copy").
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     const slot = new ArrayStateSlot(4);
+ *     slot.handle.push(1);
+ *     slot.onBarClose();
+ *     slot.handle.get(0); // 1
+ */
+export declare class ArrayStateSlot {
+    readonly capacity: number;
+    readonly committedRing: Float64RingBuffer;
+    readonly tentativeRing: Float64RingBuffer;
+    readonly handle: MutableArraySlot<number>;
+    constructor(capacity: number);
+    /** Commit the tentative ring into the committed ring (bar close). */
+    onBarClose(): void;
+    /** Roll the tentative ring back to the committed ring (head-replacing tick). */
+    onBarTick(): void;
+}
+/**
+ * Build the identity-stable {@link MutableArraySlot} handle over an
+ * {@link ArrayStateSlot}. All author-facing reads and writes route through the
+ * **tentative** ring (mirroring `StateSlot.set`/`StateSlot.get`, which read and
+ * write `tentative` for non-tick slots); the committed ring is the rollback
+ * source. `get(out-of-range)` returns `NaN` (the ring's `at` contract), never
+ * throws. A plain object with getters — no `Proxy` — because the handle has a
+ * fixed method set and is deliberately not number-coercible.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // const handle = buildArrayHandle(new ArrayStateSlot(4));
+ *     // handle.push(1);
+ *     // handle.last(); // 1
+ */
+export declare function buildArrayHandle(slot: ArrayStateSlot): MutableArraySlot<number>;
+/**
+ * Allocate a fresh {@link ArrayStateSlot} — both rings empty (`size === 0`).
+ * Unlike `state.float(init)` there is no seed value: an empty collection starts
+ * empty.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // const slot = createArrayStateSlot(20);
+ *     // slot.handle.size; // 0
+ */
+export declare function createArrayStateSlot(capacity: number): ArrayStateSlot;
+/**
+ * Rebuild an {@link ArrayStateSlot} from already-restored rings (snapshot
+ * path). The handle identity is recreated — acceptable, same as
+ * `state.series` / `ta.*` restore.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // const slot = restoreArrayStateSlot(committedRing, tentativeRing);
+ *     // slot.handle.size;
+ */
+export declare function restoreArrayStateSlot(committedRing: Float64RingBuffer, tentativeRing: Float64RingBuffer): ArrayStateSlot;
+//# sourceMappingURL=arrayStateSlot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arrayStateSlot.d.ts","sourceRoot":"","sources":["../../src/state/arrayStateSlot.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc;aAKK,QAAQ,EAAE,MAAM;IAJ5C,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;gBAEd,QAAQ,EAAE,MAAM;IAM5C,qEAAqE;IACrE,UAAU,IAAI,IAAI;IAIlB,gFAAgF;IAChF,SAAS,IAAI,IAAI;CAGpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAqB/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAErE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACjC,aAAa,EAAE,iBAAiB,EAChC,aAAa,EAAE,iBAAiB,GACjC,cAAc,CAKhB"}

package/dist/state/arrayStateSlot.js

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+import { Float64RingBuffer } from "../ringBuffer.js";
+/**
+ * Runtime slot behind a script-facing `state.array(capacity)` handle. Unlike
+ * the scalar `StateSlot` (one committed/tentative *value*) or the `SeriesSlot`
+ * (one ring advanced once per bar), this is a **bounded FIFO collection** with
+ * two `Float64RingBuffer`s: `tentativeRing` holds the live, author-facing
+ * pushes; `committedRing` is the bar-close snapshot a tick rolls back to.
+ *
+ * The committed/tentative discipline mirrors `StateSlot`: pushes during a tick
+ * mutate the tentative ring; a head-bar-replacing tick resets it from committed
+ * (in-progress pushes discarded); a bar close commits tentative into committed.
+ * The two-ring copy is `O(capacity)` per tick via a typed-array
+ * {@link Float64RingBuffer.copyFrom} memcpy — bounded because `capacity` is a
+ * required compile-time literal (see `tasks/future/state-array/README.md`
+ * Architecture Decisions: "Tick rollback = a two-ring buffer copy").
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     const slot = new ArrayStateSlot(4);
+ *     slot.handle.push(1);
+ *     slot.onBarClose();
+ *     slot.handle.get(0); // 1
+ */
+export class ArrayStateSlot {
+    capacity;
+    committedRing;
+    tentativeRing;
+    handle;
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.committedRing = new Float64RingBuffer(capacity);
+        this.tentativeRing = new Float64RingBuffer(capacity);
+        this.handle = buildArrayHandle(this);
+    }
+    /** Commit the tentative ring into the committed ring (bar close). */
+    onBarClose() {
+        this.committedRing.copyFrom(this.tentativeRing);
+    }
+    /** Roll the tentative ring back to the committed ring (head-replacing tick). */
+    onBarTick() {
+        this.tentativeRing.copyFrom(this.committedRing);
+    }
+}
+/**
+ * Build the identity-stable {@link MutableArraySlot} handle over an
+ * {@link ArrayStateSlot}. All author-facing reads and writes route through the
+ * **tentative** ring (mirroring `StateSlot.set`/`StateSlot.get`, which read and
+ * write `tentative` for non-tick slots); the committed ring is the rollback
+ * source. `get(out-of-range)` returns `NaN` (the ring's `at` contract), never
+ * throws. A plain object with getters — no `Proxy` — because the handle has a
+ * fixed method set and is deliberately not number-coercible.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // const handle = buildArrayHandle(new ArrayStateSlot(4));
+ *     // handle.push(1);
+ *     // handle.last(); // 1
+ */
+export function buildArrayHandle(slot) {
+    return {
+        push(value) {
+            slot.tentativeRing.append(value);
+        },
+        get(n) {
+            return slot.tentativeRing.at(n);
+        },
+        last() {
+            return slot.tentativeRing.at(0);
+        },
+        clear() {
+            slot.tentativeRing.reset();
+        },
+        get size() {
+            return slot.tentativeRing.length;
+        },
+        get capacity() {
+            return slot.capacity;
+        },
+    };
+}
+/**
+ * Allocate a fresh {@link ArrayStateSlot} — both rings empty (`size === 0`).
+ * Unlike `state.float(init)` there is no seed value: an empty collection starts
+ * empty.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // const slot = createArrayStateSlot(20);
+ *     // slot.handle.size; // 0
+ */
+export function createArrayStateSlot(capacity) {
+    return new ArrayStateSlot(capacity);
+}
+/**
+ * Rebuild an {@link ArrayStateSlot} from already-restored rings (snapshot
+ * path). The handle identity is recreated — acceptable, same as
+ * `state.series` / `ta.*` restore.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // const slot = restoreArrayStateSlot(committedRing, tentativeRing);
+ *     // slot.handle.size;
+ */
+export function restoreArrayStateSlot(committedRing, tentativeRing) {
+    const slot = new ArrayStateSlot(committedRing.capacity);
+    slot.committedRing.copyFrom(committedRing);
+    slot.tentativeRing.copyFrom(tentativeRing);
+    return slot;
+}
+//# sourceMappingURL=arrayStateSlot.js.map

package/dist/state/arrayStateSlot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayStateSlot.js","sourceRoot":"","sources":["../../src/state/arrayStateSlot.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAI/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,cAAc;IAKK;IAJnB,aAAa,CAAoB;IACjC,aAAa,CAAoB;IACjC,MAAM,CAA2B;IAE1C,YAA4B,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;QACxC,IAAI,CAAC,aAAa,GAAG,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QACrD,IAAI,CAAC,aAAa,GAAG,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAED,qEAAqE;IACrE,UAAU;QACN,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACpD,CAAC;IAED,gFAAgF;IAChF,SAAS;QACL,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACpD,CAAC;CACJ;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACjD,OAAO;QACH,IAAI,CAAC,KAAa;YACd,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,GAAG,CAAC,CAAS;YACT,OAAO,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC;QACD,IAAI;YACA,OAAO,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC;QACD,KAAK;YACD,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC/B,CAAC;QACD,IAAI,IAAI;YACJ,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;QACrC,CAAC;QACD,IAAI,QAAQ;YACR,OAAO,IAAI,CAAC,QAAQ,CAAC;QACzB,CAAC;KACJ,CAAC;AACN,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACjD,OAAO,IAAI,cAAc,CAAC,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACjC,aAAgC,EAChC,aAAgC;IAEhC,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACxD,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC3C,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC3C,OAAO,IAAI,CAAC;AAChB,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 { MutableArraySlot } from \"@invinite-org/chartlang-core\";\n\nimport { Float64RingBuffer } from \"../ringBuffer.js\";\n\n/**\n * Runtime slot behind a script-facing `state.array(capacity)` handle. Unlike\n * the scalar `StateSlot` (one committed/tentative *value*) or the `SeriesSlot`\n * (one ring advanced once per bar), this is a **bounded FIFO collection** with\n * two `Float64RingBuffer`s: `tentativeRing` holds the live, author-facing\n * pushes; `committedRing` is the bar-close snapshot a tick rolls back to.\n *\n * The committed/tentative discipline mirrors `StateSlot`: pushes during a tick\n * mutate the tentative ring; a head-bar-replacing tick resets it from committed\n * (in-progress pushes discarded); a bar close commits tentative into committed.\n * The two-ring copy is `O(capacity)` per tick via a typed-array\n * {@link Float64RingBuffer.copyFrom} memcpy — bounded because `capacity` is a\n * required compile-time literal (see `tasks/future/state-array/README.md`\n * Architecture Decisions: \"Tick rollback = a two-ring buffer copy\").\n *\n * @since 1.3\n * @stable\n * @example\n *     const slot = new ArrayStateSlot(4);\n *     slot.handle.push(1);\n *     slot.onBarClose();\n *     slot.handle.get(0); // 1\n */\nexport class ArrayStateSlot {\n    readonly committedRing: Float64RingBuffer;\n    readonly tentativeRing: Float64RingBuffer;\n    readonly handle: MutableArraySlot<number>;\n\n    constructor(public readonly capacity: number) {\n        this.committedRing = new Float64RingBuffer(capacity);\n        this.tentativeRing = new Float64RingBuffer(capacity);\n        this.handle = buildArrayHandle(this);\n    }\n\n    /** Commit the tentative ring into the committed ring (bar close). */\n    onBarClose(): void {\n        this.committedRing.copyFrom(this.tentativeRing);\n    }\n\n    /** Roll the tentative ring back to the committed ring (head-replacing tick). */\n    onBarTick(): void {\n        this.tentativeRing.copyFrom(this.committedRing);\n    }\n}\n\n/**\n * Build the identity-stable {@link MutableArraySlot} handle over an\n * {@link ArrayStateSlot}. All author-facing reads and writes route through the\n * **tentative** ring (mirroring `StateSlot.set`/`StateSlot.get`, which read and\n * write `tentative` for non-tick slots); the committed ring is the rollback\n * source. `get(out-of-range)` returns `NaN` (the ring's `at` contract), never\n * throws. A plain object with getters — no `Proxy` — because the handle has a\n * fixed method set and is deliberately not number-coercible.\n *\n * @since 1.3\n * @stable\n * @example\n *     // const handle = buildArrayHandle(new ArrayStateSlot(4));\n *     // handle.push(1);\n *     // handle.last(); // 1\n */\nexport function buildArrayHandle(slot: ArrayStateSlot): MutableArraySlot<number> {\n    return {\n        push(value: number): void {\n            slot.tentativeRing.append(value);\n        },\n        get(n: number): number {\n            return slot.tentativeRing.at(n);\n        },\n        last(): number {\n            return slot.tentativeRing.at(0);\n        },\n        clear(): void {\n            slot.tentativeRing.reset();\n        },\n        get size(): number {\n            return slot.tentativeRing.length;\n        },\n        get capacity(): number {\n            return slot.capacity;\n        },\n    };\n}\n\n/**\n * Allocate a fresh {@link ArrayStateSlot} — both rings empty (`size === 0`).\n * Unlike `state.float(init)` there is no seed value: an empty collection starts\n * empty.\n *\n * @since 1.3\n * @stable\n * @example\n *     // const slot = createArrayStateSlot(20);\n *     // slot.handle.size; // 0\n */\nexport function createArrayStateSlot(capacity: number): ArrayStateSlot {\n    return new ArrayStateSlot(capacity);\n}\n\n/**\n * Rebuild an {@link ArrayStateSlot} from already-restored rings (snapshot\n * path). The handle identity is recreated — acceptable, same as\n * `state.series` / `ta.*` restore.\n *\n * @since 1.3\n * @stable\n * @example\n *     // const slot = restoreArrayStateSlot(committedRing, tentativeRing);\n *     // slot.handle.size;\n */\nexport function restoreArrayStateSlot(\n    committedRing: Float64RingBuffer,\n    tentativeRing: Float64RingBuffer,\n): ArrayStateSlot {\n    const slot = new ArrayStateSlot(committedRing.capacity);\n    slot.committedRing.copyFrom(committedRing);\n    slot.tentativeRing.copyFrom(tentativeRing);\n    return slot;\n}\n"]}

package/dist/state/index.d.ts

@@ -1,5 +1,8 @@
-export { commitStateSlots, flushStateSlots, restoreStateSlots, resetTentativeStateSlots, serialiseStateSlots, } from "./lifecycle.js";
+export { isArraySlotSnapshotKey, restoreArraySlots, serialiseArraySlots, } from "./arrayPersistence.js";
+export { ArrayStateSlot } from "./arrayStateSlot.js";
+export { advanceSeriesSlots, commitArraySlots, commitSeriesSlots, commitStateSlots, flushStateSlots, resetSeriesHeads, resetTentativeArraySlots, 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,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACH,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,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,9 @@
 // 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 { isArraySlotSnapshotKey, restoreArraySlots, serialiseArraySlots, } from "./arrayPersistence.js";
+export { ArrayStateSlot } from "./arrayStateSlot.js";
+export { advanceSeriesSlots, commitArraySlots, commitSeriesSlots, commitStateSlots, flushStateSlots, resetSeriesHeads, resetTentativeArraySlots, 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","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    commitStateSlots,\n    flushStateSlots,\n    restoreStateSlots,\n    resetTentativeStateSlots,\n    serialiseStateSlots,\n} from \"./lifecycle.js\";\nexport type { StateSlotSnapshot } from \"./lifecycle.js\";\nexport { buildStateNamespace } from \"./stateNamespace.js\";\nexport type { StateSlotSerialisers } from \"./stateSlot.js\";\nexport { asMutableSlot, StateSlot } from \"./stateSlot.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAE/D,OAAO,EACH,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACH,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,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    isArraySlotSnapshotKey,\n    restoreArraySlots,\n    serialiseArraySlots,\n} from \"./arrayPersistence.js\";\nexport { ArrayStateSlot } from \"./arrayStateSlot.js\";\nexport {\n    advanceSeriesSlots,\n    commitArraySlots,\n    commitSeriesSlots,\n    commitStateSlots,\n    flushStateSlots,\n    resetSeriesHeads,\n    resetTentativeArraySlots,\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,72 @@ 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;
+/**
+ * Roll every `state.array` slot's tentative ring back to its committed ring
+ * before tick compute, so a head-replacing tick discards in-progress pushes
+ * (and a tick without a push reads the committed collection). Runs once per
+ * tick, before compute, next to {@link resetSeriesHeads}. There is no advance —
+ * the array changes only when the author pushes.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // resetTentativeArraySlots(ctx);
+ *     const reset = true;
+ *     void reset;
+ */
+export declare function resetTentativeArraySlots(ctx: RuntimeContext): void;
+/**
+ * Commit every `state.array` slot's tentative ring into its committed ring
+ * after close compute, so the next tick can roll back to it. Runs once per
+ * close, after compute, next to {@link commitSeriesSlots}.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // commitArraySlots(ctx);
+ *     const committed = true;
+ *     void committed;
+ */
+export declare function commitArraySlots(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;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAIlE;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,92 @@ 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);
+    }
+}
+/**
+ * Roll every `state.array` slot's tentative ring back to its committed ring
+ * before tick compute, so a head-replacing tick discards in-progress pushes
+ * (and a tick without a push reads the committed collection). Runs once per
+ * tick, before compute, next to {@link resetSeriesHeads}. There is no advance —
+ * the array changes only when the author pushes.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // resetTentativeArraySlots(ctx);
+ *     const reset = true;
+ *     void reset;
+ */
+export function resetTentativeArraySlots(ctx) {
+    for (const slot of ctx.arraySlots.values()) {
+        slot.onBarTick();
+    }
+}
+/**
+ * Commit every `state.array` slot's tentative ring into its committed ring
+ * after close compute, so the next tick can roll back to it. Runs once per
+ * close, after compute, next to {@link commitSeriesSlots}.
+ *
+ * @since 1.3
+ * @stable
+ * @example
+ *     // commitArraySlots(ctx);
+ *     const committed = true;
+ *     void committed;
+ */
+export function commitArraySlots(ctx) {
+    for (const slot of ctx.arraySlots.values()) {
+        slot.onBarClose();
+    }
+}
 //# sourceMappingURL=lifecycle.js.map