@lazily-hub/lazily-js 0.12.0 → 0.13.0

package/README.md

@@ -40,10 +40,10 @@ notes and platform carve-outs lives in
 | --------- | :----: | :------: | :------: | :--: | :----: | :---: | :--: | :---: |
 | Reactive graph — `Cell` / `Slot` / `Signal` / `Effect` / memo / batch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Reactive family (`ReactiveFamily`) — keyed cell/slot family + materialization mode (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Thread-safe reactive family (`ThreadSafeReactiveFamily`) — `Send + Sync` keyed family + materialization confluence (`#lzmatmode`) | ✅ | — | — | ✅ | — | ✅ | — | ✅ |
-| Async reactive family (`AsyncReactiveFamily`) — keyed family + eventual transparency (`#lzmatmode`) | ✅ | — | — | ✅ | — | ✅ | — | ✅ |
-| Reactive family sync — membership propagation + materialize-on-ingest + derived-aggregate transparency (`#lzfamilysync`) | ✅ | — | ✅ | ✅ | — | ✅ | — | ✅ |
-| Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ |
+| Thread-safe reactive family (`ThreadSafeReactiveFamily`) — `Send + Sync` keyed family + materialization confluence (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Async reactive family (`AsyncReactiveFamily`) — keyed family + eventual transparency (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reactive family sync — membership propagation + materialize-on-ingest + derived-aggregate transparency (`#lzfamilysync`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Async reactive context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Flat state machine | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Harel state charts | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -59,9 +59,10 @@ notes and platform carve-outs lives in
 | 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) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reliable sync — resync coordinator + at-least-once durable outbox + OR-set/LWW liveness (`#lzsync`) | ✅ | — | ✅ | ✅ | — | — | — | — |
 | Distributed plane — WebRTC transport + signaling | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | State projection / mirror | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Causal receipts (`CausalReceipts` outcome projection) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -72,6 +73,11 @@ notes and platform carve-outs lives in
 | Instrumentation / benchmarks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 <!-- coverage-table:end -->
 
+Two JS ✅ marks are backed by runtime-specific mechanisms while keeping the core isomorphic:
+
+- **Thread-safe** (`ThreadSafeReactiveFamily`, `Thread-safe context`) — cross-realm mutual exclusion via a `SharedArrayBuffer` + `Atomics` reentrant mutex shared across Web Workers / `worker_threads`; degrades to a single-realm guard where shared memory is unavailable (e.g. a browser without cross-origin isolation), which is sound because no shared memory means no cross-realm concurrency.
+- **C-ABI FFI** — the normative codec + in-process `FfiChannel` are pure-JS and run unchanged in the browser; the Node build additionally binds the real `lazily` shared library (`lazily_ffi_channel_*`) via koffi. Both speak the identical byte contract, so browser and native are drop-in interchangeable.
+
 CRDT convergence and the wire protocol are pinned by the shared conformance fixtures
 and JSON Schemas in `lazily-spec` and the Lean models in `lazily-formal`.
 ## Packages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Native JavaScript port of the lazily reactive core: a full reactive graph (Cell/Slot/Signal/Effect), sync/async/thread-safe keyed reactive families with materialization mode, 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": {
@@ -93,6 +93,10 @@
       "types": "./src/state-projection.d.ts",
       "default": "./src/state-projection.js"
     },
+    "./state-graph-mirror": {
+      "types": "./src/state-graph-mirror.d.ts",
+      "default": "./src/state-graph-mirror.js"
+    },
     "./signaling": {
       "types": "./src/signaling.d.ts",
       "default": "./src/signaling.js"
@@ -103,7 +107,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/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/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/state-graph-mirror.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",

package/src/distributed.js

@@ -163,10 +163,13 @@ export class WebRtcSink {
       filtered = IpcMessage.delta(
         message.delta.filterReadable(this.#permissions, this.#peer),
       );
-    } else {
+    } else if (message.isCrdtSync) {
       filtered = IpcMessage.crdtSync(
         message.crdtSync.filterReadable(this.#permissions, this.#peer),
       );
+    } else {
+      // Reliable-sync control frames carry no node content; filtering is identity.
+      filtered = message;
     }
     let frame;
     try {

package/src/ffi.js

@@ -21,7 +21,13 @@ import { IpcMessage, LazilyFfiMessageKind, LazilyFfiStatus } from "./index.js";
 export { LazilyFfiMessageKind, LazilyFfiStatus, IpcMessage };
 
 function isUnknownKind(message) {
-  return !(message && (message.isSnapshot || message.isDelta || message.isCrdtSync));
+  return !(
+    message &&
+    (message.isSnapshot ||
+      message.isDelta ||
+      message.isCrdtSync ||
+      message.isControl)
+  );
 }
 
 /**
@@ -43,6 +49,12 @@ export function kindOf(message) {
   if (message.isCrdtSync) {
     return LazilyFfiMessageKind.CrdtSync;
   }
+  if (message.kind === "ResyncRequest") {
+    return LazilyFfiMessageKind.ResyncRequest;
+  }
+  if (message.kind === "OutboxAck") {
+    return LazilyFfiMessageKind.OutboxAck;
+  }
   return LazilyFfiMessageKind.Unknown;
 }
 

package/src/index.d.ts

@@ -233,6 +233,8 @@ export class Delta {
   readonly epoch: number;
   readonly ops: readonly DeltaOpValue[];
   isNextAfter(lastEpoch: number): boolean;
+  /** Accepted-event span `epoch - baseEpoch` (>= 0); > 1 for a multi-epoch-span delta (#lzsync). */
+  span(): number;
   applyStatus(lastEpoch: number): DeltaApplyStatus;
   filterReadable(permissions: PeerPermissions, peer: PeerId): Delta;
   toWire(): unknown;
@@ -385,23 +387,97 @@ export class ReceiptProjection {
   staleReceiptIds(): string[];
 }
 
+// Reliable-sync reverse-channel control frames (#lzsync).
+export class ResyncRequest {
+  constructor(fields: { fromEpoch: number });
+  readonly fromEpoch: number;
+  toWire(): { from_epoch: number };
+  static fromWire(value: unknown): ResyncRequest;
+}
+
+export class OutboxAck {
+  constructor(fields: { throughEpoch: number });
+  readonly throughEpoch: number;
+  toWire(): { through_epoch: number };
+  static fromWire(value: unknown): OutboxAck;
+}
+
 export class IpcMessage {
-  readonly kind: "Snapshot" | "Delta" | "CrdtSync";
+  readonly kind: "Snapshot" | "Delta" | "CrdtSync" | "ResyncRequest" | "OutboxAck";
   readonly snapshot?: Snapshot;
   readonly delta?: Delta;
   readonly crdtSync?: CrdtSync;
+  readonly resyncRequest?: ResyncRequest;
+  readonly outboxAck?: OutboxAck;
   readonly isSnapshot: boolean;
   readonly isDelta: boolean;
   readonly isCrdtSync: boolean;
+  readonly isControl: boolean;
   toWire(): unknown;
   encodeJson(): Uint8Array;
   static snapshot(snapshot: Snapshot): IpcMessage;
   static delta(delta: Delta): IpcMessage;
   static crdtSync(crdtSync: CrdtSync): IpcMessage;
+  static resyncRequestMessage(request: ResyncRequest): IpcMessage;
+  static outboxAckMessage(ack: OutboxAck): IpcMessage;
   static fromWire(value: unknown): IpcMessage;
   static decodeJson(data: Uint8Array | string): IpcMessage;
 }
 
+// Reliable sync protocol (#lzsync).
+export const ResyncAction: {
+  readonly Apply: "Apply";
+  readonly RequestSnapshot: "RequestSnapshot";
+  readonly Ignore: "Ignore";
+};
+
+export type ResyncActionResult = {
+  action: "Apply" | "RequestSnapshot" | "Ignore";
+  fromEpoch?: number;
+};
+
+export class ResyncCoordinator {
+  constructor(lastEpoch?: number);
+  lastEpoch: number;
+  resyncing: boolean;
+  ingestDelta(delta: Delta): ResyncActionResult;
+  ingestSnapshot(snapshotEpoch: number): ResyncActionResult;
+  ingest(msg: IpcMessage): ResyncActionResult;
+  ack(): IpcMessage;
+}
+
+export interface DurableOutbox {
+  append(epoch: number, msg: IpcMessage): void;
+  ackThrough(epoch: number): void;
+  replayFrom(cursor: number): Array<[number, IpcMessage]>;
+  retainedEpochs(): number[];
+}
+
+export class InMemoryOutbox implements DurableOutbox {
+  ackedThrough: number;
+  append(epoch: number, msg: IpcMessage): void;
+  ackThrough(epoch: number): void;
+  replayFrom(cursor: number): Array<[number, IpcMessage]>;
+  retainedEpochs(): number[];
+}
+
+export class OrSet {
+  add(tag: string): void;
+  removeObserved(tags: Iterable<string>): void;
+  present(): boolean;
+  join(other: OrSet): void;
+}
+
+export function wireStampGreater(a: WireStamp, b: WireStamp): boolean;
+
+export class WireLwwRegister<V = unknown> {
+  constructor(stamp: WireStamp, value: V);
+  stamp: WireStamp;
+  value: V;
+  set(stamp: WireStamp, value: V): void;
+  join(other: WireLwwRegister<V>): void;
+}
+
 export const OpKind: {
   readonly Read: "read";
   readonly Write: "write";
@@ -449,6 +525,8 @@ export const LazilyFfiMessageKind: {
   readonly Snapshot: 1;
   readonly Delta: 2;
   readonly CrdtSync: 3;
+  readonly ResyncRequest: 4;
+  readonly OutboxAck: 5;
 };
 
 export const LazilyFfiStatus: {

package/src/index.js

@@ -601,6 +601,13 @@ export class Delta {
     return this.baseEpoch === lastEpoch && this.epoch === this.baseEpoch + 1;
   }
 
+  // The accepted-event span this delta advances: epoch - baseEpoch (usually 1,
+  // > 1 for a coalesced multi-epoch-span delta; #lzsync, spec § Multi-epoch-span
+  // delta). Coerced to >= 0 for a malformed backward delta.
+  span() {
+    return Math.max(0, this.epoch - this.baseEpoch);
+  }
+
   applyStatus(lastEpoch) {
     if (this.isNextAfter(lastEpoch)) {
       return DeltaApplyStatus.apply();
@@ -1007,18 +1014,61 @@ export class ReceiptProjection {
   }
 }
 
+// Reliable-sync reverse-channel control frame: request a covering Snapshot on a
+// detected gap (#lzsync, spec § ResyncCoordinator). Carries no node content.
+export class ResyncRequest {
+  constructor({ fromEpoch }) {
+    this.fromEpoch = assertInteger(fromEpoch, "fromEpoch");
+    Object.freeze(this);
+  }
+
+  toWire() {
+    return { from_epoch: this.fromEpoch };
+  }
+
+  static fromWire(value) {
+    const object = assertObject(value, "ResyncRequest");
+    return new ResyncRequest({ fromEpoch: object.from_epoch });
+  }
+}
+
+// Reliable-sync reverse-channel control frame: prove receipt through throughEpoch
+// (#lzsync, spec § DurableOutbox). Advances the sender's outbox retention cursor
+// and doubles as the reconnect resume cursor. Carries no node content.
+export class OutboxAck {
+  constructor({ throughEpoch }) {
+    this.throughEpoch = assertInteger(throughEpoch, "throughEpoch");
+    Object.freeze(this);
+  }
+
+  toWire() {
+    return { through_epoch: this.throughEpoch };
+  }
+
+  static fromWire(value) {
+    const object = assertObject(value, "OutboxAck");
+    return new OutboxAck({ throughEpoch: object.through_epoch });
+  }
+}
+
 export class IpcMessage {
   constructor(kind, value) {
     this.kind = kind;
     this.snapshot = undefined;
     this.delta = undefined;
     this.crdtSync = undefined;
+    this.resyncRequest = undefined;
+    this.outboxAck = undefined;
     if (kind === "Snapshot") {
       this.snapshot = value;
     } else if (kind === "Delta") {
       this.delta = value;
     } else if (kind === "CrdtSync") {
       this.crdtSync = value;
+    } else if (kind === "ResyncRequest") {
+      this.resyncRequest = value;
+    } else if (kind === "OutboxAck") {
+      this.outboxAck = value;
     } else {
       throw new TypeError(`unknown IpcMessage kind: ${kind}`);
     }
@@ -1037,6 +1087,11 @@ export class IpcMessage {
     return this.kind === "CrdtSync";
   }
 
+  // Reliable-sync reverse-channel control frame (no node content).
+  get isControl() {
+    return this.kind === "ResyncRequest" || this.kind === "OutboxAck";
+  }
+
   toWire() {
     if (this.kind === "Snapshot") {
       return { Snapshot: this.snapshot.toWire() };
@@ -1044,7 +1099,13 @@ export class IpcMessage {
     if (this.kind === "Delta") {
       return { Delta: this.delta.toWire() };
     }
-    return { CrdtSync: this.crdtSync.toWire() };
+    if (this.kind === "CrdtSync") {
+      return { CrdtSync: this.crdtSync.toWire() };
+    }
+    if (this.kind === "ResyncRequest") {
+      return { ResyncRequest: this.resyncRequest.toWire() };
+    }
+    return { OutboxAck: this.outboxAck.toWire() };
   }
 
   encodeJson() {
@@ -1063,6 +1124,14 @@ export class IpcMessage {
     return new IpcMessage("CrdtSync", crdtSync);
   }
 
+  static resyncRequestMessage(request) {
+    return new IpcMessage("ResyncRequest", request);
+  }
+
+  static outboxAckMessage(ack) {
+    return new IpcMessage("OutboxAck", ack);
+  }
+
   static fromWire(value) {
     const [tag, body] = assertTagged(value, "IpcMessage");
     switch (tag) {
@@ -1072,6 +1141,10 @@ export class IpcMessage {
         return IpcMessage.delta(Delta.fromWire(body));
       case "CrdtSync":
         return IpcMessage.crdtSync(CrdtSync.fromWire(body));
+      case "ResyncRequest":
+        return IpcMessage.resyncRequestMessage(ResyncRequest.fromWire(body));
+      case "OutboxAck":
+        return IpcMessage.outboxAckMessage(OutboxAck.fromWire(body));
       default:
         throw new TypeError(`unknown IpcMessage variant: ${tag}`);
     }
@@ -1104,6 +1177,8 @@ export const LazilyFfiMessageKind = Object.freeze({
   Snapshot: 1,
   Delta: 2,
   CrdtSync: 3,
+  ResyncRequest: 4,
+  OutboxAck: 5,
 });
 
 // The FFI status codes mirror schemas/ffi.json § LazilyFfiStatus.
@@ -1116,6 +1191,161 @@ export const LazilyFfiStatus = Object.freeze({
   Panic: 5,
 });
 
+// ---------------------------------------------------------------------------
+// Reliable sync protocol (#lzsync).
+//
+// Delivery-reliability over the Snapshot/Delta/CrdtSync planes (lazily-spec
+// § Reliable Sync): gap recovery, at-least-once outbox, and OR-set / LWW liveness
+// cells. Correctness backstop: lazily-formal ReliableSync.lean; cross-language
+// pins: lazily-spec/conformance/reliable-sync/.
+// ---------------------------------------------------------------------------
+
+// Receiver decision for an inbound frame (spec § ResyncCoordinator).
+export const ResyncAction = Object.freeze({
+  Apply: "Apply",
+  RequestSnapshot: "RequestSnapshot",
+  Ignore: "Ignore",
+});
+
+// Receiver-side reliable-sync coordinator. Holds lastEpoch (highest epoch fully
+// applied) and a resyncing flag (a RequestSnapshot is outstanding until a covering
+// Snapshot lands). ingest advances lastEpoch on Apply; the caller MUST fold the
+// frame's ops on Apply. Mirrors ReliableSync.step.
+export class ResyncCoordinator {
+  constructor(lastEpoch = 0) {
+    this.lastEpoch = assertInteger(lastEpoch, "lastEpoch");
+    this.resyncing = false;
+  }
+
+  // Classify + fold an inbound Delta; advances to delta.epoch on Apply (multi-epoch aware).
+  // Returns { action, fromEpoch? }.
+  ingestDelta(delta) {
+    if (delta.baseEpoch === this.lastEpoch) {
+      if (delta.epoch >= delta.baseEpoch + 1) {
+        this.lastEpoch = delta.epoch;
+        this.resyncing = false;
+        return { action: ResyncAction.Apply };
+      }
+      return { action: ResyncAction.Ignore }; // empty/backward epoch
+    }
+    if (delta.baseEpoch < this.lastEpoch) {
+      return { action: ResyncAction.Ignore }; // already applied — re-delivery
+    }
+    // gap: baseEpoch > lastEpoch
+    if (this.resyncing) {
+      return { action: ResyncAction.Ignore }; // suppress duplicate request
+    }
+    this.resyncing = true;
+    return { action: ResyncAction.RequestSnapshot, fromEpoch: this.lastEpoch };
+  }
+
+  // Adopt a Snapshot — a full-state frame always applies.
+  ingestSnapshot(snapshotEpoch) {
+    this.lastEpoch = snapshotEpoch;
+    this.resyncing = false;
+    return { action: ResyncAction.Apply };
+  }
+
+  // Classify an inbound IpcMessage. CrdtSync rides the CRDT plane and the
+  // reverse-channel control frames are for the sender's driver, so both are
+  // ignored by this data receiver.
+  ingest(msg) {
+    if (msg.isSnapshot) return this.ingestSnapshot(msg.snapshot.epoch);
+    if (msg.isDelta) return this.ingestDelta(msg.delta);
+    return { action: ResyncAction.Ignore };
+  }
+
+  // The IpcMessage(OutboxAck) advertising this receiver's resume cursor.
+  ack() {
+    return IpcMessage.outboxAckMessage(new OutboxAck({ throughEpoch: this.lastEpoch }));
+  }
+}
+
+// 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;
+  }
+
+  append(epoch, msg) {
+    this.entries.push([epoch, msg]);
+  }
+
+  ackThrough(epoch) {
+    if (epoch > this.ackedThrough) this.ackedThrough = epoch;
+    this.entries = this.entries.filter(([e]) => e > this.ackedThrough);
+  }
+
+  replayFrom(cursor) {
+    return this.entries.filter(([e]) => e > cursor).sort((a, b) => a[0] - b[0]);
+  }
+
+  retainedEpochs() {
+    return this.entries.map(([e]) => e).sort((a, b) => a - b);
+  }
+}
+
+// An observed-remove set (OR-set) liveness cell. A (doc, pid) is present iff some
+// add-tag is not shadowed by a remove that observed it (add-wins over a stale
+// remove). Join is the union of both tag sets — a semilattice, so out-of-order and
+// duplicate delivery converge (ReliableSync.joinOR_*).
+export class OrSet {
+  constructor() {
+    this.adds = new Set();
+    this.removes = new Set();
+  }
+
+  add(tag) {
+    this.adds.add(tag);
+  }
+
+  removeObserved(tags) {
+    for (const t of tags) this.removes.add(t);
+  }
+
+  present() {
+    for (const t of this.adds) if (!this.removes.has(t)) return true;
+    return false;
+  }
+
+  join(other) {
+    for (const t of other.adds) this.adds.add(t);
+    for (const t of other.removes) this.removes.add(t);
+  }
+}
+
+// Total order (wallTime, logical, peer) — the wire mirror of the HLC stamp.
+export function wireStampGreater(a, b) {
+  if (a.wallTime !== b.wallTime) return a.wallTime > b.wallTime;
+  if (a.logical !== b.logical) return a.logical > b.logical;
+  return a.peer > b.peer;
+}
+
+// A last-writer-wins register liveness cell (per-pid alive, owner lease), keyed by
+// WireStamp: the highest stamp wins. Join is the stamp-max, a semilattice
+// (ReliableSync.joinReg_*).
+export class WireLwwRegister {
+  constructor(stamp, value) {
+    this.stamp = stamp;
+    this.value = value;
+  }
+
+  // Write value at stamp iff it dominates the current stamp.
+  set(stamp, value) {
+    if (wireStampGreater(stamp, this.stamp)) {
+      this.stamp = stamp;
+      this.value = value;
+    }
+  }
+
+  // Join another replica's register (keep the higher stamp).
+  join(other) {
+    this.set(other.stamp, other.value);
+  }
+}
+
 function assertString(value, name) {
   if (typeof value !== "string") {
     throw new TypeError(`${name} must be a string`);

package/src/state-graph-mirror.d.ts

@@ -0,0 +1,58 @@
+/**
+ * lazily-js reactive `StateGraphMirror` for the agent-doc FFI state backbone
+ * (`#r5at` / `#lazilystatesync4` / `#s5`). Library-owned port of lazily-kt's
+ * `StateGraphMirror.kt`; node payloads live in reactive cells and the summary
+ * is a memoized derived slot, so consumer reads are reactive.
+ */
+
+/** The agent-doc state node `type_tag`s (cross-language vocabulary). */
+export const AgentDocNodeType: {
+  readonly ROUTE: 'agent_doc.route';
+  readonly QUEUE: 'agent_doc.queue';
+  readonly QUEUE_HEAD: 'agent_doc.queue.head';
+  readonly CLOSEOUT_CYCLE: 'agent_doc.closeout.cycle';
+  readonly TRANSPORT_PATCH: 'agent_doc.transport.patch';
+  readonly SUPERVISOR_OWNER: 'agent_doc.supervisor.owner';
+  readonly DOCUMENT_BASELINE: 'agent_doc.document.baseline';
+  readonly DOCUMENT_AUTHORITY: 'agent_doc.document.authority';
+  readonly PROOF_MARKER: 'agent_doc.proof.marker';
+};
+
+/** One tracked node in the mirror graph. `payload` is `base64(serde_json(struct))`. */
+export interface MirrorNode {
+  slotId: number;
+  typeTag: string;
+  payload: string | null;
+}
+
+/** Reactive projection summary derived from a {@link StateGraphMirror}'s cells. */
+export interface MirrorProjectionSummary {
+  routeReadiness?: string;
+  routePaneId?: string;
+  latestTransportPatchId?: string;
+  latestTransportPhase?: string;
+  proofMarkers: number;
+}
+
+/** Decode a `base64(serde_json(struct))` payload to a JSON object, or null. */
+export function decodePayload(payload: string | null | undefined): Record<string, any> | null;
+
+/** Render the compact editor-visible status string (kt `.compact()` parity). */
+export function compactMirrorSummary(summary: MirrorProjectionSummary): string;
+
+/** The pure, FFI-free reactive mirror graph a plugin holds per document. */
+export class StateGraphMirror {
+  constructor();
+  get epoch(): number;
+  get documentHash(): string | null;
+  get isInitialized(): boolean;
+  get nodeCount(): number;
+  applySnapshot(snapshot: any): boolean;
+  applyDelta(delta: any): boolean;
+  applyMessage(raw: string): boolean;
+  nodesOfType(typeTag: string): MirrorNode[];
+  singletonNode(typeTag: string): MirrorNode | null;
+  payloadObject(typeTag: string): Record<string, any> | null;
+  summary(): MirrorProjectionSummary;
+  compactSummary(): string;
+}

package/src/state-graph-mirror.js

@@ -0,0 +1,366 @@
+// lazily-js reactive `StateGraphMirror` for the agent-doc FFI state backbone
+// (`#r5at` / `#lazilystatesync4` / `#s5`).
+//
+// This is the library-owned port of lazily-kt's `StateGraphMirror.kt`
+// (`io.github.lazily.StateGraphMirror` / `MirrorProjectionSummary`,
+// `#n529`/`#lazilystatesync3`). The binary (lazily-rs) owns the authoritative
+// reactive state graph; this mirror applies the `agent_doc_state_subscribe`
+// snapshot/delta messages so editor UI (dispatch-ready / busy / queue
+// indicators) derives from tracked reactive cells instead of re-rendering the
+// full projection JSON on every observed event.
+//
+// Unlike the old hand-rolled `Map` fold that lived in the VS Code extension,
+// this mirror is a REAL lazily reactive graph: node payloads live in
+// per-`slot_id` reactive cells inside a `Context`, structure changes bump a
+// membership cell, and the projection summary is a memoized derived slot. A
+// `cell_set` on a tracked node reactively invalidates the summary; an unrelated
+// `cell_set` does not.
+//
+// Wire shapes match `agent-doc-orchestration/src/state_wire.rs` and
+// `src/lazily-spec/schemas/{snapshot,delta}.json`:
+//   - snapshot: { type:"snapshot", epoch, document_hash, nodes[], edges[], roots[] }
+//   - delta:    { type:"delta", base_epoch, epoch, document_hash, ops[] }
+//
+// Because the projection is a pure fold of deduped events, delta application is
+// deterministic and idempotent — a no-op delta (re-emit) leaves the mirror
+// unchanged (`#qdedupsync` property). Field names + the `compact()` format are
+// pinned 1:1 to the kt `MirrorProjectionSummary` for cross-language parity.
+
+import { Context } from "./reactive.js";
+
+/** The agent-doc state node `type_tag`s (cross-language vocabulary). */
+export const AgentDocNodeType = Object.freeze({
+  ROUTE: "agent_doc.route",
+  QUEUE: "agent_doc.queue",
+  QUEUE_HEAD: "agent_doc.queue.head",
+  CLOSEOUT_CYCLE: "agent_doc.closeout.cycle",
+  TRANSPORT_PATCH: "agent_doc.transport.patch",
+  SUPERVISOR_OWNER: "agent_doc.supervisor.owner",
+  DOCUMENT_BASELINE: "agent_doc.document.baseline",
+  DOCUMENT_AUTHORITY: "agent_doc.document.authority",
+  PROOF_MARKER: "agent_doc.proof.marker",
+});
+
+/**
+ * Decode a `base64(serde_json(struct))` payload to a JSON object, or null on
+ * failure / unset payload. Pure — exported for tests + consumers.
+ *
+ * @param {string | null | undefined} payload
+ * @returns {Record<string, any> | null}
+ */
+export function decodePayload(payload) {
+  if (payload == null || payload === "") return null;
+  try {
+    const json = Buffer.from(payload, "base64").toString("utf-8");
+    const parsed = JSON.parse(json);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render the compact editor-visible status string (matches the kt
+ * `MirrorProjectionSummary.compact()` EXACTLY for cross-language parity).
+ *
+ * @param {{ routeReadiness?: string, routePaneId?: string, latestTransportPatchId?: string, latestTransportPhase?: string, proofMarkers: number }} summary
+ * @returns {string}
+ */
+export function compactMirrorSummary(summary) {
+  return (
+    `route=${summary.routeReadiness ?? "unknown"} pane=${summary.routePaneId ?? "-"} ` +
+    `transport=${summary.latestTransportPatchId ?? "-"}:${summary.latestTransportPhase ?? "-"} ` +
+    `proof_markers=${summary.proofMarkers}`
+  );
+}
+
+function stringField(obj, key) {
+  if (!obj) return undefined;
+  const value = obj[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * The pure, FFI-free reactive mirror graph a plugin holds per document.
+ *
+ * Node payloads live in reactive cells keyed by `slot_id`; the projection
+ * summary is a memoized derived slot over those cells + a membership cell. The
+ * public read surface (`summary`, `nodesOfType`, `singletonNode`,
+ * `payloadObject`) reads through the reactive `Context`.
+ */
+export class StateGraphMirror {
+  /** @type {Context} */
+  #ctx;
+  /** slotId -> { typeTag, cell } — the reactive node cells. */
+  #nodes = new Map();
+  /** slotId insertion order (stable). */
+  #order = [];
+  /** "dependent:dependency" edge keys. */
+  #edges = new Set();
+  /** CellHandle<number> — bumped whenever the node set / types change. */
+  #membership;
+  #membershipVersion = 0;
+  /** SlotHandle — the memoized projection summary derived from tracked cells. */
+  #summaryMemo;
+
+  #declaredHash = null;
+  #epoch = 0;
+
+  constructor() {
+    this.#reset();
+  }
+
+  /** Rebuild a fresh reactive graph (cold snapshot / construction). */
+  #reset() {
+    this.#ctx = new Context();
+    this.#nodes = new Map();
+    this.#order = [];
+    this.#edges = new Set();
+    this.#membershipVersion = 0;
+    this.#membership = this.#ctx.cell(0);
+    this.#summaryMemo = this.#ctx.memo(() => this.#computeSummary());
+  }
+
+  #bumpMembership() {
+    this.#membershipVersion += 1;
+    this.#ctx.setCell(this.#membership, this.#membershipVersion);
+  }
+
+  static #edgeKey(dependent, dependency) {
+    return `${dependent}:${dependency}`;
+  }
+
+  /** Monotonic frontier — the highest lazily-spec epoch applied so far. */
+  get epoch() {
+    return this.#epoch;
+  }
+
+  /** The document hash declared by the last applied snapshot/delta, or null. */
+  get documentHash() {
+    return this.#declaredHash;
+  }
+
+  /** True until at least one snapshot/delta has been applied. */
+  get isInitialized() {
+    return this.#declaredHash !== null;
+  }
+
+  get nodeCount() {
+    return this.#nodes.size;
+  }
+
+  // -- Node materialization (reactive cells) ----------------------------
+
+  #putNode(slotId, typeTag, payload) {
+    const existing = this.#nodes.get(slotId);
+    if (existing) {
+      const typeChanged = existing.typeTag !== typeTag;
+      existing.typeTag = typeTag;
+      this.#ctx.setCell(existing.cell, payload ?? null);
+      if (typeChanged) this.#bumpMembership();
+      return;
+    }
+    const cell = this.#ctx.cell(payload ?? null);
+    this.#nodes.set(slotId, { typeTag, cell });
+    this.#order.push(slotId);
+    this.#bumpMembership();
+  }
+
+  #setNodePayload(slotId, payload) {
+    const node = this.#nodes.get(slotId);
+    if (node) this.#ctx.setCell(node.cell, payload ?? null);
+  }
+
+  #removeNode(slotId) {
+    if (!this.#nodes.delete(slotId)) return;
+    const idx = this.#order.indexOf(slotId);
+    if (idx !== -1) this.#order.splice(idx, 1);
+    this.#bumpMembership();
+  }
+
+  /** Read a node's live payload through the reactive context (registers dep). */
+  #nodePayload(slotId) {
+    const node = this.#nodes.get(slotId);
+    return node ? this.#ctx.getCell(node.cell) : null;
+  }
+
+  #materializedNodes() {
+    const out = [];
+    for (const slotId of this.#order) {
+      const node = this.#nodes.get(slotId);
+      if (node) out.push({ slotId, typeTag: node.typeTag, payload: this.#nodePayload(slotId) });
+    }
+    return out;
+  }
+
+  // -- Apply ------------------------------------------------------------
+
+  /**
+   * Apply a cold-read snapshot object, replacing the whole reactive graph.
+   * @param {any} snapshot parsed `{ type:"snapshot", epoch, document_hash, nodes, edges, roots }`
+   * @returns {boolean}
+   */
+  applySnapshot(snapshot) {
+    if (!snapshot || typeof snapshot !== "object") return false;
+    this.#reset();
+    if (typeof snapshot.document_hash === "string") this.#declaredHash = snapshot.document_hash;
+    if (Array.isArray(snapshot.nodes)) {
+      for (const node of snapshot.nodes) {
+        if (!node || typeof node.slot_id !== "number" || typeof node.type_tag !== "string") continue;
+        const payload = typeof node.payload === "string" ? node.payload : null;
+        this.#putNode(node.slot_id, node.type_tag, payload);
+      }
+    }
+    if (Array.isArray(snapshot.edges)) {
+      for (const edge of snapshot.edges) {
+        if (!edge || typeof edge.dependent !== "number" || typeof edge.dependency !== "number") continue;
+        this.#edges.add(StateGraphMirror.#edgeKey(edge.dependent, edge.dependency));
+      }
+    }
+    if (typeof snapshot.epoch === "number") this.#epoch = snapshot.epoch;
+    return true;
+  }
+
+  /**
+   * Apply a warm delta object. Ops are applied verbatim in emission order; the
+   * frontier advances to `max(epoch, delta.epoch)`. A no-op delta (empty ops)
+   * only advances the epoch.
+   * @param {any} delta parsed `{ type:"delta", base_epoch, epoch, document_hash, ops }`
+   * @returns {boolean}
+   */
+  applyDelta(delta) {
+    if (!delta || typeof delta !== "object") return false;
+    if (typeof delta.document_hash === "string") this.#declaredHash = delta.document_hash;
+    if (Array.isArray(delta.ops)) {
+      for (const op of delta.ops) {
+        if (!op || typeof op.op !== "string") continue;
+        switch (op.op) {
+          case "node_add": {
+            if (typeof op.slot_id !== "number" || typeof op.type_tag !== "string") break;
+            const payload = typeof op.payload === "string" ? op.payload : null;
+            this.#putNode(op.slot_id, op.type_tag, payload);
+            break;
+          }
+          case "cell_set":
+          case "slot_value": {
+            if (typeof op.slot_id !== "number") break;
+            this.#setNodePayload(op.slot_id, typeof op.payload === "string" ? op.payload : null);
+            break;
+          }
+          case "invalidate":
+            // Derived recompute is plugin-side; the mirror holds the stale
+            // payload until a cell_set arrives.
+            break;
+          case "node_remove":
+            if (typeof op.slot_id === "number") this.#removeNode(op.slot_id);
+            break;
+          case "edge_add":
+            if (typeof op.dependent === "number" && typeof op.dependency === "number") {
+              this.#edges.add(StateGraphMirror.#edgeKey(op.dependent, op.dependency));
+            }
+            break;
+          case "edge_remove":
+            if (typeof op.dependent === "number" && typeof op.dependency === "number") {
+              this.#edges.delete(StateGraphMirror.#edgeKey(op.dependent, op.dependency));
+            }
+            break;
+          default:
+            break;
+        }
+      }
+    }
+    if (typeof delta.epoch === "number") this.#epoch = Math.max(this.#epoch, delta.epoch);
+    return true;
+  }
+
+  /**
+   * Apply a raw `agent_doc_state_subscribe` message, dispatching on the
+   * lazily-spec `"type"` discriminator (`snapshot` or `delta`). Returns false
+   * when the message cannot be parsed / has an unknown type.
+   * @param {string} raw
+   * @returns {boolean}
+   */
+  applyMessage(raw) {
+    let root;
+    try {
+      root = JSON.parse(raw);
+    } catch {
+      return false;
+    }
+    if (!root || typeof root !== "object" || typeof root.type !== "string") return false;
+    if (root.type === "snapshot") return this.applySnapshot(root);
+    if (root.type === "delta") return this.applyDelta(root);
+    return false;
+  }
+
+  // -- Read (reactive) --------------------------------------------------
+
+  /** All tracked nodes of `typeTag` (stable insertion order). */
+  nodesOfType(typeTag) {
+    const out = [];
+    for (const slotId of this.#order) {
+      const node = this.#nodes.get(slotId);
+      if (node && node.typeTag === typeTag) {
+        out.push({ slotId, typeTag: node.typeTag, payload: this.#nodePayload(slotId) });
+      }
+    }
+    return out;
+  }
+
+  /** The single document-level node for `typeTag`, or null. */
+  singletonNode(typeTag) {
+    for (const slotId of this.#order) {
+      const node = this.#nodes.get(slotId);
+      if (node && node.typeTag === typeTag) {
+        return { slotId, typeTag: node.typeTag, payload: this.#nodePayload(slotId) };
+      }
+    }
+    return null;
+  }
+
+  /** Decode a node payload (`base64(serde_json(struct))`) as a JSON object, or null. */
+  payloadObject(typeTag) {
+    const node = this.singletonNode(typeTag);
+    return node ? decodePayload(node.payload) : null;
+  }
+
+  #computeSummary() {
+    // Structure dependency: recompute the summary when the node set changes.
+    this.#ctx.getCell(this.#membership);
+
+    const routeNode = this.singletonNode(AgentDocNodeType.ROUTE);
+    const route = routeNode ? decodePayload(routeNode.payload) : null;
+    const routeReadiness = stringField(route, "readiness");
+    const routePaneId = stringField(route, "pane_id");
+
+    const patches = this.nodesOfType(AgentDocNodeType.TRANSPORT_PATCH);
+    const latest = patches.length > 0
+      ? patches.reduce((a, b) => (b.slotId > a.slotId ? b : a))
+      : undefined;
+    const latestTransportPhase = latest ? stringField(decodePayload(latest.payload), "phase") : undefined;
+
+    const proofMarkers = this.nodesOfType(AgentDocNodeType.PROOF_MARKER).length;
+
+    return {
+      routeReadiness,
+      routePaneId,
+      latestTransportPatchId: undefined,
+      latestTransportPhase,
+      proofMarkers,
+    };
+  }
+
+  /**
+   * Reactive projection summary derived from this mirror's tracked cells (the
+   * memoized analog of the kt `MirrorProjectionSummary.fromMirror`).
+   * @returns {{ routeReadiness?: string, routePaneId?: string, latestTransportPatchId?: string, latestTransportPhase?: string, proofMarkers: number }}
+   */
+  summary() {
+    return this.#ctx.get(this.#summaryMemo);
+  }
+
+  /** The compact editor-visible status string (kt `.compact()` parity). */
+  compactSummary() {
+    return compactMirrorSummary(this.summary());
+  }
+}