@lazily-hub/lazily-js 0.6.1 → 0.9.0

package/.github/workflows/release.yml

@@ -39,9 +39,13 @@ jobs:
           node-version: 24
           registry-url: https://registry.npmjs.org
 
-      # Trusted publishing needs npm CLI >= 11.5.1; Node 24's bundled npm may lag.
-      - name: Upgrade npm for OIDC trusted publishing
-        run: npm install -g npm@latest
+      # OIDC trusted publishing (provenance) needs npm >= 9.5.0; Node 24's
+      # bundled npm 11.x already supports it. Do NOT `npm install -g npm@latest`
+      # — that global self-upgrade drops the `sigstore` dependency that
+      # libnpmpublish requires for provenance, producing
+      # `Cannot find module 'sigstore'` at publish time.
+      - name: Verify npm supports OIDC provenance
+        run: npm --version
 
       - name: Install dependencies
         working-directory: lazily-js
@@ -51,15 +55,19 @@ jobs:
         working-directory: lazily-js
         run: npm test --if-present
 
-      # Published under the `prev` dist-tag so this v0.x line does not steal
-      # `latest` from a higher already-published version; move `latest` explicitly
-      # (`npm dist-tag add @lazily-hub/lazily-js@<v> latest`) once the accidental
-      # v1.x releases are removed.
+      # Publish as `latest`. The accidental v1.x versions that forced the old
+      # `prev` dist-tag workaround have been removed (npm now shows only the
+      # 0.4.0 / 0.5.0 / 0.6.x line, latest = 0.6.1), so the v0.x line is the
+      # canonical latest again.
       - name: Publish
         working-directory: lazily-js
         run: |
           version="$(node -p "require('./package.json').version")"
-          if npm publish --access public --tag prev; then
+          # --provenance triggers the OIDC trusted-publishing exchange (the
+          # `id-token: write` permission minted a short-lived publish token).
+          # The bundled npm 11.x does not auto-enable provenance the way a
+          # freshly-upgraded npm@latest does, so it must be explicit.
+          if npm publish --provenance --access public; then
             echo "published @lazily-hub/lazily-js@${version}"
           elif npm view "@lazily-hub/lazily-js@${version}" version >/dev/null 2>&1; then
             echo "@lazily-hub/lazily-js@${version} already published — idempotent no-op"

package/README.md

