@lazily-hub/lazily-js 0.16.0 → 0.18.0

package/README.md

@@ -33,7 +33,7 @@ the FFI projection transport is used.
 The full `lazily` capability set across every binding. Legend: ✅ shipped ·
 `~` partial · `—` absent or not applicable. The canonical matrix with per-cell
 notes and platform carve-outs lives in
-[`lazily-spec` § Cross-Language Coverage](../lazily-spec/docs/coverage.md).
+[`lazily-spec` § Cross-Language Coverage](https://github.com/lazily-hub/lazily-spec/blob/main/docs/coverage.md).
 
 <!-- coverage-table:start -->
 | Feature | Rust | Python | Kotlin | JS | Dart | Zig | Go | C++ |
@@ -51,10 +51,13 @@ notes and platform carve-outs lives in
 | Memoized semantic tree (`SemTree`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Stable-id alignment (manufactured identity) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Reactive queue (`QueueCell` SPSC/MPSC + `QueueStorage` adapter) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Broadcast topic (`TopicCell`) — independent cursors + durable replay + safe GC (`#lztopiccell`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Competing-consumer work queue (`WorkQueueCell`) — exclusive leases + ack/nack + redelivery + DLQ (`#lzworkqueue`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Merge algebra + `MergeCell` — associative `MergePolicy` (`KeepLatest`/`Sum`/`Max`/`SetUnion`/`RawFifo`), `Cell ≡ MergeCell<KeepLatest>`, `Reactive`/`Source` split (`#relaycell`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| RelayCell — conflating relay + `BackpressurePolicy` + `SpillStore` + `Transport` + Inbox/Outbox + Rate/Window/Expiry/Priority/keyed policies (`#relaycell`) | ✅ | — | — | ✅ | — | — | — | — |
+| RelayCell — conflating relay + `BackpressurePolicy` + `SpillStore` + `Transport` + Inbox/Outbox + Rate/Window/Expiry/Priority/keyed policies (`#relaycell`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Free-text character CRDT (`TextCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `TextCrdt` delta sync (`version_vector` / `delta_since` / `apply_delta`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `CrdtTree` lossless document contract (`#lzcrdttree`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Move-aware sequence CRDT (`SeqCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Lossless tree CRDT core (`LosslessTreeCrdt`, M1) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Lossless tree — dotted-frontier anti-entropy | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -65,6 +68,7 @@ notes and platform carve-outs lives in
 | Cross-process zero-copy transport (`BlobBackend` / shm / arrow) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Distributed CRDT plane (`CrdtPlaneRuntime` / anti-entropy) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Reliable sync — resync coordinator + at-least-once durable outbox + OR-set/LWW liveness (`#lzsync`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Storage-independent durable outbox (`OutboxStore` + shared outbox protocol; SQLite/Room/IndexedDB/file adapters) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Reliable-sync transport seam + full-duplex `SyncDriver` loop (`IpcSink`/`IpcSource`, `#sync-driver`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Distributed plane — WebRTC transport + signaling | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | State projection / mirror | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -337,6 +341,26 @@ tree.value(); // 1
 tree.setValue("leaf", 99); // only the ancestor chain recomputes
 ```
 
+## Competing-consumer work queue
+
+The `queue` package exports `WorkQueueCell`, a pull-based local authority with
+exclusive FIFO claims, stable item IDs, fresh delivery IDs per attempt,
+worker-owned ack/nack, strict visibility-timeout redelivery, bounded attempts,
+and DLQ routing. Every mutation reports exact `pending_len` / `is_empty` /
+`in_flight_len` / `dead_letter_len` invalidation metadata.
+
+```js
+import { WorkQueueCell } from "@lazily-hub/lazily-js/queue";
+
+const work = new WorkQueueCell({ visibility_timeout: 30, max_deliveries: 3 });
+work.push("render-report");
+const delivery = work.claim("worker-a", 100).returns;
+work.ack("worker-a", delivery.delivery_id);
+```
+
+The instance serializes local claims; distributed/HA assignment still requires
+a leader or consensus-committed assignment log.
+
 ## CRDTs
 
 `SeqCrdt` is the move-aware sequence CRDT: each element has independent LWW
@@ -344,7 +368,10 @@ registers for value, position, and deletion, so a move is one position
 assignment rather than delete plus reinsert. `TextCrdt` is a Fugue/RGA
 character CRDT: concurrent same-point inserts are preserved, deletes are sticky
 tombstones, and merge is commutative / associative / idempotent. Both expose
-tombstone GC behind caller-supplied causal-stability watermarks.
+tombstone GC behind caller-supplied causal-stability watermarks. `TextCrdt`
+also satisfies the `CrdtTree` document contract: its snapshot is the delta from
+an empty frontier, so full hydration and incremental exchange preserve the same
+identity-bearing state.
 
 ```js
 import { SeqCrdt } from "@lazily-hub/lazily-js/seq-crdt";
@@ -360,6 +387,16 @@ peer.insert(2, "!");
 text.merge(peer); // converges
 ```
 
+## Durable outbox stores
+
+The root `Outbox` class owns one append/ack/prune/replay protocol over the
+five-operation `OutboxStore` boundary. `InMemoryStore` exercises that path in
+tests. Browsers can open an `IndexedDbStore` from
+`@lazily-hub/lazily-js/indexeddb-outbox`; await `append` before transport send
+and `ackThrough` before treating an acknowledgement as committed. Reopening the
+same database and channel restores the durable cursor and only unacknowledged
+frames.
+
 ## IPC wire types and capability negotiation
 
 Every IPC value round-trips the canonical externally-tagged

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Native JavaScript port of the lazily reactive core: a full reactive graph (Cell/Slot/Signal/Effect), sync/async/thread-safe keyed reactive maps (ReactiveMap/CellMap/SlotMap), the lazily-spec IPC wire types + C-ABI FFI boundary (isomorphic channel + Node native binding), 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, an FFI state-projection consumer, and an in-library instrumentation/benchmark API.",
   "license": "MIT",
   "repository": {
@@ -97,6 +97,11 @@
       "types": "./src/lossless-tree-crdt.d.ts",
       "default": "./src/lossless-tree-crdt.js"
     },
+    "./indexeddb-outbox": {
+      "types": "./src/indexeddb-outbox.d.ts",
+      "browser": "./src/indexeddb-outbox.js",
+      "default": "./src/indexeddb-outbox.js"
+    },
     "./state-projection": {
       "types": "./src/state-projection.d.ts",
       "default": "./src/state-projection.js"
@@ -111,7 +116,7 @@
     }
   },
   "scripts": {
-    "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/async-reactive-family.js && node --check src/thread-safe.js && node --check src/thread-safe-reactive-family.js && node --check src/ffi.js && node --check src/ffi-node.js && node --check src/instrumentation.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/merge.js && node --check src/relay.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/graph-view.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/async-reactive-family.js && node --check src/thread-safe.js && node --check src/thread-safe-reactive-family.js && node --check src/ffi.js && node --check src/ffi-node.js && node --check src/instrumentation.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/merge.js && node --check src/relay.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/indexeddb-outbox.js && node --check src/utf8-offsets.js && node --check src/lossless-tree-crdt.js && node --check src/state-projection.js && node --check src/graph-view.js && node --check src/signaling.js && node --check src/distributed.js",
     "test:formal": "node scripts/formal-check.mjs",
     "bench": "node bench/context.bench.mjs",
     "bench:scale": "node --max-old-space-size=8192 bench/scale.bench.mjs",
@@ -125,6 +130,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
+    "fake-indexeddb": "^6.2.5",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0"
   }

package/src/index.d.ts

@@ -449,20 +449,40 @@ export class ResyncCoordinator {
 }
 
 export interface DurableOutbox {
-  append(epoch: number, msg: IpcMessage): void;
-  ackThrough(epoch: number): void;
+  append(epoch: number, msg: IpcMessage): void | Promise<void>;
+  ackThrough(epoch: number): void | Promise<void>;
   replayFrom(cursor: number): Array<[number, IpcMessage]>;
   retainedEpochs(): number[];
 }
 
-export class InMemoryOutbox implements DurableOutbox {
+export interface OutboxStore {
+  put(epoch: number, frame: Uint8Array): void | Promise<void>;
+  deleteThrough(epoch: number): void | Promise<void>;
+  scanAfter(cursor: number): Array<[number, Uint8Array]>;
+  loadCursor(): number;
+  saveCursor(epoch: number): void | Promise<void>;
+}
+
+export class Outbox<S extends OutboxStore = OutboxStore> implements DurableOutbox {
+  constructor(store: S);
+  readonly store: S;
   ackedThrough: number;
-  append(epoch: number, msg: IpcMessage): void;
-  ackThrough(epoch: number): void;
+  append(epoch: number, msg: IpcMessage): void | Promise<void>;
+  ackThrough(epoch: number): void | Promise<void>;
   replayFrom(cursor: number): Array<[number, IpcMessage]>;
   retainedEpochs(): number[];
 }
 
+export class InMemoryStore implements OutboxStore {
+  put(epoch: number, frame: Uint8Array): void;
+  deleteThrough(epoch: number): void;
+  scanAfter(cursor: number): Array<[number, Uint8Array]>;
+  loadCursor(): number;
+  saveCursor(epoch: number): void;
+}
+
+export class InMemoryOutbox extends Outbox<InMemoryStore> {}
+
 export class OrSet {
   add(tag: string): void;
   removeObserved(tags: Iterable<string>): void;

package/src/index.js

@@ -1269,29 +1269,86 @@ export class ResyncCoordinator {
   }
 }
 
-// In-memory durable outbox — correct within a process lifetime; the default.
-// A DurableOutbox is any object with append/ackThrough/replayFrom/retainedEpochs.
-export class InMemoryOutbox {
-  constructor() {
-    this.entries = []; // [epoch, IpcMessage]
-    this.ackedThrough = 0;
+// A byte-oriented OutboxStore is any object with
+// put/deleteThrough/scanAfter/loadCursor/saveCursor. Stores are deliberately
+// protocol-dumb; Outbox is the one append/ack/replay implementation.
+export class Outbox {
+  constructor(store) {
+    this.store = store;
+    this.ackedThrough = store.loadCursor();
   }
 
   append(epoch, msg) {
-    this.entries.push([epoch, msg]);
+    return this.store.put(epoch, msg.encodeJson());
   }
 
   ackThrough(epoch) {
-    if (epoch > this.ackedThrough) this.ackedThrough = epoch;
-    this.entries = this.entries.filter(([e]) => e > this.ackedThrough);
+    if (epoch <= this.ackedThrough) return undefined;
+    const target = () => Math.max(this.ackedThrough, epoch, this.store.loadCursor());
+    const finish = () => {
+      this.ackedThrough = target();
+    };
+    const remove = () => this.store.deleteThrough(target());
+    const saved = this.store.saveCursor(epoch);
+    if (saved && typeof saved.then === "function") {
+      return saved.then(remove).then(finish);
+    }
+    const removed = remove();
+    if (removed && typeof removed.then === "function") {
+      return removed.then(finish);
+    }
+    finish();
+    return undefined;
   }
 
   replayFrom(cursor) {
-    return this.entries.filter(([e]) => e > cursor).sort((a, b) => a[0] - b[0]);
+    return this.store
+      .scanAfter(Math.max(cursor, this.ackedThrough))
+      .sort((a, b) => a[0] - b[0])
+      .map(([epoch, frame]) => [epoch, IpcMessage.decodeJson(frame)]);
   }
 
   retainedEpochs() {
-    return this.entries.map(([e]) => e).sort((a, b) => a - b);
+    return this.store.scanAfter(this.ackedThrough).map(([epoch]) => epoch).sort((a, b) => a - b);
+  }
+}
+
+export class InMemoryStore {
+  constructor() {
+    this.entries = new Map();
+    this.cursor = 0;
+  }
+
+  put(epoch, frame) {
+    this.entries.set(epoch, Uint8Array.from(frame));
+  }
+
+  deleteThrough(epoch) {
+    for (const key of this.entries.keys()) {
+      if (key <= epoch) this.entries.delete(key);
+    }
+  }
+
+  scanAfter(epoch) {
+    return [...this.entries]
+      .filter(([key]) => key > epoch)
+      .sort((a, b) => a[0] - b[0])
+      .map(([key, frame]) => [key, Uint8Array.from(frame)]);
+  }
+
+  loadCursor() {
+    return this.cursor;
+  }
+
+  saveCursor(epoch) {
+    this.cursor = Math.max(this.cursor, epoch);
+  }
+}
+
+// Process-local default, routed through the same protocol as persistent stores.
+export class InMemoryOutbox extends Outbox {
+  constructor() {
+    super(new InMemoryStore());
   }
 }
 

package/src/indexeddb-outbox.d.ts

@@ -0,0 +1,18 @@
+import type { OutboxStore } from "./index.js";
+
+export interface IndexedDbStoreOptions {
+  channel: string;
+  database?: string;
+  version?: number;
+  indexedDB?: IDBFactory;
+}
+
+export class IndexedDbStore implements OutboxStore {
+  static open(options: IndexedDbStoreOptions): Promise<IndexedDbStore>;
+  put(epoch: number, frame: Uint8Array): Promise<void>;
+  deleteThrough(epoch: number): Promise<void>;
+  scanAfter(cursor: number): Array<[number, Uint8Array]>;
+  loadCursor(): number;
+  saveCursor(epoch: number): Promise<void>;
+  close(): void;
+}

package/src/indexeddb-outbox.js

@@ -0,0 +1,124 @@
+/**
+ * Browser IndexedDB storage adapter for the root `Outbox` protocol.
+ *
+ * `open()` hydrates a synchronous replay mirror. Mutations return promises;
+ * callers must await `Outbox.append` before sending and `Outbox.ackThrough`
+ * before treating an ack as committed.
+ */
+export class IndexedDbStore {
+  #db;
+  #channel;
+  #entries;
+  #cursor;
+  #cursorWrites = Promise.resolve();
+
+  constructor(db, channel, entries, cursor) {
+    this.#db = db;
+    this.#channel = channel;
+    this.#entries = entries;
+    this.#cursor = cursor;
+  }
+
+  static async open({
+    channel,
+    database = "lazily-reliable-sync",
+    version = 1,
+    indexedDB = globalThis.indexedDB,
+  }) {
+    if (!indexedDB) throw new Error("IndexedDB is unavailable in this environment");
+    const db = await new Promise((resolve, reject) => {
+      const request = indexedDB.open(database, version);
+      request.onupgradeneeded = () => {
+        const next = request.result;
+        if (!next.objectStoreNames.contains("frames")) {
+          next.createObjectStore("frames", { keyPath: ["channel", "epoch"] });
+        }
+        if (!next.objectStoreNames.contains("cursors")) {
+          next.createObjectStore("cursors", { keyPath: "channel" });
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+
+    const entries = new Map();
+    const cursor = await new Promise((resolve, reject) => {
+      const tx = db.transaction(["frames", "cursors"], "readonly");
+      const frameRequest = tx.objectStore("frames").openCursor();
+      frameRequest.onsuccess = () => {
+        const row = frameRequest.result;
+        if (!row) return;
+        if (row.value.channel === channel) {
+          entries.set(row.value.epoch, Uint8Array.from(row.value.frame));
+        }
+        row.continue();
+      };
+      const cursorRequest = tx.objectStore("cursors").get(channel);
+      tx.oncomplete = () => resolve(cursorRequest.result?.epoch ?? 0);
+      tx.onerror = () => reject(tx.error);
+      tx.onabort = () => reject(tx.error);
+    });
+    return new IndexedDbStore(db, channel, entries, cursor);
+  }
+
+  #transaction(storeName, mode, operation) {
+    return new Promise((resolve, reject) => {
+      const tx = this.#db.transaction(storeName, mode);
+      operation(tx.objectStore(storeName));
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+      tx.onabort = () => reject(tx.error);
+    });
+  }
+
+  async put(epoch, frame) {
+    const bytes = Uint8Array.from(frame);
+    await this.#transaction("frames", "readwrite", (store) => {
+      store.put({ channel: this.#channel, epoch, frame: bytes });
+    });
+    this.#entries.set(epoch, bytes);
+  }
+
+  async deleteThrough(epoch) {
+    const keys = [...this.#entries.keys()].filter((key) => key <= epoch);
+    await this.#transaction("frames", "readwrite", (store) => {
+      for (const key of keys) store.delete([this.#channel, key]);
+    });
+    for (const key of keys) this.#entries.delete(key);
+  }
+
+  scanAfter(epoch) {
+    return [...this.#entries]
+      .filter(([key]) => key > epoch)
+      .sort((a, b) => a[0] - b[0])
+      .map(([key, frame]) => [key, Uint8Array.from(frame)]);
+  }
+
+  loadCursor() {
+    return this.#cursor;
+  }
+
+  saveCursor(epoch) {
+    const previous = this.#cursorWrites.catch(() => undefined);
+    const write = previous.then(async () => {
+      let next = Math.max(this.#cursor, epoch);
+      await this.#transaction("cursors", "readwrite", (store) => {
+        // IndexedDB serializes readwrite transactions that overlap this store.
+        // Reading and writing inside one transaction makes this a database-wide
+        // max, not merely a per-JavaScript-handle max.
+        const request = store.get(this.#channel);
+        request.onsuccess = () => {
+          next = Math.max(request.result?.epoch ?? 0, this.#cursor, epoch);
+          store.put({ channel: this.#channel, epoch: next });
+        };
+      });
+      this.#cursor = next;
+    });
+    this.#cursorWrites = write;
+    return write;
+  }
+
+  close() {
+    this.#db.close();
+  }
+}

package/src/queue.d.ts

@@ -87,5 +87,101 @@ export class QueueCell {
   isFull(): boolean;
   isClosed(): boolean;
   capacity(): number | null;
-  elements(): unknown[];
+elements(): unknown[];
+}
+
+export type TopicDurabilityLabel = "durable" | "ephemeral";
+export const TopicDurability: Readonly<{ Durable: "durable"; Ephemeral: "ephemeral" }>;
+
+export type TopicSubscribeOutcomeLabel = "Created" | "Reconnected" | "AlreadyConnected";
+export const TopicSubscribeOutcome: Readonly<{
+Created: "Created";
+Reconnected: "Reconnected";
+AlreadyConnected: "AlreadyConnected";
+}>;
+
+export type TopicSubscriptionSnapshot = {
+cursor: number;
+durability: TopicDurabilityLabel;
+connected: boolean;
+};
+
+export type TopicInitial = {
+base_offset?: number;
+elements?: unknown[];
+subscriptions?: Record<string, TopicSubscriptionSnapshot>;
+};
+
+export type TopicMutationResult = {
+returns: unknown;
+invalidates: Record<string, boolean>;
+offset?: number;
+};
+
+/** Broadcast log with independent, non-destructive subscriber cursors. */
+export class TopicCell {
+constructor(initial?: TopicInitial);
+static from(initial?: TopicInitial): TopicCell;
+subscribe(id: string, durability: TopicDurabilityLabel): TopicMutationResult;
+reconnect(id: string): TopicMutationResult;
+disconnect(id: string): TopicMutationResult;
+publish(value: unknown): TopicMutationResult;
+readStream(id: string): unknown[];
+read(id: string): unknown;
+advance(id: string): TopicMutationResult;
+restart(id: string): TopicMutationResult;
+gc(): TopicMutationResult;
+baseOffset(): number;
+endOffset(): number;
+elements(): unknown[];
+subscription(id: string): TopicSubscriptionSnapshot | null;
+subscriptions(): Record<string, TopicSubscriptionSnapshot>;
+  snapshot(): Required<TopicInitial>;
+}
+
+export type WorkQueueInvalidates = {
+  pending_len: boolean;
+  is_empty: boolean;
+  in_flight_len: boolean;
+  dead_letter_len: boolean;
+};
+
+export type WorkQueueItem<T = unknown> = {item_id: number; value: T; attempts: number};
+
+export type WorkQueueDelivery<T = unknown> = {
+  delivery_id: number;
+  item_id: number;
+  value: T;
+  worker: string;
+  attempt: number;
+  deadline: number;
+};
+
+export type WorkQueueDeadLetter<T = unknown> = {
+  item_id: number;
+  value: T;
+  attempts: number;
+  reason: "nack" | "expired";
+};
+
+export const WorkQueueDeadLetterReason: Readonly<{Nack: "nack"; Expired: "expired"}>;
+
+/** Pull-based competing-consumer work queue with exclusive delivery leases. */
+export class WorkQueueCell<T = unknown> {
+  constructor(config: {visibility_timeout: number; max_deliveries: number});
+  push(value: T): {returns: number; invalidates: WorkQueueInvalidates};
+  claim(worker: string, now: number): {
+    returns: WorkQueueDelivery<T> | null;
+    invalidates: WorkQueueInvalidates;
+  };
+  ack(worker: string, deliveryId: number): {returns: boolean; invalidates: WorkQueueInvalidates};
+  nack(worker: string, deliveryId: number): {returns: boolean; invalidates: WorkQueueInvalidates};
+  reapExpired(now: number): {returns: number; invalidates: WorkQueueInvalidates};
+  pendingLen(): number;
+  isEmpty(): boolean;
+  inFlightLen(): number;
+  deadLetterLen(): number;
+  pendingItems(): WorkQueueItem<T>[];
+  inFlightDeliveries(): WorkQueueDelivery<T>[];
+  deadLetterItems(): WorkQueueDeadLetter<T>[];
 }

package/src/queue.js

@@ -342,23 +342,400 @@ export class QueueCell {
 }
 
 // ---------------------------------------------------------------------------
-// Future primitives (stubs) — documented, not in v1 conformance.
+// TopicCell — broadcast log with independent subscriber cursors (#lztopiccell)
 // ---------------------------------------------------------------------------
-//
-// TopicCell (SPMC broadcast / MPMC pub-sub) and WorkQueueCell (true MPMC with
-// exclusive handoff) are genuinely distinct primitives — they differ in
-// *invalidation model and handoff semantics*, not producer/consumer
-// cardinality (see `lazily-spec/cell-model.md` § "Future queue primitives").
-//
-// - TopicCell — every subscriber receives every pushed element; each subscriber
-//   keeps its own cursor; GC bounded by the slowest cursor. Lands with the
-//   distributed-queue PRD Phase 3. Formal stub: lazily-formal/TopicCell.lean.
-//
-// - WorkQueueCell — N consumers compete for elements; each element delivered to
-//   exactly one consumer (exclusive handoff). Requires an authority (leader) to
-//   serialize pop-assignment; pure CRDT cannot provide it. Lands with the
-//   distributed-queue PRD Phase 2 (consensus core). Formal stub:
-//   lazily-formal/WorkQueueCell.lean.
+
+export const TopicDurability = Object.freeze({
+  Durable: "durable",
+  Ephemeral: "ephemeral",
+});
+
+export const TopicSubscribeOutcome = Object.freeze({
+  Created: "Created",
+  Reconnected: "Reconnected",
+  AlreadyConnected: "AlreadyConnected",
+});
+
+/**
+ * Broadcast topic: every subscriber receives every published element using an
+ * independent, non-destructive cursor. Mutating operations return the exact
+ * per-subscriber invalidation matrix used by the canonical fixtures.
+ */
+export class TopicCell {
+  /**
+   * @param {{
+   *   base_offset?: number,
+   *   elements?: unknown[],
+   *   subscriptions?: Record<string, {cursor: number, durability: "durable" | "ephemeral", connected: boolean}>
+   * }} [initial]
+   */
+  constructor(initial = {}) {
+    this.#baseOffset = initial.base_offset ?? 0;
+    this.#elements = Array.from(initial.elements ?? []);
+    this.#subscriptions = new Map();
+    if (!Number.isSafeInteger(this.#baseOffset) || this.#baseOffset < 0) {
+      throw new RangeError("TopicCell base_offset must be a non-negative safe integer");
+    }
+    const end = this.endOffset();
+    for (const [id, raw] of Object.entries(initial.subscriptions ?? {})) {
+      if (!Number.isSafeInteger(raw.cursor) || raw.cursor < this.#baseOffset || raw.cursor > end) {
+        throw new RangeError(`TopicCell cursor for ${id} is outside the retained offset range`);
+      }
+      if (raw.durability !== TopicDurability.Durable && raw.durability !== TopicDurability.Ephemeral) {
+        throw new TypeError(`invalid TopicCell durability for ${id}`);
+      }
+      if (typeof raw.connected !== "boolean") {
+        throw new TypeError(`TopicCell connected flag for ${id} must be boolean`);
+      }
+      if (raw.durability === TopicDurability.Ephemeral && !raw.connected) {
+        throw new TypeError(`disconnected ephemeral TopicCell subscription ${id} must be removed`);
+      }
+      this.#subscriptions.set(id, {
+        cursor: raw.cursor,
+        durability: raw.durability,
+        connected: raw.connected,
+      });
+    }
+  }
+
+  #baseOffset;
+  #elements;
+  #subscriptions;
+
+  static from(initial = {}) {
+    return new TopicCell(initial);
+  }
+
+  #allFalse() {
+    return Object.fromEntries(Array.from(this.#subscriptions.keys(), (id) => [id, false]));
+  }
+
+  #only(id, changed) {
+    const invalidates = this.#allFalse();
+    invalidates[id] = changed;
+    return invalidates;
+  }
+
+  /** Create at tail, or reconnect an existing durable identity in place. */
+  subscribe(id, durability) {
+    const existing = this.#subscriptions.get(id);
+    if (existing) {
+      if (existing.connected) {
+        return {
+          returns: TopicSubscribeOutcome.AlreadyConnected,
+          invalidates: this.#allFalse(),
+        };
+      }
+      existing.connected = true;
+      return {
+        returns: TopicSubscribeOutcome.Reconnected,
+        invalidates: this.#only(id, true),
+      };
+    }
+    if (durability !== TopicDurability.Durable && durability !== TopicDurability.Ephemeral) {
+      throw new TypeError(`invalid TopicCell durability for ${id}`);
+    }
+    this.#subscriptions.set(id, {
+      cursor: this.endOffset(),
+      durability,
+      connected: true,
+    });
+    return { returns: TopicSubscribeOutcome.Created, invalidates: this.#only(id, true) };
+  }
+
+  /** Reconnect a durable identity; unknown ids are created at the current tail. */
+  reconnect(id) {
+    return this.subscribe(id, TopicDurability.Durable);
+  }
+
+  /** Durable ids remain offline; ephemeral ids are removed. */
+  disconnect(id) {
+    const sub = this.#subscriptions.get(id);
+    if (!sub || !sub.connected) {
+      return { returns: null, invalidates: this.#allFalse() };
+    }
+    const invalidates = this.#only(id, true);
+    if (sub.durability === TopicDurability.Ephemeral) {
+      this.#subscriptions.delete(id);
+    } else {
+      sub.connected = false;
+    }
+    return { returns: null, invalidates };
+  }
+
+  /** Append one element without moving any cursor. */
+  publish(value) {
+    const offset = this.endOffset();
+    this.#elements.push(value);
+    const invalidates = Object.fromEntries(
+      Array.from(this.#subscriptions, ([id, sub]) => [
+        id,
+        sub.connected && sub.cursor <= offset,
+      ]),
+    );
+    return { returns: null, offset, invalidates };
+  }
+
+  /** Unread suffix for a connected subscriber. */
+  readStream(id) {
+    const sub = this.#subscriptions.get(id);
+    if (!sub || !sub.connected) return [];
+    return this.#elements.slice(Math.max(0, sub.cursor - this.#baseOffset));
+  }
+
+  /** Element at a subscriber cursor, or null at the tail/offline. */
+  read(id) {
+    return this.readStream(id)[0] ?? null;
+  }
+
+  /** Advance only the named connected cursor by one. */
+  advance(id) {
+    const sub = this.#subscriptions.get(id);
+    if (!sub || !sub.connected || sub.cursor >= this.endOffset()) {
+      return { returns: null, invalidates: this.#allFalse() };
+    }
+    const value = this.#elements[sub.cursor - this.#baseOffset];
+    sub.cursor += 1;
+    return { returns: value, invalidates: this.#only(id, true) };
+  }
+
+  /** Process restart is observational: persisted durable state is unchanged. */
+  restart(_id) {
+    return { returns: null, invalidates: this.#allFalse() };
+  }
+
+  /** Remove only the prefix below the minimum durable absolute cursor. */
+  gc() {
+    const durable = Array.from(this.#subscriptions.values())
+      .filter((sub) => sub.durability === TopicDurability.Durable)
+      .map((sub) => sub.cursor);
+    const frontier = durable.length === 0 ? this.endOffset() : Math.min(...durable);
+    const removed = frontier - this.#baseOffset;
+    this.#elements.splice(0, removed);
+    this.#baseOffset = frontier;
+    return { returns: removed, invalidates: this.#allFalse() };
+  }
+
+  baseOffset() {
+    return this.#baseOffset;
+  }
+
+  endOffset() {
+    return this.#baseOffset + this.#elements.length;
+  }
+
+  elements() {
+    return Array.from(this.#elements);
+  }
+
+  subscription(id) {
+    const sub = this.#subscriptions.get(id);
+    return sub ? { ...sub } : null;
+  }
+
+  subscriptions() {
+    return Object.fromEntries(Array.from(this.#subscriptions, ([id, sub]) => [id, { ...sub }]));
+  }
+
+  snapshot() {
+    return {
+      base_offset: this.#baseOffset,
+      elements: this.elements(),
+      subscriptions: this.subscriptions(),
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// WorkQueueCell — competing consumers with exclusive leases (#lzworkqueue)
+// ---------------------------------------------------------------------------
+
+export const WorkQueueDeadLetterReason = Object.freeze({
+  Nack: "nack",
+  Expired: "expired",
+});
+
+/**
+ * Pull-based competing-consumer work queue.
+ *
+ * This is the portable local-authority lifecycle. The owning instance
+ * serializes `claim`; a distributed/HA host puts that decision behind its
+ * leader or consensus log while preserving the same operation outcomes.
+ */
+export class WorkQueueCell {
+  /** @param {{visibility_timeout: number, max_deliveries: number}} config */
+  constructor(config) {
+    if (!config || !Number.isSafeInteger(config.visibility_timeout) || config.visibility_timeout <= 0) {
+      throw new RangeError("visibility_timeout must be a positive safe integer");
+    }
+    if (!Number.isSafeInteger(config.max_deliveries) || config.max_deliveries < 1) {
+      throw new RangeError("max_deliveries must be at least one");
+    }
+    this.#visibilityTimeout = config.visibility_timeout;
+    this.#maxDeliveries = config.max_deliveries;
+  }
+
+  #visibilityTimeout;
+  #maxDeliveries;
+  #pending = [];
+  #inFlight = new Map();
+  #deadLetters = [];
+  #nextItemId = 0;
+  #nextDeliveryId = 0;
+
+  #counts() {
+    return {
+      pending: this.#pending.length,
+      in_flight: this.#inFlight.size,
+      dead_letters: this.#deadLetters.length,
+    };
+  }
+
+  #invalidates(before) {
+    const after = this.#counts();
+    return {
+      pending_len: before.pending !== after.pending,
+      is_empty: (before.pending === 0) !== (after.pending === 0),
+      in_flight_len: before.in_flight !== after.in_flight,
+      dead_letter_len: before.dead_letters !== after.dead_letters,
+    };
+  }
+
+  #unchanged() {
+    return {
+      pending_len: false,
+      is_empty: false,
+      in_flight_len: false,
+      dead_letter_len: false,
+    };
+  }
+
+  #validateNow(now) {
+    if (!Number.isSafeInteger(now) || now < 0) {
+      throw new RangeError("now must be a non-negative safe integer");
+    }
+  }
+
+  #fail(delivery, reason) {
+    if (delivery.attempt < this.#maxDeliveries) {
+      this.#pending.push({
+        item_id: delivery.item_id,
+        value: delivery.value,
+        attempts: delivery.attempt,
+      });
+    } else {
+      this.#deadLetters.push({
+        item_id: delivery.item_id,
+        value: delivery.value,
+        attempts: delivery.attempt,
+        reason,
+      });
+    }
+  }
+
+  /** Append a pending item and return its stable item id. */
+  push(value) {
+    const before = this.#counts();
+    if (this.#nextItemId >= Number.MAX_SAFE_INTEGER) throw new RangeError("item id exhausted");
+    const itemId = this.#nextItemId;
+    this.#nextItemId += 1;
+    this.#pending.push({ item_id: itemId, value, attempts: 0 });
+    return { returns: itemId, invalidates: this.#invalidates(before) };
+  }
+
+  /** Claim the oldest pending item for one worker. */
+  claim(worker, now) {
+    this.#validateNow(now);
+    if (this.#pending.length === 0) {
+      return { returns: null, invalidates: this.#unchanged() };
+    }
+    if (this.#nextDeliveryId >= Number.MAX_SAFE_INTEGER) throw new RangeError("delivery id exhausted");
+    const before = this.#counts();
+    const item = this.#pending.shift();
+    const deliveryId = this.#nextDeliveryId;
+    this.#nextDeliveryId += 1;
+    const delivery = {
+      delivery_id: deliveryId,
+      item_id: item.item_id,
+      value: item.value,
+      worker,
+      attempt: item.attempts + 1,
+      deadline: Math.min(Number.MAX_SAFE_INTEGER, now + this.#visibilityTimeout),
+    };
+    this.#inFlight.set(deliveryId, delivery);
+    return { returns: { ...delivery }, invalidates: this.#invalidates(before) };
+  }
+
+  /** Ack only the exact current delivery owned by `worker`. */
+  ack(worker, deliveryId) {
+    const delivery = this.#inFlight.get(deliveryId);
+    if (!delivery || delivery.worker !== worker) {
+      return { returns: false, invalidates: this.#unchanged() };
+    }
+    const before = this.#counts();
+    this.#inFlight.delete(deliveryId);
+    return { returns: true, invalidates: this.#invalidates(before) };
+  }
+
+  /** Nack a delivery, requeueing at the tail or dead-lettering at the limit. */
+  nack(worker, deliveryId) {
+    const delivery = this.#inFlight.get(deliveryId);
+    if (!delivery || delivery.worker !== worker) {
+      return { returns: false, invalidates: this.#unchanged() };
+    }
+    const before = this.#counts();
+    this.#inFlight.delete(deliveryId);
+    this.#fail(delivery, WorkQueueDeadLetterReason.Nack);
+    return { returns: true, invalidates: this.#invalidates(before) };
+  }
+
+  /** Expire every lease with `deadline < now`, in delivery-id order. */
+  reapExpired(now) {
+    this.#validateNow(now);
+    const expired = Array.from(this.#inFlight.values())
+      .filter((delivery) => delivery.deadline < now)
+      .sort((a, b) => a.delivery_id - b.delivery_id);
+    if (expired.length === 0) {
+      return { returns: 0, invalidates: this.#unchanged() };
+    }
+    const before = this.#counts();
+    for (const delivery of expired) {
+      this.#inFlight.delete(delivery.delivery_id);
+      this.#fail(delivery, WorkQueueDeadLetterReason.Expired);
+    }
+    return { returns: expired.length, invalidates: this.#invalidates(before) };
+  }
+
+  pendingLen() {
+    return this.#pending.length;
+  }
+
+  isEmpty() {
+    return this.#pending.length === 0;
+  }
+
+  inFlightLen() {
+    return this.#inFlight.size;
+  }
+
+  deadLetterLen() {
+    return this.#deadLetters.length;
+  }
+
+  pendingItems() {
+    return this.#pending.map((item) => ({ ...item }));
+  }
+
+  inFlightDeliveries() {
+    return Array.from(this.#inFlight.values(), (delivery) => ({ ...delivery })).sort(
+      (a, b) => a.delivery_id - b.delivery_id,
+    );
+  }
+
+  deadLetterItems() {
+    return this.#deadLetters.map((item) => ({ ...item }));
+  }
+}
 
 // ---------------------------------------------------------------------------
 // helpers

package/src/text-crdt.d.ts

@@ -5,7 +5,22 @@ export class OpId {
   compareTo(other: OpId): number;
 }
 
-export class TextCrdt {
+export interface CrdtTree<VersionVector, Delta, Value, Self = unknown> {
+  versionVector(): VersionVector;
+  deltaSince(theirVersion: VersionVector): Delta;
+  applyDelta(delta: Delta): boolean;
+  value(): Value;
+  mergeFrom(other: Self): boolean;
+}
+
+export interface TextOp {
+  id: { counter: number; peer: number };
+  ch: string;
+  origin: { counter: number; peer: number } | null;
+  deleted: { counter: number; peer: number } | null;
+}
+
+export class TextCrdt implements CrdtTree<Record<number, number>, TextOp[], string, TextCrdt> {
   constructor(peer: number);
   static fromStr(peer: number, str: string): TextCrdt;
   fork(peer: number): TextCrdt;
@@ -19,5 +34,10 @@ export class TextCrdt {
   tombstoneCount(): number;
   clock(): OpId;
   merge(other: TextCrdt): boolean;
+  value(): string;
+  mergeFrom(other: TextCrdt): boolean;
+  versionVector(): Record<number, number>;
+  deltaSince(theirVersion: Record<number, number>): TextOp[];
+  applyDelta(delta: TextOp[]): boolean;
   gcWith(isStable: (deleteOpId: OpId) => boolean): number;
 }

package/src/text-crdt.js

@@ -213,6 +213,16 @@ export class TextCrdt {
     return this.text() !== before;
   }
 
+  // CrdtTree materialized-value surface.
+  value() {
+    return this.text();
+  }
+
+  // CrdtTree state-join surface.
+  mergeFrom(other) {
+    return this.merge(other);
+  }
+
   // Tombstone GC: collect a stable deleted element only when nothing references
   // it as a left origin. Bottom-up: pass 1 collects unreferenced leaf
   // tombstones, removing a leaf un-references its origin, so further passes