@helipod/objectstore-substrate 0.1.0

package/dist/index.js

@@ -0,0 +1,1584 @@
+// src/segment.ts
+import { convexToJson, jsonToConvex } from "@helipod/values";
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+function base64ToBytes(b64) {
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function encodeId(id) {
+  return { tableNumber: id.tableNumber, internalId: bytesToBase64(id.internalId) };
+}
+function decodeId(id) {
+  return { tableNumber: id.tableNumber, internalId: base64ToBytes(id.internalId) };
+}
+function encodeResolvedDocument(doc) {
+  return { id: encodeId(doc.id), value: convexToJson(doc.value) };
+}
+function decodeResolvedDocument(doc) {
+  return { id: decodeId(doc.id), value: jsonToConvex(doc.value) };
+}
+function encodeDocumentLogEntry(entry) {
+  return {
+    ts: entry.ts.toString(),
+    id: encodeId(entry.id),
+    value: entry.value === null ? null : encodeResolvedDocument(entry.value),
+    prev_ts: entry.prev_ts === null ? null : entry.prev_ts.toString()
+  };
+}
+function decodeDocumentLogEntry(entry) {
+  return {
+    ts: BigInt(entry.ts),
+    id: decodeId(entry.id),
+    value: entry.value === null ? null : decodeResolvedDocument(entry.value),
+    prev_ts: entry.prev_ts === null ? null : BigInt(entry.prev_ts)
+  };
+}
+function encodeIndexValue(value) {
+  return value.type === "Deleted" ? { type: "Deleted" } : { type: "NonClustered", docId: encodeId(value.docId) };
+}
+function decodeIndexValue(value) {
+  return value.type === "Deleted" ? { type: "Deleted" } : { type: "NonClustered", docId: decodeId(value.docId) };
+}
+function encodeIndexUpdate(update) {
+  return { indexId: update.indexId, key: bytesToBase64(update.key), value: encodeIndexValue(update.value) };
+}
+function decodeIndexUpdate(update) {
+  return { indexId: update.indexId, key: base64ToBytes(update.key), value: decodeIndexValue(update.value) };
+}
+function encodeIndexWrite(write) {
+  return { ts: write.ts.toString(), update: encodeIndexUpdate(write.update) };
+}
+function decodeIndexWrite(write) {
+  return { ts: BigInt(write.ts), update: decodeIndexUpdate(write.update) };
+}
+function encodeDocumentLogEntries(documents) {
+  return documents.map(encodeDocumentLogEntry);
+}
+function decodeDocumentLogEntries(wire) {
+  return wire.map(decodeDocumentLogEntry);
+}
+function encodeIndexWrites(writes) {
+  return writes.map(encodeIndexWrite);
+}
+function decodeIndexWrites(wire) {
+  return wire.map(decodeIndexWrite);
+}
+function encodeSegment(payload) {
+  const wire = {
+    documents: encodeDocumentLogEntries(payload.documents),
+    indexUpdates: encodeIndexWrites(payload.indexUpdates)
+  };
+  return new TextEncoder().encode(JSON.stringify(wire));
+}
+function decodeSegment(bytes) {
+  const wire = JSON.parse(new TextDecoder().decode(bytes));
+  return {
+    documents: decodeDocumentLogEntries(wire.documents),
+    indexUpdates: decodeIndexWrites(wire.indexUpdates)
+  };
+}
+
+// src/manifest.ts
+function manifestKey(shard) {
+  return `s${shard}/manifest`;
+}
+function emptyManifest() {
+  return { epoch: 0, frontierTs: "0", tsCounter: "0", segments: [], nextSeqno: 0, writerId: "", leaseExpiresAt: "0" };
+}
+async function readManifest(os, shard) {
+  const entry = await os.get(manifestKey(shard));
+  if (entry === null) return null;
+  const manifest = JSON.parse(new TextDecoder().decode(entry.body));
+  return { manifest, etag: entry.etag };
+}
+async function createManifest(os, shard) {
+  const manifest = emptyManifest();
+  const { etag } = await os.casPut(manifestKey(shard), new TextEncoder().encode(JSON.stringify(manifest)), null);
+  return { manifest, etag };
+}
+async function casManifest(os, shard, next, ifMatch) {
+  return os.casPut(manifestKey(shard), new TextEncoder().encode(JSON.stringify(next)), ifMatch);
+}
+
+// src/object-doc-store.ts
+import { isCasConflict as isCasConflict2 } from "@helipod/objectstore";
+
+// src/snapshot.ts
+function encodeSnapshot(payload) {
+  const wire = {
+    frontierTs: payload.frontierTs,
+    segBase: payload.segBase,
+    documents: encodeDocumentLogEntries(payload.documents),
+    indexUpdates: encodeIndexWrites(payload.indexUpdates)
+  };
+  return new TextEncoder().encode(JSON.stringify(wire));
+}
+function decodeSnapshot(bytes) {
+  const wire = JSON.parse(new TextDecoder().decode(bytes));
+  return {
+    frontierTs: wire.frontierTs,
+    segBase: wire.segBase,
+    documents: decodeDocumentLogEntries(wire.documents),
+    indexUpdates: decodeIndexWrites(wire.indexUpdates)
+  };
+}
+function snapshotKey(shard, ts) {
+  return `s${shard}/snap/${ts}`;
+}
+async function writeSnapshot(os, shard, payload) {
+  await os.putImmutable(snapshotKey(shard, payload.frontierTs), encodeSnapshot(payload));
+}
+async function readSnapshot(os, shard, ts) {
+  const entry = await os.get(snapshotKey(shard, ts));
+  if (entry === null) return null;
+  return decodeSnapshot(entry.body);
+}
+
+// src/fenced-error.ts
+var FencedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FencedError";
+  }
+};
+
+// src/consumers.ts
+import { isCasConflict } from "@helipod/objectstore";
+function consumersPrefix(shard) {
+  return `s${shard}/consumers/`;
+}
+function consumerKey(shard, consumerId) {
+  return `${consumersPrefix(shard)}${consumerId}`;
+}
+async function publishConsumerWatermark(os, shard, consumerId, watermark) {
+  const key = consumerKey(shard, consumerId);
+  const body = new TextEncoder().encode(JSON.stringify({ appliedSeqno: watermark.appliedSeqno }));
+  const MAX_ATTEMPTS = 5;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const existing = await os.get(key);
+    try {
+      await os.casPut(key, body, existing === null ? null : existing.etag);
+      return;
+    } catch (e) {
+      if (!isCasConflict(e)) throw e;
+    }
+  }
+  throw new Error(
+    `objectstore-substrate: publishConsumerWatermark exhausted ${MAX_ATTEMPTS} retries for '${key}' \u2014 unexpected sustained contention (watermarks are meant to be single-writer-per-(shard, consumerId))`
+  );
+}
+async function readConsumerWatermarks(os, shard) {
+  const prefix = consumersPrefix(shard);
+  const keys = await os.list(prefix);
+  const out = [];
+  for (const key of keys) {
+    const entry = await os.get(key);
+    if (entry === null) continue;
+    const parsed = JSON.parse(new TextDecoder().decode(entry.body));
+    out.push({ consumerId: key.slice(prefix.length), appliedSeqno: parsed.appliedSeqno });
+  }
+  return out;
+}
+async function removeConsumer(os, shard, consumerId) {
+  await os.delete(consumerKey(shard, consumerId));
+}
+
+// src/apply-snapshot.ts
+import { documentIdKey } from "@helipod/id-codec";
+async function applySnapshotState(local, snap, frontierTs) {
+  const snapshotIds = new Set(snap.documents.map((d) => documentIdKey(d.id)));
+  const currentState = await local.dumpCurrentState();
+  const dropped = currentState.documents.filter((d) => !snapshotIds.has(documentIdKey(d.id)));
+  let deletedDocs = [];
+  if (dropped.length > 0) {
+    deletedDocs = dropped.map((d) => ({ ts: frontierTs, id: d.id, value: null, prev_ts: d.ts }));
+    await local.write(deletedDocs, [], "Overwrite");
+  }
+  await local.write(snap.documents, snap.indexUpdates, "Overwrite");
+  return { deletedDocs };
+}
+
+// src/object-doc-store.ts
+function segmentKey(shard, seqno) {
+  return `s${shard}/seg/${seqno}`;
+}
+var SNAPSHOT_EVERY = 8;
+var ObjectStoreDocStore = class _ObjectStoreDocStore {
+  objectStore;
+  shard;
+  local;
+  /** The last manifest state this process successfully CAS'd (or bootstrapped from) + its etag —
+   *  the read-half of the next `casManifest`'s optimistic-concurrency check. Updated ONLY after a
+   *  successful CAS (never speculatively), under `mutex`. */
+  cached;
+  /** The next free segment seqno for THIS process — advanced by one on every successful commit CAS
+   *  (dense in the common case), AND durably burned forward by one extra on every successful
+   *  TAKEOVER `acquire()` (Task 4.6, superseding the earlier in-process-only skip-one of Task 4.5 —
+   *  see `acquire()`'s doc) to fence out the seqno the immediate predecessor may have orphaned. The
+   *  burn lives in the DURABLE `manifest.nextSeqno` itself (not just this in-process field) so it
+   *  survives across a CHAIN of stalled takeovers with no successful commit in between — see
+   *  `acquire()`. Non-dense-by-one-per-takeover is expected and harmless: never read as `[0..n]` —
+   *  `materializeTo`/GC always iterate the manifest's own explicit `segments`/`nextSeqno` fields. */
+  nextSeqno;
+  /** Set when a post-CAS local apply fails: the commit is durable but the local materialization is
+   *  inconsistent, so further commits are refused until the store is re-opened (re-bootstrapped). */
+  poisoned = false;
+  /** The lease this instance currently holds (Tier 3 Slice 4), or `null` if it has never
+   *  `acquire()`'d (or was fenced — see `heartbeat`/`commitWriteBatch`). `commitWriteBatch` refuses to
+   *  run without this set; `epoch` is the CAS-bumped value `acquire()` claimed, checked against
+   *  `this.cached.manifest.epoch` before every commit as a defense-in-depth fence check. */
+  held = null;
+  /** Serializes `commitWrite`/`commitWriteBatch` — see class doc. */
+  mutex = Promise.resolve();
+  /** Committed segments since the last successful snapshot (or since `open`) — `maybeSnapshot`'s
+   *  cadence trigger. Reset to 0 only on a successful `snapshot()`. */
+  committedSegmentsSinceSnapshot = 0;
+  constructor(objectStore, shard, local, cached, nextSeqno) {
+    this.objectStore = objectStore;
+    this.shard = shard;
+    this.local = local;
+    this.cached = cached;
+    this.nextSeqno = nextSeqno;
+  }
+  /**
+   * Open (or initialize) a shard's object-storage-backed store: read-or-create the manifest, then
+   * BOOTSTRAP (materialize) the local store — via `materializeTo`, see its doc for the snapshot +
+   * tail-replay algorithm. This claims NO ownership (Tier 3 Slice 4): a writer must additionally
+   * `acquire()` before it may commit; a replica (Slice 5) opens without ever acquiring. A fresh
+   * (empty) bucket bootstraps to an empty local store; a bucket with prior commits reconstructs the
+   * IDENTICAL current state either way.
+   */
+  static async open(opts) {
+    const { objectStore, shard, local } = opts;
+    await local.setupSchema();
+    let cached = await readManifest(objectStore, shard);
+    if (cached === null) {
+      try {
+        cached = await createManifest(objectStore, shard);
+      } catch (e) {
+        if (!isCasConflict2(e)) throw e;
+        cached = await readManifest(objectStore, shard);
+        if (cached === null) throw e;
+      }
+    }
+    const store = new _ObjectStoreDocStore(objectStore, shard, local, cached, 0);
+    await store.materializeTo(cached.manifest);
+    return store;
+  }
+  /**
+   * Materialize `this.local`/`this.nextSeqno` up to `manifest`'s frontier by applying whatever this
+   * instance hasn't already applied: if `manifest` references a snapshot this instance hasn't yet
+   * covered (`snapshotSegBase` at or beyond `this.nextSeqno`), restore it first
+   * (`write(..., "Overwrite")` of its current-state dump), then replay every remaining referenced
+   * segment in order via the same explicit-ts `write(..., "Overwrite")` path — the identical primitive
+   * a post-CAS commit applies with, and the one a replica tailer would use (design record §7).
+   *
+   * Two callers: `open()` on a brand-new instance (`this.nextSeqno === 0`, so this is a full
+   * bootstrap — snapshot-if-any + every segment), and `acquire()` on an ALREADY-materialized instance
+   * that may be behind the CURRENT manifest (a re-acquiring/challenging writer) — in that case
+   * skipping already-applied segments (and skipping a snapshot restore if this instance is already
+   * past its `segBase`) matters both for correctness (never double-apply, though `Overwrite` is
+   * idempotent) and so a challenger that's only slightly behind doesn't needlessly re-read a snapshot
+   * object. Restoring the snapshot when we're behind it is also what makes catch-up correct even if
+   * the fencing owner's `gc()` has since deleted the pre-snapshot segments we'd otherwise be missing.
+   *
+   * Not gated on `runExclusive` itself — both callers already hold it.
+   */
+  async materializeTo(manifest) {
+    let appliedThrough = this.nextSeqno - 1;
+    if (manifest.snapshotTs !== void 0 && manifest.snapshotSegBase !== void 0 && manifest.snapshotSegBase > appliedThrough) {
+      const snap = await readSnapshot(this.objectStore, this.shard, manifest.snapshotTs);
+      if (snap === null) {
+        throw new Error(
+          `objectstore-substrate: missing snapshot '${manifest.snapshotTs}' referenced by manifest for shard '${this.shard}' (torn state)`
+        );
+      }
+      await applySnapshotState(this.local, snap, BigInt(snap.frontierTs));
+      appliedThrough = manifest.snapshotSegBase;
+    }
+    for (const seqno of manifest.segments) {
+      if (seqno <= appliedThrough) continue;
+      const entry = await this.objectStore.get(segmentKey(this.shard, seqno));
+      if (entry === null) {
+        throw new Error(`objectstore-substrate: missing segment '${segmentKey(this.shard, seqno)}' referenced by manifest for shard '${this.shard}'`);
+      }
+      const payload = decodeSegment(entry.body);
+      await this.local.write(payload.documents, payload.indexUpdates, "Overwrite");
+      appliedThrough = seqno;
+    }
+    this.nextSeqno = manifest.nextSeqno;
+  }
+  /**
+   * Claim ownership of this shard for `opts.writerId` (Tier 3 Slice 4, Task 4.2) — the manifest CAS
+   * IS the fence: a successful acquire bumps `epoch`, which invalidates any prior owner's cached
+   * etag, so its next `commitWriteBatch`/`heartbeat` fails loudly (`FencedError` + poison).
+   *
+   * Re-reads the manifest FRESH (not `this.cached` — this instance may be stale or may never have
+   * committed before). If the lease is currently LIVE and held by a DIFFERENT writer
+   * (`now <= leaseExpiresAt`), refuses: `{acquired: false, heldBy, expiresAt}` — this is what
+   * prevents two live writers ping-ponging (a heartbeating owner's lease never expires). Otherwise
+   * (unowned, or the current lease is EXPIRED, or `opts.writerId` already owns it and is re-claiming)
+   * catches this instance's local store up to the just-read manifest via `materializeTo` — REQUIRED so
+   * a challenger that was behind (or a fresh instance that only `open()`'d) is fully materialized to
+   * the manifest's frontier BEFORE it starts committing under the claimed lease — then CAS-bumps
+   * `epoch` and stamps `writerId`/`leaseExpiresAt`.
+   *
+   * A `CasConflict` (lost the acquire race to a concurrent challenger) re-reads and returns
+   * `{acquired: false, ...}` — the caller may retry. Any OTHER `casManifest` failure is ambiguous
+   * (may have landed despite throwing — same lost-response concern as the commit path's C1 fix) and
+   * poisons this instance exactly like a commit/heartbeat CAS failure does (global constraint: lease
+   * CAS failures poison like commit CAS failures).
+   */
+  async acquire(opts) {
+    return this.runExclusive(async () => {
+      const fresh = await readManifest(this.objectStore, this.shard);
+      if (fresh === null) {
+        throw new Error(`objectstore-substrate: acquire() found no manifest for shard '${this.shard}' \u2014 open() must initialize it first`);
+      }
+      const { manifest, etag } = fresh;
+      if (manifest.writerId !== "" && opts.now <= Number(manifest.leaseExpiresAt) && manifest.writerId !== opts.writerId) {
+        return { acquired: false, heldBy: manifest.writerId, expiresAt: Number(manifest.leaseExpiresAt) };
+      }
+      await this.materializeTo(manifest);
+      const burn = manifest.epoch > 0;
+      const next = {
+        ...manifest,
+        epoch: manifest.epoch + 1,
+        writerId: opts.writerId,
+        leaseExpiresAt: String(opts.now + opts.leaseTtlMs),
+        nextSeqno: burn ? manifest.nextSeqno + 1 : manifest.nextSeqno
+      };
+      try {
+        const { etag: newEtag } = await casManifest(this.objectStore, this.shard, next, etag);
+        this.cached = { manifest: next, etag: newEtag };
+        this.held = { epoch: next.epoch, writerId: opts.writerId };
+        this.poisoned = false;
+        this.nextSeqno = next.nextSeqno;
+        return { acquired: true };
+      } catch (e) {
+        if (!isCasConflict2(e)) {
+          this.poisoned = true;
+          throw e;
+        }
+        const reread = await readManifest(this.objectStore, this.shard);
+        if (reread === null) throw e;
+        return { acquired: false, heldBy: reread.manifest.writerId, expiresAt: Number(reread.manifest.leaseExpiresAt) };
+      }
+    });
+  }
+  /**
+   * Renew the currently-held lease's `leaseExpiresAt` (Tier 3 Slice 4, Task 4.2) — `epoch`/`writerId`
+   * are carried forward UNCHANGED (a heartbeat is not a re-claim). Requires `this.held` (throws a
+   * clear error if `acquire()` was never called) and refuses on an already-`poisoned` instance.
+   *
+   * ANY `casManifest` failure means the manifest moved out from under this instance — a challenger
+   * bumped `epoch` (fenced us) or is mid-fence — so this ALWAYS poisons and throws `FencedError`,
+   * unlike the commit path's CasConflict-vs-ambiguous-error distinction: a heartbeat's whole job is to
+   * detect exactly this condition, so there is no "retry" case to special-case.
+   */
+  async heartbeat(opts) {
+    return this.runExclusive(async () => {
+      if (this.held === null) {
+        throw new FencedError(
+          `heartbeat on a store with no held lease for shard '${this.shard}' \u2014 ownership is lost (never acquired or already fenced)`
+        );
+      }
+      if (this.poisoned) {
+        throw new FencedError(
+          `heartbeat on a poisoned store for shard '${this.shard}' (fenced or a prior apply failed) \u2014 ownership is lost`
+        );
+      }
+      const next = { ...this.cached.manifest, leaseExpiresAt: String(opts.now + opts.leaseTtlMs) };
+      try {
+        const { etag } = await casManifest(this.objectStore, this.shard, next, this.cached.etag);
+        this.cached = { manifest: next, etag };
+      } catch (e) {
+        this.poisoned = true;
+        this.held = null;
+        throw new FencedError(
+          `heartbeat fenced: manifest for shard '${this.shard}' moved (stale etag) \u2014 this writer is no longer current and is now poisoned (re-acquire to continue). Cause: ${e?.message ?? String(e)}`
+        );
+      }
+    });
+  }
+  /** Voluntarily give up the held lease WITHOUT touching the bucket — the lease simply expires on its
+   *  own at `leaseExpiresAt` (Tier 3 Slice 4, Task 4.2). After this, `commitWriteBatch` refuses until
+   *  a fresh `acquire()`. IN-PROCESS ONLY: a challenger's `acquire()` still has to wait out the full
+   *  remaining TTL, since nothing in the bucket changed. See `relinquish()` — the graceful-shutdown
+   *  variant that ALSO clears the lease in the bucket itself, so a challenger can take over
+   *  immediately instead of waiting for expiry (Tier 3 Slice 6, Task 6.5). */
+  release() {
+    this.held = null;
+  }
+  /**
+   * Graceful-shutdown variant of `release()` (Tier 3 Slice 6, Task 6.5): best-effort CAS the manifest
+   * to clear the lease (`writerId: "", leaseExpiresAt: "0"`) so a challenger's very next `acquire()`
+   * — even at `now: 0` — sees an unowned/already-expired lease and takes over IMMEDIATELY, instead of
+   * having to wait out this writer's full remaining `leaseTtlMs`. This closes the production gap the
+   * Task 6.4 review found: every graceful rolling-deploy stop/start pair otherwise ate a full-TTL
+   * write outage.
+   *
+   * Deliberately best-effort: a CAS failure here means either (a) we were already fenced — someone
+   * else owns the shard now, which is exactly the state we wanted anyway, or (b) a transient blip —
+   * the lease still expires naturally, falling back to the pre-6.5 behavior. Neither case should
+   * block or fail a clean shutdown, so any CAS error is swallowed. Does NOT bump `epoch` — clearing
+   * `writerId`/`leaseExpiresAt` is sufficient for a challenger's refusal check to pass trivially; the
+   * challenger's own `acquire()` bumps `epoch` and fences any stale in-process state on ITS claim, the
+   * same as an expiry-based takeover always has. Does NOT poison on a swallowed CAS failure — this is
+   * a clean voluntary exit, not a fence.
+   *
+   * Runs under `runExclusive` (serializes with commits/heartbeat/acquire, same as every other
+   * lease/commit operation on this instance). A no-op if this instance never held the lease
+   * (`this.held === null` — already fenced, or `acquire()` was never called): nothing to relinquish.
+   * Always demotes `this.held` to `null` at the end, regardless of the CAS outcome.
+   */
+  async relinquish() {
+    return this.runExclusive(async () => {
+      if (this.held === null) return;
+      const next = { ...this.cached.manifest, writerId: "", leaseExpiresAt: "0" };
+      try {
+        const { etag } = await casManifest(this.objectStore, this.shard, next, this.cached.etag);
+        this.cached = { manifest: next, etag };
+      } catch {
+      }
+      this.held = null;
+    });
+  }
+  /** Chain `fn` onto the mutex so commits from this process serialize (see class doc). */
+  runExclusive(fn) {
+    const result = this.mutex.then(fn, fn);
+    this.mutex = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+  // ── Commit path (intercepted, object-first) ─────────────────────────────────────────────────
+  async commitWriteBatch(units, shardId) {
+    const tsList = await this.runExclusive(async () => {
+      if (this.held === null) {
+        throw new Error(`ObjectStoreDocStore for shard '${this.shard}': not the lease owner \u2014 call acquire() before committing`);
+      }
+      if (units.length === 0) return [];
+      if (this.poisoned) {
+        throw new Error(
+          `ObjectStoreDocStore for shard '${this.shard}' is poisoned (a prior post-commit local apply failed); it must be re-opened before further use`
+        );
+      }
+      if (this.cached.manifest.epoch !== this.held.epoch) {
+        this.poisoned = true;
+        throw new FencedError(
+          `commit fenced: shard '${this.shard}' cached epoch (${this.cached.manifest.epoch}) diverges from the held lease epoch (${this.held.epoch}) \u2014 this writer was fenced by another acquirer and is now poisoned (re-acquire to continue)`
+        );
+      }
+      const localMax = await this.local.maxTimestamp();
+      const cachedTsCounter = BigInt(this.cached.manifest.tsCounter);
+      const floor = cachedTsCounter > localMax ? cachedTsCounter : localMax;
+      const stampedUnits = [];
+      const allDocuments = [];
+      const allIndexUpdates = [];
+      const tsList2 = [];
+      for (let i = 0; i < units.length; i++) {
+        const unit = units[i];
+        const ts = floor + BigInt(i) + 1n;
+        tsList2.push(ts);
+        const stampedDocs = unit.documents.map((d) => ({ ...d, ts }));
+        const stampedIdx = unit.indexUpdates.map((w) => ({ ...w, ts }));
+        stampedUnits.push({ documents: stampedDocs, indexUpdates: stampedIdx });
+        allDocuments.push(...stampedDocs);
+        allIndexUpdates.push(...stampedIdx);
+      }
+      const maxTs = tsList2[tsList2.length - 1];
+      const seqno = this.nextSeqno;
+      const payload = { documents: allDocuments, indexUpdates: allIndexUpdates };
+      await this.objectStore.putImmutable(segmentKey(this.shard, seqno), encodeSegment(payload));
+      const next = {
+        ...this.cached.manifest,
+        epoch: this.held.epoch,
+        frontierTs: maxTs.toString(),
+        tsCounter: maxTs.toString(),
+        segments: [...this.cached.manifest.segments, seqno],
+        nextSeqno: seqno + 1
+      };
+      let etag;
+      try {
+        ({ etag } = await casManifest(this.objectStore, this.shard, next, this.cached.etag));
+      } catch (e) {
+        this.poisoned = true;
+        if (isCasConflict2(e)) {
+          this.held = null;
+          throw new FencedError(
+            `commit fenced: manifest for shard '${this.shard}' moved (stale etag) \u2014 this writer is no longer current and is now poisoned (re-open to continue)`
+          );
+        }
+        throw e;
+      }
+      try {
+        for (const u of stampedUnits) {
+          await this.local.write(u.documents, u.indexUpdates, "Overwrite", shardId);
+        }
+      } catch (e) {
+        this.poisoned = true;
+        throw new Error(
+          `post-commit local apply failed after a DURABLE commit to shard '${this.shard}' (seqno ${seqno}); the commit is durable but this ObjectStoreDocStore's local materialization is inconsistent and must be re-opened. Cause: ${e?.message ?? String(e)}`
+        );
+      }
+      this.cached = { manifest: next, etag };
+      this.nextSeqno = seqno + 1;
+      this.committedSegmentsSinceSnapshot++;
+      return tsList2;
+    });
+    await this.#maybeSnapshotBestEffort();
+    return tsList;
+  }
+  async commitWrite(documents, indexUpdates, shardId, opts) {
+    const out = await this.commitWriteBatch([{ documents, indexUpdates, meta: opts?.meta }], shardId);
+    return out[0];
+  }
+  // ── Snapshots (Tier 3 Slice 3, Task 3.2) — object-first, under the commit mutex ─────────────
+  /**
+   * Take a snapshot of the local store's current state and CAS the manifest to reference it, so a
+   * future `open` can bootstrap in O(state + tail) instead of replaying the whole segment log.
+   * Serializes against commits via `runExclusive` — same reasoning as `commitWriteBatch`: it reads
+   * `cached`/`nextSeqno` and CAS's the manifest, so it must not race a concurrent commit's CAS
+   * against the same cached etag.
+   *
+   * DEADLOCK HAZARD: `runExclusive` is NOT reentrant. Never call `snapshot()`/`maybeSnapshot()` from
+   * INSIDE another `runExclusive` body (e.g. the commit path's own exclusive block) — chain it AFTER
+   * that block resolves instead (see `commitWriteBatch`'s `#maybeSnapshotBestEffort` call site).
+   *
+   * BENIGN DIVERGENCE (whole-branch review, Minor #2): if this snapshot's boundary (`frontierTs`) is
+   * a DELETE's ts, the dump it captures (`dumpCurrentState` excludes tombstones) has no row at that
+   * ts — see the matching note at `open()`'s snapshot-restore site for the full explanation and why
+   * it's safe (the `tsCounter` commit floor, not `local.maxTimestamp()`, is what guards ts reuse).
+   */
+  async snapshot() {
+    return this.runExclusive(async () => {
+      if (this.poisoned) {
+        throw new Error(
+          `ObjectStoreDocStore for shard '${this.shard}' is poisoned (a prior post-commit local apply failed); it must be re-opened before further use`
+        );
+      }
+      if (this.nextSeqno === 0) return;
+      const dump = await this.local.dumpCurrentState();
+      const frontierTs = this.cached.manifest.frontierTs;
+      const segBase = this.nextSeqno - 1;
+      const payload = { frontierTs, segBase, documents: dump.documents, indexUpdates: dump.indexUpdates };
+      await writeSnapshot(this.objectStore, this.shard, payload);
+      const next = {
+        ...this.cached.manifest,
+        snapshotTs: frontierTs,
+        snapshotSegBase: segBase,
+        segments: this.cached.manifest.segments.filter((s) => s > segBase)
+      };
+      try {
+        const { etag } = await casManifest(this.objectStore, this.shard, next, this.cached.etag);
+        this.cached = { manifest: next, etag };
+      } catch (e) {
+        this.poisoned = true;
+        if (isCasConflict2(e)) {
+          throw new FencedError(
+            `snapshot fenced: manifest for shard '${this.shard}' moved (stale etag) \u2014 this writer is no longer current and is now poisoned (re-open to continue)`
+          );
+        }
+        throw e;
+      }
+      this.committedSegmentsSinceSnapshot = 0;
+    });
+  }
+  /** Take a snapshot if `SNAPSHOT_EVERY` segments have committed since the last one. No-op
+   *  (including a poisoned instance — the next commit/explicit `snapshot()` call will surface that
+   *  loudly) otherwise. */
+  async maybeSnapshot() {
+    if (this.poisoned) return;
+    if (this.committedSegmentsSinceSnapshot < SNAPSHOT_EVERY) return;
+    await this.snapshot();
+  }
+  /** `maybeSnapshot()`, swallowing any error — called from OUTSIDE the commit's exclusive block
+   *  (see `commitWriteBatch`). A snapshot failure must never fail an already-durable commit; if it
+   *  poisoned this instance, the next commit's own poisoned-check surfaces that loudly instead. */
+  async #maybeSnapshotBestEffort() {
+    try {
+      await this.maybeSnapshot();
+    } catch {
+    }
+  }
+  // ── GC (Tier 3 Slice 3, Task 3.3) — reclaim what the latest snapshot has superseded ─────────
+  /**
+   * Reclaim durable objects the CURRENT manifest's snapshot (and every registered consumer's
+   * watermark) has superseded: every segment with `seqno <= min(snapshotSegBase, W_min)` (where
+   * `W_min` is the SLOWEST published `s{shard}/consumers/{id}` watermark's `appliedSeqno` — `+Infinity` when
+   * no consumers are registered, so the floor collapses back to plain `snapshotSegBase`, byte-for-
+   * byte the Slice 3 behavior) and every snapshot object except the current one (`snapshotTs`) — the
+   * newest snapshot is always kept regardless of `W_min` (a replica re-materializing after falling
+   * behind the tail restores the NEWEST snapshot via `materializeTo`'s fallback path, never an older
+   * one, so keeping only the newest is correct independent of any watermark).
+   *
+   * The watermark floor is the Tier 3 Slice 5, Task 5.2 addition (closing the Slice 3/4 GC-under-
+   * replicas deferral): a lagging replica's `ObjectStoreReplicaTailer` publishes its own
+   * `appliedSeqno` via `publishConsumerWatermark`; as long as it hasn't fallen behind
+   * `snapshotSegBase` itself (its own snapshot-fallback backstop covers that case — see
+   * `replica-tailer.ts`), `gc()` here will never delete a segment `(W_min, snapshotSegBase]` that
+   * replica still needs to tail.
+   *
+   * Runs under `runExclusive` — it must not race a concurrent commit/snapshot/acquire on THIS
+   * instance. Never touches the manifest itself or `this.cached`/`nextSeqno` (beyond adopting a
+   * freshly re-read manifest when the epoch check below passes) — GC is purely subtractive over
+   * objects the manifest (and consumers) no longer need.
+   *
+   * PERFORMANCE NOTE (whole-branch review, Minor #4): because it runs under `runExclusive`, `gc()`
+   * blocks `commitWriteBatch`/`snapshot()` on this instance for the ENTIRE list+delete sweep (now
+   * also a `consumers/` list+get sweep) — fine for a manual, occasional, single-node call, but revisit
+   * the locking granularity if GC's cadence ever needs to tighten.
+   *
+   * GC-FENCING (Tier 3 Slice 7, Task 7.1 — closes the Slice-4/5/6 deferral above): `gc()` used to
+   * trust `this.cached.manifest` — a snapshot pointer that can be ARBITRARILY STALE the instant a
+   * challenger fences this writer (bumps `epoch`) without this instance having attempted a
+   * commit/heartbeat since. A stale writer's cached `snapshotTs` then names an OLD snapshot, and the
+   * pre-Slice-7 "delete every `snap/*` except my cached `snapshotTs`" predicate would delete the NEW
+   * owner's live snapshot — sinking that owner's next bootstrap. Fixed by two changes, in order:
+   *   1. `this.held === null` (never an owner — a replica, or an already-demoted/fenced writer) is a
+   *      harmless no-op: never GC.
+   *   2. RE-READ the manifest fresh (never trust `this.cached`) and compare its `epoch` against
+   *      `this.held.epoch`. A mismatch means a challenger's `acquire()` landed since we last knew —
+   *      we've been fenced RIGHT NOW, even though nothing told us yet — so we poison + demote and
+   *      delete NOTHING. Only once the epoch matches do we adopt the fresh manifest as current truth
+   *      and compute the delete floor/keepSnap FROM IT (never from a value read before this check).
+   * This closes the TOCTOU window at the READ side, but a fence could still land in the gap BETWEEN
+   * this re-read and the deletes below (the sweep isn't atomic with the epoch check) — so the delete
+   * PREDICATES themselves must independently tolerate a same-gap fence:
+   *   - Segments: `seqno <= floor` (unchanged) — a new owner's commits only ever land at HIGHER
+   *     seqnos than the frontier this floor was computed from, so this predicate can never reach one.
+   *   - Snapshots: **`BigInt(ts) < BigInt(keepSnap)`** (strictly older), not "every snapshot except
+   *     keepSnap" — a new owner racing a snapshot into the gap produces a `ts` NEWER than our
+   *     `keepSnap` (ts's are monotone `frontierTs` values), which `<` by construction never matches.
+   *     `keepSnap` itself is also never deleted (not `<` itself). Compared as `bigint`, not string —
+   *     ts's are decimal-string bigints, and a naive string compare orders `"9"` after `"10"`.
+   * Together: a fenced/stale writer's `gc()` deletes nothing (the epoch check catches the common case,
+   * and the TOCTOU-safe predicates catch the rest), while the happy-path owner's behavior is unchanged
+   * (its own re-read always matches its own held epoch).
+   */
+  async gc() {
+    return this.runExclusive(async () => {
+      if (this.poisoned) {
+        throw new Error(
+          `ObjectStoreDocStore for shard '${this.shard}' is poisoned (a prior post-commit local apply failed); it must be re-opened before further use`
+        );
+      }
+      if (this.held === null) {
+        return { deletedSegments: 0, deletedSnapshots: 0 };
+      }
+      const fresh = await readManifest(this.objectStore, this.shard);
+      if (fresh === null) {
+        throw new Error(`objectstore-substrate: gc() found no manifest for shard '${this.shard}' \u2014 open() must initialize it first`);
+      }
+      if (fresh.manifest.epoch !== this.held.epoch) {
+        this.poisoned = true;
+        this.held = null;
+        return { deletedSegments: 0, deletedSnapshots: 0 };
+      }
+      this.cached = fresh;
+      if (fresh.manifest.snapshotTs === void 0) {
+        return { deletedSegments: 0, deletedSnapshots: 0 };
+      }
+      const segBase = fresh.manifest.snapshotSegBase;
+      const keepSnap = fresh.manifest.snapshotTs;
+      const keepSnapBig = BigInt(keepSnap);
+      const watermarks = await readConsumerWatermarks(this.objectStore, this.shard);
+      const wMin = watermarks.length > 0 ? Math.min(...watermarks.map((w) => w.appliedSeqno)) : Number.POSITIVE_INFINITY;
+      const floor = Math.min(segBase, wMin);
+      const segPrefix = `s${this.shard}/seg/`;
+      const segKeys = await this.objectStore.list(segPrefix);
+      let deletedSegments = 0;
+      for (const key of segKeys) {
+        const suffix = key.slice(key.lastIndexOf("/") + 1);
+        const seqno = Number(suffix);
+        if (!Number.isInteger(seqno)) continue;
+        if (seqno <= floor) {
+          await this.objectStore.delete(key);
+          deletedSegments++;
+        }
+      }
+      const snapPrefix = `s${this.shard}/snap/`;
+      const snapKeys = await this.objectStore.list(snapPrefix);
+      let deletedSnapshots = 0;
+      for (const key of snapKeys) {
+        const ts = key.slice(key.lastIndexOf("/") + 1);
+        if (!/^\d+$/.test(ts)) continue;
+        if (BigInt(ts) < keepSnapBig) {
+          await this.objectStore.delete(key);
+          deletedSnapshots++;
+        }
+      }
+      return { deletedSegments, deletedSnapshots };
+    });
+  }
+  // ── Everything else: forward to the local materialized store ───────────────────────────────
+  setupSchema(options) {
+    return this.local.setupSchema(options);
+  }
+  write(documents, indexUpdates, conflictStrategy, shardId) {
+    return this.local.write(documents, indexUpdates, conflictStrategy, shardId);
+  }
+  /** The materialized current state (Slice 5 — migration export). Delegates to the local SQLite
+   *  store, which already holds the full materialized image the object log reduces to — the same
+   *  source `snapshot()` dumps from. */
+  dumpCurrentState() {
+    return this.local.dumpCurrentState();
+  }
+  addCommitGuard(guard) {
+    return this.local.addCommitGuard(guard);
+  }
+  get(id, readTimestamp) {
+    return this.local.get(id, readTimestamp);
+  }
+  index_scan(indexId, tableId, readTimestamp, interval, order, limit) {
+    return this.local.index_scan(indexId, tableId, readTimestamp, interval, order, limit);
+  }
+  load_documents(range, order, limit) {
+    return this.local.load_documents(range, order, limit);
+  }
+  previous_revisions(queries) {
+    return this.local.previous_revisions(queries);
+  }
+  scan(tableId, readTimestamp) {
+    return this.local.scan(tableId, readTimestamp);
+  }
+  count(tableId) {
+    return this.local.count(tableId);
+  }
+  maxTimestamp() {
+    return this.local.maxTimestamp();
+  }
+  getGlobal(key) {
+    return this.local.getGlobal(key);
+  }
+  writeGlobal(key, value) {
+    return this.local.writeGlobal(key, value);
+  }
+  writeGlobalIfAbsent(key, value) {
+    return this.local.writeGlobalIfAbsent(key, value);
+  }
+  getClientVerdict(identity, clientId, seq) {
+    return this.local.getClientVerdict(identity, clientId, seq);
+  }
+  getClientFloor(identity, clientId) {
+    return this.local.getClientFloor(identity, clientId);
+  }
+  recordClientVerdict(identity, clientId, seq, record) {
+    return this.local.recordClientVerdict(identity, clientId, seq, record);
+  }
+  updateClientVerdictValue(identity, clientId, seq, value) {
+    return this.local.updateClientVerdictValue(identity, clientId, seq, value);
+  }
+  pruneClientMutations(identity, clientId, opts) {
+    return this.local.pruneClientMutations(identity, clientId, opts);
+  }
+  sweepExpiredClientMutations(beforeMs) {
+    return this.local.sweepExpiredClientMutations(beforeMs);
+  }
+  close() {
+    return this.local.close();
+  }
+};
+
+// src/sharded-object-doc-store.ts
+import { DEFAULT_SHARD } from "@helipod/id-codec";
+
+// src/merge-sorted.ts
+function compareBytesLex(a, b) {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const diff = a[i] - b[i];
+    if (diff !== 0) return diff;
+  }
+  return a.length - b.length;
+}
+function compareBigint(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+async function* mergeSortedAsyncGenerators(sources, keyCompare, order, limit) {
+  const cursors = sources.map((gen) => ({ gen, current: void 0, done: false }));
+  async function advance(c) {
+    const r = await c.gen.next();
+    if (r.done) {
+      c.done = true;
+      c.current = void 0;
+    } else {
+      c.current = r.value;
+    }
+  }
+  try {
+    await Promise.all(cursors.map((c) => advance(c)));
+    let yielded = 0;
+    for (; ; ) {
+      if (limit !== void 0 && yielded >= limit) return;
+      let bestIdx = -1;
+      for (let i = 0; i < cursors.length; i++) {
+        const c = cursors[i];
+        if (c.done) continue;
+        if (bestIdx === -1) {
+          bestIdx = i;
+          continue;
+        }
+        const cmp = keyCompare(c.current, cursors[bestIdx].current);
+        if (order === "asc" ? cmp < 0 : cmp > 0) bestIdx = i;
+      }
+      if (bestIdx === -1) return;
+      const winner = cursors[bestIdx];
+      yield winner.current;
+      yielded++;
+      await advance(winner);
+    }
+  } finally {
+    await Promise.all(
+      cursors.filter((c) => !c.done).map(async (c) => {
+        try {
+          await c.gen.return(void 0);
+        } catch {
+        }
+      })
+    );
+  }
+}
+
+// src/sharded-object-doc-store.ts
+var ShardedObjectStoreDocStore = class {
+  lanes;
+  defaultShard;
+  constructor(lanes, opts) {
+    if (lanes.size === 0) {
+      throw new Error("ShardedObjectStoreDocStore: at least one lane is required");
+    }
+    const defaultShard = opts?.defaultShard ?? DEFAULT_SHARD;
+    if (!lanes.has(defaultShard)) {
+      throw new Error(
+        `ShardedObjectStoreDocStore: defaultShard '${defaultShard}' is not one of the composed lanes (${[...lanes.keys()].join(", ")})`
+      );
+    }
+    this.lanes = lanes;
+    this.defaultShard = defaultShard;
+  }
+  lane(shardId) {
+    const l = this.lanes.get(shardId);
+    if (!l) {
+      throw new Error(
+        `ShardedObjectStoreDocStore: unknown shard '${shardId}' \u2014 composed lanes are (${[...this.lanes.keys()].join(", ")})`
+      );
+    }
+    return l;
+  }
+  laneList() {
+    return [...this.lanes.values()];
+  }
+  // ── Writes — route by the caller-supplied shardId (the ShardedTransactor always passes one for
+  //    commits; `write`'s replica/bootstrap callers do too — see `ObjectStoreDocStore.materializeTo`) ─
+  setupSchema(options) {
+    return Promise.all(this.laneList().map((l) => l.setupSchema(options))).then(() => void 0);
+  }
+  // NOTE: these three are deliberately `async` (not a bare `return this.lane(...)...`) so an
+  // unknown-shardId lookup failure — thrown SYNCHRONOUSLY by `this.lane()` — surfaces as a REJECTED
+  // promise, matching every other `DocStore` method's async contract, rather than throwing
+  // synchronously out of the call before the caller ever gets a promise to await/catch.
+  async write(documents, indexUpdates, conflictStrategy, shardId) {
+    return this.lane(shardId ?? this.defaultShard).write(documents, indexUpdates, conflictStrategy, shardId);
+  }
+  async commitWrite(documents, indexUpdates, shardId, opts) {
+    return this.lane(shardId ?? this.defaultShard).commitWrite(documents, indexUpdates, shardId, opts);
+  }
+  async commitWriteBatch(units, shardId) {
+    return this.lane(shardId ?? this.defaultShard).commitWriteBatch(units, shardId);
+  }
+  /**
+   * Fan the SAME guard out to every lane (one registration per lane) — a guard for the sharded case
+   * therefore fences/effects PER LANE, not atomically across the whole sharded store. This matches
+   * `ObjectStoreDocStore`'s own single-lane note ("guard atomicity + effectively-once forwarding are a
+   * LATER slice") — composing N of them doesn't add a NEW atomicity gap, it just makes the existing
+   * per-lane-only scope explicit at the sharded layer too.
+   */
+  addCommitGuard(guard) {
+    const unregs = this.laneList().map((l) => l.addCommitGuard(guard));
+    return () => {
+      for (const unreg of unregs) unreg();
+    };
+  }
+  // ── Reads — MERGE across every lane (the transactor never tells us which shard a read is for) ────
+  async get(id, readTimestamp) {
+    const hits = await Promise.all(this.laneList().map((l) => l.get(id, readTimestamp)));
+    for (const hit of hits) if (hit !== null) return hit;
+    return null;
+  }
+  async *index_scan(indexId, tableId, readTimestamp, interval, order, limit) {
+    const generators = this.laneList().map((l) => l.index_scan(indexId, tableId, readTimestamp, interval, order, limit));
+    yield* mergeSortedAsyncGenerators(generators, (a, b) => compareBytesLex(a[0], b[0]), order, limit);
+  }
+  async *load_documents(range, order, limit) {
+    const generators = this.laneList().map((l) => l.load_documents(range, order, limit));
+    yield* mergeSortedAsyncGenerators(generators, (a, b) => compareBigint(a.ts, b.ts), order, limit);
+  }
+  async previous_revisions(queries) {
+    const perLane = await Promise.all(this.laneList().map((l) => l.previous_revisions(queries)));
+    const merged = /* @__PURE__ */ new Map();
+    for (const laneResult of perLane) {
+      for (const [key, entry] of laneResult) merged.set(key, entry);
+    }
+    return merged;
+  }
+  async scan(tableId, readTimestamp) {
+    const perLane = await Promise.all(this.laneList().map((l) => l.scan(tableId, readTimestamp)));
+    return perLane.flat();
+  }
+  async count(tableId) {
+    const perLane = await Promise.all(this.laneList().map((l) => l.count(tableId)));
+    return perLane.reduce((sum, n) => sum + n, 0);
+  }
+  async maxTimestamp() {
+    const perLane = await Promise.all(this.laneList().map((l) => l.maxTimestamp()));
+    let max = 0n;
+    for (const ts of perLane) if (ts > max) max = ts;
+    return max;
+  }
+  // ── Deployment-level bookkeeping — route to ONE lane (the default shard) consistently, never
+  //    fan out: these are single-source-of-truth concerns (fleet identity, per-client receipts), not
+  //    per-shard data. Routing every deployment ever to the SAME lane means a client's receipts/floor
+  //    are never split across lanes regardless of which table its mutations touched. ────────────────
+  getGlobal(key) {
+    return this.lane(this.defaultShard).getGlobal(key);
+  }
+  writeGlobal(key, value) {
+    return this.lane(this.defaultShard).writeGlobal(key, value);
+  }
+  writeGlobalIfAbsent(key, value) {
+    return this.lane(this.defaultShard).writeGlobalIfAbsent(key, value);
+  }
+  getClientVerdict(identity, clientId, seq) {
+    return this.lane(this.defaultShard).getClientVerdict(identity, clientId, seq);
+  }
+  getClientFloor(identity, clientId) {
+    return this.lane(this.defaultShard).getClientFloor(identity, clientId);
+  }
+  recordClientVerdict(identity, clientId, seq, record) {
+    return this.lane(this.defaultShard).recordClientVerdict(identity, clientId, seq, record);
+  }
+  updateClientVerdictValue(identity, clientId, seq, value) {
+    return this.lane(this.defaultShard).updateClientVerdictValue(identity, clientId, seq, value);
+  }
+  pruneClientMutations(identity, clientId, opts) {
+    return this.lane(this.defaultShard).pruneClientMutations(identity, clientId, opts);
+  }
+  sweepExpiredClientMutations(beforeMs) {
+    return this.lane(this.defaultShard).sweepExpiredClientMutations(beforeMs);
+  }
+  async close() {
+    await Promise.all(this.laneList().map((l) => l.close()));
+  }
+};
+
+// src/reshard.ts
+import { shardIdList, shardIdForKeyValue, DEFAULT_SHARD as DEFAULT_SHARD2, documentIdKey as documentIdKey2 } from "@helipod/id-codec";
+
+// src/globals.ts
+import { isCasConflict as isCasConflict3 } from "@helipod/objectstore";
+var GLOBALS_KEY = "globals";
+async function readGlobals(os) {
+  const entry = await os.get(GLOBALS_KEY);
+  if (entry === null) return null;
+  return JSON.parse(new TextDecoder().decode(entry.body));
+}
+async function createGlobals(os, globals) {
+  await os.casPut(GLOBALS_KEY, new TextEncoder().encode(JSON.stringify(globals)), null);
+  return globals;
+}
+async function ensureGlobals(os, globals) {
+  const existing = await readGlobals(os);
+  if (existing !== null) return existing;
+  try {
+    return await createGlobals(os, globals);
+  } catch (e) {
+    if (!isCasConflict3(e)) throw e;
+    const winner = await readGlobals(os);
+    if (winner === null) {
+      throw new Error("objectstore-substrate: globals CasConflict but re-read found no globals object");
+    }
+    return winner;
+  }
+}
+async function writeGlobals(os, globals) {
+  const bytes = new TextEncoder().encode(JSON.stringify(globals));
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const existing = await os.get(GLOBALS_KEY);
+    try {
+      await os.casPut(GLOBALS_KEY, bytes, existing === null ? null : existing.etag);
+      return;
+    } catch (e) {
+      if (!isCasConflict3(e)) throw e;
+    }
+  }
+  throw new Error("objectstore-substrate: writeGlobals exhausted retries on a moving globals object");
+}
+
+// src/reshard.ts
+var ReshardObjectStoreLiveError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReshardObjectStoreLiveError";
+  }
+};
+function laneIdsFor(numShards) {
+  return numShards === 1 ? ["0"] : [...shardIdList(numShards)];
+}
+function pushTo(map, key, value) {
+  const arr = map.get(key);
+  if (arr) arr.push(value);
+  else map.set(key, [value]);
+}
+async function reshardObjectStore(opts) {
+  const { objectStore: os, toShards, now, shardKeyFor, makeLocal } = opts;
+  if (!Number.isInteger(toShards) || toShards < 1) {
+    throw new RangeError(`reshardObjectStore: toShards must be a positive integer, got ${toShards}`);
+  }
+  const globals = await readGlobals(os);
+  if (globals === null) {
+    throw new Error("reshardObjectStore: no `globals` object \u2014 this bucket is not an object-storage deployment");
+  }
+  const fromShards = globals.numShards;
+  if (fromShards === toShards) {
+    return { fromShards, toShards, movedDocs: 0, perLaneCounts: {} };
+  }
+  const sourceLaneIds = laneIdsFor(fromShards);
+  const targetLaneIds = laneIdsFor(toShards);
+  const toBucketLane = (engineShard) => toShards === 1 ? "0" : engineShard;
+  for (const shard of sourceLaneIds) {
+    const m = await readManifest(os, shard);
+    if (m !== null && m.manifest.writerId !== "" && now <= Number(m.manifest.leaseExpiresAt)) {
+      throw new ReshardObjectStoreLiveError(
+        `reshardObjectStore: refusing \u2014 lane '${shard}' has a live lease held by '${m.manifest.writerId}' (expires at ${m.manifest.leaseExpiresAt}, now ${now}). Stop the deployment (scale to zero / let leases expire) first.`
+      );
+    }
+  }
+  const allDocs = [];
+  const allIndex = [];
+  const oldLaneOfDoc = /* @__PURE__ */ new Map();
+  for (const shard of sourceLaneIds) {
+    const local = makeLocal();
+    await ObjectStoreDocStore.open({ objectStore: os, shard, local });
+    const state = await local.dumpCurrentState();
+    for (const d of state.documents) {
+      allDocs.push(d);
+      oldLaneOfDoc.set(documentIdKey2(d.id), shard);
+    }
+    for (const iw of state.indexUpdates) allIndex.push(iw);
+    await local.close();
+  }
+  const laneToDocs = /* @__PURE__ */ new Map();
+  const newLaneOfDoc = /* @__PURE__ */ new Map();
+  let movedDocs = 0;
+  for (const d of allDocs) {
+    const shardKey = shardKeyFor(d.id.tableNumber);
+    const fields = d.value?.value;
+    const engineShard = shardKey !== null && fields !== void 0 ? shardIdForKeyValue(fields[shardKey], toShards) : DEFAULT_SHARD2;
+    const newLane = toBucketLane(engineShard);
+    const key = documentIdKey2(d.id);
+    newLaneOfDoc.set(key, newLane);
+    if (oldLaneOfDoc.get(key) !== newLane) movedDocs++;
+    pushTo(laneToDocs, newLane, d);
+  }
+  const laneToIndex = /* @__PURE__ */ new Map();
+  for (const iw of allIndex) {
+    if (iw.update.value.type !== "NonClustered") continue;
+    const lane = newLaneOfDoc.get(documentIdKey2(iw.update.value.docId));
+    if (lane === void 0) continue;
+    pushTo(laneToIndex, lane, iw);
+  }
+  const lanesToClear = /* @__PURE__ */ new Set([...sourceLaneIds, ...targetLaneIds]);
+  for (const shard of lanesToClear) {
+    for (const k of await os.list(`s${shard}/`)) await os.delete(k);
+  }
+  const perLaneCounts = {};
+  for (const shard of targetLaneIds) {
+    const docs = laneToDocs.get(shard) ?? [];
+    const index = laneToIndex.get(shard) ?? [];
+    perLaneCounts[shard] = docs.length;
+    const local = makeLocal();
+    const store = await ObjectStoreDocStore.open({ objectStore: os, shard, local });
+    await store.acquire({ writerId: `reshard-${shard}`, leaseTtlMs: 6e4, now });
+    if (docs.length > 0 || index.length > 0) {
+      await store.commitWriteBatch([{ documents: docs, indexUpdates: index }], shard);
+    }
+    await store.relinquish();
+    await local.close();
+  }
+  await writeGlobals(os, { deploymentId: globals.deploymentId, numShards: toShards });
+  return { fromShards, toShards, movedDocs, perLaneCounts };
+}
+
+// src/heartbeat-driver.ts
+function leaseHeartbeatDriver(store, opts) {
+  const { leaseTtlMs, heartbeatMs, onFenced } = opts;
+  if (heartbeatMs >= leaseTtlMs) {
+    throw new Error(
+      `objectstore-substrate: leaseHeartbeatDriver requires heartbeatMs (${heartbeatMs}) < leaseTtlMs (${leaseTtlMs}) \u2014 a heartbeat cadence at or slower than the lease TTL can let the lease lapse before a renewal ever lands`
+    );
+  }
+  let ctx;
+  let timer = null;
+  let stopped = false;
+  async function tick() {
+    if (stopped) return;
+    await store.heartbeat({ now: ctx.now(), leaseTtlMs });
+  }
+  function armTimer() {
+    if (stopped) return;
+    if (timer !== null) {
+      ctx.clearTimer(timer);
+      timer = null;
+    }
+    timer = ctx.setTimer(ctx.now() + heartbeatMs, wake);
+  }
+  function wake() {
+    if (stopped) return;
+    tick().then(
+      () => {
+        armTimer();
+      },
+      (e) => {
+        if (stopped) return;
+        if (e instanceof FencedError) {
+          stopped = true;
+          console.error(
+            `[objectstore-substrate] FATAL: lease heartbeat fenced \u2014 this node no longer owns its shard's write lease and must stop serving writes. Cause: ${e.message}`
+          );
+          try {
+            onFenced?.(e);
+          } catch (callbackError) {
+            console.error("[objectstore-substrate] lease heartbeat: onFenced callback threw:", callbackError);
+          }
+          return;
+        }
+        console.error("[objectstore-substrate] lease heartbeat: renewal attempt failed (will retry):", e);
+        armTimer();
+      }
+    );
+  }
+  return {
+    name: "leaseHeartbeat",
+    start(c) {
+      ctx = c;
+      armTimer();
+    },
+    stop() {
+      stopped = true;
+      if (timer !== null) {
+        ctx.clearTimer(timer);
+        timer = null;
+      }
+    },
+    // Test seam: runs one heartbeat pass and awaits its real completion, letting a `FencedError` (or
+    // any other error) propagate to the caller — unlike `wake()`, used by the timer path, which
+    // catches and branches instead. Does NOT itself set `stopped`/call `onFenced` on a fence; a test
+    // exercising that behavior should drive it through the timer callback captured by a fake
+    // `DriverContext.setTimer`, same as `receiptsReaper`'s own tests do for its policy.
+    __tick: () => tick()
+  };
+}
+
+// src/gc-driver.ts
+function gcDriver(store, opts) {
+  const { sweepMs } = opts;
+  let ctx;
+  let timer = null;
+  let stopped = false;
+  async function tick() {
+    if (stopped) return { deletedSegments: 0, deletedSnapshots: 0 };
+    return store.gc();
+  }
+  function armTimer() {
+    if (stopped) return;
+    if (timer !== null) {
+      ctx.clearTimer(timer);
+      timer = null;
+    }
+    timer = ctx.setTimer(ctx.now() + sweepMs, wake);
+  }
+  function wake() {
+    if (stopped) return;
+    tick().catch((e) => {
+      console.error("[objectstore-substrate] gc-driver: sweep pass failed (will retry):", e);
+    }).finally(() => {
+      armTimer();
+    });
+  }
+  return {
+    name: "objectStoreGc",
+    start(c) {
+      ctx = c;
+      armTimer();
+    },
+    stop() {
+      stopped = true;
+      if (timer !== null) {
+        ctx.clearTimer(timer);
+        timer = null;
+      }
+    },
+    // Test seam: runs one gc() pass and awaits its real completion, letting any error propagate
+    // (unlike `wake()`, used by the timer path, which swallows+logs) — see the interface doc above.
+    __tick: () => tick()
+  };
+}
+
+// src/frontier.ts
+async function readGlobalFrontier(os, shards) {
+  if (shards.length === 0) return 0n;
+  let min = null;
+  for (const shard of shards) {
+    const entry = await readManifest(os, shard);
+    if (entry === null) return 0n;
+    const ts = BigInt(entry.manifest.frontierTs);
+    if (min === null || ts < min) min = ts;
+  }
+  return min;
+}
+
+// src/replica-tailer.ts
+import { encodeStorageTableId, internalIdToHex } from "@helipod/id-codec";
+var MAX_MISSING_SEGMENT_RETRIES = 8;
+var ObjectStoreReplicaTailer = class {
+  objectStore;
+  shard;
+  local;
+  onInvalidation;
+  pollMs;
+  /** The highest segment seqno this tailer has itself applied (or correlated `local` to — see
+   *  `#ensureInitialized`/the "nothing new" opportunistic-seed note in `#tickOnce`). `-1` means
+   *  "not yet correlated to any manifest state" — the sentinel that makes `#materializeRound`'s
+   *  snapshot-fallback check and tail-pull loop naturally perform a FULL catch-up (every segment,
+   *  or the newest snapshot + its tail) the first time this tailer actually has new work to do,
+   *  which is the correct, safe behavior for a `local` this tailer hasn't yet correlated to a
+   *  known-caught-up point (re-applying already-present rows via `write(..., "Overwrite")` is an
+   *  idempotent no-op on `local`'s actual state; the only cost is a possibly-oversized first
+   *  invalidation batch, never a missed one). */
+  appliedSeqnoValue = -1;
+  /** The ts through which `local` is known to be caught up. Lazily seeded from
+   *  `local.maxTimestamp()` on the first `tick()` — see `#ensureInitialized`. */
+  appliedMaxTsValue = 0n;
+  initialized = false;
+  timer;
+  /** Reentrancy guard — a manual `tick()` call racing the `start()`-armed poll timer must not run
+   *  two overlapping apply rounds against the same `local`/cursor state. */
+  draining = false;
+  waiters = /* @__PURE__ */ new Set();
+  constructor(opts) {
+    this.objectStore = opts.objectStore;
+    this.shard = opts.shard;
+    this.local = opts.local;
+    this.onInvalidation = opts.onInvalidation;
+    this.pollMs = opts.pollMs ?? 1e3;
+  }
+  get appliedSeqno() {
+    return this.appliedSeqnoValue;
+  }
+  get appliedMaxTs() {
+    return this.appliedMaxTsValue;
+  }
+  /** Arms a `setInterval(tick, pollMs)`. Tick errors are swallowed (logged) — mirrors the fleet
+   *  tailer's fire-and-forget poll posture: a transient failure must not crash the caller's process,
+   *  and the NEXT tick retries from the same (unadvanced) watermark regardless. No-op if already
+   *  started. */
+  start() {
+    if (this.timer !== void 0) return;
+    this.timer = setInterval(() => {
+      void this.tick().catch((e) => {
+        console.error(`objectstore-substrate: replica tailer tick failed for shard '${this.shard}'`, e);
+      });
+    }, this.pollMs);
+  }
+  stop() {
+    if (this.timer !== void 0) {
+      clearInterval(this.timer);
+      this.timer = void 0;
+    }
+  }
+  /** Resolves when `appliedMaxTs >= ts` (immediately if already true). Poll-driven: nothing here
+   *  itself advances the watermark — either `start()` must be armed, or the caller must drive
+   *  `tick()` itself (e.g. in a test loop). Rejects on `timeoutMs` elapsing first. */
+  waitFor(ts, timeoutMs) {
+    if (this.appliedMaxTsValue >= ts) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        ts,
+        resolve: () => {
+          clearTimeout(waiter.timer);
+          this.waiters.delete(waiter);
+          resolve();
+        },
+        timer: setTimeout(() => {
+          this.waiters.delete(waiter);
+          reject(
+            new Error(
+              `ObjectStoreReplicaTailer.waitFor timed out after ${timeoutMs}ms waiting for ts >= ${ts} (currently at ${this.appliedMaxTsValue})`
+            )
+          );
+        }, timeoutMs)
+      };
+      this.waiters.add(waiter);
+    });
+  }
+  #wakeSatisfiedWaiters() {
+    for (const w of [...this.waiters]) {
+      if (this.appliedMaxTsValue >= w.ts) w.resolve();
+    }
+  }
+  /** One poll round: returns `true` if anything was applied (or the watermark otherwise advanced),
+   *  `false` if there was nothing new. Reentrancy-guarded (see `draining`'s doc) — a call landing
+   *  while another is already in flight is a no-op `false`, not queued; the next timer tick (or the
+   *  caller's own retry) picks up whatever was missed. */
+  async tick() {
+    if (this.draining) return false;
+    this.draining = true;
+    try {
+      return await this.#tickOnce();
+    } finally {
+      this.draining = false;
+    }
+  }
+  /** Seeds `appliedMaxTsValue` from `local.maxTimestamp()` on the FIRST tick only — this must be
+   *  lazy (not done in the constructor) because `DocStore.maxTimestamp()` is async and constructors
+   *  can't await. Deliberately does NOT try to also seed `appliedSeqnoValue` here: at this point we
+   *  have no manifest read yet to correlate a ts to a seqno cursor against, so `appliedSeqnoValue`
+   *  stays at its conservative `-1` sentinel — `#tickOnce`'s "nothing new" branch opportunistically
+   *  seeds it instead, the first time it reads a manifest whose `frontierTs` this exact
+   *  `appliedMaxTsValue` already covers (see that branch's doc for why that correlation is safe). */
+  async #ensureInitialized() {
+    if (this.initialized) return;
+    this.appliedMaxTsValue = await this.local.maxTimestamp();
+    this.initialized = true;
+  }
+  async #tickOnce() {
+    await this.#ensureInitialized();
+    const fresh = await readManifest(this.objectStore, this.shard);
+    if (fresh === null) return false;
+    const manifest = fresh.manifest;
+    const frontierTs = BigInt(manifest.frontierTs);
+    if (frontierTs <= this.appliedMaxTsValue) {
+      if (this.appliedSeqnoValue < manifest.nextSeqno - 1) this.appliedSeqnoValue = manifest.nextSeqno - 1;
+      return false;
+    }
+    const round = await this.#materializeRound(manifest);
+    const newMaxTs = BigInt(round.manifest.frontierTs);
+    if (round.documents.length === 0 && round.indexUpdates.length === 0) {
+      this.appliedSeqnoValue = round.appliedSeqno;
+      this.appliedMaxTsValue = newMaxTs;
+      this.#wakeSatisfiedWaiters();
+      return true;
+    }
+    const inv = this.#buildInvalidation(round.documents, round.indexUpdates, newMaxTs);
+    await this.onInvalidation(inv);
+    this.appliedSeqnoValue = round.appliedSeqno;
+    this.appliedMaxTsValue = newMaxTs;
+    this.#wakeSatisfiedWaiters();
+    return true;
+  }
+  /**
+   * Pulls + applies everything between `this.appliedSeqnoValue` and `manifest`'s frontier, mutating
+   * `local` as it goes (idempotent — a segment/snapshot already reflected in `local` is a safe
+   * no-op re-`Overwrite`), and returns every row applied THIS round (for `#buildInvalidation`), the
+   * final manifest revision actually reached, and the seqno cursor the round advanced to.
+   *
+   * Deliberately does NOT mutate `this.appliedSeqnoValue` — only `#tickOnce` may do that, and only
+   * AFTER its `onInvalidation` sink resolves (see that method's doc). This method runs entirely
+   * against a LOCAL `appliedSeqno` variable seeded from the instance field, so a caller that discards
+   * this round's result (sink threw) leaves the instance cursor exactly where it started, and a retry
+   * re-runs this same method from the same starting point — re-applying idempotently and rebuilding
+   * the identical returned batch.
+   *
+   * Mirrors `object-doc-store.ts`'s `materializeTo` — same snapshot-restore-then-replay-tail shape —
+   * with one addition `materializeTo` doesn't need: a MISSING segment (`objectStore.get` returns
+   * `null`) means a lagging replica lost a race against `gc()`, which only ever deletes a segment
+   * once a NEWER snapshot supersedes it. The safe recovery is therefore always available: re-read the
+   * manifest (it must now reference a snapshot covering the missing seqno, or GC could not have
+   * deleted it) and restart the round against that fresher manifest — looping rather than recursing,
+   * so partial progress already applied (and already reflected in the local `appliedSeqno`) is never
+   * discarded, and the accumulated `documents`/`indexUpdates` carry across the restart intact.
+   */
+  async #materializeRound(initialManifest) {
+    const documents = [];
+    const indexUpdates = [];
+    let manifest = initialManifest;
+    let appliedSeqno = this.appliedSeqnoValue;
+    let missingSegmentRetries = 0;
+    for (; ; ) {
+      if (manifest.snapshotTs !== void 0 && manifest.snapshotSegBase !== void 0 && manifest.snapshotSegBase > appliedSeqno) {
+        const snap = await readSnapshot(this.objectStore, this.shard, manifest.snapshotTs);
+        if (snap === null) {
+          throw new Error(
+            `objectstore-substrate: replica tailer for shard '${this.shard}' \u2014 missing snapshot '${manifest.snapshotTs}' referenced by the manifest (torn state)`
+          );
+        }
+        const snapFrontierTs = BigInt(snap.frontierTs);
+        const { deletedDocs } = await applySnapshotState(this.local, snap, snapFrontierTs);
+        if (deletedDocs.length > 0) {
+          documents.push(...deletedDocs);
+        }
+        documents.push(...snap.documents);
+        indexUpdates.push(...snap.indexUpdates);
+        appliedSeqno = manifest.snapshotSegBase;
+      }
+      let missedSegment = false;
+      for (const seqno of manifest.segments) {
+        if (seqno <= appliedSeqno) continue;
+        const entry = await this.objectStore.get(segmentKey(this.shard, seqno));
+        if (entry === null) {
+          if (++missingSegmentRetries > MAX_MISSING_SEGMENT_RETRIES) {
+            throw new Error(
+              `objectstore-substrate: replica tailer for shard '${this.shard}' \u2014 missing segment '${segmentKey(this.shard, seqno)}' did not resolve via snapshot fallback after ${MAX_MISSING_SEGMENT_RETRIES} retries`
+            );
+          }
+          const refreshed = await readManifest(this.objectStore, this.shard);
+          if (refreshed === null) {
+            throw new Error(
+              `objectstore-substrate: replica tailer for shard '${this.shard}' \u2014 manifest disappeared mid-round`
+            );
+          }
+          manifest = refreshed.manifest;
+          missedSegment = true;
+          break;
+        }
+        const payload = decodeSegment(entry.body);
+        await this.local.write(payload.documents, payload.indexUpdates, "Overwrite");
+        documents.push(...payload.documents);
+        indexUpdates.push(...payload.indexUpdates);
+        appliedSeqno = seqno;
+      }
+      if (!missedSegment) return { documents, indexUpdates, manifest, appliedSeqno };
+    }
+  }
+  /** `${tableId}|${internalIdHex}` — the doc-identity key `#buildInvalidation`'s dedupe uses to
+   *  distinguish applied documents by `(tableId, internalId)`. (The snapshot-restore diff this
+   *  method used to also serve, Finding 1, now lives in the shared `applySnapshotState` helper,
+   *  keyed by `@helipod/id-codec`'s own `documentIdKey` — see `apply-snapshot.ts`.) */
+  #docKey(id) {
+    return `${encodeStorageTableId(id.tableNumber)}|${internalIdToHex(id.internalId)}`;
+  }
+  /** Builds the round's `AppliedInvalidation` — mirrors the fleet tailer's derivation
+   *  (`replica-tailer.ts` ~:476-488): `writtenDocs` DISTINCT-deduped by `(tableId, internalId)` from
+   *  the applied documents, `writtenKeys` straight from the applied index writes, `writtenTables`
+   *  DISTINCT across both sources. */
+  #buildInvalidation(documents, indexUpdates, newMaxTs) {
+    const tables = /* @__PURE__ */ new Set();
+    const seenDocs = /* @__PURE__ */ new Set();
+    const writtenDocs = [];
+    for (const d of documents) {
+      const tableId = encodeStorageTableId(d.id.tableNumber);
+      tables.add(tableId);
+      const dedupeKey = this.#docKey(d.id);
+      if (seenDocs.has(dedupeKey)) continue;
+      seenDocs.add(dedupeKey);
+      writtenDocs.push({ tableId, internalId: d.id.internalId });
+    }
+    const writtenKeys = indexUpdates.map((w) => ({ indexId: w.update.indexId, key: w.update.key }));
+    for (const w of indexUpdates) {
+      if (w.update.value.type === "NonClustered") tables.add(encodeStorageTableId(w.update.value.docId.tableNumber));
+    }
+    return { newMaxTs, writtenTables: [...tables], writtenKeys, writtenDocs };
+  }
+};
+
+// src/replica-wiring.ts
+import { keyToPointRange, docKeyToPointRange } from "@helipod/id-codec";
+function startReplicaReactiveTailer(opts) {
+  const { runtime, objectStore, shard, local, consumerId, pollMs } = opts;
+  const interval = pollMs ?? 1e3;
+  const onInvalidation = async (inv) => {
+    runtime.observeTimestamp(inv.newMaxTs);
+    const ranges = [
+      ...inv.writtenKeys.map((k) => keyToPointRange(k.indexId, k.key)),
+      ...inv.writtenDocs.map((d) => docKeyToPointRange(d.tableId, d.internalId))
+    ];
+    const commitTs = Number(inv.newMaxTs);
+    await runtime.handler.notifyWrites({ tables: inv.writtenTables, ranges, commitTs });
+    runtime.notifyExternalCommit({ tables: inv.writtenTables, ranges, commitTs });
+  };
+  const tailer = new ObjectStoreReplicaTailer({ objectStore, shard, local, onInvalidation, pollMs });
+  let lastPublishedSeqno = -1;
+  let timer;
+  let stopped = false;
+  let inflight;
+  async function pump() {
+    if (stopped) return;
+    await tailer.tick();
+    if (stopped) return;
+    if (tailer.appliedSeqno !== lastPublishedSeqno) {
+      await publishConsumerWatermark(objectStore, shard, consumerId, { appliedSeqno: tailer.appliedSeqno });
+      lastPublishedSeqno = tailer.appliedSeqno;
+    }
+  }
+  function armTimer() {
+    if (stopped) return;
+    timer = setTimeout(wake, interval);
+  }
+  function wake() {
+    if (stopped) return;
+    const round = pump().catch((e) => {
+      console.error(`objectstore-substrate: replica reactive tailer wiring pump failed for shard '${shard}'`, e);
+    });
+    inflight = round;
+    void round.finally(() => {
+      if (inflight === round) inflight = void 0;
+      armTimer();
+    });
+  }
+  armTimer();
+  return {
+    async stop() {
+      stopped = true;
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      await inflight;
+      tailer.stop();
+    },
+    __pump: pump
+  };
+}
+export {
+  FencedError,
+  ObjectStoreDocStore,
+  ObjectStoreReplicaTailer,
+  ReshardObjectStoreLiveError,
+  ShardedObjectStoreDocStore,
+  casManifest,
+  compareBigint,
+  compareBytesLex,
+  createGlobals,
+  createManifest,
+  decodeSegment,
+  decodeSnapshot,
+  encodeSegment,
+  encodeSnapshot,
+  ensureGlobals,
+  gcDriver,
+  leaseHeartbeatDriver,
+  mergeSortedAsyncGenerators,
+  publishConsumerWatermark,
+  readConsumerWatermarks,
+  readGlobalFrontier,
+  readGlobals,
+  readManifest,
+  readSnapshot,
+  removeConsumer,
+  reshardObjectStore,
+  segmentKey,
+  snapshotKey,
+  startReplicaReactiveTailer,
+  writeGlobals,
+  writeSnapshot
+};
+//# sourceMappingURL=index.js.map