@@ -39,6 +39,7 @@ notes and platform carve-outs lives in
 | Feature | Rust | Python | Kotlin | JS | Dart | Zig | Go | C++ |
 | --------- | :----: | :------: | :------: | :--: | :----: | :---: | :--: | :---: |
 | Reactive graph — `Cell` / `Slot` / `Signal` / `Effect` / memo / batch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reactive family (`ReactiveFamily`) — keyed cell/slot family + materialization mode (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ |
 | Async reactive context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Flat state machine | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -46,21 +47,22 @@ notes and platform carve-outs lives in
 | Keyed cell collections (`CellMap` / `CellTree`) + reconcile | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Memoized semantic tree (`SemTree`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Stable-id alignment (manufactured identity) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Reactive queue (`QueueCell` SPSC/MPSC + `QueueStorage` adapter) | — | — | — | — | — | — | — | — |
+| Reactive queue (`QueueCell` SPSC/MPSC + `QueueStorage` adapter) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Free-text character CRDT (`TextCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `TextCrdt` delta sync (`version_vector` / `delta_since` / `apply_delta`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Move-aware sequence CRDT (`SeqCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Lossless tree CRDT core (`LosslessTreeCrdt`, M1) | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
-| Lossless tree — dotted-frontier anti-entropy | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
-| Lossless tree — concurrent merge convergence | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Lossless tree CRDT core (`LosslessTreeCrdt`, M1) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Lossless tree — dotted-frontier anti-entropy | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Lossless tree — concurrent merge convergence | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Registers (LWW / MV) + `PnCounter` + `CellCrdt` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | IPC wire — `Snapshot` + `Delta` + `CrdtSync` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Shared-memory blob path (`ShmBlobArena`) | ✅ | ✅ | ✅ | ~ | ~ | ✅ | ✅ | ✅ |
+| Shared-memory blob path (`ShmBlobArena`) | ✅ | ✅ | ✅ | ✅ | ~ | ✅ | ✅ | ✅ |
+| Cross-process zero-copy transport (`BlobBackend` / shm / arrow) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Distributed CRDT plane (`CrdtPlaneRuntime` / anti-entropy) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Distributed plane — WebRTC transport + signaling | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | State projection / mirror | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Causal receipts (`CausalReceipts` outcome projection) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Message-passing + RPC command plane (`command-plane-v1`) | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Message-passing + RPC command plane (`command-plane-v1`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | C-ABI FFI boundary | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
 | Permission boundary (`PeerPermissions` / `RemoteOp`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Capability negotiation (`SessionHandshake`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -74,8 +76,10 @@ and JSON Schemas in `lazily-spec` and the Lean models in `lazily-formal`.
 | Import | What it is |
 |--------|------------|
 | `@lazily-hub/lazily-js` | `lazily-spec` IPC wire types: `Snapshot`, `Delta`, `DeltaOp`, `IpcMessage` (`Snapshot` / `Delta` / `CrdtSync`), `NodeState`, `IpcValue`, `PeerPermissions`, `SessionHandshake`, `BINDING_CAPABILITIES` |
+| `@lazily-hub/lazily-js/transport` | Cross-process zero-copy transport (`#lzzcpy`): `ShmBlobArena`, `InProcessBackend` / `ArrowBackend`, `BlobRouter`, `spillMessage` / `resolveValue`, and the FFI-gated `createShmBackend` (Node/Bun/Deno). Isomorphic — no FFI import; browser-safe |
 | `@lazily-hub/lazily-js/reactive` | Reactive dependency graph: `Context`, `Cell`, `Slot`, `Signal`, `Effect` |
 | `@lazily-hub/lazily-js/reactive-async` | Async reactive graph: `AsyncContext` — Promise-driven slots/effects with revision-guarded stale-completion discard, in-flight dedup, and cancellation |
+| `@lazily-hub/lazily-js/reactive-family` | Unified keyed reactive family: `ReactiveFamily` (`EntryKind` cell/slot × `MaterializationMode` eager/lazy) + `cellFamily` input-cell specialization (`#lzmatmode`) |
 | `@lazily-hub/lazily-js/state-machine` | Flat finite-state-machine kernel backed by a reactive `Cell` |
 | `@lazily-hub/lazily-js/statechart` | Harel/SCXML chart interpreter plus `ChartBuilder`, `StateBuilder`, `TransitionBuilder` |
 | `@lazily-hub/lazily-js/collections` | `CellMap`, `CellTree`, keyed reconciliation, and LIS move minimization |
@@ -155,6 +159,44 @@ ctx.setCell(userId, 2); // supersedes any in-flight compute; slot re-resolves
 await ctx.getAsync(profile); // the profile for user 2
 ```
 
+## Reactive family and materialization mode
+
+`ReactiveFamily` (from `@lazily-hub/lazily-js/reactive-family`) is the unified
+**keyed reactive family** (`#lzmatmode`): it maps keys to per-entry reactive
+nodes and abstracts over the entry's handle kind. Two orthogonal axes:
+
+- **Entry kind** — `EntryKind.Cell` entries are input cells (**always
+  materialized**, any mode); `EntryKind.Slot` entries are derived slots (what
+  materialization governs). `cellFamily(...)` is the input-cell specialization.
+- **Materialization mode** — `MaterializationMode.Eager` (**default**) allocates
+  every derived node up front; `MaterializationMode.Lazy` (opt-in) allocates a
+  derived node on its **first read** ("materialize on pull") and caches it.
+
+Mode is **observationally transparent**: a read returns the same value under
+either mode — it changes allocation timing and memory, never results. Lazy pays
+off only for sparsely-touched large keyed address spaces.
+
+```js
+import { Context } from "@lazily-hub/lazily-js/reactive";
+import { ReactiveFamily } from "@lazily-hub/lazily-js/reactive-family";
+
+const ctx = new Context();
+
+// A derived (slot) family of key*3 over a large address space, built lazily:
+// nothing is allocated until a key is read.
+const fam = ReactiveFamily.lazy(ctx, range(0, 1_000_000), (k) => k * 3);
+fam.presentCount(); // 0
+
+fam.observe(5); // 15 — first read materializes just this entry
+fam.presentCount(); // 1
+fam.isPresent(5); // true
+fam.isPresent(6); // false
+
+// Eager builds the same values up front — observationally identical.
+const eager = ReactiveFamily.eager(ctx, [0, 1, 2, 3], (k) => k * 3);
+eager.observe(2) === fam.observe(2); // true
+```
+
 ## State machine and state charts
 
 `StateMachine` is the flat finite-state-machine kernel: a pure
@@ -344,6 +386,69 @@ signaling, and the WebRTC transport are shipped; C-ABI FFI is `none` because
 browser/Worker JS cannot host a native in-process ABI. The same payload types
 can still be carried by any transport a host application owns.
 
+## Cross-process zero-copy transport
+
+`@lazily-hub/lazily-js/transport` implements the pluggable blob-backend
+transport (`#lzzcpy`). A large payload is not copied through the wire codec: the
+producer **spills** it to a backend (which mints a `ShmBlobRef` descriptor) and
+ships only the descriptor; the receiver **routes** the descriptor by its
+`backend` discriminator and **resolves** it zero-copy — reading the backend's own
+bytes in place. `ShmBlobRef` gained an optional `backend` field (`shm` | `arrow`
+| `in_process`) that defaults to `shm` and is omitted from the wire, so every
+pre-transport descriptor round-trips byte-for-byte.
+
+The module is **isomorphic**: it imports no FFI, so it bundles and runs in the
+browser. `InProcessBackend`, `ArrowBackend`, the `BlobRouter`, and the
+spill/resolve policy are pure JS and available everywhere (including a
+main-thread ↔ Web Worker deployment).
+
+```js
+import {
+  BlobRouter,
+  InProcessBackend,
+  ArrowBackend,
+  spillMessage,
+} from "@lazily-hub/lazily-js/transport";
+import { Delta, DeltaOp, IpcMessage, IpcValue } from "@lazily-hub/lazily-js";
+
+const backend = new InProcessBackend(); // or ArrowBackend for columnar payloads
+const big = IpcValue.inline(new Uint8Array(4096));
+const { message, spilledBytes } = spillMessage(
+  IpcMessage.delta(new Delta({ baseEpoch: 0, epoch: 1, ops: [DeltaOp.slotValue(7, big)] })),
+  backend,
+); // message now carries a small SharedBlob descriptor; spilledBytes === 4096
+
+const router = new BlobRouter().register(backend);
+router.resolve(message.delta.ops[0].payload); // Uint8Array view, zero copy
+```
+
+The genuine **cross-process** `shm` backend (POSIX `shm_open` + `mmap`) is loaded
+lazily and only where a runtime provides FFI — Node (via `koffi`), Bun (`bun:ffi`),
+or Deno (`Deno.dlopen`, needs `--allow-ffi --unstable-ffi`). A peer process on the
+same host that attaches the same name resolves the descriptor without copying
+across the process boundary. In the browser (or any runtime without FFI)
+`createShmBackend` rejects with `ShmUnavailableError`; guard with `shmSupported()`
+and fall back to `InProcessBackend` / `ArrowBackend`.
+
+```js
+import { createShmBackend, shmSupported } from "@lazily-hub/lazily-js/transport";
+
+if (shmSupported()) {
+  const shm = await createShmBackend("my-session", { capacity: 1 << 20 });
+  const ref = shm.write(new Uint8Array([1, 2, 3])); // ref.backend === "shm"
+  // ...ship `ref` to a peer; the peer attaches `createShmBackend("my-session",
+  // { capacity: 1 << 20, create: false })` and calls `shm.readView(ref)`.
+  shm.close();
+}
+```
+
+All three runtimes are verified end-to-end, including cross-runtime interop: a
+Node process writes a region that a separate Deno process attaches and resolves,
+proving the layout is byte-identical across FFI implementations. The `shm` region
+is a bump-allocated arena with a fixed header (magic / version / capacity / epoch
+/ generation / cursor) and per-entry `{ generation, epoch, len, checksum }`
+validation.
+
 ## Distributed plane
 
 The `@lazily-hub/lazily-js/signaling` and `@lazily-hub/lazily-js/distributed`
@@ -384,7 +489,11 @@ lazily-js replays the shared `lazily-spec` fixtures for IPC, agent-doc state,
 keyed collections (`CellMap`, `CellTree`, LIS reconciliation), semantic tree,
 sequence and text CRDTs (incl. `TextCrdt` delta sync, `#lztextsync`:
 `textcrdt_convergence.json` + `textcrdt_delta_sync.json`), manufactured text
-identity, Harel state charts, the signaling protocol (`signaling/frames.json`,
+identity, the reactive family / materialization mode (`#lzmatmode`:
+`materialization/observational_transparency.json`,
+`materialization/deferral_not_deallocation.json`,
+`materialization/entry_kind_orthogonal_to_mode.json`), Harel state charts, the
+signaling protocol (`signaling/frames.json`,
 `signaling/anti_spoof_session.json`), and the distributed CRDT plane
 (`distributed/crdt_sync_frames.json`, `distributed/anti_entropy_converge.json`).
 It also validates generated wire values against the canonical JSON Schemas.
@@ -404,6 +513,7 @@ names the Lean theorems it mirrors:
 | `Reactive` | `reactive-properties.test.js` | `setCell_equal_preserves_graph`, `setCell_different_invalidates_dependents`, `recomputeSlot_equal_preserves_dependents`, `recomputeSlot_different_invalidates_dependents`, `signal_materialized_after_recompute` |
 | `Collection` | `collection-properties.test.js` | `setEntryValue_preserves_{membership,order,siblings}`, `moveKey_preserves_{membership,values}`, `moveKey_advances_order`, `addKey_advances_membership_and_order`, `Family.get_idempotent_after_first` |
 | `Tree` | `tree-properties.test.js` | `setNodeValue_preserves_{other_nodes,node_signals}`, `moveChild_preserves_{non_parent,parent_value}`, `moveChild_advances_order_signal_only` |
+| `Materialization` | `reactive-family.test.js` | `observe_canonical`, `eager_lazy_observationally_equivalent`, `eager_materializes_all`, `lazy_defers_slots`, `materialize_present_monotone`, `lazy_present_subset_eager`, `materialize_preserves_observe`, `cell_entries_materialized_in_every_mode`, `slot_entries_deferred_under_lazy` |
 | `Reconciliation` | `reconciliation-properties.test.js` | `lisBy_longest`, `reconcile_move_minimized`, `reconcile_stable_not_invalidated` |
 | `AsyncSlotState` | `reactive-async.test.js` | `stale_completeOk_discarded`, `current_completeOk_publishes`, `current_completeErr_to_error` |
 | `AsyncEffect` | `reactive-async.test.js` | `fire_blocked_during_cleanup`, `invalidate_from_idle_schedules`, `cleanupDone_resumes_deferred`, `dispose_absorbing`, `disposed_terminal` |

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.6.1",
+  "version": "0.9.0",
   "description": "Native JavaScript port of the lazily reactive core: a full reactive graph (Cell/Slot/Signal/Effect), the lazily-spec IPC wire types, keyed cell collections + LIS reconciliation, the memoized semantic tree, the move-aware sequence CRDT, the Fugue/RGA text CRDT, manufactured text identity, full-Harel state charts, and an FFI state-projection consumer.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lazily-hub/lazily-js.git"
+  },
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -10,6 +15,10 @@
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
     },
+    "./transport": {
+      "types": "./src/transport.d.ts",
+      "default": "./src/transport.js"
+    },
     "./reactive": {
       "types": "./src/reactive.d.ts",
       "default": "./src/reactive.js"
@@ -18,6 +27,10 @@
       "types": "./src/reactive-async.d.ts",
       "default": "./src/reactive-async.js"
     },
+    "./reactive-family": {
+      "types": "./src/reactive-family.d.ts",
+      "default": "./src/reactive-family.js"
+    },
     "./state-machine": {
       "types": "./src/state-machine.d.ts",
       "default": "./src/state-machine.js"
@@ -30,6 +43,10 @@
       "types": "./src/collections.d.ts",
       "default": "./src/collections.js"
     },
+    "./queue": {
+      "types": "./src/queue.d.ts",
+      "default": "./src/queue.js"
+    },
     "./sem-tree": {
       "types": "./src/sem-tree.d.ts",
       "default": "./src/sem-tree.js"
@@ -64,7 +81,7 @@
     }
   },
   "scripts": {
-    "build": "node --check src/index.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/state-machine.js && node --check src/statechart.js && node --check src/collections.js && node --check src/sem-tree.js && node --check src/stable-id.js && node --check src/seq-crdt.js && node --check src/text-crdt.js && node --check src/utf8-offsets.js && node --check src/lossless-tree-crdt.js && node --check src/state-projection.js && node --check src/signaling.js && node --check src/distributed.js",
+    "build": "node --check src/index.js && node --check src/transport.js && node --check src/shm-backend.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/reactive-family.js && node --check src/state-machine.js && node --check src/statechart.js && node --check src/collections.js && node --check src/queue.js && node --check src/sem-tree.js && node --check src/stable-id.js && node --check src/seq-crdt.js && node --check src/text-crdt.js && node --check src/utf8-offsets.js && node --check src/lossless-tree-crdt.js && node --check src/state-projection.js && node --check src/signaling.js && node --check src/distributed.js",
     "test:formal": "node scripts/formal-check.mjs",
     "bench": "node bench/context.bench.mjs",
     "benchmark-update": "node scripts/run-benchmarks.mjs",

package/src/index.d.ts

@@ -2,6 +2,14 @@ export type NodeId = number;
 export type PeerId = number;
 export type WireBytes = readonly number[] | Uint8Array;
 
+export type BlobBackendKindValue = "shm" | "arrow" | "in_process";
+
+export const BlobBackendKind: {
+  readonly Shm: "shm";
+  readonly Arrow: "arrow";
+  readonly InProcess: "in_process";
+};
+
 export class ShmBlobRef {
   constructor(fields: {
     offset: number;
@@ -9,12 +17,15 @@ export class ShmBlobRef {
     generation: number;
     epoch: number;
     checksum: number;
+    backend?: BlobBackendKindValue;
   });
   readonly offset: number;
   readonly len: number;
   readonly generation: number;
   readonly epoch: number;
   readonly checksum: number;
+  readonly backend: BlobBackendKindValue;
+  withBackend(backend: BlobBackendKindValue): ShmBlobRef;
   toWire(): ShmBlobRefWire;
   static fromWire(value: ShmBlobRefWire): ShmBlobRef;
 }
@@ -25,6 +36,7 @@ export type ShmBlobRefWire = {
   generation: number;
   epoch: number;
   checksum: number;
+  backend?: BlobBackendKindValue;
 };
 
 export class NodeStatePayload {

package/src/index.js

@@ -73,24 +73,62 @@ function normalizeNodeKey(key) {
   return key;
 }
 
+// The pluggable blob backends a descriptor may name (zero-copy transport,
+// `#lzzcpy`). `shm` is the default and is omitted from the wire so legacy
+// descriptors round-trip byte-for-byte. See src/transport.js and
+// lazily-spec/docs/zero-copy-transport.md.
+export const BlobBackendKind = Object.freeze({
+  Shm: "shm",
+  Arrow: "arrow",
+  InProcess: "in_process",
+});
+
+const BLOB_BACKEND_KINDS = new Set(Object.values(BlobBackendKind));
+
 export class ShmBlobRef {
-  constructor({ offset, len, generation, epoch, checksum }) {
+  constructor({ offset, len, generation, epoch, checksum, backend }) {
     this.offset = assertInteger(offset, "offset");
     this.len = assertInteger(len, "len");
     this.generation = assertInteger(generation, "generation");
     this.epoch = assertInteger(epoch, "epoch");
     this.checksum = assertInteger(checksum, "checksum");
+    // Optional pluggable-backend discriminator. Defaults to `shm` so every
+    // pre-transport descriptor keeps meaning "POSIX shared memory".
+    const kind = backend ?? BlobBackendKind.Shm;
+    if (!BLOB_BACKEND_KINDS.has(kind)) {
+      throw new TypeError(`unknown blob backend: ${kind}`);
+    }
+    this.backend = kind;
     Object.freeze(this);
   }
 
+  // Return a copy of this descriptor tagged for `backend`. Backends stamp their
+  // own kind onto an arena-minted descriptor via this helper.
+  withBackend(backend) {
+    return new ShmBlobRef({
+      offset: this.offset,
+      len: this.len,
+      generation: this.generation,
+      epoch: this.epoch,
+      checksum: this.checksum,
+      backend,
+    });
+  }
+
   toWire() {
-    return {
+    const wire = {
       offset: this.offset,
       len: this.len,
       generation: this.generation,
       epoch: this.epoch,
       checksum: this.checksum,
     };
+    // Omit the default `shm` so the descriptor stays byte-compatible with the
+    // pre-`#lzzcpy` wire form (the `backend`-absent conformance fixture).
+    if (this.backend !== BlobBackendKind.Shm) {
+      wire.backend = this.backend;
+    }
+    return wire;
   }
 
   static fromWire(value) {
@@ -101,6 +139,7 @@ export class ShmBlobRef {
       generation: object.generation,
       epoch: object.epoch,
       checksum: object.checksum,
+      backend: object.backend ?? BlobBackendKind.Shm,
     });
   }
 }

package/src/queue.d.ts

@@ -0,0 +1,91 @@
+// Reactive queue: QueueCell + pluggable QueueStorage backend (#lzqueue).
+// Pure logic — no reactive graph. See queue.js for the reader-kind invalidation
+// contract and the shell / storage split.
+
+export type QueuePushErrorLabel = "Full" | "Closed";
+export type QueuePopErrorLabel = "Empty" | "Closed";
+
+export const QueuePushError: Readonly<{ Full: "Full"; Closed: "Closed" }>;
+export const QueuePopError: Readonly<{ Empty: "Empty"; Closed: "Closed" }>;
+
+/** The reader-kind invalidation matrix returned by every mutating op. */
+export type QueueInvalidates = {
+  head: boolean;
+  len: boolean;
+  is_empty: boolean;
+  is_full: boolean;
+  closed: boolean;
+};
+
+/** Result of a push op (`returns` is the error label, or `null` on success). */
+export type QueuePushResult = {
+  returns: null | QueuePushErrorLabel;
+  invalidates: QueueInvalidates;
+};
+
+/** Result of a pop op (`returns` is the element, or the error label). */
+export type QueuePopResult = {
+  returns: unknown | QueuePopErrorLabel;
+  invalidates: QueueInvalidates;
+};
+
+/** Result of a close op. */
+export type QueueCloseResult = {
+  returns: null;
+  invalidates: QueueInvalidates;
+};
+
+/** A duck-typed `QueueStorage` backend. */
+export type QueueStorage = {
+  tryPush(value: unknown): null | QueuePushErrorLabel;
+  tryPop(): unknown | QueuePopErrorLabel;
+  peek(): unknown;
+  len(): number;
+  capacity(): number | null;
+  isClosed(): boolean;
+  close(): void;
+  snapshot(): QueueStorageSnapshot;
+};
+
+export type QueueStorageSnapshot = {
+  elements: unknown[];
+  capacity: number | null;
+  closed: boolean;
+};
+
+export type QueueInitial = {
+  elements?: unknown[];
+  capacity?: number | null;
+  closed?: boolean;
+};
+
+/** The reference `QueueStorage` backend (unbounded or bounded array FIFO). */
+export class VecDequeStorage {
+  constructor(initial?: QueueInitial);
+  elements: unknown[];
+  static from(initial?: QueueInitial): VecDequeStorage;
+  tryPush(value: unknown): null | QueuePushErrorLabel;
+  tryPop(): unknown | QueuePopErrorLabel;
+  peek(): unknown;
+  len(): number;
+  capacity(): number | null;
+  isClosed(): boolean;
+  close(): void;
+  snapshot(): QueueStorageSnapshot;
+}
+
+/** A reactive FIFO queue — SPSC primitive with an MPSC usage rule. */
+export class QueueCell {
+  constructor(initial?: QueueInitial, storage?: QueueStorage);
+  static from(initial?: QueueInitial, storage?: QueueStorage): QueueCell;
+  tryPush(value: unknown): QueuePushResult;
+  tryPop(): QueuePopResult;
+  close(): QueueCloseResult;
+  head(): unknown;
+  len(): number;
+  isEmpty(): boolean;
+  isFull(): boolean;
+  isClosed(): boolean;
+  capacity(): number | null;
+  elements(): unknown[];
+}