@tangentfeed/core 0.2.0

package/dist/index.js

@@ -0,0 +1,966 @@
+// src/hlc.ts
+var MAX_COUNTER = 65535;
+var MAX_MILLIS = 2 ** 48 - 1;
+var MAX_DRIFT_MS = 3e5;
+var ClockDriftError = class extends Error {
+  code = "CLOCK_DRIFT";
+  constructor(remoteMillis, physicalNow) {
+    super(
+      `remote HLC is ${remoteMillis - physicalNow}ms ahead of local clock (max allowed ${MAX_DRIFT_MS}ms); check system time`
+    );
+  }
+};
+var DEVICE_ID_HEX = 32;
+var HLC_LENGTH = 50;
+var DEVICE_ID_RE = /^[0-9a-f]{32}$/;
+var HLC_STRING_RE = /^[0-9a-f]{12}-[0-9a-f]{4}-[0-9a-f]{32}$/;
+function isValidDeviceId(s) {
+  return DEVICE_ID_RE.test(s);
+}
+function encodeHlc(h) {
+  return h.millis.toString(16).padStart(12, "0") + "-" + h.counter.toString(16).padStart(4, "0") + "-" + h.deviceId;
+}
+function decodeHlc(s) {
+  if (!HLC_STRING_RE.test(s)) {
+    throw new Error(`malformed HLC string: ${JSON.stringify(s)}`);
+  }
+  return {
+    millis: parseInt(s.slice(0, 12), 16),
+    counter: parseInt(s.slice(13, 17), 16),
+    deviceId: s.slice(18)
+  };
+}
+function compareHlc(a, b) {
+  if (a.millis !== b.millis) return a.millis < b.millis ? -1 : 1;
+  if (a.counter !== b.counter) return a.counter < b.counter ? -1 : 1;
+  if (a.deviceId !== b.deviceId) return a.deviceId < b.deviceId ? -1 : 1;
+  return 0;
+}
+var HybridLogicalClock = class {
+  millis;
+  counter;
+  deviceId;
+  physicalClock;
+  constructor(opts) {
+    if (!isValidDeviceId(opts.deviceId)) {
+      throw new Error(`invalid deviceId: ${JSON.stringify(opts.deviceId)}`);
+    }
+    this.deviceId = opts.deviceId;
+    this.physicalClock = opts.physicalClock ?? Date.now;
+    this.millis = opts.millis ?? 0;
+    this.counter = opts.counter ?? 0;
+    this.checkBounds();
+  }
+  /** Current state, for persistence. Does not advance the clock. */
+  state() {
+    return { millis: this.millis, counter: this.counter, deviceId: this.deviceId };
+  }
+  /**
+   * Issue a timestamp for a new local op. §4.1 "send/local event".
+   * Strictly greater than every timestamp this clock has issued or observed.
+   */
+  now() {
+    const pt = this.physicalClock();
+    if (pt > this.millis) {
+      this.millis = pt;
+      this.counter = 0;
+    } else {
+      this.counter += 1;
+      if (this.counter > MAX_COUNTER) {
+        this.millis += 1;
+        this.counter = 0;
+      }
+    }
+    this.checkBounds();
+    return this.state();
+  }
+  /**
+   * Observe a remote timestamp. §4.1 "receive".
+   * Throws ClockDriftError if the remote is > MAX_DRIFT_MS ahead of our
+   * physical clock (§4.5). On success the local clock becomes strictly
+   * greater than both its previous state and the remote timestamp.
+   */
+  receive(remote) {
+    const pt = this.physicalClock();
+    if (remote.millis > pt + MAX_DRIFT_MS) {
+      throw new ClockDriftError(remote.millis, pt);
+    }
+    const m = Math.max(this.millis, remote.millis, pt);
+    let c;
+    if (m === this.millis && m === remote.millis) {
+      c = Math.max(this.counter, remote.counter) + 1;
+    } else if (m === this.millis) {
+      c = this.counter + 1;
+    } else if (m === remote.millis) {
+      c = remote.counter + 1;
+    } else {
+      c = 0;
+    }
+    this.millis = m;
+    this.counter = c;
+    if (this.counter > MAX_COUNTER) {
+      this.millis += 1;
+      this.counter = 0;
+    }
+    this.checkBounds();
+    return this.state();
+  }
+  checkBounds() {
+    if (this.millis > MAX_MILLIS) {
+      throw new Error("HLC millis exceeded 48-bit range");
+    }
+  }
+};
+
+// src/signing.ts
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+var SIGNING_DOMAIN = "tangentfeed/v2/op";
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return "[" + value.map(canonicalJson).join(",") + "]";
+  const keys = Object.keys(value).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJson(value[k])).join(",") + "}";
+}
+function generateDeviceKey() {
+  const { secretKey, publicKey } = ed25519.keygen();
+  return { publicKey, privateKey: secretKey };
+}
+function deviceIdFromPublicKey(publicKey) {
+  const digest = sha256(publicKey);
+  let out = "";
+  for (let i = 0; i < 16; i++) out += digest[i].toString(16).padStart(2, "0");
+  return out;
+}
+function signPayload(payload, privateKey) {
+  return base64Encode(ed25519.sign(payload, privateKey));
+}
+function verifyPayload(payload, signature, publicKey) {
+  try {
+    const sig = base64Decode(signature);
+    if (sig.length !== 64) return false;
+    return ed25519.verify(sig, payload, publicKey);
+  } catch {
+    return false;
+  }
+}
+function base64Encode(bytes) {
+  if (typeof btoa === "function") {
+    let bin = "";
+    for (const b of bytes) bin += String.fromCharCode(b);
+    return btoa(bin);
+  }
+  return Buffer.from(bytes).toString("base64");
+}
+function base64Decode(s) {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(s)) throw new Error("not base64");
+  if (typeof atob === "function") {
+    const bin = atob(s);
+    return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+  }
+  return new Uint8Array(Buffer.from(s, "base64"));
+}
+
+// src/op.ts
+var TOMBSTONE_COLUMN = "-";
+var BadOpError = class extends Error {
+  code = "BAD_OP";
+  constructor(msg) {
+    super(`BAD_OP: ${msg}`);
+  }
+};
+var NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]{0,63}$/;
+var ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
+var MAX_OP_BYTES = 64 * 1024;
+var MAX_BATCH_OPS = 1e3;
+function validateOp(op) {
+  if (typeof op !== "object" || op === null) throw new BadOpError("not an object");
+  const o = op;
+  for (const f of ["id", "table", "row", "column", "hlc", "device", "sig"]) {
+    if (typeof o[f] !== "string") throw new BadOpError(`field ${f} must be a string`);
+  }
+  if (!("value" in o)) throw new BadOpError("missing value");
+  const { id, table, row, column, hlc, device } = o;
+  let decoded;
+  try {
+    decoded = decodeHlc(hlc);
+  } catch {
+    throw new BadOpError(`malformed hlc: ${hlc}`);
+  }
+  if (id !== hlc) throw new BadOpError("id must equal hlc in v0.1");
+  if (device !== decoded.deviceId) throw new BadOpError("device does not match hlc suffix");
+  if (!NAME_RE.test(table)) throw new BadOpError(`bad table name: ${table}`);
+  if (column !== TOMBSTONE_COLUMN && !NAME_RE.test(column)) {
+    throw new BadOpError(`bad column name: ${column}`);
+  }
+  if (!ULID_RE.test(row)) throw new BadOpError(`row is not a ULID: ${row}`);
+  assertJson(o["value"], "value");
+  if (JSON.stringify(op).length > MAX_OP_BYTES) throw new BadOpError("op exceeds 64 KiB");
+}
+function assertJson(v, path) {
+  switch (typeof v) {
+    case "boolean":
+    case "string":
+      return;
+    case "number":
+      if (!Number.isFinite(v)) throw new BadOpError(`${path}: non-finite number`);
+      return;
+    case "object": {
+      if (v === null) return;
+      if (Array.isArray(v)) {
+        v.forEach((x, i) => assertJson(x, `${path}[${i}]`));
+        return;
+      }
+      for (const [k, x] of Object.entries(v)) assertJson(x, `${path}.${k}`);
+      return;
+    }
+    default:
+      throw new BadOpError(`${path}: unsupported type ${typeof v}`);
+  }
+}
+function aboveFrontier(op, frontier) {
+  const seen = frontier[op.device];
+  return seen === void 0 || op.hlc > seen;
+}
+function advanceFrontier(frontier, op) {
+  const seen = frontier[op.device];
+  if (seen !== void 0 && seen >= op.hlc) return frontier;
+  return { ...frontier, [op.device]: op.hlc };
+}
+function signedPayload(op) {
+  const { id, table, row, column, value, hlc, device } = op;
+  return new TextEncoder().encode(
+    SIGNING_DOMAIN + canonicalJson({ id, table, row, column, value, hlc, device })
+  );
+}
+function verifyOp(op, publicKey) {
+  return verifyPayload(signedPayload(op), op.sig, publicKey);
+}
+
+// src/ulid.ts
+var B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function ulid(time = Date.now(), randomBytes = defaultRandomBytes) {
+  if (!Number.isInteger(time) || time < 0 || time > 2 ** 48 - 1) {
+    throw new Error(`ulid: time out of range: ${time}`);
+  }
+  let t = time;
+  const timeChars = new Array(10);
+  for (let i = 9; i >= 0; i--) {
+    timeChars[i] = B32[t % 32];
+    t = Math.floor(t / 32);
+  }
+  const rand = randomBytes(10);
+  let bits = 0;
+  let acc = 0;
+  let out = "";
+  for (const byte of rand) {
+    acc = acc << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += B32[acc >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  return timeChars.join("") + out;
+}
+function defaultRandomBytes(n) {
+  const b = new Uint8Array(n);
+  globalThis.crypto.getRandomValues(b);
+  return b;
+}
+
+// src/storage.ts
+var SEP = "\0";
+function cellKey(table, row, column) {
+  return table + SEP + row + SEP + column;
+}
+var MemoryAdapter = class {
+  opsById = /* @__PURE__ */ new Map();
+  /** table → row → column → winning op */
+  tables = /* @__PURE__ */ new Map();
+  frontier = {};
+  clock;
+  deviceKey;
+  peerFrontiers = {};
+  async getRow(table, row) {
+    return this.tables.get(table)?.get(row);
+  }
+  async listRows(table) {
+    return [...this.tables.get(table)?.keys() ?? []];
+  }
+  async listTables() {
+    return [...this.tables.keys()];
+  }
+  async hasOp(id) {
+    return this.opsById.has(id);
+  }
+  async getWinner(table, row, column) {
+    return this.tables.get(table)?.get(row)?.get(column);
+  }
+  async opsSince(frontier) {
+    const out = [];
+    for (const op of this.opsById.values()) {
+      const seen = frontier[op.device];
+      if (seen === void 0 || op.hlc > seen) out.push(op);
+    }
+    out.sort((a, b) => a.hlc < b.hlc ? -1 : a.hlc > b.hlc ? 1 : 0);
+    return out;
+  }
+  async getFrontier() {
+    return this.frontier;
+  }
+  async getDeviceKey() {
+    return this.deviceKey;
+  }
+  async setDeviceKey(key) {
+    this.deviceKey = key;
+  }
+  async getClock() {
+    return this.clock;
+  }
+  async opCount() {
+    return this.opsById.size;
+  }
+  async allOps() {
+    return [...this.opsById.values()].sort(
+      (a, b) => a.hlc < b.hlc ? -1 : a.hlc > b.hlc ? 1 : 0
+    );
+  }
+  async getPeerFrontiers() {
+    return this.peerFrontiers;
+  }
+  async setPeerFrontier(peer, frontier) {
+    this.peerFrontiers = { ...this.peerFrontiers, [peer]: frontier };
+  }
+  async compact(write) {
+    const newOps = new Map(this.opsById);
+    for (const id of write.opIds) newOps.delete(id);
+    const newTables = new Map(this.tables);
+    for (const key of write.cellKeys) {
+      const [table, row, column] = key.split(SEP);
+      const rows = new Map(newTables.get(table) ?? []);
+      const cells = new Map(rows.get(row) ?? []);
+      cells.delete(column);
+      if (cells.size === 0) rows.delete(row);
+      else rows.set(row, cells);
+      if (rows.size === 0) newTables.delete(table);
+      else newTables.set(table, rows);
+    }
+    this.opsById = newOps;
+    this.tables = newTables;
+  }
+  async applyBatch(batch) {
+    const newOps = new Map(this.opsById);
+    for (const op of batch.ops) newOps.set(op.id, op);
+    const newTables = new Map(this.tables);
+    for (const [key, op] of batch.winners) {
+      const [table, row, column] = key.split(SEP);
+      const rows = new Map(newTables.get(table) ?? []);
+      const cells = new Map(rows.get(row) ?? []);
+      cells.set(column, op);
+      rows.set(row, cells);
+      newTables.set(table, rows);
+    }
+    this.opsById = newOps;
+    this.tables = newTables;
+    this.frontier = batch.frontier;
+    this.clock = batch.clock;
+  }
+};
+
+// src/compaction.ts
+var ZERO_HLC = "";
+var SEP2 = "\0";
+function compactionHorizon(own, peerFrontiers) {
+  const horizon = { ...own };
+  for (const frontier of Object.values(peerFrontiers)) {
+    for (const device of Object.keys(horizon)) {
+      const seen = frontier[device] ?? ZERO_HLC;
+      if (seen < horizon[device]) horizon[device] = seen;
+    }
+  }
+  return horizon;
+}
+function blockingPeers(own, peerFrontiers) {
+  const blockers = [];
+  for (const [peer, frontier] of Object.entries(peerFrontiers)) {
+    for (const [device, ours] of Object.entries(own)) {
+      if ((frontier[device] ?? ZERO_HLC) < ours) {
+        blockers.push(peer);
+        break;
+      }
+    }
+  }
+  return blockers.sort();
+}
+function rowKeyOf(op) {
+  return op.table + SEP2 + op.row;
+}
+function planCompaction(ops, winningCells2, horizon, opts) {
+  const winnerIds = /* @__PURE__ */ new Set();
+  for (const op of winningCells2.values()) winnerIds.add(op.id);
+  const below = (op) => op.hlc <= (horizon[op.device] ?? ZERO_HLC);
+  const doomedRows = /* @__PURE__ */ new Set();
+  if (opts.includeTombstones) {
+    const candidates = /* @__PURE__ */ new Set();
+    for (const [key, winner] of winningCells2) {
+      if (winner.column === TOMBSTONE_COLUMN && winner.value === true && below(winner)) {
+        candidates.add(key.slice(0, key.lastIndexOf(SEP2)));
+      }
+    }
+    const blockedRows = /* @__PURE__ */ new Set();
+    for (const op of ops) {
+      if (!below(op)) blockedRows.add(rowKeyOf(op));
+    }
+    for (const row of candidates) {
+      if (!blockedRows.has(row)) doomedRows.add(row);
+    }
+  }
+  const opIds = [];
+  const cellKeys = /* @__PURE__ */ new Set();
+  let removed = 0;
+  let retainedWinners = 0;
+  let retainedAboveHorizon = 0;
+  for (const op of ops) {
+    if (doomedRows.has(rowKeyOf(op))) {
+      opIds.push(op.id);
+      cellKeys.add(cellKey(op.table, op.row, op.column));
+      removed += 1;
+      continue;
+    }
+    if (!below(op)) {
+      retainedAboveHorizon += 1;
+      continue;
+    }
+    if (!winnerIds.has(op.id)) {
+      opIds.push(op.id);
+      removed += 1;
+      continue;
+    }
+    retainedWinners += 1;
+  }
+  for (const key of winningCells2.keys()) {
+    if (doomedRows.has(key.slice(0, key.lastIndexOf(SEP2)))) cellKeys.add(key);
+  }
+  return {
+    opIds,
+    cellKeys: [...cellKeys],
+    stats: {
+      scanned: ops.length,
+      removed,
+      rowsReclaimed: doomedRows.size,
+      retainedWinners,
+      retainedAboveHorizon
+    }
+  };
+}
+async function winningCells(storage) {
+  const out = /* @__PURE__ */ new Map();
+  for (const table of await storage.listTables()) {
+    for (const row of await storage.listRows(table)) {
+      const cells = await storage.getRow(table, row);
+      for (const [column, op] of cells ?? []) {
+        out.set(cellKey(table, row, column), op);
+      }
+    }
+  }
+  return out;
+}
+
+// src/cipher.ts
+var CIPHER_PREFIX = "e1:";
+function isEncryptedValue(v) {
+  return typeof v === "string" && v.startsWith(CIPHER_PREFIX);
+}
+var DecryptError = class extends Error {
+  code = "DECRYPT_FAIL";
+  constructor(msg) {
+    super(`DECRYPT_FAIL: ${msg}`);
+  }
+};
+
+// src/engine.ts
+var SyncEngine = class _SyncEngine {
+  deviceId;
+  storage;
+  clock;
+  cipher;
+  subscribers = /* @__PURE__ */ new Set();
+  deviceKey;
+  /** deviceId -> public key. Seeded with our own so we can verify our own ops. */
+  keys = /* @__PURE__ */ new Map();
+  /** serializes all mutations; JS is single-threaded but ops are async */
+  mutex = Promise.resolve();
+  constructor(opts, clock, key) {
+    this.deviceId = clock.deviceId;
+    this.storage = opts.storage;
+    this.clock = clock;
+    this.cipher = opts.cipher;
+    this.deviceKey = key;
+    this.keys.set(clock.deviceId, key.publicKey);
+  }
+  /** This device's public key, for the `hello` message. Section 6.1. */
+  get publicKey() {
+    return this.deviceKey.publicKey;
+  }
+  /** Every device key known to this replica, for the `keys` message. */
+  knownKeys() {
+    return new Map(this.keys);
+  }
+  /**
+   * Records a peer's public key.
+   *
+   * Returns false when the key does not hash to the claimed id. That check is
+   * what makes the directory self-validating: a peer can relay keys it learned
+   * from others, but cannot invent one for somebody else.
+   */
+  learnKey(deviceId, publicKey) {
+    if (deviceIdFromPublicKey(publicKey) !== deviceId) return false;
+    this.keys.set(deviceId, publicKey);
+    return true;
+  }
+  /**
+   * Opens a replica. Identity comes from the stored keypair, so a restart keeps
+   * the same device rather than minting a new one. Section 4.3.
+   */
+  static async open(opts) {
+    let key = await opts.storage.getDeviceKey();
+    if (!key) {
+      key = generateDeviceKey();
+      await opts.storage.setDeviceKey(key);
+    }
+    const persisted = await opts.storage.getClock();
+    const clock = new HybridLogicalClock({
+      deviceId: deviceIdFromPublicKey(key.publicKey),
+      ...opts.physicalClock ? { physicalClock: opts.physicalClock } : {},
+      ...persisted ? { millis: persisted.millis, counter: persisted.counter } : {}
+    });
+    return new _SyncEngine(opts, clock, key);
+  }
+  // ---------- reads ----------
+  /** Materialized row, or undefined if absent/tombstoned. §5. */
+  async get(table, row) {
+    const cells = await this.storage.getRow(table, row);
+    if (!cells) return void 0;
+    if (isTombstoned(cells)) return void 0;
+    return this.materialize(row, cells);
+  }
+  /** All visible rows of a table, sorted by rowId (ULID = insertion order). */
+  async list(table) {
+    const out = [];
+    for (const row of (await this.storage.listRows(table)).sort()) {
+      const cells = await this.storage.getRow(table, row);
+      if (cells && !isTombstoned(cells)) out.push(this.materialize(row, cells));
+    }
+    return out;
+  }
+  /** Full materialized state; used by tests and conformance vectors. */
+  async dump() {
+    const state = {};
+    for (const table of (await this.storage.listTables()).sort()) {
+      for (const row of (await this.storage.listRows(table)).sort()) {
+        const cells = await this.storage.getRow(table, row);
+        if (!cells || isTombstoned(cells)) continue;
+        const { id: _id, ...cols } = this.materialize(row, cells);
+        (state[table] ??= {})[row] = cols;
+      }
+    }
+    return state;
+  }
+  // ---------- local writes ----------
+  /** Insert a row; returns its generated rowId. */
+  async insert(table, values) {
+    const row = ulid(this.clockMillisForUlid());
+    await this.update(table, row, values);
+    return row;
+  }
+  /** Write one op per column. */
+  async update(table, row, values) {
+    return this.locked(async () => {
+      const ops = Object.entries(values).map(
+        ([column, value]) => this.makeLocalOp(table, row, column, value)
+      );
+      await this.commit(ops, "local");
+    });
+  }
+  /** Row tombstone. §5. */
+  async delete(table, row) {
+    return this.locked(async () => {
+      await this.commit([this.makeLocalOp(table, row, TOMBSTONE_COLUMN, true)], "local");
+    });
+  }
+  // ---------- sync surface (§6) ----------
+  async frontier() {
+    return this.storage.getFrontier();
+  }
+  /** Ops the caller is missing, given their frontier. §6 step 3. */
+  async opsSince(frontier) {
+    return this.storage.opsSince(frontier);
+  }
+  /**
+   * Apply a batch of remote ops. Validates, drift-checks, dedupes, merges,
+   * persists atomically, notifies. Returns number of newly applied ops.
+   * Throws BadOpError / ClockDriftError; on throw, nothing was applied.
+   */
+  async applyRemoteOps(remoteOps) {
+    if (remoteOps.length > MAX_BATCH_OPS) {
+      throw new BadOpError(`batch exceeds ${MAX_BATCH_OPS} ops`);
+    }
+    for (const op of remoteOps) validateOp(op);
+    const ops = remoteOps;
+    for (const op of ops) {
+      const publicKey = this.keys.get(op.device);
+      if (!publicKey) {
+        throw new BadOpError(`unknown device ${op.device}; no key to verify against`);
+      }
+      if (!verifyOp(op, publicKey)) {
+        throw new BadOpError(`bad signature on op ${op.id}`);
+      }
+    }
+    return this.locked(async () => {
+      const maxOp = ops.reduce(
+        (m, o) => m === null || o.hlc > m.hlc ? o : m,
+        null
+      );
+      if (maxOp) this.clock.receive(decodeHlc(maxOp.hlc));
+      const fresh = [];
+      for (const op of ops) {
+        if (!await this.storage.hasOp(op.id) && !fresh.some((f) => f.id === op.id)) {
+          fresh.push(op);
+        }
+      }
+      if (fresh.length === 0) {
+        await this.storage.applyBatch({
+          ops: [],
+          winners: /* @__PURE__ */ new Map(),
+          frontier: await this.storage.getFrontier(),
+          clock: this.clock.state()
+        });
+        return 0;
+      }
+      await this.commit(fresh, "remote");
+      return fresh.length;
+    });
+  }
+  /**
+   * Observe a peer's clock from a hello message (§6 step 1). Drift-checks and
+   * advances + persists our clock without applying any ops.
+   */
+  async observeRemoteClock(hlc) {
+    return this.locked(async () => {
+      this.clock.receive(decodeHlc(hlc));
+      await this.storage.applyBatch({
+        ops: [],
+        winners: /* @__PURE__ */ new Map(),
+        frontier: await this.storage.getFrontier(),
+        clock: this.clock.state()
+      });
+    });
+  }
+  // ---------- compaction (§9) ----------
+  /**
+   * Record a peer's frontier, learned from a since/ack exchange. This is the
+   * input that lets compaction know what has safely reached everyone.
+   */
+  async recordPeerFrontier(peer, frontier) {
+    if (peer === this.deviceId) return;
+    await this.storage.setPeerFrontier(peer, frontier);
+  }
+  async peerFrontiers() {
+    return this.storage.getPeerFrontiers();
+  }
+  /** Number of ops currently retained in the log. */
+  async opCount() {
+    return this.storage.opCount();
+  }
+  /**
+   * Reclaim superseded ops (§9). Safe by construction: winners are never
+   * dropped, and nothing above the compaction horizon is touched. Tombstone
+   * GC is opt-in via `includeTombstones` — see compaction.ts for why.
+   */
+  async compact(opts = {}) {
+    return this.locked(async () => {
+      const own = await this.storage.getFrontier();
+      const peers = await this.storage.getPeerFrontiers();
+      const horizon = compactionHorizon(own, peers);
+      const winners = await winningCells(this.storage);
+      const ops = await this.storage.allOps();
+      const plan = planCompaction(ops, winners, horizon, opts);
+      if (!opts.dryRun && (plan.opIds.length > 0 || plan.cellKeys.length > 0)) {
+        await this.storage.compact({ opIds: plan.opIds, cellKeys: plan.cellKeys });
+      }
+      return { ...plan.stats, blockedBy: blockingPeers(own, peers) };
+    });
+  }
+  // ---------- subscriptions ----------
+  subscribe(cb) {
+    this.subscribers.add(cb);
+    return () => this.subscribers.delete(cb);
+  }
+  // ---------- internals ----------
+  makeLocalOp(table, row, column, value) {
+    const hlc = encodeHlc(this.clock.now());
+    const stored = this.cipher && column !== TOMBSTONE_COLUMN ? this.cipher.encrypt(value, hlc) : value;
+    const unsigned = { id: hlc, table, row, column, value: stored, hlc, device: this.deviceId };
+    const op = {
+      ...unsigned,
+      sig: signPayload(signedPayload(unsigned), this.deviceKey.privateKey)
+    };
+    validateOp(op);
+    return op;
+  }
+  /**
+   * The single mutation path (local and remote both land here):
+   * compute LWW winners for affected cells, advance frontier, persist
+   * atomically, notify subscribers. §5, §8.2.
+   */
+  async commit(ops, origin) {
+    const winners = /* @__PURE__ */ new Map();
+    let frontier = await this.storage.getFrontier();
+    for (const op of ops) {
+      const key = cellKey(op.table, op.row, op.column);
+      const pending = winners.get(key);
+      const current = pending ?? await this.storage.getWinner(op.table, op.row, op.column);
+      if (current === void 0 || op.hlc > current.hlc) {
+        winners.set(key, op);
+      } else if (pending === void 0) {
+        winners.set(key, current);
+      }
+      frontier = advanceFrontier(frontier, op);
+    }
+    await this.storage.applyBatch({
+      ops,
+      winners,
+      frontier,
+      clock: this.clock.state()
+    });
+    const changed = [...new Set(ops.map((o) => o.table + "\0" + o.row))].map((k) => {
+      const [table, row] = k.split("\0");
+      return { table, row };
+    });
+    const event = { changes: changed, ops, origin };
+    for (const cb of this.subscribers) cb(event);
+  }
+  /** Decrypt (if needed) and shape stored cells into a row. */
+  materialize(row, cells) {
+    const out = {};
+    for (const [column, op] of cells) {
+      if (column === TOMBSTONE_COLUMN) continue;
+      const value = this.cipher && isEncryptedValue(op.value) ? this.cipher.decrypt(op.value, op.id) : op.value;
+      if (value !== null) out[column] = value;
+    }
+    return { id: row, ...out };
+  }
+  clockMillisForUlid() {
+    const s = this.clock.state();
+    return Math.max(s.millis, Date.now()) % 2 ** 48;
+  }
+  locked(fn) {
+    const run = this.mutex.then(fn, fn);
+    this.mutex = run.catch(() => void 0);
+    return run;
+  }
+};
+function isTombstoned(cells) {
+  return cells.get(TOMBSTONE_COLUMN)?.value === true;
+}
+async function syncOnce(a, b) {
+  for (const [id, k] of a.knownKeys()) b.learnKey(id, k);
+  for (const [id, k] of b.knownKeys()) a.learnKey(id, k);
+  const [fa, fb] = [await a.frontier(), await b.frontier()];
+  const aToB = await a.opsSince(fb);
+  const bToA = await b.opsSince(fa);
+  if (aToB.length) await b.applyRemoteOps(aToB);
+  if (bToA.length) await a.applyRemoteOps(bToA);
+  await a.recordPeerFrontier(b.deviceId, await b.frontier());
+  await b.recordPeerFrontier(a.deviceId, await a.frontier());
+}
+
+// src/replicator.ts
+var WIRE_VERSION = 2;
+var OPS_PER_MESSAGE = 500;
+var Replicator = class {
+  engine;
+  transport;
+  space;
+  events;
+  peers = /* @__PURE__ */ new Map();
+  unsubs = [];
+  started = false;
+  constructor(opts) {
+    this.engine = opts.engine;
+    this.transport = opts.transport;
+    this.space = opts.space;
+    this.events = opts.events ?? {};
+  }
+  get peerIds() {
+    return new Set(this.peers.keys());
+  }
+  async start() {
+    if (this.started) return;
+    this.started = true;
+    this.unsubs.push(this.transport.onMessage((msg) => void this.handle(msg)));
+    if (this.transport.onPeerConnect) {
+      this.unsubs.push(
+        this.transport.onPeerConnect(() => void this.sendHello())
+      );
+    }
+    this.unsubs.push(
+      this.engine.subscribe((ev) => {
+        if (ev.origin !== "local" || ev.ops.length === 0) return;
+        for (const chunk of chunks(ev.ops, OPS_PER_MESSAGE)) {
+          this.transport.send(this.msg({ t: "ops", ops: chunk }));
+        }
+      })
+    );
+    await this.sendHello();
+  }
+  stop() {
+    this.started = false;
+    for (const u of this.unsubs) u();
+    this.unsubs = [];
+    this.peers.clear();
+    this.events.onPeersChange?.(this.peerIds);
+  }
+  async sendHello() {
+    const latest = (await this.engine.opsSince({})).at(-1)?.hlc;
+    this.transport.send(
+      this.msg({
+        t: "hello",
+        clock: latest ?? zeroClock(this.engine.deviceId),
+        key: hex(this.engine.publicKey)
+      })
+    );
+  }
+  /**
+   * Every device key we hold, sent before any ops so a peer never receives an
+   * op it cannot verify. Section 6.1.
+   *
+   * Relaying keys we learned from others is what lets an op reach a peer that
+   * never met its author. It is safe because learnKey discards any entry that
+   * does not hash to its claimed id.
+   */
+  async sendKeys(to) {
+    const keys = {};
+    for (const [id, k] of this.engine.knownKeys()) keys[id] = hex(k);
+    this.transport.send(this.msg(to === void 0 ? { t: "keys", keys } : { t: "keys", to, keys }));
+  }
+  // ---------- inbound ----------
+  async handle(msg) {
+    try {
+      if (!this.started) return;
+      if (msg.space !== this.space || msg.v !== WIRE_VERSION) return;
+      if (msg.from === this.engine.deviceId) return;
+      if ("to" in msg && msg.to !== void 0 && msg.to !== this.engine.deviceId) return;
+      switch (msg.t) {
+        case "hello": {
+          if (typeof msg.key === "string") this.engine.learnKey(msg.from, unhex(msg.key));
+          await this.engine.observeRemoteClock(msg.clock);
+          const isNew = !this.peers.has(msg.from);
+          if (isNew) {
+            this.peers.set(msg.from, {});
+            this.events.onPeersChange?.(this.peerIds);
+            await this.sendHello();
+          }
+          await this.sendKeys(msg.from);
+          this.transport.send(
+            this.msg({ t: "since", to: msg.from, have: await this.engine.frontier() })
+          );
+          break;
+        }
+        case "keys": {
+          for (const [id, k] of Object.entries(msg.keys)) {
+            this.engine.learnKey(id, unhex(k));
+          }
+          break;
+        }
+        case "since": {
+          this.peers.set(msg.from, { frontier: msg.have });
+          await this.engine.recordPeerFrontier(msg.from, msg.have);
+          const missing = await this.engine.opsSince(msg.have);
+          if (missing.length > 0) await this.sendKeys(msg.from);
+          for (const chunk of chunks(missing, OPS_PER_MESSAGE)) {
+            this.transport.send(this.msg({ t: "ops", to: msg.from, ops: chunk }));
+          }
+          break;
+        }
+        case "ops": {
+          if (msg.ops.length === 0) return;
+          const applied = await this.engine.applyRemoteOps(msg.ops);
+          if (applied > 0) {
+            this.transport.send(
+              this.msg({ t: "ack", to: msg.from, frontier: await this.engine.frontier() })
+            );
+          }
+          break;
+        }
+        case "ack": {
+          this.peers.set(msg.from, { frontier: msg.frontier });
+          await this.engine.recordPeerFrontier(msg.from, msg.frontier);
+          break;
+        }
+      }
+    } catch (err) {
+      this.events.onError?.(err, { from: msg.from });
+    }
+  }
+  msg(body) {
+    return {
+      v: WIRE_VERSION,
+      space: this.space,
+      from: this.engine.deviceId,
+      ...body
+    };
+  }
+};
+function* chunks(arr, size) {
+  for (let i = 0; i < arr.length; i += size) yield arr.slice(i, i + size);
+}
+function zeroClock(deviceId) {
+  return "0".repeat(12) + "-0000-" + deviceId;
+}
+var hex = (b) => [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+var unhex = (s) => new Uint8Array((s.match(/../g) ?? []).map((h) => parseInt(h, 16)));
+export {
+  BadOpError,
+  CIPHER_PREFIX,
+  ClockDriftError,
+  DEVICE_ID_HEX,
+  DecryptError,
+  HLC_LENGTH,
+  HybridLogicalClock,
+  MAX_BATCH_OPS,
+  MAX_COUNTER,
+  MAX_DRIFT_MS,
+  MAX_MILLIS,
+  MAX_OP_BYTES,
+  MemoryAdapter,
+  OPS_PER_MESSAGE,
+  Replicator,
+  SIGNING_DOMAIN,
+  SyncEngine,
+  TOMBSTONE_COLUMN,
+  WIRE_VERSION,
+  aboveFrontier,
+  advanceFrontier,
+  blockingPeers,
+  canonicalJson,
+  cellKey,
+  compactionHorizon,
+  compareHlc,
+  decodeHlc,
+  deviceIdFromPublicKey,
+  encodeHlc,
+  generateDeviceKey,
+  isEncryptedValue,
+  isValidDeviceId,
+  planCompaction,
+  signPayload,
+  signedPayload,
+  syncOnce,
+  ulid,
+  validateOp,
+  verifyOp,
+  verifyPayload,
+  winningCells
+};