trellis 3.1.34 → 3.2.0

package/dist/state-demo.bundle.js

@@ -0,0 +1,1033 @@
+// src/vcs/ops.ts
+async function hashVcsOp(op) {
+  const content = JSON.stringify({
+    kind: op.kind,
+    timestamp: op.timestamp,
+    agentId: op.agentId,
+    previousHash: op.previousHash,
+    vcs: op.vcs
+  });
+  const msgUint8 = new TextEncoder().encode(content);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", msgUint8);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `trellis:op:${hashHex}`;
+}
+async function verifyVcsOpHash(op) {
+  return op.hash === await hashVcsOp(op);
+}
+async function createVcsOp(kind, params) {
+  const opBase = {
+    kind,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    agentId: params.agentId,
+    previousHash: params.previousHash,
+    vcs: params.vcs
+  };
+  return {
+    ...opBase,
+    hash: await hashVcsOp(opBase)
+  };
+}
+function isVcsOpKind(kind) {
+  return kind.startsWith("vcs:");
+}
+
+// demo/state-demo/issue-projector.ts
+function projectIssues(ops) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const op of ops) {
+    const id = op.vcs?.issueId;
+    if (!id) continue;
+    if (op.kind === "vcs:issueCreate") {
+      byId.set(id, {
+        id,
+        title: op.vcs?.issueTitle ?? id,
+        status: op.vcs?.issueStatus === "closed" ? "closed" : "open",
+        priority: op.vcs?.issuePriority,
+        agentId: op.agentId
+      });
+      continue;
+    }
+    const issue = byId.get(id);
+    if (!issue) continue;
+    if (op.kind === "vcs:issueClose") {
+      issue.status = "closed";
+    } else if (op.kind === "vcs:issueReopen") {
+      issue.status = "open";
+    } else if (op.kind === "vcs:issueUpdate" && op.vcs?.issueStatus === "closed") {
+      issue.status = "closed";
+    } else if (op.kind === "vcs:issueUpdate" && op.vcs?.issueTitle) {
+      issue.title = op.vcs.issueTitle;
+    }
+  }
+  return [...byId.values()];
+}
+
+// demo/state-demo/demo-session.ts
+var DemoSession = class {
+  agentId;
+  ops = [];
+  issueSeq = 0;
+  onChange;
+  onAfterWrite;
+  constructor(opts = {}) {
+    this.agentId = opts.agentId ?? "agent:demo";
+    this.onChange = opts.onChange;
+    this.onAfterWrite = opts.onAfterWrite;
+  }
+  getAgentId() {
+    return this.agentId;
+  }
+  getOps() {
+    return [...this.ops];
+  }
+  getIssues() {
+    const owned = /* @__PURE__ */ new Set();
+    for (const op of this.ops) {
+      if (op.kind === "vcs:issueCreate" && op.agentId === this.agentId && op.vcs?.issueId) {
+        owned.add(op.vcs.issueId);
+      }
+    }
+    return projectIssues(this.ops).filter((i) => owned.has(i.id));
+  }
+  /** Merge remote ops (dedupe by hash, sort by time). */
+  integrate(remote) {
+    const seen = new Set(this.ops.map((o) => o.hash));
+    let changed = false;
+    for (const op of remote) {
+      if (seen.has(op.hash)) continue;
+      this.ops.push(op);
+      seen.add(op.hash);
+      changed = true;
+    }
+    if (changed) {
+      this.ops.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+      this.emit();
+    }
+  }
+  nextIssueId() {
+    this.issueSeq += 1;
+    const slug = this.agentId.replace(/^agent:/, "") || "peer";
+    return `TRL-${slug}-${this.issueSeq}`;
+  }
+  async addIssue(title, priority = "medium") {
+    const issueId = this.nextIssueId();
+    const op = await createVcsOp("vcs:issueCreate", {
+      agentId: this.agentId,
+      previousHash: this.lastHash(),
+      vcs: {
+        issueId,
+        issueTitle: title.trim() || "Untitled",
+        issueStatus: "queue",
+        issuePriority: priority
+      }
+    });
+    this.ops.push(op);
+    const advance = await createVcsOp("vcs:branchAdvance", {
+      agentId: this.agentId,
+      previousHash: op.hash,
+      vcs: { branchName: "main", headHash: op.hash }
+    });
+    this.ops.push(advance);
+    this.emit();
+    return op;
+  }
+  async setIssueClosed(id, closed) {
+    const issue = this.getIssues().find((i) => i.id === id);
+    if (!issue) return null;
+    if (closed && issue.status === "closed") return null;
+    if (!closed && issue.status === "open") return null;
+    const kind = closed ? "vcs:issueClose" : "vcs:issueReopen";
+    const op = await createVcsOp(kind, {
+      agentId: this.agentId,
+      previousHash: this.lastHash(),
+      vcs: {
+        issueId: id,
+        issueStatus: closed ? "closed" : "queue"
+      }
+    });
+    this.ops.push(op);
+    this.emit();
+    return op;
+  }
+  lastHash() {
+    return this.ops[this.ops.length - 1]?.hash;
+  }
+  emit() {
+    this.onChange?.({ ops: this.getOps(), issues: this.getIssues() });
+    void this.onAfterWrite?.();
+  }
+};
+function mergeOps(...logs) {
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const log of logs) {
+    for (const op of log) {
+      if (seen.has(op.hash)) continue;
+      seen.add(op.hash);
+      merged.push(op);
+    }
+  }
+  return merged.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+}
+
+// src/sync/types.ts
+var PROTOCOL_VERSION = 1;
+var MIN_SUPPORTED_VERSION = 1;
+var MAX_SUPPORTED_VERSION = 1;
+
+// src/sync/room-core.ts
+var DEFAULT_SNAPSHOT_MAX_OPS = 500;
+var SyncRoomCore = class {
+  roomPeer;
+  peers = /* @__PURE__ */ new Map();
+  ops = [];
+  constructor(roomId = "room", roomName = roomId) {
+    this.roomPeer = {
+      id: roomId,
+      name: roomName
+    };
+  }
+  connectPeer(peerId, peerName = peerId) {
+    this.peers.set(peerId, {
+      id: peerId,
+      name: peerName,
+      lastSeen: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  disconnectPeer(peerId) {
+    this.peers.delete(peerId);
+  }
+  getRoomPeer() {
+    return { ...this.roomPeer };
+  }
+  peersFor(peerId) {
+    return [
+      this.getRoomPeer(),
+      ...[...this.peers.values()].filter((peer) => peer.id !== peerId).map((peer) => ({ ...peer }))
+    ];
+  }
+  getOps() {
+    return [...this.ops];
+  }
+  getOpCount() {
+    return this.ops.length;
+  }
+  /** Build a tail snapshot for late-joiner catch-up. */
+  buildSnapshot(maxOps = DEFAULT_SNAPSHOT_MAX_OPS) {
+    const opCount = this.ops.length;
+    const headHash = this.ops.at(-1)?.hash;
+    if (opCount <= maxOps) {
+      return {
+        headHash,
+        opCount,
+        truncated: false,
+        ops: [...this.ops]
+      };
+    }
+    return {
+      headHash,
+      opCount,
+      truncated: true,
+      ops: this.ops.slice(-maxOps)
+    };
+  }
+  /** Deliver a snapshot message to a connected peer. */
+  snapshotDeliveries(peerId, maxOps = DEFAULT_SNAPSHOT_MAX_OPS) {
+    const snap = this.buildSnapshot(maxOps);
+    return [
+      {
+        peerId,
+        message: {
+          version: PROTOCOL_VERSION,
+          type: "snapshot",
+          peerId: this.roomPeer.id,
+          headHash: snap.headHash,
+          opCount: snap.opCount,
+          truncated: snap.truncated,
+          ops: snap.ops
+        }
+      }
+    ];
+  }
+  async receive(fromPeerId, message) {
+    const peer = this.peers.get(fromPeerId);
+    if (peer) {
+      peer.lastSeen = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    if (typeof message.version !== "number" || message.version < MIN_SUPPORTED_VERSION || message.version > MAX_SUPPORTED_VERSION) {
+      return [
+        {
+          peerId: fromPeerId,
+          message: {
+            version: PROTOCOL_VERSION,
+            type: "nack",
+            peerId: this.roomPeer.id,
+            refs: [],
+            reason: "protocol-version",
+            details: `Unsupported protocol version ${message.version}; supported range is ${MIN_SUPPORTED_VERSION}-${MAX_SUPPORTED_VERSION}.`
+          }
+        }
+      ];
+    }
+    switch (message.type) {
+      case "have":
+        return this.handleHave(fromPeerId, message);
+      case "want":
+        return this.handleWant(fromPeerId, message);
+      case "sync-snapshot":
+        return this.snapshotDeliveries(
+          fromPeerId,
+          message.maxOps ?? DEFAULT_SNAPSHOT_MAX_OPS
+        );
+      case "ops":
+        return this.handleOps(fromPeerId, message.ops);
+      case "ack":
+      case "nack":
+      case "snapshot":
+        return [];
+    }
+  }
+  async handleHave(peerId, message) {
+    const deliveries = this.roomOpsDeliveries(peerId, message.heads.main);
+    const roomHashes = new Set(this.ops.map((op) => op.hash));
+    const peerHead = message.heads.main;
+    if (message.opCount > this.ops.length || peerHead && !roomHashes.has(peerHead)) {
+      deliveries.push({
+        peerId,
+        message: {
+          version: PROTOCOL_VERSION,
+          type: "want",
+          peerId: this.roomPeer.id,
+          wantHashes: []
+        }
+      });
+    } else if (!deliveries.some(
+      (d) => d.message.type === "want" || d.message.type === "ops"
+    )) {
+      deliveries.push({
+        peerId,
+        message: {
+          version: PROTOCOL_VERSION,
+          type: "want",
+          peerId: this.roomPeer.id,
+          wantHashes: []
+        }
+      });
+    }
+    return deliveries;
+  }
+  async handleWant(peerId, message) {
+    if (message.wantHashes.length > 0) {
+      const wanted = new Set(message.wantHashes);
+      return this.opsDelivery(
+        peerId,
+        this.ops.filter((op) => wanted.has(op.hash))
+      );
+    }
+    if (message.maxOps !== void 0 && message.maxOps > 0 && !message.afterHash) {
+      return this.snapshotDeliveries(peerId, message.maxOps);
+    }
+    return this.roomOpsDeliveries(peerId, message.afterHash);
+  }
+  async handleOps(peerId, ops) {
+    const result = await this.appendOps(ops);
+    const accepted = ops.filter(
+      (op) => this.ops.some((roomOp) => roomOp.hash === op.hash)
+    );
+    const deliveries = [];
+    if (accepted.length > 0) {
+      deliveries.push({
+        peerId,
+        message: {
+          version: PROTOCOL_VERSION,
+          type: "ack",
+          peerId: this.roomPeer.id,
+          integrated: accepted.map((op) => op.hash)
+        }
+      });
+    }
+    if (result.acceptedOps.length > 0) {
+      deliveries.push(...this.broadcastOps(peerId, result.acceptedOps));
+    }
+    return deliveries;
+  }
+  async appendOps(incomingOps) {
+    const known = new Set(this.ops.map((op) => op.hash));
+    const pendingByHash = /* @__PURE__ */ new Map();
+    const rejected = [];
+    const acceptedOps = [];
+    let skipped = 0;
+    let applied = 0;
+    for (const op of incomingOps) {
+      if (known.has(op.hash) || pendingByHash.has(op.hash)) {
+        skipped++;
+        continue;
+      }
+      if (!isVcsOpKind(op.kind)) {
+        rejected.push({
+          op,
+          reason: "invalid-kind",
+          message: `Rejected non-VCS op kind '${op.kind}'.`
+        });
+        continue;
+      }
+      if (!await verifyVcsOpHash(op)) {
+        rejected.push({
+          op,
+          reason: "hash-mismatch",
+          message: `Rejected op with mismatched hash '${op.hash}'.`
+        });
+        continue;
+      }
+      pendingByHash.set(op.hash, op);
+    }
+    let pending = [...pendingByHash.values()];
+    while (pending.length > 0) {
+      const nextPending = [];
+      let progressed = false;
+      for (const op of pending) {
+        if (op.previousHash && !known.has(op.previousHash)) {
+          nextPending.push(op);
+          continue;
+        }
+        this.ops.push(op);
+        known.add(op.hash);
+        acceptedOps.push(op);
+        applied++;
+        progressed = true;
+      }
+      if (!progressed) {
+        for (const op of nextPending) {
+          rejected.push({
+            op,
+            reason: "missing-dependency",
+            message: `Missing previousHash '${op.previousHash}' for op '${op.hash}'.`
+          });
+        }
+        break;
+      }
+      pending = nextPending;
+    }
+    return { applied, skipped, rejected, acceptedOps };
+  }
+  roomOpsDeliveries(peerId, afterHash) {
+    let ops = this.ops;
+    if (afterHash) {
+      const index = this.ops.findIndex((op) => op.hash === afterHash);
+      ops = index >= 0 ? this.ops.slice(index + 1) : this.ops;
+    }
+    return this.opsDelivery(peerId, ops);
+  }
+  opsDelivery(peerId, ops) {
+    if (ops.length === 0) return [];
+    return [
+      {
+        peerId,
+        message: {
+          version: PROTOCOL_VERSION,
+          type: "ops",
+          peerId: this.roomPeer.id,
+          ops
+        }
+      }
+    ];
+  }
+  broadcastOps(fromPeerId, ops) {
+    const deliveries = [];
+    for (const peerId of this.peers.keys()) {
+      if (peerId === fromPeerId) continue;
+      deliveries.push(...this.opsDelivery(peerId, ops));
+    }
+    return deliveries;
+  }
+};
+
+// src/sync/memory-room.ts
+var MemorySyncRoom = class {
+  core;
+  transports = /* @__PURE__ */ new Map();
+  constructor(roomId = "room", roomName = roomId) {
+    this.core = new SyncRoomCore(roomId, roomName);
+  }
+  connectPeer(peerId, peerName = peerId) {
+    this.core.connectPeer(peerId, peerName);
+    const transport = new MemoryRoomTransport(this, peerId, peerName);
+    this.transports.set(peerId, transport);
+    return transport;
+  }
+  disconnectPeer(peerId) {
+    this.core.disconnectPeer(peerId);
+    this.transports.delete(peerId);
+  }
+  getRoomPeer() {
+    return this.core.getRoomPeer();
+  }
+  peersFor(peerId) {
+    return this.core.peersFor(peerId);
+  }
+  getOps() {
+    return this.core.getOps();
+  }
+  getOpCount() {
+    return this.core.getOpCount();
+  }
+  async receive(fromPeerId, message) {
+    const deliveries = await this.core.receive(fromPeerId, message);
+    for (const delivery of deliveries) {
+      await this.deliver(delivery.peerId, delivery.message);
+    }
+  }
+  async deliver(peerId, message) {
+    const transport = this.transports.get(peerId);
+    if (!transport) {
+      throw new Error(`Peer not connected to room: ${peerId}`);
+    }
+    await transport.deliver(message);
+  }
+};
+var MemoryRoomTransport = class {
+  room;
+  peerId;
+  peerName;
+  handlers = [];
+  constructor(room, peerId, peerName = peerId) {
+    this.room = room;
+    this.peerId = peerId;
+    this.peerName = peerName;
+  }
+  async send(peerId, message) {
+    if (peerId !== this.room.getRoomPeer().id) {
+      throw new Error(`Peer not connected through room: ${peerId}`);
+    }
+    await this.room.receive(this.peerId, message);
+  }
+  onMessage(handler) {
+    this.handlers.push(handler);
+  }
+  peers() {
+    return this.room.peersFor(this.peerId);
+  }
+  getPeerId() {
+    return this.peerId;
+  }
+  getPeerName() {
+    return this.peerName;
+  }
+  async deliver(message) {
+    for (const handler of this.handlers) {
+      await handler(message);
+    }
+  }
+};
+
+// src/sync/reconciler.ts
+function findForkPoint(opsA, opsB) {
+  const hashesB = new Set(opsB.map((o) => o.hash));
+  let forkPoint = null;
+  for (const op of opsA) {
+    if (hashesB.has(op.hash)) {
+      forkPoint = op.hash;
+    }
+  }
+  return forkPoint;
+}
+function reconcile(opsA, opsB) {
+  const forkPoint = findForkPoint(opsA, opsB);
+  const hashesA = new Set(opsA.map((o) => o.hash));
+  const hashesB = new Set(opsB.map((o) => o.hash));
+  const shared = [];
+  const uniqueToA = [];
+  const uniqueToB = [];
+  for (const op of opsA) {
+    if (hashesB.has(op.hash)) {
+      shared.push(op);
+    } else {
+      uniqueToA.push(op);
+    }
+  }
+  for (const op of opsB) {
+    if (!hashesA.has(op.hash)) {
+      uniqueToB.push(op);
+    }
+  }
+  if (uniqueToA.length === 0) {
+    return {
+      merged: [...shared, ...uniqueToB],
+      uniqueToA: [],
+      uniqueToB,
+      forkPoint,
+      clean: true,
+      conflicts: []
+    };
+  }
+  if (uniqueToB.length === 0) {
+    return {
+      merged: [...shared, ...uniqueToA],
+      uniqueToA,
+      uniqueToB: [],
+      forkPoint,
+      clean: true,
+      conflicts: []
+    };
+  }
+  const conflicts = detectConflicts(uniqueToA, uniqueToB);
+  const interleaved = interleaveByTimestamp(uniqueToA, uniqueToB);
+  return {
+    merged: [...shared, ...interleaved],
+    uniqueToA,
+    uniqueToB,
+    forkPoint,
+    clean: conflicts.length === 0,
+    conflicts
+  };
+}
+var FILE_MUTATION_KINDS = /* @__PURE__ */ new Set([
+  "vcs:fileAdd",
+  "vcs:fileModify",
+  "vcs:fileDelete",
+  "vcs:fileRename"
+]);
+function detectConflicts(uniqueA, uniqueB) {
+  const conflicts = [];
+  const aMutations = /* @__PURE__ */ new Map();
+  for (const op of uniqueA) {
+    if (!FILE_MUTATION_KINDS.has(op.kind) || !op.vcs?.filePath) continue;
+    const path = op.vcs.filePath;
+    if (!aMutations.has(path)) aMutations.set(path, []);
+    aMutations.get(path).push(op);
+  }
+  for (const op of uniqueB) {
+    if (!FILE_MUTATION_KINDS.has(op.kind) || !op.vcs?.filePath) continue;
+    const path = op.vcs.filePath;
+    const aOps = aMutations.get(path);
+    if (!aOps) continue;
+    for (const aOp of aOps) {
+      if (aOp.kind === "vcs:fileModify" && op.kind === "vcs:fileModify") {
+        conflicts.push({
+          opA: aOp,
+          opB: op,
+          filePath: path,
+          reason: `Both sides modified ${path}`
+        });
+      } else if (aOp.kind === "vcs:fileDelete" && op.kind === "vcs:fileModify" || aOp.kind === "vcs:fileModify" && op.kind === "vcs:fileDelete") {
+        conflicts.push({
+          opA: aOp,
+          opB: op,
+          filePath: path,
+          reason: `Delete/modify conflict on ${path}`
+        });
+      } else if (aOp.kind === "vcs:fileAdd" && op.kind === "vcs:fileAdd") {
+        if (aOp.vcs?.contentHash !== op.vcs?.contentHash) {
+          conflicts.push({
+            opA: aOp,
+            opB: op,
+            filePath: path,
+            reason: `Both sides added ${path} with different content`
+          });
+        }
+      }
+    }
+  }
+  return conflicts;
+}
+function interleaveByTimestamp(a, b) {
+  const result = [];
+  let ai = 0;
+  let bi = 0;
+  while (ai < a.length && bi < b.length) {
+    const tA = new Date(a[ai].timestamp).getTime();
+    const tB = new Date(b[bi].timestamp).getTime();
+    if (tA <= tB) {
+      result.push(a[ai++]);
+    } else {
+      result.push(b[bi++]);
+    }
+  }
+  while (ai < a.length) result.push(a[ai++]);
+  while (bi < b.length) result.push(b[bi++]);
+  return result;
+}
+
+// src/sync/sync-engine.ts
+var SyncEngine = class {
+  localPeerId;
+  state;
+  transport;
+  getLocalOps;
+  onOpsReceived;
+  onNackReceived;
+  branchPolicy;
+  constructor(opts) {
+    this.localPeerId = opts.localPeerId;
+    this.transport = opts.transport;
+    this.getLocalOps = opts.getLocalOps;
+    this.onOpsReceived = opts.onOpsReceived;
+    this.onNackReceived = opts.onNackReceived;
+    this.branchPolicy = opts.branchPolicy ?? { linear: true };
+    this.state = {
+      localPeerId: opts.localPeerId,
+      peerHeads: /* @__PURE__ */ new Map(),
+      pendingAcks: /* @__PURE__ */ new Set(),
+      lastSync: /* @__PURE__ */ new Map()
+    };
+    this.transport.onMessage((msg) => this.handleMessage(msg));
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /**
+   * Initiate a sync with a specific peer.
+   * Sends a 'have' message advertising our heads.
+   */
+  async pushTo(peerId) {
+    const ops = this.getLocalOps();
+    const heads = {};
+    if (ops.length > 0) {
+      heads["main"] = ops[ops.length - 1].hash;
+    }
+    await this.transport.send(peerId, {
+      version: PROTOCOL_VERSION,
+      type: "have",
+      peerId: this.localPeerId,
+      heads,
+      opCount: ops.length
+    });
+  }
+  /**
+   * Request ops from a peer.
+   */
+  async pullFrom(peerId) {
+    const ops = this.getLocalOps();
+    const lastHash = ops.length > 0 ? ops[ops.length - 1].hash : void 0;
+    await this.transport.send(peerId, {
+      version: PROTOCOL_VERSION,
+      type: "want",
+      peerId: this.localPeerId,
+      wantHashes: [],
+      afterHash: lastHash
+    });
+  }
+  /**
+   * Request the peer's complete op set and rely on hash dedupe during ingest.
+   */
+  async pullAllFrom(peerId) {
+    await this.transport.send(peerId, {
+      version: PROTOCOL_VERSION,
+      type: "want",
+      peerId: this.localPeerId,
+      wantHashes: []
+    });
+  }
+  /**
+   * Request a truncated tail snapshot from a room peer (late-joiner catch-up).
+   * The room replies with a `snapshot` message handled like `ops`.
+   */
+  async requestSnapshot(peerId, maxOps = DEFAULT_SNAPSHOT_MAX_OPS) {
+    await this.transport.send(peerId, {
+      version: PROTOCOL_VERSION,
+      type: "sync-snapshot",
+      peerId: this.localPeerId,
+      maxOps
+    });
+  }
+  /**
+   * Send all our ops to a peer (full push).
+   */
+  async sendOps(peerId, ops) {
+    const opsToSend = ops ?? this.getLocalOps();
+    await this.sendOpsMessage(peerId, opsToSend);
+  }
+  /**
+   * Internal: send an `ops` message and track outbound hashes in
+   * `pendingAcks` until the receiver acks or nacks them. All three sites
+   * that emit `ops` (sendOps, handleHave, handleWant) route through here so
+   * pendingAcks reflects every outbound op uniformly.
+   */
+  async sendOpsMessage(peerId, ops) {
+    if (ops.length === 0) return;
+    for (const op of ops) {
+      this.state.pendingAcks.add(op.hash);
+    }
+    await this.transport.send(peerId, {
+      version: PROTOCOL_VERSION,
+      type: "ops",
+      peerId: this.localPeerId,
+      ops
+    });
+  }
+  /**
+   * Reconcile our ops with a remote peer's ops.
+   */
+  reconcileWith(remoteOps) {
+    const localOps = this.getLocalOps();
+    return reconcile(localOps, remoteOps);
+  }
+  /**
+   * Get current sync state.
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Get branch policy.
+   */
+  getBranchPolicy() {
+    return this.branchPolicy;
+  }
+  /**
+   * Set branch policy.
+   */
+  setBranchPolicy(policy) {
+    this.branchPolicy = policy;
+  }
+  /**
+   * List known peers.
+   */
+  listPeers() {
+    return this.transport.peers();
+  }
+  // -------------------------------------------------------------------------
+  // Message handling
+  // -------------------------------------------------------------------------
+  async handleMessage(msg) {
+    if (typeof msg.version !== "number" || msg.version < MIN_SUPPORTED_VERSION || msg.version > MAX_SUPPORTED_VERSION) {
+      await this.transport.send(msg.peerId, {
+        version: PROTOCOL_VERSION,
+        type: "nack",
+        peerId: this.localPeerId,
+        refs: [],
+        reason: "protocol-version",
+        details: `Unsupported protocol version ${msg.version}; supported range is ${MIN_SUPPORTED_VERSION}-${MAX_SUPPORTED_VERSION}.`
+      });
+      return;
+    }
+    switch (msg.type) {
+      case "have":
+        await this.handleHave(msg);
+        break;
+      case "want":
+        await this.handleWant(msg);
+        break;
+      case "ops":
+        await this.handleOps(msg);
+        break;
+      case "ack":
+        this.handleAck(msg);
+        break;
+      case "nack":
+        await this.handleNack(msg);
+        break;
+      case "snapshot":
+        await this.handleSnapshot(msg);
+        break;
+      case "sync-snapshot":
+        break;
+    }
+  }
+  async handleSnapshot(msg) {
+    if (msg.ops.length === 0) return;
+    await this.handleOps({
+      version: msg.version,
+      type: "ops",
+      peerId: msg.peerId,
+      ops: msg.ops
+    });
+  }
+  async handleHave(msg) {
+    this.state.peerHeads.set(msg.peerId, msg.heads);
+    const localOps = this.getLocalOps();
+    const localHashes = new Set(localOps.map((o) => o.hash));
+    for (const [, hash] of Object.entries(msg.heads)) {
+      if (!localHashes.has(hash)) {
+        const afterHash = msg.opCount > localOps.length ? void 0 : localOps.length > 0 ? localOps[localOps.length - 1].hash : void 0;
+        await this.transport.send(msg.peerId, {
+          version: PROTOCOL_VERSION,
+          type: "want",
+          peerId: this.localPeerId,
+          wantHashes: [],
+          afterHash
+        });
+        return;
+      }
+    }
+    if (msg.opCount > localOps.length) {
+      await this.transport.send(msg.peerId, {
+        version: PROTOCOL_VERSION,
+        type: "want",
+        peerId: this.localPeerId,
+        wantHashes: []
+      });
+      return;
+    }
+    const peerOpCount = msg.opCount;
+    if (localOps.length > peerOpCount) {
+      await this.sendOpsMessage(msg.peerId, localOps.slice(peerOpCount));
+    }
+  }
+  async handleWant(msg) {
+    const localOps = this.getLocalOps();
+    let opsToSend;
+    if (msg.afterHash) {
+      const idx = localOps.findIndex((o) => o.hash === msg.afterHash);
+      opsToSend = idx >= 0 ? localOps.slice(idx + 1) : localOps;
+    } else if (msg.wantHashes.length > 0) {
+      const wanted = new Set(msg.wantHashes);
+      opsToSend = localOps.filter((o) => wanted.has(o.hash));
+    } else {
+      opsToSend = localOps;
+    }
+    await this.sendOpsMessage(msg.peerId, opsToSend);
+  }
+  async handleOps(msg) {
+    if (msg.ops.length === 0) return;
+    let result;
+    if (this.branchPolicy.linear) {
+      const localOps = this.getLocalOps();
+      const localHashes = new Set(localOps.map((o) => o.hash));
+      const newOps = msg.ops.filter((o) => !localHashes.has(o.hash));
+      if (newOps.length > 0) {
+        result = await this.onOpsReceived(newOps) ?? void 0;
+      }
+    } else {
+      const reconciled = this.reconcileWith(msg.ops);
+      if (reconciled.uniqueToB.length > 0) {
+        result = await this.onOpsReceived(reconciled.uniqueToB) ?? void 0;
+      }
+    }
+    const rejections = result?.rejections ?? [];
+    if (rejections.length > 0) {
+      const byReason = /* @__PURE__ */ new Map();
+      for (const r of rejections) {
+        const entry = byReason.get(r.reason) ?? {
+          refs: [],
+          details: r.details
+        };
+        entry.refs.push(r.hash);
+        byReason.set(r.reason, entry);
+      }
+      for (const [reason, entry] of byReason) {
+        await this.transport.send(msg.peerId, {
+          version: PROTOCOL_VERSION,
+          type: "nack",
+          peerId: this.localPeerId,
+          refs: entry.refs,
+          reason,
+          details: entry.details
+        });
+      }
+    }
+    const rejectedSet = new Set(rejections.map((r) => r.hash));
+    const ackHashes = msg.ops.map((o) => o.hash).filter((h) => !rejectedSet.has(h));
+    if (ackHashes.length > 0) {
+      await this.transport.send(msg.peerId, {
+        version: PROTOCOL_VERSION,
+        type: "ack",
+        peerId: this.localPeerId,
+        integrated: ackHashes
+      });
+    }
+    this.state.lastSync.set(msg.peerId, (/* @__PURE__ */ new Date()).toISOString());
+  }
+  handleAck(msg) {
+    for (const hash of msg.integrated) {
+      this.state.pendingAcks.delete(hash);
+    }
+    this.state.lastSync.set(msg.peerId, (/* @__PURE__ */ new Date()).toISOString());
+  }
+  async handleNack(msg) {
+    for (const ref of msg.refs) {
+      this.state.pendingAcks.delete(ref);
+    }
+    this.state.lastSync.set(msg.peerId, (/* @__PURE__ */ new Date()).toISOString());
+    if (this.onNackReceived) {
+      await this.onNackReceived(msg);
+    }
+  }
+};
+
+// demo/state-demo/multiplayer-room.ts
+var MultiplayerRoom = class {
+  alice;
+  bob;
+  room = new MemorySyncRoom("docs-state-demo", "Docs state");
+  engineAlice;
+  engineBob;
+  roomPeerId;
+  onChange;
+  pushDebounceMs;
+  pushTimer;
+  flushing = false;
+  constructor(opts = {}) {
+    this.onChange = opts.onChange;
+    this.pushDebounceMs = opts.pushDebounceMs ?? 80;
+    this.roomPeerId = this.room.getRoomPeer().id;
+    const scheduleSync = () => this.scheduleSync();
+    this.alice = new DemoSession({
+      agentId: "agent:alice",
+      onChange: () => this.emit(),
+      onAfterWrite: scheduleSync
+    });
+    this.bob = new DemoSession({
+      agentId: "agent:bob",
+      onChange: () => this.emit(),
+      onAfterWrite: scheduleSync
+    });
+    this.engineAlice = new SyncEngine({
+      localPeerId: "alice",
+      transport: this.room.connectPeer("alice", "Alice"),
+      getLocalOps: () => this.alice.getOps(),
+      onOpsReceived: (ops) => {
+        this.alice.integrate(ops);
+      },
+      branchPolicy: { linear: false }
+    });
+    this.engineBob = new SyncEngine({
+      localPeerId: "bob",
+      transport: this.room.connectPeer("bob", "Bob"),
+      getLocalOps: () => this.bob.getOps(),
+      onOpsReceived: (ops) => {
+        this.bob.integrate(ops);
+      },
+      branchPolicy: { linear: false }
+    });
+  }
+  getMergedOps() {
+    return mergeOps(this.alice.getOps(), this.bob.getOps());
+  }
+  emit() {
+    this.onChange?.({
+      alice: { ops: this.alice.getOps(), issues: this.alice.getIssues() },
+      bob: { ops: this.bob.getOps(), issues: this.bob.getIssues() },
+      mergedOps: this.getMergedOps()
+    });
+  }
+  scheduleSync() {
+    if (this.pushTimer !== void 0) clearTimeout(this.pushTimer);
+    this.pushTimer = setTimeout(() => {
+      this.pushTimer = void 0;
+      void this.flushSync();
+    }, this.pushDebounceMs);
+  }
+  /** Push/pull both peers through the room relay. */
+  async flushSync() {
+    if (this.flushing) return;
+    this.flushing = true;
+    try {
+      await this.engineAlice.pushTo(this.roomPeerId);
+      await this.engineBob.pullAllFrom(this.roomPeerId);
+      await this.engineBob.pushTo(this.roomPeerId);
+      await this.engineAlice.pullAllFrom(this.roomPeerId);
+      this.emit();
+    } finally {
+      this.flushing = false;
+    }
+  }
+};
+export {
+  DemoSession,
+  MultiplayerRoom,
+  mergeOps,
+  projectIssues
+};