@helipod/objectstore-substrate 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1114 @@
+import { DocumentLogEntry, IndexWrite, DocStore, CommitUnit, ShardId, SchemaSetupOptions, ConflictStrategy, CommitGuardUnit, InternalDocumentId, LatestDocument, Interval, Order, TimestampRange, PrevRevQuery, ClientVerdictRecord, ClientVerdictWrite } from '@helipod/docstore';
+import { ObjectStore } from '@helipod/objectstore';
+import { JSONValue } from '@helipod/values';
+import { SqliteDocStore } from '@helipod/docstore-sqlite';
+import { Driver } from '@helipod/component';
+import { SerializedKeyRange } from '@helipod/index-key-codec';
+
+/**
+ * The segment codec (Tier 3 Slice 2, design record §5) — a segment is one immutable object
+ * (`s{shard}/seg/{seqno}`) holding a batch's worth of `DocumentLogEntry`/`IndexWrite` rows, JSON-encoded
+ * so it survives any `ObjectStore` byte-string backend unchanged.
+ *
+ * JSON has no native `bigint`/`Uint8Array`, so the wire form tags them explicitly:
+ *   - `bigint` (ts/prev_ts)      → decimal string
+ *   - `Uint8Array` (id bytes, index keys) → base64
+ * A document's own field VALUES (`ResolvedDocument.value`, a `Record<string, Value>`) reuse
+ * `@helipod/values`' existing `convexToJson`/`jsonToConvex` — the same tagged-JSON transport the rest
+ * of the engine already round-trips `Value` (including nested `bigint`/`ArrayBuffer`) through.
+ */
+
+/** One segment's worth of staged rows — the unit `encodeSegment`/`decodeSegment` round-trip. */
+interface SegmentPayload {
+    documents: DocumentLogEntry[];
+    indexUpdates: IndexWrite[];
+}
+/** Encode a segment's rows to bytes (UTF-8 JSON) for `ObjectStore.putImmutable`. */
+declare function encodeSegment(payload: SegmentPayload): Uint8Array;
+/** Decode segment bytes (as read from `ObjectStore.get`) back to `SegmentPayload`. Inverse of
+ *  {@link encodeSegment} — round-trips bigints and byte arrays exactly. */
+declare function decodeSegment(bytes: Uint8Array): SegmentPayload;
+
+/**
+ * Manifest helpers (Tier 3 Slice 2, design record §5/§7) — the per-shard pointer object
+ * (`s{shard}/manifest`) that names the segment chain and the commit frontier. It is the object the
+ * commit path CAS's on (`casPut`), so it is the fencing/linearization point for `ObjectStoreDocStore`.
+ *
+ * `tsCounter` (mirrors `frontierTs` today — Slice 2 has no group-commit-ahead-of-frontier gap yet) is
+ * the MONOTONE field the seam doc calls for: a real `ObjectStore`'s etag is content-derived, so an
+ * A→B→A content sequence could reuse an etag (ABA) — a manifest that never repeats its content (because
+ * this field strictly increases every successful CAS) closes that hole.
+ *
+ * `epoch`/`writerId`/`leaseExpiresAt` (Tier 3 Slice 4, Task 4.2) turn the manifest into the LEASE: an
+ * unowned/fresh manifest has `writerId: ""`, `leaseExpiresAt: "0"`, `epoch: 0`. `ObjectStoreDocStore`'s
+ * `acquire()` CAS's `epoch` upward and stamps `writerId`/`leaseExpiresAt` to claim ownership (the epoch
+ * bump is what FENCES any prior owner's cached etag); `heartbeat()` CAS-renews `leaseExpiresAt` alone.
+ * See `object-doc-store.ts`'s class doc for the full acquire/heartbeat/commit-gating protocol.
+ */
+
+/** The per-shard commit pointer AND lease. `frontierTs`/`tsCounter` are decimal-string bigints (JSON
+ *  has no native bigint) — the highest committed timestamp and the monotone CAS-content counter,
+ *  respectively. `segments` is the `seqno` chain of `s{shard}/seg/{seqno}` objects a bootstrap still
+ *  needs to replay, in order — dense (`[0, 1, 2, …]`) from a fresh manifest, but TRIMMED by
+ *  `snapshot()` (Tier 3 Slice 3, Task 3.3 fix) to only `seqno > snapshotSegBase` once a snapshot
+ *  covers the earlier ones, so this array stays BOUNDED (the post-snapshot tail) rather than growing
+ *  with total commit history. `nextSeqno` (Task 3.3 fix) is the authoritative next-free-segment-seqno
+ *  cursor — it is NOT derivable from `segments` once `segments` is trimmed (a `Math.max(...segments)`
+ *  bootstrap computation both breaks on a trimmed/empty array and throws `RangeError` on a large
+ *  untrimmed one), so it is tracked as its own field and must be read directly by `open()`.
+ *  `snapshotTs`/`snapshotSegBase` (Tier 3 Slice 3, Task 3.2) are optional and set together: the
+ *  latest snapshot's key suffix (`s{shard}/snap/{snapshotTs}`) and the highest segment seqno it
+ *  COVERS — bootstrap restores that snapshot then replays only segments with `seqno >
+ *  snapshotSegBase`. Unset on a fresh manifest (no snapshot taken yet) — full-replay bootstrap.
+ *  `writerId`/`leaseExpiresAt` (Tier 3 Slice 4) are the LEASE: `writerId === ""` means unowned;
+ *  otherwise the lease is live while `now <= Number(leaseExpiresAt)` (both are decimal-string
+ *  ms-epoch, matching the `frontierTs`/`tsCounter` no-native-bigint-in-JSON convention — `now` itself
+ *  is a plain number, not a bigint, so `leaseExpiresAt` is a decimal STRING of a NUMBER, not a bigint,
+ *  purely for the same JSON-round-trip-safety reason). `epoch` (present since Slice 2, now
+ *  load-bearing) is bumped by every successful `acquire()` — the epoch bump is the mechanical fence
+ *  that invalidates a prior owner's cached etag. */
+interface Manifest {
+    epoch: number;
+    frontierTs: string;
+    tsCounter: string;
+    segments: number[];
+    nextSeqno: number;
+    writerId: string;
+    leaseExpiresAt: string;
+    snapshotTs?: string;
+    snapshotSegBase?: number;
+}
+/** Read the shard's current manifest + its etag (for a follow-up `casManifest`), or `null` if the
+ *  shard has never been initialized (no manifest object yet — call `createManifest` first). */
+declare function readManifest(os: ObjectStore, shard: string): Promise<{
+    manifest: Manifest;
+    etag: string;
+} | null>;
+/** Create-only initialization of a shard's manifest (`casPut` with `ifMatch: null`). Throws
+ *  `CasConflict` (via `@helipod/objectstore`'s `isCasConflict`) if the manifest already exists —
+ *  callers racing to initialize the same shard must treat that as "someone else already did it" and
+ *  `readManifest` instead. */
+declare function createManifest(os: ObjectStore, shard: string): Promise<{
+    manifest: Manifest;
+    etag: string;
+}>;
+/** Compare-and-swap the shard's manifest to `next`, conditional on `ifMatch` still being the current
+ *  etag. Throws `CasConflict` (see `isCasConflict`) if another committer's manifest write already moved
+ *  the etag — the caller (the commit path) must treat this as a fence: nothing else may be applied. */
+declare function casManifest(os: ObjectStore, shard: string, next: Manifest, ifMatch: string): Promise<{
+    etag: string;
+}>;
+
+/**
+ * `ObjectStoreDocStore` (Tier 3 Slice 2, design record §4/§6a/§7) — a `DocStore` DECORATOR over a
+ * local `SqliteDocStore` + one shard of an `ObjectStore`. Object storage is the linearization point
+ * (the durable log a second process replays); the local SQLite store is a materialized cache that
+ * must never get ahead of it.
+ *
+ * - Every read/non-commit method is a straight FORWARD to the local store (it already has the
+ *   fully materialized, queryable state — that's the point of local materialization, design §6a).
+ * - `commitWrite`/`commitWriteBatch` are INTERCEPTED and made OBJECT-FIRST: allocate ts from the
+ *   manifest → append an immutable segment → CAS the manifest (the fence) → only on CAS success
+ *   apply the same rows to the local store via the explicit-ts `write(..., "Overwrite")` path (the
+ *   same primitive `open`'s bootstrap and a replica tailer use — no second explicit-ts path).
+ *
+ * Commits serialize under an in-process mutex (`runExclusive`) so the cached `{manifest, etag}` this
+ * instance holds is always read-then-CAS'd by exactly one commit at a time — required because the
+ * manifest CAS is optimistic (etag-conditional) but the LOCAL apply that follows it is not: without
+ * the mutex two concurrent `commitWriteBatch` calls from the same process could race the same cached
+ * etag into `casManifest` and (since only one wins) leave the loser's local apply inconsistent with
+ * which segment its ts's actually landed in.
+ *
+ * Any `casManifest` failure (fence OR ambiguous/lost-response) POISONS this instance (whole-branch
+ * review C1): the cached cursor is then untrustworthy. `putImmutable` is KEEP-FIRST on every adapter
+ * (fs/memory/s3 — s3 via a create-only `IfNoneMatch: "*"` conditional PUT, Tier 3 Slice 4 review), so a
+ * reused segment seqno can never overwrite a durable, manifest-referenced segment written by someone
+ * else — it silently no-ops and the writer's OWN manifest CAS fails separately on its stale etag. Poison
+ * is therefore not a corruption guard against overwriting live data (there is no such hazard left); it's
+ * the correct response to an untrustworthy cached cursor after any CAS failure. Recovery = re-open
+ * (re-bootstrap).
+ *
+ * OWNERSHIP (Tier 3 Slice 4, Task 4.2): `open()` only MATERIALIZES — it bootstraps `local` from the
+ * bucket (snapshot + tail replay) but claims NO ownership. A writer must additionally `acquire()`
+ * before it may commit; a replica (Slice 5) opens without ever acquiring. `acquire({writerId,
+ * leaseTtlMs, now})` re-reads the manifest fresh, refuses if a DIFFERENT writer's lease is still live,
+ * else catches this instance's local store up to the manifest frontier (`materializeTo` — the same
+ * primitive `open()` bootstraps with) and CAS-bumps `epoch` to claim the lease — the epoch bump is
+ * what fences any prior owner's cached etag. `heartbeat({now, leaseTtlMs})` CAS-renews
+ * `leaseExpiresAt` alone (epoch/writerId unchanged); ANY heartbeat CAS failure means a challenger
+ * fenced this instance — it poisons and throws `FencedError`. `commitWriteBatch` now REQUIRES a held
+ * lease (throws before the poisoned check if `acquire()` was never called) and additionally asserts
+ * its cached epoch still matches the held epoch before every CAS — defense in depth against serving a
+ * commit after having been silently fenced.
+ *
+ * SLICE-2 BOUNDARIES — follow-ups the failover/replica slices (S4/S5) MUST NOT inherit silently:
+ * - **Globals + client-verdict receipts are LOCAL-ONLY** (`writeGlobal*`/`recordClientVerdict`/… forward
+ *   to the local store; they never enter the segment log). So a from-scratch bootstrap over object
+ *   storage alone does NOT reconstruct them: `createEmbeddedRuntime` would mint a NEW `deploymentId`
+ *   (flipping every outbox client to `known:false`) and lose dedup receipts (effectively-once →
+ *   at-least-once). Single-node with a PERSISTENT local SQLite file survives restarts fine; but the
+ *   failover slice (a fresh node materializing from the bucket) MUST persist `deploymentId` (e.g. in
+ *   the manifest) and address receipt durability before it can claim "byte-identical from object
+ *   storage alone" for engine bookkeeping. Effectively-once itself → the manifest idempotency window (deferred).
+ * - **Fence/failure paths are exercised at the substrate level only on `objectstore-fs`** (keep-first
+ *   `putImmutable`, same as every adapter now — `objectstore-s3` was fixed to keep-first too, Tier 3
+ *   Slice 4 review, closing the overwrite hazard this note used to describe). The `objectstore-s3`
+ *   package's OWN conformance suite (run against real MinIO under `HELIPOD_OBJECTSTORE_S3=1`) proves
+ *   the keep-first invariant on S3 directly; a MinIO-gated fence/failure variant AT THIS SUBSTRATE LEVEL
+ *   (as opposed to a bare adapter conformance check) is still a nice-to-have for the failover slice, not
+ *   a correctness gap — the adapter-level guarantee is what the fence's safety actually rests on.
+ */
+
+/** Exported (Tier 3 Slice 5, Task 5.1) so `replica-tailer.ts` can pull the SAME segment objects this
+ *  class's own commit/`materializeTo` path writes/reads, without duplicating the key format. */
+declare function segmentKey(shard: string, seqno: number): string;
+interface ObjectStoreDocStoreOpts {
+    objectStore: ObjectStore;
+    shard: string;
+    local: SqliteDocStore;
+}
+declare class ObjectStoreDocStore implements DocStore {
+    #private;
+    private readonly objectStore;
+    private readonly shard;
+    private readonly 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`. */
+    private 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. */
+    private 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). */
+    private poisoned;
+    /** 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. */
+    private held;
+    /** Serializes `commitWrite`/`commitWriteBatch` — see class doc. */
+    private mutex;
+    /** Committed segments since the last successful snapshot (or since `open`) — `maybeSnapshot`'s
+     *  cadence trigger. Reset to 0 only on a successful `snapshot()`. */
+    private committedSegmentsSinceSnapshot;
+    private constructor();
+    /**
+     * 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 open(opts: ObjectStoreDocStoreOpts): Promise<ObjectStoreDocStore>;
+    /**
+     * 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.
+     */
+    private materializeTo;
+    /**
+     * 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).
+     */
+    acquire(opts: {
+        writerId: string;
+        leaseTtlMs: number;
+        now: number;
+    }): Promise<{
+        acquired: true;
+    } | {
+        acquired: false;
+        heldBy: string;
+        expiresAt: number;
+    }>;
+    /**
+     * 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.
+     */
+    heartbeat(opts: {
+        now: number;
+        leaseTtlMs: number;
+    }): Promise<void>;
+    /** 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(): void;
+    /**
+     * 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.
+     */
+    relinquish(): Promise<void>;
+    /** Chain `fn` onto the mutex so commits from this process serialize (see class doc). */
+    private runExclusive;
+    commitWriteBatch(units: readonly CommitUnit[], shardId?: ShardId): Promise<bigint[]>;
+    commitWrite(documents: readonly DocumentLogEntry[], indexUpdates: readonly IndexWrite[], shardId?: ShardId, opts?: {
+        meta?: Record<string, string>;
+    }): Promise<bigint>;
+    /**
+     * 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).
+     */
+    snapshot(): Promise<void>;
+    /** 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. */
+    maybeSnapshot(): Promise<void>;
+    /**
+     * 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).
+     */
+    gc(): Promise<{
+        deletedSegments: number;
+        deletedSnapshots: number;
+    }>;
+    setupSchema(options?: SchemaSetupOptions): Promise<void>;
+    write(documents: readonly DocumentLogEntry[], indexUpdates: readonly IndexWrite[], conflictStrategy: ConflictStrategy, shardId?: ShardId): Promise<void>;
+    /** 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(): Promise<{
+        documents: DocumentLogEntry[];
+        indexUpdates: IndexWrite[];
+    }>;
+    addCommitGuard(guard: (q: any, units: readonly CommitGuardUnit[], shardId: ShardId) => void | Promise<void>): () => void;
+    get(id: InternalDocumentId, readTimestamp?: bigint): Promise<LatestDocument | null>;
+    index_scan(indexId: string, tableId: string, readTimestamp: bigint, interval: Interval, order: Order, limit?: number): AsyncGenerator<readonly [Uint8Array, LatestDocument]>;
+    load_documents(range: TimestampRange, order: Order, limit?: number): AsyncGenerator<DocumentLogEntry>;
+    previous_revisions(queries: readonly PrevRevQuery[]): Promise<Map<string, DocumentLogEntry>>;
+    scan(tableId: string, readTimestamp?: bigint): Promise<LatestDocument[]>;
+    count(tableId: string): Promise<number>;
+    maxTimestamp(): Promise<bigint>;
+    getGlobal(key: string): Promise<JSONValue | null>;
+    writeGlobal(key: string, value: JSONValue): Promise<void>;
+    writeGlobalIfAbsent(key: string, value: JSONValue): Promise<boolean>;
+    getClientVerdict(identity: string, clientId: string, seq: number): Promise<ClientVerdictRecord | null>;
+    getClientFloor(identity: string, clientId: string): Promise<number | null>;
+    recordClientVerdict(identity: string, clientId: string, seq: number, record: ClientVerdictWrite): Promise<void>;
+    updateClientVerdictValue(identity: string, clientId: string, seq: number, value: JSONValue): Promise<void>;
+    pruneClientMutations(identity: string, clientId: string, opts: {
+        ackedThrough?: number;
+        ttlBeforeMs?: number;
+    }): Promise<{
+        prunedThroughSeq: number;
+    }>;
+    sweepExpiredClientMutations(beforeMs: number): Promise<{
+        deletedCount: number;
+    }>;
+    close(): void | Promise<void>;
+}
+
+/**
+ * `ShardedObjectStoreDocStore` — object-storage multi-shard SINGLE-NODE write scale-out: one node
+ * owns ALL N object-storage lanes (each a full `ObjectStoreDocStore`, design record §5's `s{shard}/…`
+ * physically independent prefix) and this class composes them behind ONE `DocStore` the engine's
+ * `ShardedTransactor` talks to exactly as it talks to a single store today.
+ *
+ * OWNERSHIP: this class is a pure DocStore-shaped decorator over an already-open, already-`acquire()`d
+ * `Map<ShardId, ObjectStoreDocStore>` — it does NOT open/acquire/heartbeat/gc the lanes itself (the
+ * boot layer, `packages/cli/src/boot.ts`, drives each lane's lease/heartbeat/gc independently, so a
+ * fence on one lane doesn't wait on another lane's cadence). This mirrors `ObjectStoreDocStore`'s own
+ * "everything else forwards" shape, just fanned out over N lanes instead of one.
+ *
+ * ROUTING CONTRACT (confirmed against `packages/transactor/src/shard-writer.ts`): `commitWrite`/
+ * `commitWriteBatch`/`write` are ALWAYS called by the transactor with an explicit `shardId` (the
+ * `ShardedTransactor`'s own `ShardWriter.shardId`) — that is the ONE input that tells this class which
+ * lane owns the commit. `get`/`scan`/`index_scan`/`load_documents`/`previous_revisions` are NEVER
+ * called with a shard id (a query spans every shard) — so every read method here MERGES across every
+ * lane. This is the asymmetry the whole class is built around: writes route by an explicit key, reads
+ * fan out and merge.
+ *
+ * READ-MERGE CORRECTNESS NOTE (the caveat worth flagging to a reviewer): `get`/`scan`/
+ * `previous_revisions` probe EVERY lane (a doc lives in exactly one lane — the one-doc-one-ring
+ * invariant B2a established — but the `DocStore` interface gives `get(id)` no shard hint, since the
+ * shard key is a document FIELD, not derivable from the internal id alone). This is O(N lanes) local
+ * SQLite calls per read — correct, and cheap in practice (every lane is a FULLY MATERIALIZED local
+ * store per design §6a, so this is N in-process SQLite lookups, never network I/O), but is a real cost
+ * that grows with shard count. A future optimization could route `get`/`previous_revisions` directly
+ * when a caller happens to know the shard; out of scope here.
+ */
+
+interface ShardedObjectStoreDocStoreOpts {
+    /** The lane this class routes deployment-level bookkeeping to (globals, client-verdict receipts) —
+     *  a single source of truth rather than N independently-diverging copies. Unset -> `"default"`
+     *  (`DEFAULT_SHARD`), matching the un-sharded-table convention every other routing seam in the repo
+     *  uses (`shard.ts`'s `DEFAULT_SHARD`, `jump-hash.ts`'s slot 0). MUST be a key present in `lanes`. */
+    defaultShard?: ShardId;
+}
+declare class ShardedObjectStoreDocStore implements DocStore {
+    private readonly lanes;
+    private readonly defaultShard;
+    constructor(lanes: ReadonlyMap<ShardId, DocStore>, opts?: ShardedObjectStoreDocStoreOpts);
+    private lane;
+    private laneList;
+    setupSchema(options?: SchemaSetupOptions): Promise<void>;
+    write(documents: readonly DocumentLogEntry[], indexUpdates: readonly IndexWrite[], conflictStrategy: ConflictStrategy, shardId?: ShardId): Promise<void>;
+    commitWrite(documents: readonly DocumentLogEntry[], indexUpdates: readonly IndexWrite[], shardId?: ShardId, opts?: {
+        meta?: Record<string, string>;
+    }): Promise<bigint>;
+    commitWriteBatch(units: readonly CommitUnit[], shardId?: ShardId): Promise<bigint[]>;
+    /**
+     * 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: (q: any, units: readonly CommitGuardUnit[], shardId: ShardId) => void | Promise<void>): () => void;
+    get(id: InternalDocumentId, readTimestamp?: bigint): Promise<LatestDocument | null>;
+    index_scan(indexId: string, tableId: string, readTimestamp: bigint, interval: Interval, order: Order, limit?: number): AsyncGenerator<readonly [Uint8Array, LatestDocument]>;
+    load_documents(range: TimestampRange, order: Order, limit?: number): AsyncGenerator<DocumentLogEntry>;
+    previous_revisions(queries: readonly PrevRevQuery[]): Promise<Map<string, DocumentLogEntry>>;
+    scan(tableId: string, readTimestamp?: bigint): Promise<LatestDocument[]>;
+    count(tableId: string): Promise<number>;
+    maxTimestamp(): Promise<bigint>;
+    getGlobal(key: string): Promise<JSONValue | null>;
+    writeGlobal(key: string, value: JSONValue): Promise<void>;
+    writeGlobalIfAbsent(key: string, value: JSONValue): Promise<boolean>;
+    getClientVerdict(identity: string, clientId: string, seq: number): Promise<ClientVerdictRecord | null>;
+    getClientFloor(identity: string, clientId: string): Promise<number | null>;
+    recordClientVerdict(identity: string, clientId: string, seq: number, record: ClientVerdictWrite): Promise<void>;
+    updateClientVerdictValue(identity: string, clientId: string, seq: number, value: JSONValue): Promise<void>;
+    pruneClientMutations(identity: string, clientId: string, opts: {
+        ackedThrough?: number;
+        ttlBeforeMs?: number;
+    }): Promise<{
+        prunedThroughSeq: number;
+    }>;
+    sweepExpiredClientMutations(beforeMs: number): Promise<{
+        deletedCount: number;
+    }>;
+    close(): Promise<void>;
+}
+
+/**
+ * A generic k-way merge over N already-sorted `AsyncGenerator`s, used by
+ * `ShardedObjectStoreDocStore` to merge each lane's own `index_scan`/`load_documents` stream into
+ * ONE globally-ordered stream without ever buffering a whole lane into memory.
+ *
+ * Each source generator MUST already yield in the SAME order this merge is told to produce (the
+ * caller — `ShardedObjectStoreDocStore` — gets this for free: it calls every lane's `index_scan`/
+ * `load_documents` with the identical `order` argument, and each lane's own store already honors
+ * that ordering, exactly as `SqliteDocStore.index_scan`'s SQL `ORDER BY i.key ASC|DESC` does). This
+ * function does not itself sort anything — it only ever compares the CURRENT head of each source.
+ */
+/** Byte-lexicographic comparison — matches SQLite's own BLOB ordering (unsigned byte-wise), which
+ *  `SqliteDocStore.index_scan`'s `ORDER BY i.key` already relies on, so merging N lanes' index-scan
+ *  streams by this comparator reproduces the SAME total order a single, unsharded store would. */
+declare function compareBytesLex(a: Uint8Array, b: Uint8Array): number;
+/** bigint comparison — for merging `load_documents`' `ts`-ordered streams. */
+declare function compareBigint(a: bigint, b: bigint): number;
+/**
+ * Merge `sources` (each already sorted per `keyCompare`/`order`) into one sorted `AsyncGenerator`,
+ * stopping after `limit` yielded items (or exhausting every source when `limit` is undefined).
+ *
+ * Algorithm: prime every source's first item, then repeatedly pick the source whose current head
+ * compares smallest (`order: "asc"`) or largest (`order: "desc"`) per `keyCompare`, yield it, and
+ * advance ONLY that source. This is the textbook k-way merge — O(log k) per step with a heap, but a
+ * linear scan over k sources here (k = shard count, expected small — tens at most) is simpler and
+ * fast enough; a heap can replace the linear scan later if shard counts ever grow large.
+ *
+ * `limit`, when set, is a HARD cap on the number of items this generator yields — matching every
+ * `DocStore.index_scan`/`load_documents` implementation's own `limit` contract. Passing the SAME
+ * `limit` down to each individual source (as `ShardedObjectStoreDocStore` does) is always a safe
+ * over-fetch: the merged output can never need MORE than `limit` items from any single source, since
+ * the whole merged output is capped at `limit`.
+ *
+ * On early exit (limit reached, or the caller stops iterating this generator before exhaustion — a
+ * `for await` `break`), every NOT-YET-EXHAUSTED source generator is `.return()`'d so it can release
+ * whatever resources it's holding (mirroring how a single-store `AsyncGenerator` is expected to clean
+ * up on an early `.return()` call — the same contract, just fanned out over N sources).
+ */
+declare function mergeSortedAsyncGenerators<T>(sources: readonly AsyncGenerator<T>[], keyCompare: (a: T, b: T) => number, order: "asc" | "desc", limit?: number): AsyncGenerator<T>;
+
+/**
+ * Offline object-storage reshard (`docs/superpowers/plans/2026-02-20-objectstore-reshard.md`).
+ *
+ * Changes a STOPPED object-storage deployment's shard count N→M. Unlike the fleet reshard (logical lanes
+ * over one shared store → moves no rows), object-storage lanes each have their own physical log, so a doc
+ * whose lane changes (`shardIdForKeyValue(doc[shardKey], N) ≠ …M`) has its current state PHYSICALLY MOVED
+ * between lane logs. The operation:
+ *   1. GATE — refuse if any source lane has a live lease (an online reshard is out of scope).
+ *   2. MATERIALIZE every source lane's current state into memory (`dumpCurrentState`).
+ *   3. RE-PARTITION each doc by `shardIdForKeyValue(doc[table.shardKey], M)` (a doc's table with no
+ *      shardKey → the "default" lane), routing each live index entry to the same lane as its doc.
+ *   4. REWRITE — delete all objects for every lane in source∪target, then write each target lane fresh
+ *      (open empty → acquire → commit its re-partitioned docs+index → relinquish).
+ *   5. Set `globals.numShards = M` LAST — the linearization point.
+ *
+ * CRASH-SAFETY, honest: object storage has no cross-object transaction, so step 4 is a NON-ATOMIC full
+ * rewrite. A crash mid-rewrite leaves the bucket partially rewritten and is NOT resumable — the contract
+ * is OFFLINE, against a BACKED-UP bucket, don't interrupt. (The whole current state is read into memory
+ * in step 2 first, so the destructive window is as short as possible and never races the read.)
+ */
+
+/** Thrown when reshard is asked to run against a deployment that still has a live lease on any lane. */
+declare class ReshardObjectStoreLiveError extends Error {
+    constructor(message: string);
+}
+interface ReshardObjectStoreOpts {
+    objectStore: ObjectStore;
+    /** The target shard count (M ≥ 1). */
+    toShards: number;
+    /** Wall-clock ms (caller-supplied — the substrate holds no ambient clock). Used only for the live-lease
+     *  gate and the transient lease `acquire` while writing each fresh lane. */
+    now: number;
+    /** The table's shard key field (`schema.ts` `.shardKey(field)`), or null when the table isn't sharded.
+     *  The reshard's ONLY schema dependency — injected so the core needs no schema loader (the CLI wires the
+     *  composed catalog's `getTableByNumber(n)?.shardKey`). */
+    shardKeyFor: (tableNumber: number) => string | null;
+    /** Mint a throwaway local `SqliteDocStore` (`:memory:`) for materialization + each fresh lane's commit —
+     *  injected so the substrate stays adapter-agnostic. */
+    makeLocal: () => SqliteDocStore;
+}
+interface ReshardObjectStoreResult {
+    fromShards: number;
+    toShards: number;
+    /** Docs whose owning lane changed (physically moved between lane logs). */
+    movedDocs: number;
+    /** Doc count landed in each target lane. */
+    perLaneCounts: Record<string, number>;
+}
+declare function reshardObjectStore(opts: ReshardObjectStoreOpts): Promise<ReshardObjectStoreResult>;
+
+/**
+ * Fleet globals (Tier 3 Slice 4, Task 4.1, design record §5 layout / carried note I1) — a persist-once,
+ * bucket-root `globals` object carrying the deployment's identity (`deploymentId`, `numShards`). A fresh
+ * node materializing from the bucket must ADOPT this existing identity rather than mint a new one — a
+ * re-minted `deploymentId` would flip every outbox client to `known:false`. Mirrors `manifest.ts`'s
+ * create-only-via-`casPut` + JSON-encode/decode shape, but for a single bucket-wide key instead of a
+ * per-shard one.
+ */
+
+/** The deployment-wide identity every node adopts on open. `numShards` is recorded once at deployment
+ *  creation (Task 4.3 composes `numShards` independent per-shard lanes over the same bucket). */
+interface FleetGlobals {
+    deploymentId: string;
+    numShards: number;
+}
+/** Read the bucket's fleet globals, or `null` if no node has created them yet. */
+declare function readGlobals(os: ObjectStore): Promise<FleetGlobals | null>;
+/** Create-only initialization of the bucket's fleet globals (`casPut` with `ifMatch: null`). Throws
+ *  `CasConflict` (see `isCasConflict`) if another node already wrote them — callers racing to initialize
+ *  the same bucket must treat that as "someone else already did it" and `readGlobals` instead (this is
+ *  exactly what `ensureGlobals` does below). */
+declare function createGlobals(os: ObjectStore, globals: FleetGlobals): Promise<FleetGlobals>;
+/** Adopt-on-open: read the bucket's existing fleet globals and return them if present — NEVER overwrite
+ *  an already-established `deploymentId`/`numShards`. Only when the bucket has no globals yet does this
+ *  create them (create-only). Two nodes racing to initialize a fresh bucket both call this concurrently:
+ *  the `casPut` one-winner property means exactly one `createGlobals` lands; the loser's `CasConflict` is
+ *  caught here and resolved by re-reading — so both callers converge on the SAME winning globals. */
+/**
+ * SINGLE-DEPLOYMENT-PER-BUCKET (whole-branch review, Finding 3, Task 4.5): Slice 4's object keyspace
+ * is bare (`s{shard}/...`, `globals`) — NOT namespaced per deployment (design record §5's
+ * `deployment/{id}/...` layout is deferred to Slice 5/6). Consequence: this function has no way to
+ * tell "a fresh deployment pointed at an already-occupied bucket" apart from "a node of the SAME
+ * deployment reconnecting" — a misconfigured second deployment aimed at an occupied bucket silently
+ * ADOPTS the first's `deploymentId` (and, if it differs, its `numShards` too) rather than erroring.
+ * This is a documented boundary, not a bug: fix it by giving each deployment its own bucket/prefix
+ * until key-namespacing lands.
+ */
+declare function ensureGlobals(os: ObjectStore, globals: FleetGlobals): Promise<FleetGlobals>;
+/**
+ * OVERWRITE the bucket's globals (create if absent). Unlike `ensureGlobals` (adopt-if-present), this
+ * REPLACES the value — used by the offline reshard tool to set the new `numShards` as the linearization
+ * point of a completed reshard. Read the current etag (or null if absent) then `casPut` against it; a
+ * `CasConflict` (a concurrent writer moved the globals) is re-tried a few times. Reshard runs against a
+ * STOPPED deployment, so contention here is not expected — the retry is belt-and-braces.
+ */
+declare function writeGlobals(os: ObjectStore, globals: FleetGlobals): Promise<void>;
+
+/**
+ * Thrown when `ObjectStoreDocStore`'s manifest CAS loses the race — this writer's cached etag no
+ * longer matches the shard's `s{shard}/manifest` object, meaning some other committer's write
+ * already advanced it. The manifest CAS IS the fence for this substrate (design record §4/§7):
+ * unlike `@helipod/fleet`'s Postgres-epoch fence (`FencedError` on a zero-row epoch-predicated
+ * UPDATE, see `ee/packages/fleet/src/fenced-error.ts`), here the fence is the object store's own
+ * conditional-write primitive (`CasConflict` on `casPut`) rather than a database row.
+ *
+ * This package deliberately does NOT import `@helipod/fleet`'s `FencedError` — the object-storage
+ * substrate is an ALTERNATIVE single-shard store to fleet's Postgres store, not a consumer of it, and
+ * the whole-arc plan keeps this package leaf-dependency-free of `ee/packages/fleet`. A later
+ * multi-shard/failover slice over this substrate is expected to unify the two error types (or at
+ * least their self-demote handling) once fleet-style writer promotion/relinquish lands here too.
+ *
+ * Same retry contract as fleet's: the transactor only OCC-retries `OccConflictError`. `FencedError`
+ * is any other error as far as the transactor is concerned, so it propagates uncaught and is NEVER
+ * retried — a fenced writer must stop (its cached manifest state is stale), not blindly resend the
+ * same commit against a manifest that has already moved on.
+ */
+declare class FencedError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * The object-storage writer's lease-heartbeat driver (Tier 3 Slice 6, Task 6.2) — a recurring
+ * `Driver` (the same seam `@helipod/scheduler`/`@helipod/triggers`/`storageReaper`/
+ * `receiptsReaper` run on) that keeps this node's `ObjectStoreDocStore` lease alive by calling
+ * `store.heartbeat({now, leaseTtlMs})` on a fixed cadence, so a long-running writer never lets its
+ * lease lapse just because nobody happened to commit recently.
+ *
+ * Mirrors `receiptsReaper`'s (`packages/receipts/src/reaper.ts`) single-timer shape — `start`
+ * captures `ctx` and calls `wake()`, `wake()` fires the tick fire-and-forget and (on the SUCCESS/
+ * transient-failure paths only, see below) re-arms via `.finally`-equivalent branching, `stop()`
+ * sets a `stopped` guard before clearing the timer.
+ *
+ * THE CRITICAL DIFFERENCE FROM EVERY OTHER DRIVER IN THIS CODEBASE: a heartbeat's `FencedError`
+ * does not mean "retry later" — it means this node has DEFINITIVELY LOST the lease (some other
+ * writer's `acquire()` already bumped the manifest epoch past this instance's, per
+ * `ObjectStoreDocStore.heartbeat`'s doc comment) and `store` is now `poisoned`: every further
+ * `commitWriteBatch` on it will throw immediately anyway. Silently re-arming and retrying would
+ * just keep failing forever while the caller believes the node is healthy. So on `FencedError` this
+ * driver does NOT re-arm — it logs a loud, unambiguous fatal and calls `opts.onFenced?.(e)`, which
+ * the CLI wires to trigger graceful node shutdown (a fenced writer MUST stop serving writes, never
+ * keep accepting them against a store that will reject every one). Every OTHER error (a transient
+ * object-store blip — a timeout, a 5xx, a network blip) is NOT a fence: the lease may still be alive
+ * until `leaseExpiresAt` elapses, so this driver logs and re-arms, keeping up the renewal attempts —
+ * exactly the resilience `receiptsReaper`'s "one bad pass doesn't kill the reaper" policy embodies,
+ * just with the fence case carved out as the one terminal exception.
+ */
+
+/** The minimal surface this driver needs from `ObjectStoreDocStore` — kept narrow (rather than
+ *  importing the whole class as a type) so a test fake doesn't need to construct a real store. */
+interface HeartbeatableStore {
+    heartbeat(opts: {
+        now: number;
+        leaseTtlMs: number;
+    }): Promise<void>;
+}
+interface LeaseHeartbeatDriverOpts {
+    /** The lease TTL to renew to on every successful heartbeat — must match the TTL `acquire()` was
+     *  called with (the driver does not itself acquire; it only renews an already-held lease). */
+    leaseTtlMs: number;
+    /** How often to attempt a renewal. Should be comfortably shorter than `leaseTtlMs` (the same
+     *  "renew well before expiry" margin every lease-holding system needs) — this driver does not
+     *  enforce a ratio; that's the caller's judgment call. */
+    heartbeatMs: number;
+    /** Called exactly once, synchronously from within `wake()`, the moment a heartbeat surfaces a
+     *  `FencedError` — i.e. this node has lost the lease. The CLI wires this to trigger graceful
+     *  shutdown (stop serving writes). Optional so a test can omit it. */
+    onFenced?: (e: FencedError) => void;
+}
+/** Test/introspection seam mirroring `ReceiptsReaperDriver`'s `__tick`: runs one heartbeat pass and
+ *  awaits its real completion (propagating any error) rather than the timer path's swallow+log. */
+interface LeaseHeartbeatDriver extends Driver {
+    __tick: () => Promise<void>;
+}
+/**
+ * Build the lease-heartbeat driver for `store` (Tier 3 Slice 6, Task 6.2). See the module doc above
+ * for the full fence-vs-transient-error policy.
+ */
+declare function leaseHeartbeatDriver(store: HeartbeatableStore, opts: LeaseHeartbeatDriverOpts): LeaseHeartbeatDriver;
+
+/**
+ * The object-storage writer's periodic reclamation driver (Tier 3 Slice 7, Task 7.2) — a recurring
+ * `Driver` (the same seam `@helipod/scheduler`/`@helipod/triggers`/`storageReaper`/
+ * `receiptsReaper`/`leaseHeartbeatDriver` all run on) that calls `store.gc()` on a fixed cadence, so a
+ * long-running writer's superseded segments/snapshots get reclaimed automatically instead of only on a
+ * manual call.
+ *
+ * Mirrors `receiptsReaper`'s (`packages/receipts/src/reaper.ts`) single-timer shape — `start` arms the
+ * first timer, `wake()` fires the tick fire-and-forget and unconditionally re-arms once it settles
+ * (success or failure), `stop()` sets a `stopped` guard before clearing the timer.
+ *
+ * UNLIKE `leaseHeartbeatDriver` (`./heartbeat-driver.ts`), this driver has NO terminal/fence carve-out:
+ * `gc()` is SELF-FENCING by construction (Task 7.1 — it re-reads the manifest and aborts as a harmless
+ * no-op if this instance no longer owns the current epoch, or was never an owner at all), so a fenced
+ * gc() call simply returns zero counts rather than throwing. Any error `gc()` DOES throw (a transient
+ * object-store blip, or the `poisoned` guard's own throw) is therefore never a "must stop serving
+ * writes now" signal the way a heartbeat's `FencedError` is — it's just "this sweep didn't complete,
+ * try again next cadence." So this driver swallows EVERY error (log + re-arm) and never signals
+ * shutdown, exactly `receiptsReaper`'s "one bad pass doesn't kill the reaper" policy with no exception
+ * carved out.
+ */
+
+/** The minimal surface this driver needs from `ObjectStoreDocStore` — kept narrow (rather than
+ *  importing the whole class as a type) so a test fake doesn't need to construct a real store, same
+ *  spirit as `heartbeat-driver.ts`'s `HeartbeatableStore`. */
+interface GcableStore {
+    gc(): Promise<{
+        deletedSegments: number;
+        deletedSnapshots: number;
+    }>;
+}
+interface GcDriverOpts {
+    /** How often to run a gc() sweep. gc() is best-effort/idempotent and self-fencing, so there's no
+     *  correctness ratio to enforce here (unlike the heartbeat driver's heartbeatMs < leaseTtlMs) — pick
+     *  a cadence that trades reclamation latency against sweep cost (default ~60s, mirroring
+     *  `storageReaper`'s cadence — see the caller's default). */
+    sweepMs: number;
+}
+/** Test/introspection seam mirroring `ReceiptsReaperDriver`'s `__tick`: runs one gc() pass and awaits
+ *  its real completion (propagating any error) rather than the timer path's swallow+log. */
+interface GcDriver extends Driver {
+    __tick: () => Promise<{
+        deletedSegments: number;
+        deletedSnapshots: number;
+    }>;
+}
+/**
+ * Build the periodic gc-driver for `store` (Tier 3 Slice 7, Task 7.2). See the module doc above for
+ * the full swallow-everything/no-fence-carve-out policy.
+ */
+declare function gcDriver(store: GcableStore, opts: GcDriverOpts): GcDriver;
+
+/**
+ * The snapshot codec + object helpers (Tier 3 Slice 3, design record §6b, Task 3.1) — a snapshot
+ * `s{shard}/snap/{ts}` is a materialized image of a shard's CURRENT state at `frontierTs = ts`: the
+ * current (non-tombstone) revision of every live document at its REAL `ts`/`prev_ts`, plus the
+ * current row of every index entry. Produced by `SqliteDocStore.dumpCurrentState()` and restored via
+ * the SAME `write(..., "Overwrite")` primitive segments use — see that method's doc comment.
+ *
+ * The wire codec deliberately REUSES `segment.ts`'s per-row `DocumentLogEntry`/`IndexWrite`
+ * bigint/base64/`Value` tagging (`encodeDocumentLogEntries`/`decodeDocumentLogEntries`/
+ * `encodeIndexWrites`/`decodeIndexWrites`) rather than duplicating it — a snapshot's `documents`/
+ * `indexUpdates` are the exact same row shapes a segment carries; only the envelope (`frontierTs`/
+ * `segBase` instead of none) differs.
+ */
+
+/** A snapshot's payload — the CURRENT state of a shard's local store at `frontierTs`, covering
+ *  every committed segment up to and including seqno `segBase` (bootstrap replays only segments
+ *  with seqno > `segBase` after restoring this). `documents`/`indexUpdates` are the same
+ *  `DocumentLogEntry`/`IndexWrite` rows `SqliteDocStore.dumpCurrentState()` returns — real `ts`/
+ *  `prev_ts`, not renumbered. */
+interface SnapshotPayload {
+    frontierTs: string;
+    segBase: number;
+    documents: DocumentLogEntry[];
+    indexUpdates: IndexWrite[];
+}
+/** Encode a snapshot's payload to bytes (UTF-8 JSON) for `ObjectStore.putImmutable`. */
+declare function encodeSnapshot(payload: SnapshotPayload): Uint8Array;
+/** Decode snapshot bytes (as read from `ObjectStore.get`) back to `SnapshotPayload`. Inverse of
+ *  {@link encodeSnapshot} — round-trips bigints and byte arrays exactly, same as `decodeSegment`. */
+declare function decodeSnapshot(bytes: Uint8Array): SnapshotPayload;
+/** The object key a shard's snapshot at `ts` (a decimal-string `frontierTs`, matching the manifest's
+ *  own string-bigint convention) lives at — `s{shard}/snap/{ts}`, parallel to `segmentKey`'s
+ *  `s{shard}/seg/{seqno}` in `object-doc-store.ts`. */
+declare function snapshotKey(shard: string, ts: string): string;
+/** Write a snapshot object (immutable — one snapshot per `frontierTs`, never overwritten). Callers
+ *  write the snapshot object FIRST, then CAS the manifest to reference it (Task 3.2) — never the
+ *  reverse, so the manifest can never point at an absent snapshot (the same torn-forward discipline
+ *  segments follow). */
+declare function writeSnapshot(os: ObjectStore, shard: string, payload: SnapshotPayload): Promise<void>;
+/** Read + decode a shard's snapshot at `ts`, or `null` if no such snapshot object exists. */
+declare function readSnapshot(os: ObjectStore, shard: string, ts: string): Promise<SnapshotPayload | null>;
+
+/**
+ * Cross-shard frontier (Tier 3 Slice 5, Task 5.1, design record §8) — the object-storage analog of
+ * the shipped fleet `ReplicaTailer.readFrontier`'s `min(shard_leases.frontier_ts)` — but read
+ * straight from each shard's own manifest object instead of a shared Postgres table, since object
+ * storage has no cross-shard row to `min()` over server-side.
+ *
+ * `F = min(manifest.frontierTs)` over every shard in `shards` is the dense prefix the WHOLE fleet has
+ * durably committed: a caller may treat state up to `F` as fully replicated everywhere. Mirrors the
+ * fleet's partial-lease-set guard (`count < numShards` → not-ready): a shard whose manifest doesn't
+ * exist yet (never `open()`'d/initialized) makes the WHOLE frontier `0n`, not merely excluded from the
+ * min — a half-initialized fleet must not let the present shards' min fake readiness.
+ *
+ * Pure read helper: it does not track/assert monotonicity itself (unlike the fleet tailer's own
+ * internal `readFrontier`, which owns a `lastF` cache) — a caller that needs the monotone-assertion
+ * belt-and-braces should track its own last-observed value and compare across calls, mirroring
+ * `ReplicaTailer`'s `lastF` if it wants that defense-in-depth.
+ */
+
+/** `min(frontierTs)` over every shard's manifest — `0n` if any shard's manifest is absent (a
+ *  partial/not-yet-initialized shard set, the same F1×N hole guard the fleet tailer applies). A
+ *  single-shard replica passes `[shard]`; an empty `shards` array also returns `0n` (vacuously
+ *  "nothing is ready" rather than a vacuous `+Infinity`-derived value). */
+declare function readGlobalFrontier(os: ObjectStore, shards: readonly string[]): Promise<bigint>;
+
+/**
+ * `ObjectStoreReplicaTailer` (Tier 3 Slice 5, Task 5.1, design record §7/§8) — the object-storage
+ * analog of the shipped fleet `ReplicaTailer` (`ee/packages/fleet/src/replica-tailer.ts`): polls a
+ * shard's manifest, pulls whatever segments/snapshot it references that this replica hasn't already
+ * applied, materializes them onto a local `SqliteDocStore` via the SAME `write(..., "Overwrite")`
+ * primitive `ObjectStoreDocStore.open()`'s `materializeTo` uses, derives an `AppliedInvalidation` from
+ * the SAME batch it just applied (not a separate query), and advances its watermark only after the
+ * caller's `onInvalidation` sink resolves — mirroring the fleet tailer's tick()/`AppliedInvalidation`/
+ * watermark-after-sink shape (see that file's module doc for the fuller rationale this class carries
+ * over unmodified: verbatim apply, advance-after-sink so a throwing/slow handler can't skip a range).
+ *
+ * DIVERGES from the fleet tailer in exactly the ways the substrate itself diverges from Postgres:
+ *   - No LISTEN/NOTIFY wake — object storage has no such primitive, so this tailer is PURELY poll-
+ *     driven (`start()` arms a `setInterval`; a caller can also drive `tick()` directly, e.g. in tests).
+ *   - No `batchSize` cap — a round always pulls everything between the last applied point and the
+ *     manifest's CURRENT frontier in one pass (a segment is already a bounded unit; there is no
+ *     unbounded single-transaction pull to guard against the way Postgres's per-row `load_documents`
+ *     needed capping).
+ *   - No density assertions — object storage's manifest CAS is itself the fence (Slice 2/4); a
+ *     replica can only ever observe a manifest state that was durably, atomically committed, so
+ *     there is no "torn" row shape to defend against the way Postgres's row-at-a-time replication
+ *     could theoretically skip a write.
+ *   - A SNAPSHOT FALLBACK the fleet tailer has no analog for: object storage's `gc()` can delete a
+ *     segment a lagging replica hasn't pulled yet (there is no `pg_advisory` retention the way a
+ *     logical-replication slot would give Postgres) — see `#materializeRound`'s doc for how a missing
+ *     segment falls back to a snapshot restore instead of failing outright. Task 5.2's watermark-aware
+ *     `gc()` is the production mitigation (never GC below a lagging consumer's watermark); this
+ *     fallback is the correctness backstop for the eventually-consistent object-store window regardless.
+ *
+ * BOOTSTRAP: unlike the fleet tailer (which bootstraps itself via a bounded catch-up loop inside
+ * `start()`), this tailer does NOT bootstrap `local` — the caller is expected to have already
+ * materialized it (typically via `ObjectStoreDocStore.open({objectStore, shard, local})`, or by
+ * simply handing over a bare, empty `SqliteDocStore` and letting this tailer's OWN first `tick()`
+ * perform the full catch-up, since `#materializeRound`'s snapshot-fallback + tail-pull IS the same
+ * algorithm `materializeTo` runs). The tailer discovers where `local` actually stands lazily, on its
+ * first `tick()`, by reading `local.maxTimestamp()` — see `#ensureInitialized`'s doc for why this must
+ * happen lazily (on first tick, not in the constructor) and how it seeds `appliedSeqno` safely. Either
+ * way, the caller MUST have already run `local.setupSchema()` before handing it over (`open()`'s own
+ * first step) — this tailer never creates the schema itself, only applies rows into it.
+ */
+
+/** Mirrors the fleet tailer's `AppliedInvalidation` shape byte-for-byte (see that file's doc for why
+ *  this is a deliberate parallel type, not a shared import — the substrate must not depend on
+ *  `@helipod/fleet`). `newMaxTs` is the ts THROUGH which this round applied — the manifest's
+ *  `frontierTs` at the moment this round finished (see `#tickOnce`'s doc for why that, not a
+ *  row-derived max, is the authoritative value here). */
+interface AppliedInvalidation {
+    newMaxTs: bigint;
+    /** DISTINCT storage-encoded table ids touched, derived from BOTH the applied documents' own ids
+     *  AND any applied index write whose value is a live (`NonClustered`) entry — a `Deleted` index
+     *  entry carries no docId to derive a table from, so it contributes nothing here (its owning
+     *  document's own entry in the SAME round already does). */
+    writtenTables: string[];
+    /** Raw written index keys — point invalidation input, NOT yet point ranges. */
+    writtenKeys: Array<{
+        indexId: string;
+        key: Uint8Array;
+    }>;
+    /** DISTINCT `(tableId, internalId)` pairs written this round, deduped from the applied
+     *  `DocumentLogEntry` rows (one entry per doc regardless of how many revisions accompanied it).
+     *  Point invalidation input for the DOCUMENT keyspace, NOT yet point ranges — same split as
+     *  `writtenKeys` above. */
+    writtenDocs: Array<{
+        tableId: string;
+        internalId: Uint8Array;
+    }>;
+}
+interface ObjectStoreReplicaTailerOptions {
+    objectStore: ObjectStore;
+    shard: string;
+    /** The replica's materialize target. The CALLER is responsible for it existing (typically via
+     *  `ObjectStoreDocStore.open()`'s bootstrap, or a bare fresh `SqliteDocStore` — see the class doc). */
+    local: SqliteDocStore;
+    /** Invoked once per non-empty applied round, AFTER the round has already been written to `local`.
+     *  The watermark only advances after this resolves — a throwing/slow handler must not cause a
+     *  round to be silently skipped on the next tick. */
+    onInvalidation: (inv: AppliedInvalidation) => Promise<void>;
+    /** Wall-clock poll interval for `start()`, in ms. Default 1000. */
+    pollMs?: number;
+}
+/** Poll-driven object-storage replica tailer — see the module doc for the full contract. */
+declare class ObjectStoreReplicaTailer {
+    #private;
+    private readonly objectStore;
+    private readonly shard;
+    private readonly local;
+    private readonly onInvalidation;
+    private readonly 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). */
+    private appliedSeqnoValue;
+    /** The ts through which `local` is known to be caught up. Lazily seeded from
+     *  `local.maxTimestamp()` on the first `tick()` — see `#ensureInitialized`. */
+    private appliedMaxTsValue;
+    private initialized;
+    private 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. */
+    private draining;
+    private readonly waiters;
+    constructor(opts: ObjectStoreReplicaTailerOptions);
+    get appliedSeqno(): number;
+    get appliedMaxTs(): bigint;
+    /** 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(): void;
+    stop(): void;
+    /** 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: bigint, timeoutMs: number): Promise<void>;
+    /** 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. */
+    tick(): Promise<boolean>;
+}
+
+/**
+ * Consumer watermarks (Tier 3 Slice 5, Task 5.2, design record §6c) — a per-shard
+ * `s{shard}/consumers/{id}` object per registered consumer (a replica's `ObjectStoreReplicaTailer`,
+ * keyed by whatever `consumerId` the caller chooses — e.g. a per-`(replica, shard)` id) carrying the
+ * seqno it has durably applied. `ObjectStoreDocStore.gc()` floors its deletion at the SLOWEST
+ * published watermark ON ITS OWN SHARD so it never reclaims a segment a lagging replica still needs
+ * to tail.
+ *
+ * SHARD-SCOPED (Finding 2, whole-branch review): keys were originally bucket-global (`consumers/{id}`),
+ * but `gc()` is per-shard with per-shard seqno spaces (a seqno on shard "0" and the SAME numeric
+ * seqno on shard "1" are unrelated cursors) — a bucket-global watermark set meant a stuck consumer on
+ * ANY shard floored GC on EVERY shard, over-retaining bucket-wide instead of just on its own shard.
+ * Scoping the key prefix to `s{shard}/consumers/{consumerId}` confines that (already-safe,
+ * never-under-retains) over-retention to the shard the lagging consumer is actually on.
+ *
+ * Unlike a segment (`putImmutable`, keep-first-immutable) or the manifest (`casManifest`, the fence
+ * a WRITER contends on), a watermark is a single value that must be OVERWRITABLE as its owning
+ * consumer advances — `putImmutable`'s keep-first semantics (Tier 3 Slice 4 fix) make it unusable
+ * here. This module instead does a plain read-etag-then-`casPut` upsert: `get()` the current etag (or
+ * `null` if the object doesn't exist yet, which makes the `casPut` create-only), then CAS the new
+ * value over it. A watermark is single-writer-per-`(shard, consumerId)` in the intended usage (one
+ * tailer instance publishes its own watermark), so a lost CAS race is expected only from a genuine
+ * concurrent writer under the SAME key (a misconfiguration, or a brief overlap during a consumer's
+ * own restart) — handled with a small bounded retry (re-read, re-CAS) rather than treated as a hard
+ * error on the first conflict.
+ */
+
+/** Upsert `consumerId`'s watermark to `appliedSeqno` on `shard` — overwritable (see module doc), NOT
+ *  `putImmutable`. Retries a handful of times on a lost CAS race (re-reading the current etag each
+ *  time) before giving up loudly; a genuine single-writer-per-`(shard, consumerId)` caller should
+ *  never exhaust this. */
+declare function publishConsumerWatermark(os: ObjectStore, shard: string, consumerId: string, watermark: {
+    appliedSeqno: number;
+}): Promise<void>;
+/** List every consumer registered on `shard` and its published watermark. Order is whatever
+ *  `os.list()` returns (unspecified) — callers that need `min(appliedSeqno)` (GC) reduce over the
+ *  whole set anyway. */
+declare function readConsumerWatermarks(os: ObjectStore, shard: string): Promise<{
+    consumerId: string;
+    appliedSeqno: number;
+}[]>;
+/** Deregister a departing consumer (e.g. a decommissioned replica) on `shard` so it no longer floors
+ *  that shard's GC. */
+declare function removeConsumer(os: ObjectStore, shard: string, consumerId: string): Promise<void>;
+
+/**
+ * `startReplicaReactiveTailer` (Tier 3 Slice 8, Task 8.1, design record §7/§8) — extracts the
+ * reactive-tailer wiring the Slice-5 cross-node E2E (`test/cross-node-reactivity.e2e.test.ts`) built
+ * inline into a reusable production helper: a caller (typically `helipod serve --replica`'s boot
+ * path, Task 8.2) hands over a REPLICA-side runtime + its materialized `local` store + the bucket,
+ * and this helper drives the runtime's reactive fan-out from the writer's committed segments, and
+ * publishes the replica's consumer watermark (so the writer's `gcDriver`, Slice 7, never reclaims a
+ * segment this replica hasn't tailed yet).
+ *
+ * The sink mirrors the Slice-5 E2E's `invalidationSink` — itself mirroring the shipped fleet
+ * `invalidationSink` (`ee/packages/fleet/src/node.ts` ~:1358) — byte-for-byte:
+ *   1. `runtime.observeTimestamp(inv.newMaxTs)` — BEFORE fanning ranges into the sync handler, so the
+ *      query oracle's re-run actually reads the newly-applied rows.
+ *   2. Convert the round's raw `writtenKeys`/`writtenDocs` into point ranges via the canonical
+ *      `keyToPointRange`/`docKeyToPointRange` (`@helipod/id-codec`, Task 8.1's other half of this
+ *      extraction).
+ *   3. `await runtime.handler.notifyWrites(...)` — the live-subscription re-run/re-push path.
+ *   4. `runtime.notifyExternalCommit(...)` — wakes any driver `onCommit` listener (e.g. a composed
+ *      component's own reactive hook) on this replica process.
+ * The sink is REACTIVITY ONLY — it does NOT publish the consumer watermark. `ObjectStoreReplicaTailer`
+ * advances `appliedSeqno` only AFTER `onInvalidation` resolves (the Slice-5 redelivery-safety
+ * discipline: if the sink throws, the next tick must redeliver the identical round), so reading
+ * `tailer.appliedSeqno` FROM INSIDE the sink observes the PRE-advance value (`-1` on the very first
+ * round) — one round stale, and permanently stuck-stale for a replica that goes idle after its last
+ * commit (no further tick ever republishes the true position). Under-reporting is GC-safe (a stale-low
+ * watermark only makes `gc()` over-retain), but stuck-stale defeats the watermark's whole purpose for a
+ * mostly-idle replica. Instead, THIS HELPER owns its own poll loop (`#pump`, below): each pass calls
+ * `tailer.tick()` (which drives the sink above AND THEN advances `appliedSeqno`), and only afterward —
+ * if `appliedSeqno` actually advanced — publishes the accurate POST-advance value. A `__pump()` test
+ * seam (mirroring `gc-driver.ts`'s `__tick`) drives one round deterministically, awaiting completion
+ * and propagating errors, for tests that don't want to wait on a real timer.
+ *
+ * `ReplicaReactiveRuntime` is a deliberately NARROW structural type — only the three members this
+ * sink actually calls — rather than an import of `@helipod/runtime-embedded`'s `EmbeddedRuntime`.
+ * `objectstore-substrate` must not take a dependency on `runtime-embedded` just for this helper's
+ * type signature; the real `EmbeddedRuntime` already satisfies this shape structurally, so the CLI's
+ * boot path (Task 8.2) can pass one straight through with no adapter.
+ */
+
+/** The shape a runtime's reactive tier must expose for this sink to drive it — satisfied
+ *  structurally by `@helipod/runtime-embedded`'s `EmbeddedRuntime` (see module doc). */
+interface ReplicaReactiveRuntime {
+    /** Advances the runtime's own observed timestamp so a re-run oracle sees rows through `ts`. */
+    observeTimestamp(ts: bigint): void;
+    handler: {
+        /** Re-runs/re-pushes every live subscription whose recorded read set intersects `ranges`. */
+        notifyWrites(inv: {
+            tables: string[];
+            ranges: SerializedKeyRange[];
+            commitTs: number;
+        }): Promise<void>;
+    };
+    /** Wakes any driver `onCommit` listener composed into this runtime. */
+    notifyExternalCommit(inv: {
+        tables: string[];
+        ranges: SerializedKeyRange[];
+        commitTs: number;
+    }): void;
+}
+interface StartReplicaReactiveTailerOptions {
+    /** The replica-side runtime whose reactive tier this helper drives. */
+    runtime: ReplicaReactiveRuntime;
+    objectStore: ObjectStore;
+    shard: string;
+    /** The SAME `local` the replica's runtime/store reads from — the tailer applies the writer's
+     *  segments directly onto it. */
+    local: SqliteDocStore;
+    /** This replica's consumer-watermark identity (shard-scoped key `s{shard}/consumers/{id}`, Slice
+     *  5 Task 5.2) — a per-process id the caller mints. */
+    consumerId: string;
+    /** Wall-clock poll interval, ms. Default (`ObjectStoreReplicaTailer`'s own default): 1000. */
+    pollMs?: number;
+}
+/** Returned by `startReplicaReactiveTailer` — see that function's doc. */
+interface ReplicaReactiveTailerHandle {
+    /** Halts this helper's own poll loop (idempotent, no re-arm after). Does NOT deregister the
+     *  consumer watermark (`removeConsumer` is a boot-path/shutdown concern for the caller, not this
+     *  helper — see Task 8.2). Defensively also calls `tailer.stop()`, though this helper never calls
+     *  `tailer.start()` itself (no self-timer of the tailer's own to clear). */
+    stop(): Promise<void>;
+    /** Test/introspection seam mirroring `gc-driver.ts`'s `__tick`: runs exactly one
+     *  `tailer.tick()` + the conditional watermark publish, awaiting real completion and propagating
+     *  any error (unlike the timer path, which swallows + logs + re-arms). Lets a test drive
+     *  deterministic rounds without waiting on a real timer. */
+    __pump(): Promise<void>;
+}
+/**
+ * Builds an `ObjectStoreReplicaTailer` over `opts.local`/`opts.objectStore`/`opts.shard` whose
+ * `onInvalidation` sink drives `opts.runtime`'s reactive fan-out, then arms this helper's OWN poll
+ * loop (see the module doc for why the watermark publish must live HERE, post-`tick()`, rather than
+ * inside the sink). `stop()` halts the loop.
+ */
+declare function startReplicaReactiveTailer(opts: StartReplicaReactiveTailerOptions): ReplicaReactiveTailerHandle;
+
+export { type AppliedInvalidation, FencedError, type FleetGlobals, type GcDriver, type GcDriverOpts, type GcableStore, type HeartbeatableStore, type LeaseHeartbeatDriver, type LeaseHeartbeatDriverOpts, type Manifest, ObjectStoreDocStore, type ObjectStoreDocStoreOpts, ObjectStoreReplicaTailer, type ObjectStoreReplicaTailerOptions, type ReplicaReactiveRuntime, type ReplicaReactiveTailerHandle, ReshardObjectStoreLiveError, type ReshardObjectStoreOpts, type ReshardObjectStoreResult, type SegmentPayload, ShardedObjectStoreDocStore, type ShardedObjectStoreDocStoreOpts, type SnapshotPayload, type StartReplicaReactiveTailerOptions, 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 };