@lazily-hub/lazily-js 0.15.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,8 +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`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 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 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -63,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 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -335,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
@@ -342,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";
@@ -358,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.15.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": {
@@ -69,6 +69,14 @@
       "types": "./src/queue.d.ts",
       "default": "./src/queue.js"
     },
+    "./merge": {
+      "types": "./src/merge.d.ts",
+      "default": "./src/merge.js"
+    },
+    "./relay": {
+      "types": "./src/relay.d.ts",
+      "default": "./src/relay.js"
+    },
     "./sem-tree": {
       "types": "./src/sem-tree.d.ts",
       "default": "./src/sem-tree.js"
@@ -89,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"
@@ -103,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/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",
@@ -117,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/merge.d.ts

@@ -0,0 +1,50 @@
+// Phase 1 of the RelayCell backpressure plan (#relaycell) — merge algebra +
+// the Reactive/Source read/write split. See lazily-spec/docs/reactive-graph.md
+// § "MergeCell and the merge algebra".
+
+import type { CellHandle, Context } from "./reactive.js";
+
+/** An associative merge policy `⊕: T×T→T` with its transport-selected flags. */
+export interface MergePolicy<T> {
+  readonly name: string;
+  /** The associative fold. MUST satisfy `(a⊕b)⊕c == a⊕(b⊕c)`. */
+  merge(old: T, op: T): T;
+  /** `⊕` is commutative (reordering tax). */
+  readonly commutative: boolean;
+  /** `⊕` is idempotent — `(a⊕b)⊕b == a⊕b` (durability tax). */
+  readonly idempotent: boolean;
+  /** Conflation bounds the state (the `Conflate` overflow precondition). */
+  readonly conflates: boolean;
+}
+
+export const KeepLatest: MergePolicy<unknown>;
+export const Sum: MergePolicy<number>;
+export const Max: MergePolicy<number>;
+export const SetUnion: MergePolicy<Set<unknown>>;
+export const RawFifo: MergePolicy<unknown[]>;
+
+/** A cell whose write is a merge under `policy` (`Cell ≡ MergeCell(KeepLatest)`). */
+export class MergeCell<T> {
+  readonly ctx: Context;
+  readonly cell: CellHandle<T>;
+  readonly policy: MergePolicy<T>;
+  constructor(ctx: Context, cell: CellHandle<T>, policy: MergePolicy<T>);
+  /** Read the current converged value. */
+  get(): T;
+  /** Replace the value (keep-latest write). */
+  set(value: T): void;
+  /** Fold `op` into the value under the policy. */
+  merge(op: T): void;
+}
+
+/** Create a `MergeCell` over `ctx`. */
+export function mergeCell<T>(ctx: Context, initial: T, policy: MergePolicy<T>): MergeCell<T>;
+
+/** Adapt a plain cell to the `Source` shape (get/set/merge; merge == replace). */
+export function asSource<T>(
+  ctx: Context,
+  cellHandle: CellHandle<T>,
+): { get(): T; set(value: T): void; merge(op: T): void };
+
+/** Adapt any read handle to the `Reactive` shape (`{ get }`). */
+export function asReactive<T>(ctx: Context, handle: unknown): { get(): T };

package/src/merge.js

@@ -0,0 +1,142 @@
+// Phase 1 of the RelayCell backpressure plan (#relaycell) — the merge algebra
+// and the Reactive/Source read/write split.
+//
+// See lazily-spec/docs/reactive-graph.md § "MergeCell and the merge algebra" and
+// relaycell-backpressure-analysis.md §4.0/§4.3. A merge policy is an *associative*
+// fold ⊕: T×T→T; the properties it satisfies (associativity always; commutativity
+// = reordering tax; idempotency = durability tax) select which overflow behaviour
+// is sound. `MergeCell` generalizes a plain `Cell` — `Cell ≡ MergeCell(KeepLatest)`
+// — a source whose write is a merge. Backed by an ordinary cell, so it inherits
+// the Phase-0 `==` store-guard and store-without-cascade.
+
+// -- Merge policies ----------------------------------------------------------
+//
+// A policy is a plain object: { name, merge(old, op), commutative, idempotent,
+// conflates }. Associativity is a law (verified by law-tests), not a field. The
+// three flags surface the transport-selected branches; `conflates` gates the
+// `Conflate` overflow (only RawFifo — concat — cannot bound, Phase 2).
+
+/** Keep-latest band: `old ⊕ op = op`. The policy behind a plain `Cell`. */
+export const KeepLatest = Object.freeze({
+  name: "KeepLatest",
+  merge: (_old, op) => op,
+  commutative: false,
+  idempotent: true,
+  conflates: true,
+});
+
+/** Additive commutative monoid: `old + op`. Not idempotent. */
+export const Sum = Object.freeze({
+  name: "Sum",
+  merge: (old, op) => old + op,
+  commutative: true,
+  idempotent: false,
+  conflates: true,
+});
+
+/** Max semilattice: `max(old, op)`. Associative, commutative, idempotent. */
+export const Max = Object.freeze({
+  name: "Max",
+  merge: (old, op) => (op > old ? op : old),
+  commutative: true,
+  idempotent: true,
+  conflates: true,
+});
+
+/** Grow-only set-union semilattice over `Set`. */
+export const SetUnion = Object.freeze({
+  name: "SetUnion",
+  merge: (old, op) => {
+    const out = new Set(old);
+    for (const x of op) out.add(x);
+    return out;
+  },
+  commutative: true,
+  idempotent: true,
+  conflates: true,
+});
+
+/** Raw FIFO append over arrays: `old ++ op`. Order + multiplicity are meaning —
+ *  associative only; cannot conflate. */
+export const RawFifo = Object.freeze({
+  name: "RawFifo",
+  merge: (old, op) => old.concat(op),
+  commutative: false,
+  idempotent: false,
+  conflates: false,
+});
+
+// -- MergeCell ---------------------------------------------------------------
+
+/**
+ * A cell whose write is a *merge* under `policy`, rather than a replace.
+ * `Cell ≡ MergeCell(KeepLatest)`.
+ */
+export class MergeCell {
+  /** @param {import("./reactive.js").Context} ctx */
+  constructor(ctx, cell, policy) {
+    this.ctx = ctx;
+    /** underlying CellHandle */
+    this.cell = cell;
+    this.policy = policy;
+    Object.freeze(this);
+  }
+
+  /** Read the current converged value (tracks a dependency inside a computation). */
+  get() {
+    return this.ctx.getCell(this.cell);
+  }
+
+  /** Replace the value outright (the keep-latest write), bypassing the policy. */
+  set(value) {
+    this.ctx.setCell(this.cell, value);
+  }
+
+  /** Fold `op` into the current value under the policy. Routes through `setCell`
+   *  so the `==` store-guard (free dedup for idempotent ⊕) + store-without-cascade
+   *  apply unchanged. */
+  merge(op) {
+    const old = this.ctx.getCell(this.cell);
+    this.ctx.setCell(this.cell, this.policy.merge(old, op));
+  }
+}
+
+/** Create a `MergeCell` over `ctx` with `initial` value under `policy`. */
+export function mergeCell(ctx, initial, policy) {
+  return new MergeCell(ctx, ctx.cell(initial), policy);
+}
+
+// -- Reactive / Source -------------------------------------------------------
+//
+// JavaScript is structurally typed, so the `Reactive<T>` read supertype and the
+// `Source<T>: Reactive<T>` write sub-interface are documented shapes rather than
+// declared types. A reader (Slot/Signal) exposes { get }; a source (Cell/MergeCell)
+// exposes { get, set, merge }. `asSource` adapts a plain CellHandle to the Source
+// shape (its `merge` is a replace — Cell ≡ MergeCell(KeepLatest)).
+
+/** Adapt a plain `CellHandle` to the `Source` shape (get/set/merge). */
+export function asSource(ctx, cellHandle) {
+  return {
+    get: () => ctx.getCell(cellHandle),
+    set: (value) => ctx.setCell(cellHandle, value),
+    // Cell ≡ MergeCell(KeepLatest): merge replaces.
+    merge: (op) => ctx.setCell(cellHandle, op),
+  };
+}
+
+/** Adapt any read handle (Slot/Signal/Cell) to the `Reactive` shape ({ get }). */
+export function asReactive(ctx, handle) {
+  // Cells read via getCell; slots/signals via get/getSignal. Detect by shape.
+  if (handle instanceof MergeCell) return { get: () => handle.get() };
+  if (handle && handle.slot !== undefined) return { get: () => ctx.getSignal(handle) };
+  // Fall back: try getCell then get.
+  return {
+    get: () => {
+      try {
+        return ctx.getCell(handle);
+      } catch {
+        return ctx.get(handle);
+      }
+    },
+  };
+}