@helipod/fleet 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1777 @@
+import { PgClient, PgQuerier, PostgresDocStore, NodePgClient } from '@helipod/docstore-postgres';
+import { ShardId } from '@helipod/id-codec';
+export { docKeyToPointRange, keyToPointRange } from '@helipod/id-codec';
+import { JSONValue } from '@helipod/values';
+import { EmbeddedWriteFanoutAdapter, EmbeddedWriteFanoutPayload, FanoutListener, WriteRouter, ClientReplay, EmbeddedRuntime } from '@helipod/runtime-embedded';
+import { InternalDocumentId, DocStore, SchemaSetupOptions, DocumentLogEntry, IndexWrite, ConflictStrategy, ShardId as ShardId$1, CommitUnit, CommitGuardUnit, LatestDocument, Interval, Order, TimestampRange, PrevRevQuery, ClientVerdictRecord, ClientVerdictWrite } from '@helipod/docstore';
+import { SqliteDocStore } from '@helipod/docstore-sqlite';
+
+/**
+ * Non-blocking per-shard commit-mutex seam (see `Transactor.tryRunExclusiveOnShard` /
+ * `EmbeddedRuntime.tryRunExclusiveOnShard`): run `fn` under shard `shardId`'s commit mutex if that
+ * shard is IDLE right now (returns `true`), else skip without running it (returns `false`). "Idle"
+ * means BOTH the commit mutex is free AND no group-commit batch is staged/flushing — Fleet B4's group
+ * commit runs the flush I/O OFF the mutex, so mutex-freedom alone no longer implies "nothing in
+ * flight". `closeIdleFrontiers` takes this so each idle shard's frontier bump is mutually exclusive
+ * with that shard's own commits AND with any mid-flush batch — the fix for the frontier-inversion race
+ * (an idle-closer publishing a frontier ahead of an in-flight commit's or batch's not-yet-landed
+ * rows). The writer owns both the closer and every shard's commits, so this single-process check is
+ * airtight; cross-node closing of a held shard is impossible by design (only the lease holder closes
+ * its own held shards).
+ */
+type TryRunExclusiveOnShard = (shardId: ShardId, fn: () => Promise<void>) => Promise<boolean>;
+/** The current fleet writer lease: which epoch is live and which node holds it. */
+interface LeaseState {
+    epoch: bigint;
+    writerUrl: string;
+    /** The row's fenced-frontier high-water mark at acquisition time (Fleet B3). On an `ON CONFLICT`
+     *  re-acquire the upsert leaves `frontier_ts` untouched, so this returns the value an INTERIM owner
+     *  advanced it to while this node didn't hold the shard — the exact floor the caller feeds to
+     *  `runtime.observeWriteTimestamp` so a re-acquired shard's write snapshot never sits stale. */
+    frontierTs: bigint;
+}
+/** `LeaseManager.read()`'s full row — every `shard_leases` column (Fenced Frontier B1, D2). The
+ *  extra columns beyond `LeaseState` are consumed by the D4 eviction/D5 tailer-frontier work; this
+ *  class only writes them (frontier_ts/prev_ts advance via the commit-guard SQL installed in
+ *  `node.ts`, never through this class directly), so they're returned loosely typed for now. */
+interface LeaseRow extends LeaseState {
+    writerAppName: string | null;
+    /** Raw Postgres value for the TIMESTAMPTZ column (a `Date` under `NodePgClient`, ISO-ish string
+     *  under PGlite) — not a `LeaseManager` client's job to interpret; a heartbeat/fence caller only
+     *  cares about row-count effects, not the wall-clock value. */
+    expiresAt: unknown;
+    frontierTs: bigint;
+    prevTs: bigint;
+}
+interface LeaseManagerOptions {
+    /** URL this node advertises as the writer, recorded into shard_leases on acquire. */
+    advertiseUrl: string;
+    /** This node's Postgres `application_name` (see `fleetApplicationName`), recorded on acquire so
+     *  a D4 eviction fencer can `pg_terminate_backend` the exact wedged holder's connection. */
+    applicationName?: string;
+    /** Interval between tryAcquire() attempts inside acquireLoop(). Default 2000ms. */
+    retryMs?: number;
+    /** How long a fresh acquisition/heartbeat extends `expires_at` by, in ms. Default 15000ms. The
+     *  whole failover clock scales with this: a wedged writer's lease expires this long after its last
+     *  heartbeat, so a follower's eviction can't fire before then. Shortened by
+     *  `HELIPOD_FLEET_LEASE_TTL_MS` for the wedged-writer E2E (and available to operators as tuning);
+     *  the LeaseMonitor's probe cadence is derived from it so a live writer always renews in time. */
+    ttlMs?: number;
+}
+/** Effectively-once forwarding (Fleet B3, D3): the `fleet_idempotency.value_json` cap. A recorded
+ *  mutation result larger than this is NOT stored — the row keeps `value_json = NULL` and
+ *  `oversized = true` instead, so a replay reports `valueMissing: true` rather than growing this
+ *  control table unboundedly on a large mutation return value. The WRITE itself is unaffected
+ *  either way (this cap only governs the best-effort RESULT-VALUE cache, not the commit). */
+declare const IDEMPOTENCY_VALUE_CAP_BYTES: number;
+/** A `fleet_idempotency` row read back for replay (Fleet B3, D3). `hasValue` distinguishes a
+ *  genuinely-recorded value (including a mutation that legitimately returned JSON `null`, which is
+ *  still stored as the TEXT `"null"`) from `value_json` being SQL NULL — the crash-window
+ *  (commit landed, the post-run value UPDATE never ran) and the oversized-cap cases both leave
+ *  `value_json` SQL NULL, and both replay as `valueMissing: true` uniformly. */
+interface IdempotencyReplay {
+    commitTs: bigint;
+    hasValue: boolean;
+    value: JSONValue | null;
+    oversized: boolean;
+}
+/**
+ * Coordinates the single-writer lease across a fleet of nodes sharing one Postgres database.
+ * The advisory lock (PgClient.tryAcquireWriterLock) is the FAST-PATH mutual-exclusion primitive;
+ * `shard_leases` is the fencing token + discovery row + frontier chain — one row per shard (B1:
+ * only `'default'`) so any node (including read replicas forwarding writes) can find the current
+ * writer's URL/epoch, and so `PostgresDocStore`'s installed commit guard can verify — inside every
+ * commit transaction — that the writer holding the advisory lock is STILL the epoch on file (see
+ * `node.ts`'s `installCommitGuard`). `epoch` bumps on every acquisition (D2); `frontier_ts`/
+ * `prev_ts` are the durable-commit chain the guard advances (D3) — this class never writes them
+ * itself beyond seeding them to 0 on first creation.
+ *
+ * Liveness: the LeaseMonitor's periodic probe IS `heartbeat()` (see `node.ts`) — one round-trip
+ * serves liveness-probe + TTL maintenance + fence verification, per D2. `heartbeat()` returning 0
+ * rows means this node's epoch has been superseded (fenced) even though its connection is still
+ * alive — a DEFINITIVE loss, distinct from the probe-miss tolerance used for transient blips.
+ */
+declare class LeaseManager {
+    private readonly client;
+    /** This node's advertised URL, recorded onto `shard_leases`/`fleet_nodes`. Public so the balancer
+     *  can use it as this node's rendezvous identity (`ShardLeaseBalancer.myUrl`) without threading it
+     *  separately through `startFleetNode`. */
+    readonly advertiseUrl: string;
+    private readonly applicationName;
+    private readonly retryMs;
+    /** The lease TTL in ms this manager stamps onto `expires_at`. Public so the LeaseMonitor can
+     *  derive its probe cadence from the SAME knob (see `startFleetNode`) — a live writer must renew
+     *  well within the TTL. */
+    readonly ttlMs: number;
+    /** `ttlMs` as a whole-ms integer, ready to interpolate into the `interval '<n> milliseconds'` SQL
+     *  below. Integer-coerced (never a fraction/NaN) so the interpolation can't produce invalid SQL. */
+    private readonly ttlMsSql;
+    private timer;
+    private stopped;
+    /** Per-shard epoch map: `shardId → the epoch this node most recently acquired for it`. B1 tracked
+     *  ONE `lastEpoch` (default shard only); B2a's writer holds N shards, each fenced against its own
+     *  epoch, so the commit guard/heartbeat/idle-closer look up `currentEpoch(shardId)`. Updated on
+     *  every successful per-shard `tryAcquire(shardId)` (including re-promotion's epoch bumps) so the
+     *  guard always fences against the CURRENT epoch, not a boot snapshot. A shard absent from the
+     *  map is one this node has never acquired. */
+    private readonly lastEpochByShard;
+    constructor(client: PgClient, opts: LeaseManagerOptions);
+    /**
+     * Idempotent DDL: creates shard_leases if it doesn't already exist, and — when `shardIds` is
+     * non-empty — pre-seeds a row for every shard in the list (Fleet B3, D4: the concurrent-boot
+     * count-gate fix, reversing B2a's "no pre-seeding" call).
+     *
+     * B2a originally left this deliberately EMPTY (no pre-seeded rows): a bare `frontier_ts = 0` row
+     * created at DDL time, on a database that already held documents (a pre-`--fleet` upgrade), would
+     * be momentarily visible at `frontier_ts = 0` to a concurrently-booting sync node — `count(*) = N`
+     * AND `min(frontier_ts) = 0` would fake-report ready with an EMPTY replica (the F1×N hole,
+     * recurring ×N). That is why row existence used to be tied to a REAL, frontier-seeded acquisition
+     * (`tryAcquire`) rather than to `setup()`.
+     *
+     * The reversal here is safe ONLY because the seed now travels WITH the row: `documentsExist` (the
+     * caller's `documentsTableExists` probe, run BEFORE calling this) selects the exact same
+     * `frontierSeedExpr` fragment `tryAcquire` uses — `0` on a fresh database (no `documents` table
+     * yet: correct, there is no history to protect against), or `(SELECT COALESCE(MAX(ts), 0) FROM
+     * documents)` on an upgrade (`documents` already exists: correct, the row is born at the true
+     * high-water mark, never momentarily at 0). A pre-seeded row is created UNACQUIRED — `epoch = 0`,
+     * `writer_url = NULL`, already-expired `expires_at` — so the FIRST real `tryAcquire` still lands on
+     * its `ON CONFLICT` branch and bumps `epoch` from 0 to 1, byte-identical to a fresh INSERT's
+     * `epoch = 1`; every existing epoch/ownership assertion in the test suite is unaffected. Idempotent
+     * (`ON CONFLICT (shard_id) DO NOTHING`): a row already created by a peer's concurrent `setup()` or
+     * by a real acquisition is left untouched — this can only ever RAISE a row into existence, never
+     * clobber one. With every shard row present immediately, the tailer's `count(*) < NUM_SHARDS →
+     * not-ready` gate is satisfied the instant `setup()` returns — a concurrent multi-writer boot no
+     * longer stalls waiting for a writer to finish its acquire-all pass. See `node.ts`'s
+     * `prepareFleetNode` for the `documentsTableExists` probe + call site, and `replica-tailer.ts`'s
+     * `readFrontier` for the count gate.
+     */
+    /** Run one DDL statement, swallowing the concurrent-boot duplicate-object race family
+     *  (23505 unique_violation / 42P07 duplicate_table / 42710 duplicate_object — the third face
+     *  is "type <table> already exists", the table's composite rowtype, which is what two nodes
+     *  racing CREATE TABLE IF NOT EXISTS actually surface). The statement's objective — the
+     *  object exists — is achieved when any of these fires; anything else propagates. Mirrors
+     *  docstore-postgres setupSchema's discipline; added when the SIMULTANEOUS multi-writer boot
+     *  E2E caught the unguarded race here (Plan A's extra boot DDL widened the window). */
+    private ddl;
+    setup(shardIds?: readonly ShardId[], documentsExist?: boolean): Promise<void>;
+    /**
+     * The `frontier_ts` seed SQL fragment shared by `setup()`'s row pre-seed and `tryAcquire()`'s
+     * first-creation INSERT (Fleet B3, D4 — the one place this reasoning is written down): `0` when the
+     * caller has verified `documents` does not exist yet (a fresh database — no history to protect
+     * against), else `(SELECT COALESCE(MAX(ts), 0) FROM documents)` (an upgrade — the row is born at the
+     * store's true high-water mark, never momentarily visible below it). Both call sites gate this on
+     * the SAME `documentsTableExists` probe (`node.ts`), so a row is never seeded incorrectly regardless
+     * of which of the two code paths creates it first.
+     */
+    private frontierSeedExpr;
+    /**
+     * Upsert this node's `fleet_nodes` presence row (B2b, D3), extending `expires_at` by the lease TTL.
+     * Called at boot (BEFORE the writer-election `tryAcquire`, so a losing node is already visible when
+     * it boots sync) and on every balancer beat / writer probe — the node's liveness signal now. A node
+     * whose process dies stops heartbeating; its row expires after the TTL and it drops out of every
+     * survivor's `liveNodes()`, re-converging the rendezvous assignment. `epoch` increments per beat —
+     * carried only for observability/debugging (which incarnation of a node the row belongs to); the
+     * live-set membership check keys off `expires_at`, not `epoch`.
+     */
+    heartbeatPresence(): Promise<void>;
+    /**
+     * The live fleet node set (B2b, D3): distinct unexpired `fleet_nodes` advertise URLs, UNION the live
+     * `shard_leases` writer URLs (belt-and-braces — a writer whose presence heartbeat momentarily lapsed
+     * but whose shard lease is still live is unambiguously alive). Every node computes rendezvous over
+     * this set, so they all derive the same shard→owner assignment. Expiry is `expires_at >= now()` per
+     * the DB's OWN clock, authoritative against host clock skew.
+     */
+    liveNodes(): Promise<string[]>;
+    /**
+     * Per-shard ownership snapshot for the balancer (B2b, D3): for each EXISTING `shard_leases` row, its
+     * `writer_url` (null = orphaned) and whether it has expired per the DB clock. A shard with no row is
+     * simply absent from the map — the balancer treats an absent shard as acquirable (never created, or
+     * fully reaped), the same as an orphaned one. Read-only; the balancer decides acquire/release from it.
+     */
+    readShardOwnership(): Promise<Map<ShardId, {
+        writerUrl: string | null;
+        expired: boolean;
+    }>>;
+    /**
+     * Self-fence a shard this node currently holds, for a GRACEFUL balancer release (B2b, D3): bump the
+     * epoch (so this node's own subsequent commit/heartbeat on the now-stale epoch fences cleanly),
+     * clear `writer_url` (so the shard reads as orphaned and its rightful rendezvous owner acquires it),
+     * and GREATEST-bump `frontier_ts` from the shared sequence (so F never regresses across the handoff).
+     * Predicated on this node's currently-held epoch — a silent no-op if the shard is already fenced/
+     * relinquished (`currentEpoch === null`). The caller runs this only when the shard is fully IDLE —
+     * `runtime.tryRunExclusiveOnShard` grants the mutex only if no commit holds it AND no group-commit
+     * batch is staged/flushing (Fleet B4), so no in-flight commit's OR batch's frontier write races the
+     * GREATEST-bump here; the release is deferred a beat if the shard is busy rather than fencing
+     * mid-flush (see `releaseShard` in `node.ts`). A mutation that begins mid-execute after the fence
+     * simply hits `FencedError` at its own commit (OCC-retryable, the forwarder re-routes the retry to
+     * the new owner). Mirrors `evictExpired`'s frontier-bump SQL, but unconditional on expiry (this is a
+     * voluntary handoff, not an eviction of a wedged peer).
+     */
+    selfFence(shardId: ShardId): Promise<void>;
+    /**
+     * The epoch this node most recently acquired for `shardId` (via `tryAcquire`), or `null` if it
+     * never has. Read live — not a boot-time snapshot — by the commit guard and the heartbeat probe,
+     * so a re-promotion's epoch bump (another `tryAcquire` call) is picked up automatically with no
+     * extra threading between `prepareFleetNode`/`startFleetNode`/`promoteFleetNode`. Defaults to the
+     * default shard so B1 call sites (`currentEpoch()`) are unchanged.
+     */
+    currentEpoch(shardId?: ShardId): bigint | null;
+    /** The (shard, epoch) pairs this node currently holds — the input to the batched heartbeat,
+     *  all-rows seed, and idle-shard closer (all fence per-row against the epoch on file). A snapshot
+     *  of the live per-shard epoch map, so it reflects any re-promotion's epoch bumps. */
+    heldPairs(): Array<{
+        shardId: ShardId;
+        epoch: bigint;
+    }>;
+    /**
+     * Drop `shardId` from this node's held-epoch map (Fenced Frontier B2b, D2 — per-shard relinquish).
+     * After this call `currentEpoch(shardId)` returns `null`, so:
+     *  - the commit guard's "no acquired epoch" branch fences any straggler commit on `shardId`
+     *    cleanly (rather than a stale epoch happening to still match a row some other node has since
+     *    re-fenced and moved on from);
+     *  - `heldPairs()` (and therefore `heartbeatAll()`/`closeIdleFrontiers()`/`seedFrontierAll()`) stop
+     *    including this shard.
+     * Idempotent: forgetting a shard this node doesn't currently hold is a silent no-op — the
+     * relinquish dispatcher (`node.ts`) relies on exactly this for ITS OWN idempotency, via
+     * `currentEpoch(shardId) === null` as its "already relinquished" check. Deliberately does NOT touch
+     * the `shard_leases` ROW — only the caller's advisory-lock release (`PgClient.releaseShardLock`) and
+     * this in-memory forget are relinquish's job; the row itself was already epoch-bumped by whoever
+     * fenced this node (or will lapse via TTL), and a future re-acquire (`tryAcquire`) is a fresh INSERT/
+     * ON CONFLICT UPDATE regardless of what this map remembers.
+     */
+    forgetShard(shardId: ShardId): void;
+    /**
+     * One non-blocking attempt: takes the advisory lock (fast path); on success, runs the fencing
+     * upsert against `shard_leases` (bumping `epoch`, recording this node's URL/app-name, extending
+     * `expires_at`) and returns the new state. On failure to take the lock, returns null.
+     * `prev_ts` is seeded to 0 on first creation only, and `frontier_ts` to either 0 or the store's
+     * current `MAX(ts)` (see `seedFrontierFromDocuments`) — an `ON CONFLICT` re-acquisition (including
+     * promotion) leaves BOTH untouched, so the durable-commit chain survives across epochs (D3 depends
+     * on this: frontier must never reset just because the writer changed).
+     *
+     * `seedFrontierFromDocuments` (the F1×N residual-window fix): when a row is FIRST created, seed its
+     * `frontier_ts` to `MAX(ts)` from the `documents` log inside the same INSERT — atomically, so the
+     * row is NEVER momentarily visible at `frontier_ts = 0` on a pre-loaded store (which would let a
+     * concurrently-booting sync node pass its `count == N ∧ min-F` ready gate with an empty replica).
+     * Pass `true` only when the `documents` table is known to exist (post-`setupSchema`, or a pre-loaded
+     * store) — the caller guards this; `false` (the default, and the only safe value pre-DDL on a fresh
+     * database) creates the row at `frontier_ts = 0`, which is correct precisely because a fresh store
+     * holds no data. `seedFrontierAll` remains the idempotent belt-and-braces second pass.
+     */
+    tryAcquire(shardId?: ShardId, slot?: number, seedFrontierFromDocuments?: boolean): Promise<LeaseState | null>;
+    /**
+     * Extend `expires_at` for this node's `epoch` — the LeaseMonitor's periodic probe (D2: one
+     * round-trip serves liveness-probe + TTL maintenance + fence verification). Returns the number
+     * of rows updated: 1 = still this node's epoch (TTL extended), 0 = fenced — some other node has
+     * bumped the epoch (a D4 eviction) and this node no longer holds the lease, even though its
+     * connection never dropped. Callers (see `node.ts`) treat 0 as definitive lease loss.
+     */
+    heartbeat(epoch: bigint, shardId?: ShardId): Promise<number>;
+    /**
+     * Batched heartbeat over EVERY (shard, epoch) pair this node holds — one UPDATE per beat (B2a):
+     * the writer holds N leases and must renew all of them in a single round-trip, not N. Returns
+     * `{ updated, expected, fencedShardIds }` where `expected` is how many pairs this node believes it
+     * holds, `updated` is how many rows actually matched, and `fencedShardIds` (B2b, D2) is PRECISELY
+     * which held shards did NOT match — diffing the `RETURNING shard_id` rows against the held set —
+     * so the caller can relinquish exactly those shards rather than treat `updated < expected` as an
+     * undifferentiated whole-node signal. `updated < expected` (equivalently `fencedShardIds.length >
+     * 0`) means at least one shard's epoch was superseded; `fencedShardIds` is always `[]` when this
+     * node holds nothing (never a writer) — see the early return. The `(shard_id, epoch) IN ((..),(..))`
+     * tuple form fences per row.
+     */
+    heartbeatAll(): Promise<{
+        updated: number;
+        expected: number;
+        fencedShardIds: ShardId[];
+    }>;
+    /**
+     * Read-only expiry check: does the lease row exist AND is `expires_at` in the past, per the DB's
+     * OWN clock? Used as the acquire loop's per-tick pre-gate before the heavier `evictExpired`
+     * transaction — a healthy (live) lease must NOT make every follower take the row lock every tick and
+     * contend with the writer's commit guard, so the common case stays a single cheap SELECT. The
+     * comparison is `now()` in SQL (not `read().expiresAt` in JS) so it's authoritative against clock
+     * skew between a follower's host and Postgres.
+     */
+    isExpired(shardId?: ShardId): Promise<boolean>;
+    /**
+     * Fencing-first eviction of an EXPIRED lease (Fenced Frontier B1, D4). Bumps `epoch` (fencing the
+     * wedged holder — its next commit guard / heartbeat now matches 0 rows), clears `writer_url`/
+     * `writer_app_name`, and advances `frontier_ts`, all predicated on the lease actually being
+     * expired. Returns `{ fenced: true, oldAppName }` capturing the evicted holder's `writer_app_name`
+     * (so the acquire loop can `pg_terminate_backend` its lingering connection); `{ fenced: false }`
+     * when the row is live (no-op) OR the row lock couldn't be taken within `lock_timeout` (retry next
+     * tick — never throws that to the loop).
+     *
+     * Why a `SELECT ... FOR UPDATE` then a separate `UPDATE`, NOT a single `UPDATE ... RETURNING (SELECT
+     * writer_app_name FROM cte)`: on Postgres, RETURNING — and the inlined CTE subquery it evaluates —
+     * sees the NEW (already-nulled) row, so a single statement reads back NULL for the old app name
+     * (verified on PGlite; a `MATERIALIZED` CTE with its own `FOR UPDATE` instead collides with the
+     * same-statement UPDATE's row lock and yields zero rows). The two-statement form captures the old
+     * value cleanly, and the `FOR UPDATE` takes the very row lock a concurrent commit-guard UPDATE
+     * contends on — serializing eviction against an in-flight commit. That contention is single-
+     * connection-untestable and covered E2E only (see the test header).
+     */
+    evictExpired(shardId?: ShardId): Promise<{
+        fenced: boolean;
+        oldAppName: string | null;
+    }>;
+    /**
+     * Kill the evicted holder's lingering Postgres backend(s) by `application_name` so its session-level
+     * advisory writer lock is released and the NEXT acquire tick can win. Matches the fleet E2E's query
+     * shape exactly, including the `pid <> pg_backend_pid()` self-exclusion (the fencer never terminates
+     * its own connection — its app name differs anyway, so this is belt-and-braces). Best-effort: if the
+     * backend is already gone, the query simply affects zero rows.
+     */
+    terminateBackend(appName: string): Promise<void>;
+    /**
+     * A tick observed the advisory-lock try FAIL — another backend still holds the writer lock. If the
+     * lease has ALSO expired, that holder is wedged (its heartbeat stopped) while its connection lingers
+     * (a hung/paused process still owns the advisory lock, so no other node can acquire). Fence it
+     * (`evictExpired` bumps the epoch) then terminate its backend to release the lock; the next tick's
+     * advisory try then succeeds → normal acquisition → promotion. No-op when the lease is still live.
+     */
+    private maybeEvictWedged;
+    /** Loop tryAcquire() every retryMs until it succeeds, then invoke onAcquired once. stop() cancels.
+     *  On a tick where the advisory try fails AND the lease has expired, the wedged holder is fenced +
+     *  its backend terminated (`maybeEvictWedged`) so a later tick can take over. */
+    acquireLoop(onAcquired: (s: LeaseState) => void): void;
+    /** Cancels any pending acquireLoop() retry. */
+    stop(): void;
+    /**
+     * F1 fix (Fenced Frontier B1 whole-branch review, BLOCKER): seed `frontier_ts` up to at least
+     * `maxTs` — the writer-BOOT step that closes the "pre-loaded database" hole. `tryAcquire()` only
+     * seeds `frontier_ts` to 0 on the row's FIRST creation (see above); a single-node Postgres `serve`
+     * that accumulates real data BEFORE `--fleet` is ever turned on has no `shard_leases` row at all,
+     * so the first `tryAcquire()` after enabling `--fleet` creates one at `frontier_ts=0` even though
+     * the store already holds history. Because the tailer targets `F=frontier_ts` (not
+     * `primary.maxTimestamp()`, see `replica-tailer.ts`'s D5), a fresh sync node's ready gate
+     * (`wm=0 < target=0`) is then a silent no-op — it reports ready with an EMPTY replica while the
+     * primary holds everything. Callers must invoke this at WRITER BOOT, after this node's own
+     * `setupSchema()` has definitely run (the `documents` table this reads may not exist before
+     * that — see `prepareFleetNode`/`startFleetNode`'s boot ordering) and BEFORE the node is reported
+     * ready; a later promotion does NOT need to call this — by then `frontier_ts` is already live,
+     * tracking every commit via the guard installed by `installCommitGuard`.
+     *
+     * `GREATEST` makes this a no-op on an already-live fleet (frontier already tracks every commit)
+     * and on re-acquisition — never regresses `frontier_ts`. Epoch-fenced like every other
+     * `shard_leases` write: a stale `epoch` here (this node lost the writer race to someone else
+     * between its `tryAcquire()` and this call) affects 0 rows rather than clobbering the new
+     * writer's state — that writer's own commit guard is the source of truth for `frontier_ts` going
+     * forward regardless. Deliberately does NOT touch `prev_ts`: this is a seed of the high-water
+     * mark, not a commit, so there is no new "previous commit" to record — the next REAL commit's
+     * guard sets `prev_ts := frontier_ts` (now the seeded value) exactly as it always does.
+     */
+    seedFrontier(epoch: bigint, maxTs: bigint, shardId?: ShardId): Promise<void>;
+    /**
+     * All-rows frontier seed (B2a — the F1×N fix): seed EVERY shard this node holds up to `maxTs` in
+     * ONE batched, per-row-epoch-fenced UPDATE, run at writer boot BEFORE the node reports ready. The
+     * same reasoning as single-shard `seedFrontier` applies to every row at once: any future commit on
+     * any shard takes a later `nextval`, so seeding all held frontiers to the store's current max can
+     * never over-shoot a real commit, and `GREATEST` keeps it a no-op on an already-live fleet.
+     * Epoch-fenced per pair (`(shard_id, epoch) IN (...)`), so a shard this node lost between acquiring
+     * it and this call is simply skipped rather than clobbered. See `node.ts`'s writer boot.
+     */
+    seedFrontierAll(maxTs: bigint): Promise<void>;
+    /**
+     * Per-shard idle-shard frontier closing (B2a, D5 — needed the moment N>1: an idle shard pins the
+     * fleet's `F = min(frontier_ts)`). Allocate a single fresh `nextval` `N` from the shared
+     * `helipod_ts` sequence per beat, then for EACH held shard advance its frontier up to `N` —
+     * `UPDATE ... SET frontier_ts = GREATEST(frontier_ts, $N) WHERE shard_id=$s AND epoch=$e AND
+     * frontier_ts < $N` — but run each shard's UPDATE UNDER THAT SHARD'S COMMIT MUTEX
+     * (`runExclusiveOnShard`), skipping any shard currently mid-commit (mutex busy → left for the next
+     * beat). Returns the `nextval` used (the ceiling this beat closed idle shards up to).
+     *
+     * Why skip-if-busy, not the old bare batched UPDATE (the frontier-inversion fix): the commit
+     * guard writes `frontier_ts := commitTs` for a commit that drew its ts `T` from the SAME sequence,
+     * *inside* the commit transaction — which runs under the shard's commit mutex (single-commit) or at
+     * FLUSH time for a group-commit batch (Fleet B4). If the closer drew `N > T` and bare-wrote
+     * `frontier_ts = N` while that commit's/batch's rows had not yet landed, a tailer could read `F ≥
+     * N`, pull `(watermark, N]`, and MISS `T`'s rows when they land afterward (silent replica miss), or
+     * the guard's later write of `T` would trip a frontier-regression assert. `runExclusiveOnShard`
+     * treats a shard as available only when it is fully IDLE — mutex free AND no staged/flushing
+     * group-commit batch (`ShardWriter.hasInFlightWork()`): group commit runs the flush OFF the mutex,
+     * so a mid-flush batch (ts's already drawn, rows not yet landed) reads BUSY even though the mutex is
+     * free, and is skipped for the next beat. Given that, the closer and that shard's commits are
+     * mutually exclusive on this (single, writer-owned) node: any commit/batch STARTED before the draw
+     * either holds the mutex or is staged/flushing → skipped this beat; any commit/batch that STARTS
+     * after the closer's `nextval` draws its `T` at commit/flush time, AFTER `N`, so `T > N` and
+     * `GREATEST` keeps `frontier_ts ≥ N` with no regression and nothing in-flight ever sits below `N`.
+     * Cross-node closing of a held shard is impossible by design (only
+     * the lease holder closes its own held shards; orphan bumping via `evictExpired` targets
+     * writer-less rows, where no commit can be in flight). Epoch-fenced per pair. No-op (returns the
+     * allocated ts anyway) when this node holds nothing.
+     */
+    closeIdleFrontiers(runExclusiveOnShard: TryRunExclusiveOnShard): Promise<bigint>;
+    /**
+     * Orphan frontier bumping (B2b, D4): advance the frontier of every WRITER-LESS shard row
+     * (`writer_url IS NULL`) that lags `ceiling`, so an unassigned/relinquished/expired shard never
+     * pins the fleet's `F = min(frontier_ts)` below the live commit position. Runs on the WRITER beat
+     * alongside `closeIdleFrontiers` (which only ever touches THIS node's OWN held rows via
+     * `heldPairs()` and so structurally cannot un-pin a shard nobody holds).
+     *
+     * Safe with NO commit mutex, unlike `closeIdleFrontiers`: a writer-less shard has no in-flight
+     * commit by construction — its last writer was fenced (epoch-bumped, `writer_url` nulled) BEFORE
+     * the row became orphaned, so nothing can be mid-commit writing `frontier_ts` on it. The `UPDATE`'s
+     * own row lock serializes any two writers racing this bump, and `GREATEST` + `frontier_ts < ceiling`
+     * keep it monotone regardless. Reuses the SAME `ceiling` (one `nextval` per beat) the idle closer
+     * drew, so a beat costs one sequence draw, not two.
+     */
+    bumpOrphanFrontiers(ceiling: bigint): Promise<void>;
+    /** Reads the current lease row for `shardId` (discovery for forwarding, plus the full fencing/
+     *  frontier state); null if none exists yet. Defaults to the default shard (B1 call sites). */
+    read(shardId?: ShardId): Promise<LeaseRow | null>;
+    /** All shard rows' `(shard_id, frontier_ts)` — the fleet-wide frontier picture the writer's
+     *  frontier-lag monitor reads to compute `min(frontier_ts)` + which shard is pinning it (D5's
+     *  health observability). Ordered by frontier ascending so `rows[0]` is the pinning shard. */
+    readAllFrontiers(): Promise<Array<{
+        shardId: ShardId;
+        frontierTs: bigint;
+    }>>;
+    /**
+     * Read back `key`'s `fleet_idempotency` row for a replay decision (Fleet B3, D3), or `null` if no
+     * such key has ever committed (a genuine miss — proceed to run). Called by `packages/cli`'s
+     * `/_fleet/run` handler BOTH before running (the SELECT-first check) and after catching a
+     * unique_violation on this table (the concurrent-duplicate race's loser re-selecting the
+     * winner's row). See `IdempotencyReplay` for what `hasValue`/`oversized` distinguish.
+     */
+    lookupIdempotency(key: string): Promise<IdempotencyReplay | null>;
+    /**
+     * Best-effort post-run recording of a forwarded mutation's return VALUE onto its already-committed
+     * `fleet_idempotency` row (Fleet B3, D3) — the value isn't known inside the commit transaction (the
+     * guard only sees `commitTs`), so this runs AFTER `runtime.run`/`runAction`/`runSystem` returns,
+     * from `packages/cli`'s `/_fleet/run` handler. Over `IDEMPOTENCY_VALUE_CAP_BYTES` → `value_json`
+     * stays/goes NULL and `oversized = true` instead of storing it (a replay then reports
+     * `valueMissing: true`, same as the crash-window case where this UPDATE never ran at all). A
+     * missing row (no matching `key` — e.g. a no-op mutation that staged nothing, so the guard never
+     * ran) silently affects 0 rows; the caller doesn't need to check for that itself.
+     */
+    recordIdempotencyValue(key: string, value: JSONValue): Promise<void>;
+    /**
+     * Reclaim `fleet_idempotency` rows older than the TTL (Fleet B3, D3) — a cheap indexed (PK-only
+     * table, no index needed at this scale) delete run on the balancer beat of every WRITER-ish node
+     * (see `ShardLeaseBalancerDeps.sweepIdempotency` / `node.ts`'s wiring). A retry arriving after a
+     * row has been swept simply re-executes (documented boundary — retries are seconds-scale, the
+     * sweep window is 1h).
+     */
+    sweepIdempotency(): Promise<void>;
+    /**
+     * Build a `(shard_id, epoch) IN ((...),(...))` VALUES-list clause + its flat params array for a
+     * batched per-row-fenced statement, with placeholder numbers starting AFTER `offset` positional
+     * params the caller already consumed (e.g. a leading `$1 = maxTs`). Returns `{ clause, params }`
+     * where `params` is `[shardA, epochA, shardB, epochB, …]` in placeholder order.
+     */
+    private tupleInClause;
+}
+
+/**
+ * Fleet writer liveness monitor (Task 4, C4). Runs ONLY while a node is the writer. Its job: notice
+ * when this node has lost its exclusive writer lease and exit the process so it can rejoin the fleet
+ * as a fresh sync node (exit-and-rejoin) — rather than lingering as a zombie writer that believes it
+ * still owns the lock while some other node has taken over.
+ *
+ * Three independent loss signals feed it:
+ *
+ *  - `connectionLost()` — DEFINITIVE. The advisory lock lives on `NodePgClient`'s single pinned
+ *    connection, which never reconnects (see `NodePgClient.ensure()`); if that connection closes or
+ *    errors, the session-level `pg_advisory_lock` is released by Postgres the instant the backend
+ *    goes away. So a closed pinned connection == lease definitely lost → exit immediately.
+ *
+ *  - `fenced()` — DEFINITIVE (Fenced Frontier B1, D2/D3). The connection is still alive, but this
+ *    node's epoch has been superseded — either the heartbeat probe found 0 rows for `(shard_id,
+ *    epoch)`, or an epoch-fenced commit guard's UPDATE matched 0 rows. Both mean some OTHER node
+ *    now holds the lease, so — exactly like `connectionLost()` — this bypasses the probe-miss
+ *    tolerance below (which exists only for transient/ambiguous blips; a fenced epoch never is)
+ *    and exits immediately.
+ *
+ *  - `probe()` misses — a BACKSTOP for a silently-wedged connection that isn't emitting error/end
+ *    events (e.g. a half-open TCP connection). The probe is a caller-supplied liveness round-trip
+ *    (`() => client.query("SELECT 1")`); it must NEVER be `pg_try_advisory_lock` — that is re-entrant
+ *    on the session already holding the lock and would leak a lock count on every probe. We tolerate
+ *    `maxMisses` consecutive failures (transient blips) and exit on the NEXT one; any success resets
+ *    the counter. Each probe is itself bounded by `probeTimeoutMs` (default `probeMs`) via
+ *    `Promise.race` — a silently-wedged connection (e.g. a half-open TCP socket) can leave
+ *    `SELECT 1` hanging forever with no error/end event; without a per-probe timeout `inFlight`
+ *    would stay true and every subsequent tick would early-return, so misses would never accrue and
+ *    this exact backstop would never fire. A timed-out probe counts as a miss; if the underlying
+ *    query later settles anyway, that late settlement is discarded (`Promise.race` only ever acts on
+ *    whichever of the probe/timeout settles first) — no reset, no double-count. `inFlight` still
+ *    clears once the race settles, so the next tick starts its own fresh attempt regardless of what
+ *    the abandoned probe call eventually does.
+ *
+ * `onExit` is injected: production passes `(reason) => { console.error(...); process.exit(1); }`;
+ * tests pass a spy. It fires AT MOST ONCE — the first of (connectionLost, probe-exhaustion) wins,
+ * and `stop()` (graceful shutdown / promotion hand-off) halts everything so nothing fires after.
+ */
+interface LeaseMonitorDeps {
+    /** Liveness round-trip against the pinned writer connection. MUST be a plain query (e.g.
+     *  `SELECT 1`), NEVER `pg_try_advisory_lock` (re-entrant → leaks a lock count per probe). */
+    probe: () => Promise<void>;
+    /** Fired at most once when the lease is deemed lost. Production: `console.error` + `process.exit(1)`. */
+    onExit: (reason: string) => void;
+    /** Interval between probes. Default 5000ms. */
+    probeMs?: number;
+    /** Consecutive probe failures tolerated before exit — the NEXT (maxMisses+1-th) miss exits. Default 3. */
+    maxMisses?: number;
+    /** Per-probe timeout — a probe that hasn't settled by this point counts as a miss (the wedged
+     *  connection is abandoned, not awaited further). Default `probeMs`. */
+    probeTimeoutMs?: number;
+}
+declare class LeaseMonitor {
+    private readonly probe;
+    private readonly onExit;
+    private readonly probeMs;
+    private readonly maxMisses;
+    private readonly probeTimeoutMs;
+    private timer;
+    private misses;
+    private inFlight;
+    private exited;
+    private stopped;
+    constructor(deps: LeaseMonitorDeps);
+    /** Begin probing every `probeMs`. Idempotent; a no-op once stopped or after exit. */
+    start(): void;
+    private tick;
+    private recordMiss;
+    /** DEFINITIVE lease loss (pinned connection closed/errored) → exit immediately. */
+    connectionLost(): void;
+    /** DEFINITIVE lease loss (epoch superseded — heartbeat or commit guard found 0 rows for this
+     *  node's epoch) → exit immediately, mirroring `connectionLost()`. Idempotent/at-most-once via
+     *  the same `fireExit` guard — safe to call from both the heartbeat probe and a commit guard. */
+    fenced(reason?: string): void;
+    private fireExit;
+    /** Halt all probing and disarm exit — graceful shutdown or promotion hand-off. */
+    stop(): void;
+    private clearTimer;
+}
+
+/**
+ * Thrown when this node's epoch has been superseded by another writer (Fenced Frontier B1, D2/D3).
+ * Two sources:
+ *
+ *   - `LeaseManager.heartbeat(epoch)` finds zero rows matching `(shard_id, epoch)` — some other
+ *     node has fenced this one (bumped the epoch, e.g. the D4 wedged-writer eviction path) and
+ *     this node's lease is gone even though it never lost its Postgres connection.
+ *   - `PostgresDocStore`'s installed commit guard's epoch-predicated `UPDATE` matches zero rows —
+ *     a straggler commit that raced a fencer and lost; the whole transaction aborts.
+ *
+ * Both are DEFINITIVE lease loss — exactly like a dropped connection — and are routed to
+ * `LeaseMonitor.fenced()` for immediate exit (bypassing the probe-miss tolerance, which exists
+ * only for transient/ambiguous blips; a fenced epoch is never ambiguous).
+ */
+declare class FencedError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Cross-process commit propagation for a Postgres-backed fleet (scale-seam #4, multi-process
+ * variant): the in-memory `EmbeddedWriteFanoutAdapter` only fans a commit out within ONE process.
+ * `NotifyingFanoutAdapter` (writer side) wraps it so every publish ALSO does
+ * `pg_notify('helipod_commits', …)`; each follower's `ReplicaTailer` (`replica-tailer.ts`)
+ * LISTENs for that channel (plus a wall-clock poll fallback, since NOTIFY delivery is not
+ * guaranteed while a listener connection is reconnecting) and, on each wake, verbatim-applies the
+ * primary's MVCC log onto its local replica and derives what to invalidate from that same batch —
+ * no in-process `OplogDelta` ever crosses a process boundary.
+ *
+ * The `CommitChannelClient` seam below (the LISTEN/NOTIFY + parameterized-query slice of
+ * `NodePgClient`) is shared by both the writer-side adapter here and the follower-side
+ * `ReplicaTailer`. The slice-1 `CommitTailer` (which derived-only, never applied to a replica)
+ * was removed in slice 2 once `ReplicaTailer` subsumed it.
+ */
+
+/**
+ * The narrow slice of `NodePgClient` this module (and `ReplicaTailer`) depends on (LISTEN/NOTIFY
+ * plus a plain parameterized query) — kept as a structural interface, matching the `PgClient` seam's
+ * own philosophy of never tying engine/fleet logic to a concrete driver class. A `NodePgClient`
+ * instance satisfies this; so does any test double that implements the same shape.
+ */
+interface CommitChannelClient extends PgQuerier {
+    /** LISTEN on `channel`; returns a closer. Rejecting (e.g. no LISTEN support) is tolerated by
+     *  `ReplicaTailer.start()`, which falls back to poll-only. */
+    listen(channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>>;
+    notify(channel: string, payload: string): Promise<void>;
+}
+/** Writer side: wraps the in-memory adapter; every publish ALSO does
+ *  `pg_notify('helipod_commits', String(commitTs))` so followers wake promptly instead of
+ *  waiting out the poll interval. NOTIFY is a latency optimization only — the poll fallback in
+ *  `CommitTailer` is the correctness path if it's ever dropped or a listener misses it. */
+declare class NotifyingFanoutAdapter implements EmbeddedWriteFanoutAdapter {
+    private readonly inner;
+    private readonly client;
+    constructor(inner: EmbeddedWriteFanoutAdapter, client: CommitChannelClient);
+    publish(payload: EmbeddedWriteFanoutPayload): void;
+    subscribe(listener: FanoutListener): () => void;
+}
+
+/**
+ * `ReplicaTailer` (Fleet slice 2, Task 2; Fenced Frontier B1, D5/D6) — tails the Postgres
+ * primary's MVCC log VERBATIM onto a local embedded replica `DocStore` (an in-process SQLite
+ * instance, in the intended deployment), deriving invalidation ranges straight from the SAME
+ * batch it just applied — not a separate query — so a follower's reactive fan-out is provably
+ * consistent with what actually landed on the replica.
+ *
+ * Evolves `CommitTailer` (`commit-notifier.ts`, slice 1)'s LISTEN + poll wake posture, the
+ * `draining` re-entrancy guard, and watermark-advances-only-after-`onInvalidation`-resolves
+ * semantics — but diverges in structural ways `CommitTailer` never needed:
+ *
+ *   1. VERBATIM APPLY — `CommitTailer` only ever derived ranges to wake a LIVE in-process runtime;
+ *      it never touched a second store. This class additionally re-materializes the primary's
+ *      actual `DocumentLogEntry`/`IndexWrite` rows onto a real replica `DocStore` via `write(...,
+ *      "Overwrite")`, so the replica is a byte-for-byte MVCC mirror (historical reads included),
+ *      not just a wake signal.
+ *   2. BOOTSTRAP CATCH-UP — a fresh replica starts at watermark 0 (or wherever it last left off),
+ *      which can be arbitrarily far behind the primary. `start()` doesn't resolve until the
+ *      replica has caught up to the FENCED FRONTIER `F` AT CALL TIME (the ready gate), batching
+ *      the catch-up in `batchSize`-sized ticks instead of one unbounded pull.
+ *   3. FENCED-FRONTIER TARGETING (D5) — the pull target is no longer `primary.maxTimestamp()` (the
+ *      log's live high-water mark, which can include a commit that raced past the last fence
+ *      check under contention) but `F = shard_leases.frontier_ts` — the durably-fenced, dense
+ *      prefix the epoch-fenced commit guard (`node.ts`'s `installCommitGuard`) advances inside
+ *      every commit transaction. At one shard F advances exactly with commits, so this is
+ *      behavior-identical to the old target in the steady state; the difference only matters
+ *      under a wedged-writer fencing race (B1 D3/D4), where `maxTimestamp()` could momentarily
+ *      run ahead of what's actually safe to consider durable. See `stable-prefix.ts` for the
+ *      `StablePrefixTs` brand this introduces.
+ *   4. DENSITY ASSERTIONS (D5) — defense-in-depth: the construction (D1 store-allocated ts + D3
+ *      epoch-fenced commits) is what actually PREVENTS a skipped commit from ever landing on a
+ *      replica, but the apply loop additionally verifies it, per document entry, before applying:
+ *      the replica's current head for that doc must chain from `prev_ts` exactly (or be absent,
+ *      for an insert). A violation throws `DensityViolationError` — crash loudly rather than serve
+ *      silently corrupted state; the operator remedy is the already-shipped delete-and-re-bootstrap
+ *      (a replica file is a rebuildable mirror).
+ *
+ * `CommitTailer` was the slice-1 derive-only precursor; slice 2 (Task 4) deleted it once this class
+ * subsumed its wake/derive posture with verbatim replica apply. `AppliedInvalidation` below carries
+ * the invalidation shape (identical members to what `CommitTailer.DerivedInvalidation` had).
+ *
+ * Per-tick pipeline (see the class body for the full step-by-step):
+ *   1. `F = await readFrontier()` (D5: `shard_leases.frontier_ts`, branded `StablePrefixTs`); no-op
+ *      if `<= watermark`. F is asserted non-decreasing across reads (D5's other defense-in-depth
+ *      invariant) — a regression means `shard_leases` itself was corrupted/hand-tampered.
+ *   2. Pull `DocumentLogEntry` rows for `(watermark, F]` via `primary.load_documents`, capped at
+ *      `batchSize` — but never splitting a single commit's ts group across ticks (a transaction
+ *      shares exactly one commit `ts` across all its writes, see `postgres-docstore.ts`'s
+ *      `write()` doc comment; if the batch fills mid-way through a ts group, the remaining
+ *      same-ts rows are drained too before capping, so a partial transaction's writes are never
+ *      applied on the replica).
+ *   3. Pull the matching `indexes` rows for the SAME `(watermark, cappedMax]` via raw SQL and
+ *      invert `postgres-docstore.ts`'s `write()` serialization exactly: `deleted=true` → the
+ *      `Deleted` variant, else `NonClustered` carrying the decoded `docId`.
+ *   4. Density-assert the batch (D5) against the replica's PRE-apply state, THEN
+ *      `replica.write(docs, indexWrites, "Overwrite")` — verbatim, idempotent re-apply.
+ *   5. Build `AppliedInvalidation` from the SAME in-memory batch (index-derived writtenTables/
+ *      writtenKeys, DISTINCT-by-(tableId,internalId) writtenDocs from the doc entries).
+ *   6. `await onInvalidation(inv)`, THEN advance the watermark (branded `StablePrefixTs`), THEN
+ *      resolve any satisfied `waitFor()`s — a throwing/slow handler must not cause a range to be
+ *      silently skipped.
+ */
+
+/**
+ * Thrown by the apply loop's density assertion (D5, defense-in-depth — the construction, D1 store-
+ * allocated ts + D3 epoch-fenced commits, is the actual guarantee that prevents this) when a
+ * document entry's `prev_ts` doesn't chain from the replica's actual current head: either a
+ * non-null `prev_ts` that doesn't match (or is missing entirely — no live head), or a null
+ * `prev_ts` (an insert) where the replica already has a live head. Either shape means a commit
+ * touching this document was skipped somewhere between the primary and this replica — serving
+ * reads off it from here on would be silent corruption, so the tailer crashes loudly instead. The
+ * shipped operator remedy is deleting the local replica file and letting it re-bootstrap from the
+ * primary (a replica is always a rebuildable mirror).
+ */
+declare class DensityViolationError extends Error {
+    readonly docId: InternalDocumentId;
+    readonly expectedPrevTs: bigint | null;
+    readonly actualHeadTs: bigint | null;
+    constructor(docId: InternalDocumentId, expectedPrevTs: bigint | null, actualHeadTs: bigint | null);
+}
+/** Mirrors slice 1's `DerivedInvalidation` shape byte-for-byte (see the module doc comment for why
+ *  this is a deliberate parallel type, not an import). `newMaxTs` is the tick's APPLIED ceiling,
+ *  which may be less than the primary's live `maxTimestamp()` when a batch was capped. */
+interface AppliedInvalidation {
+    newMaxTs: bigint;
+    /** DISTINCT `table_id` values touched, as strings (the storage-encoded table id). */
+    writtenTables: string[];
+    /** Raw written index keys — point invalidation input, NOT yet point ranges. */
+    writtenKeys: Array<{
+        indexId: string;
+        key: Uint8Array;
+    }>;
+    /** DISTINCT `(table_id, internal_id)` pairs written in this batch, deduped from the applied
+     *  `DocumentLogEntry` rows themselves (one entry per doc regardless of how many revisions or
+     *  index rows accompanied it in this batch). Point invalidation input for the DOCUMENT
+     *  keyspace, NOT yet point ranges — same split as `writtenKeys` above. */
+    writtenDocs: Array<{
+        tableId: string;
+        internalId: Uint8Array;
+    }>;
+}
+interface ReplicaTailerOptions {
+    /**
+     * Tailer mode (B2b, D5/T5-c):
+     *  - `"replica"` (default, sync node): verbatim-apply the primary's MVCC log onto the local replica
+     *    `DocStore` AND derive invalidation from the applied batch — the shipped follower behavior.
+     *  - `"invalidateOnly"` (writer-ish node in MULTI-WRITER mode): DERIVE-ONLY. The node already has
+     *    every shard's data (it reads the primary directly), so it never applies to a replica and never
+     *    runs the density assertions — it only pulls `(watermark, F]` to derive what a FOREIGN writer's
+     *    commit touched, then fires `onInvalidation` so its own live subscriptions re-run and its oracle
+     *    observes the new ts. Watermark seeds at boot F (only invalidate commits from here on, not
+     *    re-derive all history). In this mode the `replica` constructor arg is NEVER dereferenced.
+     */
+    mode?: "replica" | "invalidateOnly";
+    /** Wall-clock poll fallback interval, in ms. Default 1000. */
+    pollMs?: number;
+    /** Max `DocumentLogEntry` rows pulled per tick (bootstrap catch-up + steady state). Default
+     *  1000. A tick may apply slightly more than this to avoid splitting a commit's ts group. */
+    batchSize?: number;
+    /** Number of shards the fleet runs (B2a). The tailer's target is `F = min(frontier_ts)` over ALL
+     *  shard rows, and it refuses to treat a partial `shard_leases` (`count(*) < numShards`) as ready —
+     *  a half-created lease table must not fake a min (belt-and-braces against the F1×N hole). Default
+     *  1 → B1's single-shard behavior. */
+    numShards?: number;
+    /** Invoked once per non-empty applied batch, in watermark order, AFTER the batch has already
+     *  been written to the replica. The watermark only advances after this resolves. */
+    onInvalidation: (inv: AppliedInvalidation) => Promise<void>;
+}
+type WaitOutcome = "reached" | "timeout" | "released";
+/** Verbatim log-apply tailer: primary Postgres MVCC log -> local replica `DocStore`, plus the
+ *  batch-derived invalidation feed and the `waitFor` read-your-own-writes primitive Task 3 needs. */
+declare class ReplicaTailer {
+    private readonly client;
+    private readonly primary;
+    private readonly replica;
+    private readonly mode;
+    private readonly pollMs;
+    private readonly batchSize;
+    private readonly numShards;
+    private readonly onInvalidation;
+    /** The tailer's own applied high-water mark — a `StablePrefixTs` (D6): only ever seeded from the
+     *  replica's own persisted `maxTimestamp()` (a prior run's watermark, on restart) or advanced to
+     *  a freshly-read/capped `F`. Never assigned a raw, un-branded `bigint` directly. */
+    private wm;
+    /** The last-observed fenced frontier (D5) — tracked purely to assert F never regresses across
+     *  reads (`null` = no read yet, so the first `readFrontier()` establishes the baseline without
+     *  asserting anything). */
+    private lastF;
+    private timer;
+    private unlisten;
+    private stopped;
+    /** Reentrancy guard: a NOTIFY wake and a poll tick can land back-to-back — only one
+     *  pull-apply-invalidate walk runs at a time, so `onInvalidation` never sees overlapping ranges,
+     *  and the bootstrap loop in `start()` never races a concurrent LISTEN-triggered tick. */
+    private draining;
+    private readonly waiters;
+    constructor(client: CommitChannelClient, primary: PostgresDocStore, replica: DocStore, opts: ReplicaTailerOptions);
+    /** Plain `bigint` on purpose (not the branded `StablePrefixTs`) — external callers (tests, the
+     *  `PromotionDeps` seam) only ever compare/print this value; widening away the internal brand at
+     *  the public boundary costs nothing and avoids forcing every caller to know about the brand. */
+    watermark(): bigint;
+    /**
+     * Reads the fenced frontier `F` (Fenced Frontier B1 D5, generalized to N shards in B2a) —
+     * `F = min(frontier_ts)` over ALL `shard_leases` rows — via the same `CommitChannelClient` already
+     * threaded in for LISTEN/NOTIFY. The min is the dense prefix the WHOLE fleet has durably fenced: a
+     * replica may serve reads up to it and never past a commit that hasn't been fenced on every shard.
+     *
+     * Belt-and-braces (B2a — the F1×N hole otherwise recurs ×N): treat `count(*) < numShards` as
+     * F=0-equivalent (NOT ready). A half-created `shard_leases` — some shards claimed+seeded, others not
+     * yet — must not let `min` over the present rows fake a ready frontier; the writer's acquire-all +
+     * seed-all completes (all N rows present, each seeded ≥ max) BEFORE it reports ready, so a real min
+     * only appears once every shard is genuinely fenced. `count(*) = 0` (fresh fleet, pre-acquisition)
+     * is the same F=0.
+     *
+     * Asserts F is monotonically non-decreasing across reads once the count gate is satisfied (D5's
+     * defense-in-depth invariant) — a regression can only mean `shard_leases` was corrupted/hand-
+     * tampered. The assertion is skipped while `count(*) < numShards` (F is a placeholder 0 there, so a
+     * later real min is legitimately larger, not a regression).
+     */
+    private readFrontier;
+    /**
+     * @param seedWm ONLY consulted in `"invalidateOnly"` mode (ignored in `"replica"` mode, which always
+     *   seeds from the replica's own persisted high-water mark — see below). When provided, seeds the
+     *   watermark from THIS value instead of a fresh `readFrontier()` read.
+     *
+     *   Fixes the PROMOTION-HANDOFF INVALIDATION GAP (B2b whole-branch review): a promoting node stops
+     *   its `ReplicaTailer` (sync mode) at some watermark `W`, then starts this derive-only listener.
+     *   Between the tailer's stop and the listener's start, a co-writer's commit can land and bump the
+     *   fenced frontier `F` past `W` — if the listener then seeds from a FRESH `readFrontier()` (i.e.
+     *   that same later `F`), it treats everything up to `F` as already-known and never derives/
+     *   invalidates the `(W, F]` range, even though nothing ever actually invalidated it: the sync
+     *   tailer was already stopped, and this listener starts past it. A subscription open across the
+     *   promotion goes silently stale for exactly those commits.
+     *
+     *   The caller (`node.ts`'s `startWriterInvalidationListener`) closes this gap by passing the
+     *   OUTGOING tailer's own final `watermark()` (captured right after `tailer.stop()`) as `seedWm` on
+     *   promotion, so the listener picks up exactly where the tailer left off — contiguous coverage,
+     *   with the tailer's own last-applied range harmlessly re-derived (idempotent double-invalidation).
+     *   Writer BOOT (no prior tailer, so no gap by construction) omits `seedWm` and keeps the original
+     *   fresh-`readFrontier()` behavior.
+     */
+    start(seedWm?: bigint): Promise<void>;
+    stop(): Promise<void>;
+    /** Resolves when `watermark() >= ts` (immediately if already true), or when `release()` fires.
+     *  Task 3's read-your-own-writes primitive: a client that just committed at `ts` can wait for
+     *  a follower's replica to have caught up before serving that client's next read from it. */
+    waitFor(ts: bigint, timeoutMs: number): Promise<WaitOutcome>;
+    /** Releases ALL pending `waitFor()`s with `"released"` (e.g. this node was just promoted to
+     *  writer, or is shutting down, and callers should stop waiting on replica catch-up). */
+    release(): void;
+    private wakeSatisfiedWaiters;
+    private tick;
+    /** One pull-apply-invalidate walk. Split out from `tick()` so `tick()` can wrap it with the
+     *  DensityViolationError halt handling without that catch swallowing the `draining` bookkeeping. */
+    private drainOnce;
+    /**
+     * Density assertion (D5, defense-in-depth): for EVERY document entry in this batch, in
+     * `DocumentLogEntry` order, the replica's head for that document IMMEDIATELY BEFORE this entry
+     * lands must chain from `entry.prev_ts` exactly — `prev_ts !== null` requires a live head equal
+     * to it; `prev_ts === null` (an insert) requires no live head at all. Throws `DensityViolationError`
+     * on the first mismatch.
+     *
+     * IDEMPOTENT RE-APPLY exception: if the replica's head is ALREADY at this exact entry's own
+     * `ts`, that's not a violation — it's this exact revision being re-applied (the whole class is
+     * built around `"Overwrite"` idempotency, e.g. a restart re-walking an already-applied range).
+     * Since `ts` is the log's globally unique per-shard commit position, a head landing on it can
+     * only mean this precise commit already landed here, never an unrelated collision.
+     *
+     * A batch can carry more than one revision of the SAME document (it was written more than once
+     * inside the pulled `(wm, F]` range), so "the head immediately before this entry" is a running
+     * per-batch simulation — seeded from the replica's REAL state (`replica.get`) the first time a
+     * doc is encountered, then advanced in-memory to each entry's own `ts` as it's validated —
+     * rather than re-reading the replica for every entry (which would see later, not-yet-applied
+     * entries' predecessor as still absent).
+     */
+    private assertDensity;
+    /**
+     * Pull `DocumentLogEntry` rows for `(after, upTo]` from `load_documents`, capped at
+     * `this.batchSize` — but if the cap lands mid-way through a group of rows sharing the same
+     * commit `ts`, keep draining until that ts group is fully collected before stopping. A single
+     * transaction shares exactly one commit `ts` across every document it wrote (see
+     * `postgres-docstore.ts`'s `write()`), so cutting a batch mid-group would apply a transaction's
+     * writes partially, which `load_documents`'s `(after, cap]`-shaped next-tick range would then
+     * never revisit (the excluded rows share `ts === cap`, which the next tick's range excludes as
+     * its own lower bound).
+     *
+     * `TimestampRange` is `{minInclusive, maxExclusive}` (see `packages/docstore/src/types.ts`) —
+     * the half-open opposite skew from the `(after, upTo]` shape this tailer needs, so the bounds
+     * are translated with a `+1n` offset on both sides (safe: `ts` is a monotonic integer log
+     * position, never a real number needing density guarantees).
+     */
+    private pullDocs;
+}
+
+/**
+ * `WriteForwarder` — the non-owner side of the fleet write path. Implements the engine's
+ * per-shard `WriteRouter` seam (B2b, D1): for any shard this node does NOT currently hold,
+ * `forward()` POSTs the call to that shard's owner (`/_fleet/run`, discovered per-shard from the
+ * `shard_leases` row) and returns its JSON result. `isLocalWriter(shardId)` is a live view of the
+ * node's held-shard set (`LeaseManager.currentEpoch(shardId) !== null` — the SAME source of truth
+ * `relinquish()` uses for its own idempotency check), so a shard acquired/relinquished mid-flight
+ * (balancer rebalancing, failover) takes effect on the very next call — no caching, no stale role.
+ *
+ * The forwarder learns each shard's writer URL from that shard's `shard_leases` discovery row (via
+ * `LeaseManager.read(shardId)`), never from static config — so a failover to a new owner is picked
+ * up by re-reading the lease. `writerUrlFor(shardId)` caches per shard (one node normally forwards
+ * the same shard repeatedly) and refreshes on a POST failure, retrying once — same shape as the
+ * shipped single-shard `writerUrl()` this replaces, generalized per shard.
+ *
+ * Single-hop guard (B2b, D1 spec-review edit): every forward body carries `forwarded: true`. If it
+ * lands on a node that is ALSO not the shard's owner (a point-in-time race during rebalance
+ * convergence), the receiver's `/_fleet/run` handler rejects with a typed, retryable
+ * `NotShardOwnerError` instead of re-forwarding itself (which would let a forward chase a moving
+ * target unboundedly). `forward()` treats that ONE error shape like a transport failure — refresh
+ * the shard's cached URL and retry once — then surfaces whatever the second attempt does. Any OTHER
+ * typed `HelipodError` (an OCC conflict, a validation failure, …) means a LIVE owner answered
+ * DEFINITIVELY and is re-thrown unchanged, exactly as before.
+ *
+ * Task 3 (read-your-own-writes): `/_fleet/run`'s response carries the write's `commitTs`
+ * (stringified — bigints don't survive `JSON.stringify`). If a `ReplicaTailer` has been attached
+ * via `attachTailer()` (this node is a fleet SYNC node reading off a local replica), `forward()`
+ * waits for that replica's watermark to reach `commitTs` before resolving — otherwise a client that
+ * just wrote through this node could immediately read its own write's absence off a replica that
+ * hasn't caught up yet. `promote()` also releases any pending wait: once this node becomes the
+ * writer, replica catch-up is no longer the right thing to block on.
+ */
+
+interface WriteForwarderOptions {
+    /** Admin bearer token — the `/_fleet/run` endpoint authenticates with the deployment admin key. */
+    adminKey: string;
+    /** This node's own advertised URL (recorded on the lease when/if it becomes the writer). */
+    selfUrl: string;
+}
+/**
+ * The narrow seam `WriteForwarder` needs from `ReplicaTailer` — declared locally (rather than
+ * typing `attachTailer` as `ReplicaTailer` itself) so tests can pass a lightweight structural stub
+ * instead of standing up a real tailer (which needs a live Postgres primary + replica store).
+ * A real `ReplicaTailer` satisfies this trivially since it's a strict subset of its public API.
+ */
+type ReplicaWaiter = Pick<ReplicaTailer, "waitFor" | "release">;
+declare class WriteForwarder implements WriteRouter {
+    private readonly lease;
+    private readonly opts;
+    private tailer;
+    /** Guard each distinct malformed-response warning to once per process (independently — an absent
+     *  commitTs and an unparseable one are different failure modes and each deserves its own log
+     *  line) so a bad/old writer response doesn't spam the log on every subsequent forwarded write. */
+    private warnedMissingCommitTs;
+    private warnedUnparseableCommitTs;
+    /** Per-shard writer-URL cache (B2b, T2): populated on first forward for a shard, refreshed on a
+     *  POST failure (transport error OR a not-the-owner rejection) and retried once. A node normally
+     *  forwards the same shard repeatedly, so caching avoids a `shard_leases` read on every call. */
+    private readonly writerUrlCache;
+    constructor(lease: LeaseManager, opts: WriteForwarderOptions);
+    /** Attach the local `ReplicaTailer` this node reads off, enabling the read-your-own-writes wait
+     *  in `forward()`. Fleet WRITER nodes never call this — they have no replica to wait on. */
+    attachTailer(t: ReplicaWaiter): void;
+    /** Called on promotion (sync → writer-ish). Releases any read-your-own-writes wait in flight —
+     *  this node no longer serves reads off a replica for its own forwarded writes, so waiting on
+     *  catch-up would only add latency. `isLocalWriter` itself needs no flip here: it already reads
+     *  the live `LeaseManager` state directly (see below), which promotion's `tryAcquire` calls
+     *  update as a side effect.
+     *
+     *  NOTE (Fleet B3): a HYBRID promotion (multi-writer) does NOT call this — a hybrid keeps its
+     *  replica + tailer running past promotion and STILL serves reads (and forwarded writes to shards
+     *  it doesn't own) off the replica, so releasing the RYOW waits would be wrong. Only the
+     *  single-writer failover promotion (`promoteFleetNode`, no replica read path afterward) calls it. */
+    promote(): void;
+    /**
+     * Fleet B3 (D2) — the HYBRID own-commit RYOW gate. Wired as the runtime's `beforeNotify` drain
+     * hook: awaited before a LOCALLY-committed mutation's subscription re-runs fire, so those re-runs
+     * (which read this node's replica, via the hybrid query path) don't observe the commit's absence on
+     * a replica that hasn't applied it yet. Delegates to the SAME attached `ReplicaTailer.waitFor` the
+     * forwarded-write RYOW uses (`attachTailer`), so local and forwarded writes share one catch-up
+     * primitive. No-op when no tailer is attached (a single-writer node with no replica, or before the
+     * tailer exists) or when nothing committed (`0n`). A timeout is swallowed — reactivity is
+     * best-effort; the read path stays correct regardless (the re-run just fires against a replica that
+     * is still catching up, no worse than the pre-gate behavior).
+     */
+    waitForReplica(commitTs: bigint): Promise<void>;
+    /**
+     * True iff this node currently holds `shardId`'s write lease (B2b, D1: per-shard membership, not
+     * a whole-node binary role). `LeaseManager.currentEpoch(shardId) !== null` is the SAME live
+     * held-set accessor `relinquish()` uses as its own idempotency check (`node.ts`) — so this can
+     * never disagree with what the commit guard / relinquish dispatcher consider "held". Consulted
+     * fresh on every call (never cached): a shard acquired or relinquished mid-flight (balancer
+     * rebalance, failover, promotion) takes effect on the very next mutation.
+     */
+    isLocalWriter(shardId?: ShardId): boolean;
+    forward(kind: "mutation" | "action", path: string, args: JSONValue, identity: string | null, shardId?: ShardId, dedup?: {
+        clientId: string;
+        seq: number;
+    }): Promise<{
+        value: JSONValue;
+        commitTs?: number;
+        shardId?: string;
+        replay?: ClientReplay;
+    }>;
+    /** Discover shard `shardId`'s current writer URL — cached after the first read. */
+    private writerUrlFor;
+    /** Force a fresh `shard_leases` read for `shardId`, overwriting any cached URL — the refresh half
+     *  of `writerUrlFor`'s cache, also used directly by `forward()`'s retry-once path. */
+    private refreshWriterUrlFor;
+    private post;
+    /** Waits for the local replica to observe `commitTsStr`, when a tailer is attached. No-op on a
+     *  fleet WRITER node (no tailer attached) or when the write committed nothing (`0`/absent). */
+    private waitForReplicaCatchUp;
+}
+
+/**
+ * `ShardLeaseBalancer` — the deterministic, coordinator-free shard placement loop (B2b, D3).
+ *
+ * Every fleet node (writer OR sync) runs one. Each ~2s beat:
+ *   1. HEARTBEAT this node's `fleet_nodes` presence row (its liveness signal — the balancer is the
+ *      presence heartbeat for a shardless SYNC node, which has no `shard_leases` row and no
+ *      LeaseMonitor; a writer node's LeaseMonitor probe also heartbeats presence, redundantly and
+ *      harmlessly).
+ *   2. READ the live node set (`fleet_nodes` ∪ live `shard_leases` holders) and compute this node's
+ *      rendezvous TARGET shards — the shards HRW assigns to `myUrl` over that set. Every node derives
+ *      the same assignment from the same rows (`rendezvous.ts`), so there is nothing to negotiate.
+ *   3. If this node is a pure SYNC node (`!isWriterish()`) and any NON-default target is currently
+ *      acquirable (orphaned/expired/missing) — a peer released it, or its holder died — request the
+ *      shipped whole-node PROMOTION (sync → writer-ish); a promoted node then acquires on the next
+ *      steps. (The DEFAULT shard has its own shipped election path — `LeaseManager.acquireLoop` — so
+ *      it is not a promotion trigger here; that avoids a redundant second promotion driver racing the
+ *      election.)
+ *   4. Writer-ish node: ACQUIRE any target shard it does not hold that is acquirable (orphaned/
+ *      expired/missing). This is failover — un-damped and prompt; it NEVER touches a live non-target
+ *      holder's row (advisory locks + fencing already guarantee at most one holder, so acquisition is
+ *      always safe).
+ *   5. Writer-ish node, under DAMPING (live set identical for ≥2 consecutive beats): gracefully
+ *      RELEASE any held shard NOT in its target set — a point-in-time self-fence (`releaseShard`, wired
+ *      in `node.ts`) that hands the shard to its rightful owner, which acquires it on its own next
+ *      beat (~2s), no TTL wait, no failover event. Damping keeps a flapping membership from thrashing
+ *      placement; acquisition (step 4) is intentionally NOT damped so a real death recovers promptly.
+ *
+ * The balancer owns ZERO SQL beyond the three lease reads — all acquire/release/promote effects are
+ * injected thunks (`node.ts` wires them over `LeaseManager`/the runtime), so this class is a pure
+ * orchestrator and unit-testable with lightweight fakes.
+ */
+
+/** The narrow slice of `LeaseManager` the balancer reads — a structural interface so tests can pass a
+ *  fake, and so the balancer never reaches past these three reads into the lease's write surface. */
+interface BalancerLease {
+    /** Upsert this node's `fleet_nodes` presence row, extending `expires_at` by the lease TTL. */
+    heartbeatPresence(): Promise<void>;
+    /** Distinct unexpired advertise URLs — `fleet_nodes` ∪ live `shard_leases.writer_url` holders. */
+    liveNodes(): Promise<string[]>;
+    /** Per-shard ownership snapshot: for each existing `shard_leases` row, its `writer_url` (null =
+     *  orphaned) and whether it has expired per the DB clock. A shard with NO row is absent from the map
+     *  (treated as acquirable). */
+    readShardOwnership(): Promise<Map<ShardId, {
+        writerUrl: string | null;
+        expired: boolean;
+    }>>;
+}
+interface ShardLeaseBalancerDeps {
+    lease: BalancerLease;
+    /** This node's advertised URL — its identity in the rendezvous candidate set. */
+    myUrl: string;
+    /** Shard count (the fleet's fixed NUM_SHARDS). Drives the `shardIdList` this balancer ranges over. */
+    numShards: number;
+    /** Live per-shard held-set membership (`LeaseManager.currentEpoch(shardId) !== null`). */
+    isHeld(shardId: ShardId): boolean;
+    /** Is this node writer-ish (has completed promotion / booted as the writer)? A pure sync node only
+     *  heartbeats presence and may request promotion; it never acquires/releases. */
+    isWriterish(): boolean;
+    /** Acquire `shardId`'s lease (+ its per-slot advisory lock), evicting a wedged expired holder if
+     *  needed. Returns whether the shard is now held. One tick's attempt — a miss retries next beat. */
+    tryAcquireShard(shardId: ShardId): Promise<boolean>;
+    /** Gracefully release a held shard (point-in-time self-fence under the shard's commit mutex, then
+     *  the T3 relinquish-unwind) so its rightful owner can acquire it. */
+    releaseShard(shardId: ShardId): Promise<void>;
+    /** Run the shipped whole-node promotion (sync → writer-ish). Idempotent at the node level. */
+    requestPromotion(): Promise<void>;
+    /**
+     * Fleet B3, D3 (effectively-once forwarding): reclaim `fleet_idempotency` rows older than the
+     * TTL — a cheap indexed delete, run on every WRITER-ish beat (see `LeaseManager.sweepIdempotency`).
+     * Optional so an older/stub `ShardLeaseBalancerDeps` (and every existing balancer test) needs no
+     * change; a pure sync node never has this called regardless (see `tick()`).
+     */
+    sweepIdempotency?(): Promise<void>;
+    /**
+     * Multi-writer scale-out mode (B2b, D3 — the "writer nodes vs sync nodes" scaling knob, off by
+     * default). When OFF (the default, and the shipped single-writer behavior): this node's target set is
+     * EVERY shard (the sole writer owns them all), the balancer NEVER gracefully releases a live-held
+     * shard to a peer, and a pure sync node is NEVER auto-promoted by rendezvous — additional nodes stay
+     * READ REPLICAS (sync), reading off their local replica whose tailer sees every shard's commits.
+     * Failover acquisition (picking up an orphaned/expired shard) and presence heartbeating are ON
+     * regardless. When ON: full rendezvous distribution — each live node owns and writes its HRW share,
+     * peers gracefully release a newcomer's share, and a sync node promotes to claim an orphaned share.
+     * (Enabling it makes a joining node a CO-WRITER, whose own subscriptions do not yet receive
+     * cross-writer reactivity for shards it doesn't hold — that is T6's proving ground.)
+     */
+    multiWriter?: boolean;
+    /** Beat interval (ms). Default 2000. */
+    beatMs?: number;
+    /** Structured-log seam for a tick error, defaults to `console.error`. */
+    log?: (msg: string) => void;
+}
+declare class ShardLeaseBalancer {
+    private readonly deps;
+    private readonly shards;
+    private readonly multiWriter;
+    private readonly beatMs;
+    private readonly log;
+    private timer;
+    private stopped;
+    private running;
+    /** Canonical (sorted, comma-joined) live set from the PREVIOUS beat — damping compares against it:
+     *  a RELEASE only fires when the current live set equals this (identical for ≥2 consecutive beats). */
+    private previousLiveSet;
+    constructor(deps: ShardLeaseBalancerDeps);
+    /** Begin the periodic beat. The FIRST beat fires after `beatMs` (never synchronously) — prompt boot
+     *  acquisition is done explicitly via `acquireTargetsNow()`, not the periodic loop. Idempotent. */
+    start(): void;
+    stop(): void;
+    /** Resolve the live candidate set for a beat: the DB's live nodes ∪ this node itself (a node is
+     *  always live to itself — belt-and-braces so its own boot never depends on its presence row having
+     *  landed/propagated yet). Returns both the URL array (rendezvous input) and its canonical form. */
+    private liveCandidates;
+    /** This node's target shards. In single-writer mode (the default) the sole writer's targets are ALL
+     *  shards — byte-identical to B2a's acquire-all — so a joining node never steals a share. In
+     *  multi-writer mode it is this node's rendezvous (HRW) share over `liveUrls`. */
+    private targetsFor;
+    /** A shard is acquirable iff it has no row (absent from the map), is orphaned (`writer_url NULL`), or
+     *  has expired — i.e. NOT held live by a peer. Acquisition only ever targets these; a live non-target
+     *  holder is never fenced by the balancer (that's failover's job). */
+    private acquirable;
+    /**
+     * Un-damped acquire pass over this node's CURRENT rendezvous targets — called at writer boot and on
+     * promotion so the node holds its share PROMPTLY (before the ready line / before the first periodic
+     * beat), rather than waiting out a 2s tick. In a single-node fleet the target set is EVERY shard, so
+     * this acquires all N — byte-identical steady state to B2a's acquire-all. Seeds `previousLiveSet` so
+     * the first periodic beat treats the boot membership as the damping baseline.
+     */
+    acquireTargetsNow(): Promise<void>;
+    /** One balancer beat (see the class doc for the five steps). Never throws — a tick error is logged
+     *  and the loop continues; the next beat retries against fresh state. */
+    tick(): Promise<void>;
+}
+
+/**
+ * Rendezvous (highest-random-weight) hashing for the shard balancer (B2b, D3).
+ *
+ * Every fleet node runs the SAME pure function over the SAME live-node set (discovered from
+ * `fleet_nodes` ∪ live `shard_leases` holders — see `LeaseManager.liveNodes`), so all nodes derive
+ * an identical shard→owner assignment with NOTHING to negotiate. For each shard we compute a stable
+ * 64-bit weight `hash(shardId, advertiseUrl)` per candidate node and pick the max — the owner. When
+ * the membership set changes, HRW moves ONLY the shards whose max-weight node changed (minimality),
+ * so a join/leave reshuffles a bounded, minimal set of shards rather than the whole ring.
+ *
+ * The weight is FNV-1a-64 over the UTF-8 bytes of `${shardId}${advertiseUrl}` — the same
+ * hashing discipline `@helipod/id-codec`'s jump-hash router uses (FNV-1a-64 → a well-mixed 64-bit
+ * key), reimplemented locally rather than importing that package's private helper so the rendezvous
+ * weight function is self-contained and its exact bytes are pinned here. It MUST stay a pure function
+ * of the two strings and identical across nodes/releases — every node's placement decision depends on
+ * byte-for-byte agreement.
+ */
+
+/**
+ * The rendezvous weight of `advertiseUrl` for `shardId` — a stable 64-bit value. A space separates
+ * the two fields so `("s1","x")` and `("s","1x")` can never collide into the same input — safe
+ * because neither `shardId` nor `advertiseUrl` ever contains a space (shard ids are short identifiers
+ * like `"default"`/`"s1"`; advertise URLs are `scheme://host:port` with no whitespace).
+ */
+declare function rendezvousWeight(shardId: ShardId, advertiseUrl: string): bigint;
+/**
+ * The owner of `shardId` under rendezvous hashing over `liveUrls`: the node with the maximum weight,
+ * ties broken by the lexicographically-smaller URL (so the choice is fully deterministic even in the
+ * astronomically unlikely event of a 64-bit weight collision). Returns `""` for an empty candidate
+ * set (no live node — the caller always includes at least its own URL, so this is defensive only).
+ * Pure and allocation-light; identical output on every node given the same `liveUrls` (order-
+ * independent — the max/tie-break does not depend on the input array's order).
+ */
+declare function rendezvousOwner(shardId: ShardId, liveUrls: readonly string[]): string;
+
+/**
+ * A `DocStore` that forwards every call to a swappable inner delegate, so a replica-to-primary
+ * promotion (Task 4) can become a single atomic pointer swap instead of a coordinated teardown of
+ * every in-flight caller.
+ *
+ * Atomicity contract: each method reads `this.delegate` exactly once, at call entry, into a local
+ * binding, and completes its whole operation against that snapshot. A call already in progress when
+ * `swapTo()` runs finishes against the OLD delegate; a call started after `swapTo()` returns sees
+ * the NEW one. There is no instant where a single call is torn between two delegates. This holds for
+ * the async generators too (`index_scan`/`load_documents`): the delegate is captured before the
+ * first `yield`, so a scan already draining rows from the old store keeps draining the old store to
+ * completion even if `swapTo()` runs concurrently.
+ *
+ * `close()` semantics: closes only the CURRENT delegate (whatever `this.delegate` is at the moment
+ * `close()` is called). It does NOT close a delegate that was swapped out by an earlier `swapTo()` —
+ * this class has no memory of former delegates once replaced. Closing a swapped-out (e.g. demoted
+ * primary, or promoted-from replica) delegate is the lifecycle owner's responsibility (Task 4
+ * decides when that's safe — e.g. after draining its in-flight callers), not this wrapper's.
+ */
+declare class SwitchableDocStore implements DocStore {
+    private delegate;
+    constructor(initial: DocStore);
+    /** Atomically repoint all future calls at `next`. Does not touch the outgoing delegate. */
+    swapTo(next: DocStore): void;
+    /** The delegate current calls are being forwarded to. */
+    current(): DocStore;
+    setupSchema(options?: SchemaSetupOptions): Promise<void>;
+    write(documents: readonly DocumentLogEntry[], indexUpdates: readonly IndexWrite[], conflictStrategy: ConflictStrategy, shardId?: ShardId$1): Promise<void>;
+    commitWrite(documents: readonly DocumentLogEntry[], indexUpdates: readonly IndexWrite[], shardId?: ShardId$1, opts?: {
+        meta?: Record<string, string>;
+    }): Promise<bigint>;
+    commitWriteBatch(units: readonly CommitUnit[], shardId?: ShardId$1): Promise<bigint[]>;
+    /** Forwards to the CURRENT delegate at call entry, same atomicity contract as every other
+     * method here — but note the resulting registration is NOT itself re-forwarded on a later
+     * `swapTo()`: the guard lands on whichever concrete store was `this.delegate` at the moment
+     * `addCommitGuard` was called, and stays registered there even after the switchable repoints
+     * elsewhere. In practice fleet code (`node.ts`) always calls `addCommitGuard` on the concrete
+     * `PostgresDocStore` directly (never through this wrapper), so this pass-through exists purely
+     * for `DocStore` interface conformance. */
+    addCommitGuard(guard: (q: any, units: readonly CommitGuardUnit[], shardId: ShardId$1) => 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>;
+}
+
+/** The filename of a sync node's local embedded replica, under the serve data dir. */
+declare const REPLICA_DB_FILENAME = "fleet-replica.db";
+/** Default number of shards a fleet node runs (B2a). T5 owns the persist-once/env/`HELIPOD_FLEET_
+ *  SHARDS` story; this task threads it as a plain parameter (`prepareFleetNode`'s `numShards` dep),
+ *  defaulting here. The one node holds ALL N shard leases, commits in parallel across them (per-shard
+ *  commit-connection pool + per-shard `ShardedTransactor` mutexes), and F = min over the N frontiers. */
+declare const DEFAULT_NUM_SHARDS = 8;
+/** A point-in-time frontier-lag reading for the health endpoint (D5): the fleet-wide fenced frontier
+ *  (`min(frontier_ts)` across all shard rows), how long (wall-clock ms) it has been stuck at that
+ *  value, and which shard is holding it there. */
+interface FrontierStats {
+    frontier: bigint;
+    lagMs: number;
+    pinningShard: ShardId;
+}
+/**
+ * Fleet frontier-lag monitor + (writer-only) idle-shard closer (B2a, D5). One runs per fleet node:
+ *
+ *  - On the WRITER (`closeIdle: true`) each beat first CLOSES idle shards — `lease.closeIdleFrontiers`
+ *    allocates one `nextval` and advances every held shard whose frontier lags it — so an idle shard
+ *    can't pin `F = min(frontier_ts)` below the live commit position for more than a beat. A local
+ *    commit also schedules a coalesced beat (~10ms) so F reacts promptly to writes on sibling shards.
+ *  - On EITHER role each beat then READS all shard frontiers to compute `min` + the pinning shard and
+ *    track how long `min` has been stuck (wall-clock since it last advanced) → the `FrontierStats`
+ *    the health endpoint reports. A lag past `lagWarnMs` logs a warning naming the pinning shard
+ *    (once per stall, reset when it recovers), the console signal D5 asks for.
+ *
+ * A sync node runs it read-only (`closeIdle: false`) — it holds no leases, so it must NOT allocate
+ * `nextval` (only the writer drives the frontier); it just observes whether the fleet frontier is
+ * advancing.
+ */
+declare class FrontierMonitor {
+    private readonly lease;
+    private readonly opts;
+    private timer;
+    private coalesceTimer;
+    private stopped;
+    private running;
+    private cached;
+    /** The last-observed `min(frontier_ts)` and the wall-clock time it was first seen — lag is the age
+     *  of the CURRENT min (how long it's been stuck), so both reset whenever min advances. */
+    private lastMin;
+    private minSinceMs;
+    private warned;
+    /** D4 — replica-lag tracking: wall-clock time this node's OWN tailer watermark was first observed
+     *  BEHIND the fleet frontier F, or `null` while it's caught up. Mirrors `minSinceMs`/`lastMin`'s
+     *  "age of the current stuck condition" shape, but for the replica catch-up gap rather than F's own
+     *  advance. Reset the instant `wm` reaches `F` again — a transient blip re-arms silently. */
+    private replicaLagSinceMs;
+    private replicaLagWarned;
+    constructor(lease: LeaseManager, opts: {
+        closeIdle: boolean;
+        /** Per-shard commit-mutex seam the idle-frontier closer runs each bump under (see
+         *  `closeIdleFrontiers`). Required when `closeIdle` is true; ignored otherwise. */
+        runExclusiveOnShard?: TryRunExclusiveOnShard;
+        beatMs?: number;
+        coalesceMs?: number;
+        lagWarnMs?: number;
+        now?: () => number;
+        warn?: (msg: string) => void;
+        /**
+         * D4 — this node's own local replica-tailer watermark, when it has one: a sync node's
+         * `ReplicaTailer`, or (in the hybrid/multi-writer regime) a writer's own read-replica tailer.
+         * Omitted for a non-hybrid writer (it reads the primary directly — no replica, no lag to track).
+         * Compared against the fleet frontier `F = min(frontier_ts)` each beat; `wm` falling more than
+         * `lagWarnMs` behind `F` logs ONE operator warning naming this node's replica (`lease.advertiseUrl`
+         * — there is only ever one replica per node, so naming the NODE identifies it), silent below the
+         * threshold and while caught up. Same shape/once-ness as the pinning-shard warning above; applies
+         * identically whether this monitor is a sync node's or a hybrid writer's (same `beat()` code path).
+         */
+        tailerWatermark?: () => bigint;
+        /**
+         * T3.5 (the fleet-connections bench's notify-diagnosis fix): fired at most once per beat, only
+         * when this beat's `closeIdleFrontiers`/`bumpOrphanFrontiers` (or a concurrent commit) actually
+         * pushed the fleet ceiling `F = min(frontier_ts)` past what the PRIOR beat observed. Neither
+         * closer NOTIFYs on its own bare `UPDATE` — without this, an idle-shard close that finally
+         * un-pins F is invisible to every `ReplicaTailer`'s LISTEN, and delivery silently falls through
+         * to the tailer's `DEFAULT_POLL_MS` (1000ms) fallback even though NOTIFY itself is wired and
+         * fires within ~1ms of the real commit (see `.superpowers/sdd/notify-diagnosis.md`). Omitted
+         * entirely on a sync node (`closeIdle: false`) — only the writer's own beat performs the
+         * advancing work, so only it needs to announce it. The callback owns its own failure handling
+         * (fire-and-forget, matching `NotifyingFanoutAdapter.publish`'s own NOTIFY) — a rejected notify
+         * must not, and structurally cannot, break the beat.
+         */
+        notifyOnAdvance?: (ceiling: bigint) => void;
+    });
+    private get now();
+    start(): void;
+    /** Schedule a single coalesced beat `coalesceMs` out — called on each local commit so an idle
+     *  sibling shard un-pins F within ~10ms instead of waiting out the periodic beat. Multiple commits
+     *  inside the window collapse onto one beat. */
+    triggerCoalesced(): void;
+    private beat;
+    /** The most recent frontier reading, or null if no beat has completed yet. `lagMs` is recomputed
+     *  against the current clock so a caller between beats still sees a fresh age. */
+    stats(): FrontierStats | null;
+    stop(): void;
+}
+/**
+ * D4 — a generic async-op serializer: returns a `run(op)` function where every queued `op` executes
+ * only after the PREVIOUS one has settled (resolved OR rejected — `.then(op, op)`, so one op
+ * rejecting never wedges the chain for the next). Callers that fire-and-forget a burst of overlapping
+ * async calls (see `startFleetNode`'s `startDriversChained`/`stopDriversOnlyChained`) get a
+ * deterministic EXECUTION order matching the ISSUE order, even when the callee itself is merely
+ * idempotent (idempotence alone doesn't prevent a later-issued-but-faster call from resolving before
+ * an earlier one, which is the race this closes). Each call to `createAsyncChain()` returns an
+ * independent chain — callers needing one shared serialization point construct exactly one instance
+ * and route every op through the same returned function.
+ */
+declare function createAsyncChain(): (op: () => Promise<void>) => Promise<void>;
+/**
+ * Bounded-writer-session timeouts (Fenced Frontier B1, D4) applied to every fleet node's pinned
+ * Postgres connection — the single `NodePgClient` `prepareFleetNode` builds is the writer-capable one
+ * (a sync node's same connection becomes the writer's on promotion via `pgStore.setWritable()`), so
+ * it is bounded from boot. `idle_in_transaction=5s` kills a transaction a wedged writer leaves open
+ * mid-commit (releasing the row lock a fencer's `evictExpired` needs); `statement=10s` caps any single
+ * runaway statement. A NON-fleet single-node `serve`/`dev` (`makeStore` in `packages/cli`) constructs
+ * `NodePgClient` WITHOUT this option and stays unbounded — see that call site.
+ */
+declare const FLEET_WRITER_SESSION_TIMEOUTS: {
+    idleInTransactionMs: number;
+    statementMs: number;
+};
+declare function fleetApplicationName(advertiseUrl: string): string;
+/**
+ * Whether this deployment runs in MULTI-WRITER mode (`HELIPOD_FLEET_MULTI_WRITER`), read in ONE
+ * place so `prepareFleetNode` (which decides the runtime store/queryStore wiring) and
+ * `startFleetNode` (which decides the tailer/promotion wiring) can never disagree about a node's
+ * shape. Multi-writer IS the hybrid regime (Fleet B3): every writer-ish node keeps a local replica
+ * and serves queries from it while committing to the primary. Off (the production default) → the
+ * shipped single-writer topology: the sole writer holds every shard and reads the primary, additional
+ * nodes are pure read-replica sync nodes — no hybrid machinery anywhere (byte-identical to B2b).
+ */
+declare function fleetMultiWriterEnabled(): boolean;
+/**
+ * Whether group commit (Fleet B4) is enabled (`HELIPOD_GROUP_COMMIT`), read the SAME way as
+ * `fleetMultiWriterEnabled` above — one place, so every `runtimeOptions` construction site in
+ * `prepareFleetNode` reads the identical value. Threaded straight into `createEmbeddedRuntime`
+ * (`EmbeddedRuntimeOptions.groupCommit`), which routes every shard's commits through the two-buffer
+ * stage-then-flush committer loop. Default OFF at Fleet B4/T4 — T5 owns flipping the production
+ * default once the throughput win is E2E-proven; unset/anything else → the byte-identical
+ * single-commit path every shard already runs.
+ */
+declare function groupCommitEnabled(): boolean;
+interface FleetHandles {
+    role(): "sync" | "writer";
+    /** The current writer's URL — the proxy target for public httpActions handled on a sync node. */
+    writerUrl(): Promise<string>;
+    /** Register a callback fired once, when this node is promoted from sync to writer. */
+    onPromoted(cb: () => void): void;
+    /** The current frontier-lag reading (D5 health observability): `min(frontier_ts)` across shards,
+     *  how long it's been stuck (ms), and the pinning shard. Null before the first frontier beat, or if
+     *  no shard rows exist yet. */
+    frontierStats(): FrontierStats | null;
+    /**
+     * Group-commit counters (Fleet B4, T4 health observability): `EmbeddedRuntime.groupCommitStats()`'s
+     * aggregate reading plus a derived `flushesPerSec` — a rolling delta between successive calls
+     * (`(flushCount now - flushCount at the prior call) / elapsed seconds`), the simplest honest
+     * throughput signal without a dedicated timer. The first call after boot (or after any gap) has no
+     * prior sample, so it reports 0 for that one call. Structurally all-zero when `HELIPOD_GROUP_
+     * COMMIT` is off (the underlying counters are never touched on the single-commit path) — never
+     * null, unlike `frontierStats` (no "before the first beat" gating applies here).
+     */
+    groupCommitStats(): {
+        lastBatchSize: number;
+        maxBatchSize: number;
+        flushCount: number;
+        flushesPerSec: number;
+    };
+    /** Per-shard ownership (B2b, D1): does THIS node currently hold `shardId`'s write lease? Backs
+     *  the `/_fleet/run` single-hop guard (`packages/cli`'s `http-handler.ts`) — delegates straight to
+     *  `WriteForwarder.isLocalWriter`, the same live held-set view the executor's own per-shard
+     *  router and `relinquish()` consult. */
+    isLocalWriter(shardId: ShardId): boolean;
+    /**
+     * Effectively-once forwarding (Fleet B3, D3): read back `key`'s `fleet_idempotency` row for a
+     * replay decision. Delegates to `LeaseManager.lookupIdempotency` — the SAME control table the
+     * commit guard (`installCommitGuard`) writes into, on the SAME `client`, so a lookup immediately
+     * after a catch always sees a just-committed sibling's row. `packages/cli`'s `/_fleet/run`
+     * handler calls this BOTH before running (SELECT-first) and after catching a unique_violation on
+     * this table (the concurrent-duplicate race's loser re-selecting the winner's row).
+     */
+    idempotencyLookup(key: string): Promise<IdempotencyReplay | null>;
+    /** Best-effort post-run recording of a forwarded mutation's return value — see
+     *  `LeaseManager.recordIdempotencyValue`. */
+    idempotencyRecordValue(key: string, value: JSONValue): Promise<void>;
+    stop(): Promise<void>;
+}
+/** The createEmbeddedRuntime option deltas the caller threads through `bootProject`. `store` is the
+ *  node's RUNTIME (WRITE) store: the writable Postgres store for a writer, the `SwitchableDocStore`
+ *  (over the local replica, until promotion swaps in the Postgres store) for a single-writer sync
+ *  node, and — for a HYBRID (multi-writer) node — ALWAYS the Postgres store (mutations commit to the
+ *  primary), paired with `queryStore` for the replica-backed read path. */
+interface FleetRuntimeOptions {
+    store: DocStore;
+    writeRouter: WriteRouter;
+    deferDrivers: boolean;
+    fanoutAdapter?: EmbeddedWriteFanoutAdapter;
+    /** Number of shards this node's runtime runs (B2a). Threaded to `createEmbeddedRuntime`, which
+     *  builds ONE `ShardedTransactor` (N per-shard mutexes) over the pooled store instead of the
+     *  single-shard `SingleWriterTransactor` when >1 — so cross-shard commits run in parallel. */
+    numShards: number;
+    /**
+     * Fleet B3 hybrid nodes (D1) — the replica-backed QUERY store (the `SwitchableDocStore` over the
+     * local replica). Set ONLY on a hybrid (multi-writer) node: `store` (above) is the primary, where
+     * mutations commit, while queries/subscriptions read this replica store. `createEmbeddedRuntime`
+     * builds a separate query-path transactor + QueryRuntime over it, and routes `observeTimestamp`
+     * (fed by this node's ReplicaTailer post-apply) to the query oracle so a query snapshot never
+     * exceeds the replica watermark. Absent → every query runs against `store` (single-writer/sync/
+     * non-fleet), byte-identical to before B3.
+     */
+    queryStore?: DocStore;
+    /**
+     * Receipted Outbox (verdict §(c) placement) — the AUTHORITATIVE receipts store the Connect
+     * handshake classifies/prunes against. Set to the PRIMARY (`pgStore`) on a SYNC node so the
+     * handshake never reads the local replica (which carries no `client_mutations`/`client_floors`
+     * receipts → spurious `known:false` resets / false kill-after-commit failures). Threaded straight
+     * into `createEmbeddedRuntime`. Absent → the runtime uses `store` (writer boots, where `store` IS
+     * the primary; and every non-fleet deployment). See `EmbeddedRuntimeOptions.receiptsStore`.
+     */
+    receiptsStore?: DocStore;
+    /**
+     * Fleet B3 hybrid RYOW (D2) — awaited in the runtime's serial fan-out `drain()` before a local
+     * commit's subscription re-runs, so those re-runs (reading the replica) don't observe the commit's
+     * absence on a replica that hasn't applied it yet. Wired to `forwarder.waitForReplica`. Set only on
+     * a hybrid node. Absent → the drain is byte-identical to before B3.
+     */
+    beforeNotify?: (commitTs: bigint) => Promise<void>;
+    /**
+     * Fleet B4 (T4): group commit — resolved once via `groupCommitEnabled()` (above) and threaded
+     * uniformly onto every boot shape (writer/sync × single-writer/hybrid). Unset/false →
+     * `createEmbeddedRuntime` builds the byte-identical single-commit path, as shipped.
+     */
+    groupCommit?: boolean;
+    /**
+     * Triggers D1 — the stable-prefix accessor for `DriverContext.readLog`. In a fleet, N per-shard
+     * commit connections land timestamps out of order, so the log tail is gap-free ONLY below
+     * `min(shard_leases.frontier_ts)` (the fenced fleet frontier). Wired here to exactly that read (the
+     * same `readAllFrontiers`-min the frontier-lag monitor uses), so `readLog` never surfaces — nor
+     * skips — a change above an in-flight gap. Threaded onto every boot shape; consulted only when a
+     * driver runs (post-promotion on a sync node), by which point `store` points at the primary.
+     */
+    stablePrefix?: () => Promise<bigint | null>;
+    /**
+     * Receipted Outbox — receipts-guard ownership handoff. Always `true` for a fleet node: fleet owns
+     * installing the `clientReceiptsGuard()` exactly-once barrier on the CONCRETE Postgres store in
+     * `armWriter` (before the epoch fence, release-on-re-arm), NOT on `store` — which for a sync node is
+     * a `SwitchableDocStore` the runtime would register the guard on, only for it to silently vanish on
+     * the promotion swapTo (leaving a promoted single-writer node's client mutations un-receipted → a
+     * resent (clientId, seq) re-executes). Threaded to `createEmbeddedRuntime` so its `create()` skips
+     * its own registration. See `EmbeddedRuntimeOptions.externalReceiptsGuard` and `armWriter`.
+     */
+    externalReceiptsGuard?: boolean;
+}
+interface FleetPrep {
+    client: NodePgClient;
+    /** The Postgres store. Writer: the runtime store (writable). Sync: the tail source + promotion
+     *  swap target (read-only until promoted) — NOT the runtime store (`runtimeOptions.store` is the
+     *  `SwitchableDocStore` over the local replica for a sync node). */
+    pgStore: PostgresDocStore;
+    /** The local file-backed replica the runtime reads queries through, and the switchable wrapper it
+     *  points at. Present for a single-writer SYNC boot (runtime store = the switchable) AND for a
+     *  HYBRID (multi-writer) boot of EITHER role (the switchable is `runtimeOptions.queryStore`, the
+     *  read path beside the primary write store). Absent only for a single-writer WRITER boot (no
+     *  replica — it reads the primary). */
+    replica?: SqliteDocStore;
+    switchable?: SwitchableDocStore;
+    /** The on-disk path of `replica`, threaded through to `startFleetNode` so its C7
+     *  `reconcileReplicaIdentity` call (deferred there — see that function's doc comment) can rebuild
+     *  the file in place if needed. Present whenever `replica` is (sync boot, or any hybrid boot). */
+    replicaPath?: string;
+    lease: LeaseManager;
+    forwarder: WriteForwarder;
+    role: "sync" | "writer";
+    /** The shard count decided at boot — threaded through to `startFleetNode` (acquire-all loop,
+     *  all-rows seed, per-shard commit guard, idle closer) and the tailer's `count(*) < N` ready gate. */
+    numShards: number;
+    runtimeOptions: FleetRuntimeOptions;
+}
+/**
+ * Decide writer-vs-sync BEFORE the runtime is constructed: one `tryAcquire()` after the lease
+ * table exists. This must run before `bootProject` because the acquire result determines the
+ * store's writability, the fan-out adapter, whether drivers are deferred, and the forwarder's
+ * starting role — all of which are `createEmbeddedRuntime` inputs.
+ */
+declare function prepareFleetNode(deps: {
+    databaseUrl: string;
+    advertiseUrl: string;
+    adminKey: string;
+    /** The serve data dir — the sync node's local replica is created at `<dataDir>/fleet-replica.db`. */
+    dataDir: string;
+    /** Lease TTL in ms — the single knob the whole failover clock scales from (see `fleetProbeMs`/
+     *  `fleetAcquireRetryMs`). Threaded from serve's fleet config, which reads
+     *  `HELIPOD_FLEET_LEASE_TTL_MS` (ops/test tuning; the wedged-writer E2E uses 4000). Default 15000
+     *  reproduces the historical constants exactly. */
+    leaseTtlMs?: number;
+    /** Number of shards this fleet runs (B2a). This task threads it as a plain parameter (default 8);
+     *  T5 owns the persist-once/`HELIPOD_FLEET_SHARDS`/mismatch-fail-fast story. Drives the commit
+     *  pool's connection set, the acquire-all loop, and the runtime's `ShardedTransactor`. */
+    numShards?: number;
+}): Promise<FleetPrep>;
+interface StartFleetNodeDeps {
+    client: NodePgClient;
+    /** The Postgres store — the tail source + promotion swap target (sync), or the live runtime store
+     *  (writer, in which case `startFleetNode` just returns handles). */
+    pgStore: PostgresDocStore;
+    runtime: EmbeddedRuntime;
+    lease: LeaseManager;
+    forwarder: WriteForwarder;
+    /** Sync only: the local replica the tailer applies onto, and the switchable the runtime reads
+     *  through (swapped to the Postgres store on promotion). Absent/ignored for a writer boot. */
+    replica?: SqliteDocStore;
+    switchable?: SwitchableDocStore;
+    /** Sync only: `replica`'s on-disk path — needed here (not just in `prepareFleetNode`) because the
+     *  C7 `reconcileReplicaIdentity` check now runs in THIS function, right before `tailer.start()`. */
+    replicaPath?: string;
+    /** Process-exit indirection (C4/C5). Injected so tests observe exits instead of killing the runner;
+     *  defaults to `console.error` + `process.exit(1)`. Fires on writer lease loss (the lease monitor)
+     *  and on a failed promotion step. */
+    onExit?: (reason: string) => void;
+    /** Number of shards this node runs (B2a) — from `prepareFleetNode`'s decision (`FleetPrep.numShards`).
+     *  The writer/promotion arming acquires all N shard leases (slots 1…N-1 beyond the default), seeds
+     *  all N frontiers before ready, and drives the idle-shard closer over them. Defaults to 1 so an
+     *  older single-shard call site (the B1 lifecycle tests that drive `startFleetNode` directly) is
+     *  byte-identical — one shard, one lease, one frontier. */
+    numShards?: number;
+}
+/** The seam the C5 promotion wrap touches — narrow structural spies over the promotion sequence,
+ *  monitor start, promoted-callback fan-out, and the exit indirection. */
+interface PromotionRunDeps {
+    /** The CRITICAL PROMOTION ORDER (`promoteFleetNode`), as a thunk. */
+    promote: () => Promise<void>;
+    /** Start the writer lease monitor — this node is now the writer and must self-exit on lease loss. */
+    startMonitor: () => void;
+    /** Notify the http layer to drop its writer proxy. */
+    firePromoted: () => void;
+    /** Exit indirection — any promotion-step failure routes here (a half-promoted node must not linger). */
+    onExit: (reason: string) => void;
+}
+/**
+ * C5 promotion error policy: wrap the promotion sequence so ANY step failure is caught, logged, and
+ * turned into an exit rather than left as a silent unhandled rejection with the node stuck
+ * half-promoted (writable pg store, un-swapped runtime, no drivers). On success the lease monitor is
+ * started (writer self-exit is now armed) and the http layer is told to drop its proxy. Fires exit at
+ * most once by construction — it's invoked once per node (guarded by the caller's `promoting` flag).
+ */
+declare function runPromotion(deps: PromotionRunDeps): Promise<void>;
+/**
+ * Install the epoch-fenced commit guard (Fenced Frontier B1, D3) on `pgStore`. Runs inside every
+ * `commitWrite` transaction, after the row inserts, before COMMIT — the SAME row as the lease
+ * (`shard_leases`) advances the durable-commit frontier chain (`prev_ts := frontier_ts, frontier_ts
+ * := commitTs`) predicated on THIS node's epoch still being current, so frontier publication,
+ * fencing, and the lease are one row with zero extra round-trips. `lease.currentEpoch()` is read
+ * LIVE on every commit (not a snapshot taken at install time) so a later re-promotion's epoch bump
+ * is honored automatically. Zero rows updated (a stale/superseded epoch) throws `FencedError`, which
+ * aborts the whole transaction — AND calls `onFenced(shardId, reason)` before throwing so the caller
+ * can react (B2b, D2: `startFleetNode` wires this straight to `relinquish(shardId, reason)` — drop
+ * JUST this shard, keep serving everything else — never to a whole-node exit; see `relinquish` below
+ * for why `LeaseMonitor.fenced()`/`onExit` are NOT reached from here anymore). Called at writer boot
+ * AND on promotion success — see the two call sites below.
+ *
+ * Returns the `addCommitGuard` unregister handle (Receipted Outbox decision 2 — the guard
+ * slot→chain migration). `armWriter` re-arms on EVERY promotion; a caller that calls
+ * `installCommitGuard` again WITHOUT first calling the PRIOR returned unregister function stacks a
+ * duplicate epoch-fence guard on the chain — duplicate frontier bumps + duplicate
+ * `fleet_idempotency` INSERTs at the same ts, so every subsequent forwarded commit self-PK-collides
+ * and aborts. See `armWriter`'s `unregisterCommitGuard` handling below for the required pattern.
+ */
+declare function installCommitGuard(pgStore: PostgresDocStore, lease: LeaseManager, onFenced: (shardId: ShardId, reason: string) => void): () => void;
+/** The narrow seams `relinquish` needs — deliberately structural (not the concrete `NodePgClient`) so
+ *  it's unit-testable with a stub, and reusable by T4's balancer without depending on `startFleetNode`'s
+ *  internal closures. */
+interface RelinquishDeps {
+    lease: LeaseManager;
+    /** `releaseShardLock` is consulted defensively (`?.`) — absent on a poolless/PGlite client, though
+     *  every real B2b fleet node runs in pool mode and always has it. */
+    client: {
+        releaseShardLock?: (slot: number) => Promise<void>;
+    };
+    /** Ordered shard list (index = slot) — how `shardId`'s per-slot advisory lock is found for
+     *  `releaseShardLock`. The same list `prepareFleetNode`/`startFleetNode` derive via `shardIdList`. */
+    shards: readonly ShardId[];
+    /** Structured-log seam, defaults to `console.error`. Tests inject a spy. */
+    log?: (msg: string) => void;
+    /**
+     * Invoked when the DEFAULT shard is relinquished (B2b, D5 — "drivers follow the default shard"):
+     * `startFleetNode` wires this to `runtime.stopDriversOnly()`, so the moment this node loses the
+     * default ring the scheduler/workflow/cron/reaper drivers go quiet (a different node now owns that
+     * ring). Optional — the balancer/relinquish unit tests that don't care about drivers omit it, in
+     * which case relinquishing the default shard just drops the shard with no driver side effect.
+     */
+    onDefaultRelinquished?: () => void;
+}
+/**
+ * Per-shard relinquish dispatcher (Fenced Frontier B2b, D2): the reduction a `FencedError` on shard
+ * `s` gets now — "drop `s`, keep serving everything else" — instead of B1/B2a's "kill the node".
+ * Routed to from the commit guard's `onFenced` (a fence discovered mid-commit — that commit itself
+ * still aborts and propagates `FencedError` to its caller, OCC-retryable; relinquish is the SIDE
+ * EFFECT, not a swallow), the batched heartbeat's `fencedShardIds` (a fence discovered on the probe
+ * beat), and a per-shard commit-connection loss.
+ *
+ * Idempotent per shard: `lease.currentEpoch(shardId) === null` means this shard is already forgotten
+ * (a prior relinquish call, or a shard this node never held) — a silent no-op, so callers never need
+ * to track "have I already relinquished this" themselves.
+ *
+ *  1. `lease.forgetShard(shardId)` — drops the held-epoch entry, so the commit guard's "no acquired
+ *     epoch" branch fences any straggler commit on `s` cleanly, and `heartbeatAll`/`closeIdleFrontiers`
+ *     stop touching it.
+ *  2. Release `s`'s per-slot advisory lock (`PgClient.releaseShardLock`) — UNLESS `opts.connectionLost`:
+ *     a dead commit connection already released its session-scoped lock the instant the backend went
+ *     away, so there is nothing left to release (and no live connection to run the unlock query on).
+ *  3. Log one structured line. Relinquishing the DEFAULT shard additionally WARNS that drivers keep
+ *     running (scheduler/workflow/cron/reaper stay armed on this node) until a later task wires
+ *     `stopDriversOnly` (D5) — driver stop/start is deliberately NOT built here.
+ *
+ * Deliberately does NOT touch `LeaseMonitor` and never calls `onExit` — the whole point of B2b is that
+ * a per-shard fence must no longer escalate to a whole-node exit. `LeaseMonitor` stays reserved for
+ * pinned-connection loss and probe exhaustion (definitive WHOLE-NODE loss); see `startFleetNode`.
+ */
+declare function relinquish(deps: RelinquishDeps, shardId: ShardId, reason: string, opts?: {
+    connectionLost?: boolean;
+}): void;
+/**
+ * Acquire one non-default shard's lease as the writer (B2a acquire-all). `tryAcquire(shardId, slot)`
+ * epoch-bumps that shard's row (fencing any prior holder) and takes its per-shard advisory lock. If
+ * the lock is still held by a wedged prior holder AND that shard's lease has expired, fence + evict +
+ * terminate its backend (the same fencing-first eviction the default-shard acquire loop uses) and
+ * retry. Bounded by a generous deadline (~10 lease TTLs): the common failover frees every slot at once
+ * when the default-shard loop terminates the whole wedged node, so this normally succeeds on the first
+ * try (fresh boot) or right after one eviction. Exceeding the deadline throws → promotion/boot fails →
+ * the node exits and rejoins fresh, never silently running as a partial-shard writer.
+ */
+declare function acquireShardAsWriter(lease: LeaseManager, shardId: ShardId, slot: number, retryMs: number, seedFrontierFromDocuments?: boolean): Promise<void>;
+/**
+ * Pure throughput derivation for group-commit health (Fleet B4, T4): a rolling delta of
+ * `flushCount` between two `groupCommitStats()` reads, over the elapsed wall-clock time — the
+ * simplest honest `flushesPerSec` signal without a dedicated timer/interval. `prevReadMs === null`
+ * (no prior sample — the first read after boot, or after any gap) and a non-positive elapsed time
+ * (a clock that hasn't advanced, or moved backward) both report 0 rather than a division artifact.
+ * Extracted as a standalone pure function so it's unit-testable without booting a fleet node.
+ */
+declare function deriveFlushesPerSec(prevReadMs: number | null, prevFlushCount: number, nowMs: number, nowFlushCount: number): number;
+/**
+ * Wire the running fleet node. A writer node is already fully live (promoted in `prepareFleetNode`,
+ * drivers started at `create()`) — it just gets handles. A sync node starts the replica tailer (its
+ * `start()` catch-up is the node's ready gate) and the lease acquire loop, and promotes on acquire
+ * via `promoteFleetNode`.
+ */
+declare function startFleetNode(deps: StartFleetNodeDeps): Promise<FleetHandles>;
+
+/**
+ * `StablePrefixTs` (Fenced Frontier B1, D6) — a compile-time brand over `bigint` marking a
+ * timestamp as a member of the FENCED FRONTIER: the stable prefix of the primary's MVCC log that
+ * `ReplicaTailer` is allowed to pull from, per D5. A raw `bigint` (e.g. `primary.maxTimestamp()`,
+ * which reports the log's live high-water mark INCLUDING any commit that raced past the last fence
+ * check) is NOT a `StablePrefixTs` — only a value read straight off `shard_leases.frontier_ts`, or
+ * a watermark previously derived from one, is.
+ *
+ * This is deliberately narrow: it brands ONLY `ReplicaTailer`'s internal pull target (`F`) and its
+ * own watermark (`wm`), which must never advance past `F` (D5's "wm never exceeds F" invariant).
+ * It does NOT brand `waitFor`'s public `ts` parameter — that's a caller-supplied `commitTs` (a raw
+ * log position by nature, e.g. forwarded from `WriteForwarder`'s `/_fleet/run` response), and RYOW
+ * correctness only needs `wm >= ts`, which is a plain bigint comparison regardless of which side is
+ * branded. Branding that parameter too would just force every call site to launder a raw commitTs
+ * through the constructor for no safety benefit.
+ *
+ * The sole constructor, `stablePrefixFromFrontier`, is intentionally the ONLY way to produce one —
+ * assigning a raw `bigint` to a `StablePrefixTs`-typed binding without going through it is a
+ * compile error (see `replica-tailer.test.ts`'s `@ts-expect-error` cases). At runtime this is a
+ * plain `bigint`; the brand (`__stablePrefix`) exists purely in the type system and costs nothing.
+ */
+type StablePrefixTs = bigint & {
+    readonly __stablePrefix: unique symbol;
+};
+/**
+ * The sole constructor. Call this ONLY where a value is actually a frontier — a fresh read of
+ * `shard_leases.frontier_ts` (via the tailer's `CommitChannelClient`), or a watermark already
+ * derived from a prior `StablePrefixTs` (e.g. the replica's own persisted `maxTimestamp()` on
+ * restart, which IS this node's last-applied frontier). Do not use this to launder an arbitrary
+ * `bigint` (e.g. `primary.maxTimestamp()`, or a document's raw `ts`) into the brand — that value is
+ * NOT guaranteed to be a durably-fenced, dense prefix and defeats the whole point of the type.
+ */
+declare function stablePrefixFromFrontier(raw: bigint): StablePrefixTs;
+
+/**
+ * The offline fleet reshard tool (B5 Part 1, Task 9.1): change a STOPPED Postgres fleet's shard
+ * count N→M by updating the persist-once `fleet:numShards` global + creating/deleting
+ * `shard_leases` lane rows — atomically, in one transaction — and NOTHING else. Because a shard is
+ * a logical commit-serialization lane over one shared store (`documents.shard_id` is decorative;
+ * routing always recomputes `shardIdForKeyValue(key, numShards)` fresh), resharding moves no rows:
+ * only which lane FUTURE commits for a key serialize through changes. See
+ * `docs/dev/research/write-sharding/b5-reshard-and-object-storage.md` (Part 1) and
+ * `docs/superpowers/plans/2026-02-20-fleet-reshard-b5.md` for the full design.
+ *
+ * Safety rests on the STOPPED-FLEET precondition (no `--force`): a live node makes the old-N and
+ * new-M epochs potentially overlap in time, which is out of scope (needs an epoch-fence vocabulary
+ * this tool doesn't have — see the plan's "online reshard" scope boundary). A quiesced fleet makes
+ * the two epochs strictly non-overlapping, so changing a key's lane between them is as safe as any
+ * config change to a stopped system.
+ *
+ * `F = min(frontier_ts)` is monotone across a reshard: new lanes are seeded at `MAX(ts)` (never
+ * below the true high-water mark — the same F1 seed `LeaseManager.setup()`/`tryAcquire()` use, see
+ * `frontierSeedExpr` in `./lease.ts`), retained lanes are GREATEST-bumped up to that same floor
+ * (never lowered — a documented, safe deviation from "retained rows untouched": raise-only can
+ * never regress F, and it proactively heals a lane whose frontier legitimately lags `MAX(ts)` after
+ * a crash stop — no `selfFence` ran, so nothing bumped it since the last idle-closer beat — the
+ * same healing a node boot's `seedFrontierAll` would eventually do), and deleting a lane can only
+ * raise or hold `min(frontier_ts)`, never lower it. Net effect: EVERY post-reshard lane is
+ * `>= MAX(ts)`, making the post-verify's F1 check a true post-condition rather than a best-effort one.
+ */
+
+/** The `persistence_globals` key the resolved shard count is stamped under — byte-identical to
+ *  `packages/cli/src/boot.ts`'s `NUM_SHARDS_GLOBAL_KEY` (kept as an independent literal here: the
+ *  ee `@helipod/fleet` package has no dependency on core `packages/cli`, mirroring the same
+ *  independent-literal choice `boot.ts`'s own doc comment makes for `DEFAULT_NUM_SHARDS`). */
+declare const NUM_SHARDS_GLOBAL_KEY = "fleet:numShards";
+/** Thrown when `reshardFleet` is asked to run against a fleet with any live `fleet_nodes` or
+ *  `shard_leases.writer_url` row — the hard stopped-fleet precondition, no `--force` escape hatch.
+ *  `liveUrls` names every live node/writer URL found, so the operator error is actionable. */
+declare class ReshardFleetLiveError extends Error {
+    readonly liveUrls: string[];
+    constructor(liveUrls: string[]);
+}
+/** Thrown when the post-commit verification pass finds the reshard did not land as expected —
+ *  should be impossible (a guard against a logic bug, not an expected operational outcome). */
+declare class ReshardVerificationError extends Error {
+    constructor(message: string);
+}
+/** Thrown when `reshardFleet` is pointed at a Postgres database that has never run a fleet on it —
+ *  no `shard_leases`/`fleet_nodes` tables. Without this pre-gate, the live-fleet gate query below
+ *  would throw a raw `relation "fleet_nodes" does not exist`, which reads like an internal SQL bug
+ *  rather than the operator-actionable "you haven't booted a fleet here yet" that it actually is. */
+declare class ReshardNotAFleetError extends Error {
+    constructor();
+}
+interface ReshardResult {
+    previousShards: number;
+    newShards: number;
+    /** Shard ids newly created (present in the target set, absent from the prior lane set). */
+    created: string[];
+    /** Shard ids removed (present in the prior lane set, absent from the target set). Never includes
+     *  `"default"` — it is a member of `shardIdList(M)` for every `M >= 1` and so can never be a
+     *  target-set omission. */
+    deleted: string[];
+    /** `min(frontier_ts)` across every post-reshard lane, as a decimal string (frontier_ts is a
+     *  Postgres BIGINT — carried as a string rather than risk a JS-number precision loss). */
+    frontierFloor: string;
+}
+/**
+ * Change a STOPPED Postgres fleet's shard count from whatever it currently is to `opts.targetShards`.
+ * See the module doc comment for the full safety argument. Steps (verbatim to the plan, plus the
+ * not-a-fleet pre-gate):
+ *   1. validate `targetShards >= 1`
+ *   2. probe that this is actually a fleet store (`shard_leases`/`fleet_nodes` exist) —
+ *      `ReshardNotAFleetError` otherwise, before the next step's raw SQL can throw an opaque
+ *      "relation does not exist"
+ *   3. refuse if any `fleet_nodes`/`shard_leases` row is live (`ReshardFleetLiveError`)
+ *   4. read the current lane set + the current `fleet:numShards` global
+ *   5. one transaction: upsert the global, INSERT new lanes (seeded at `MAX(ts)`), DELETE surplus
+ *      lanes, then GREATEST-bump every remaining lane's frontier up to that same `MAX(ts)` floor
+ *      (heals a retained lane that crash-stopped below it — see the module doc comment)
+ *   6. post-verify (count/set/frontier-floor/global) — `ReshardVerificationError` on any mismatch
+ */
+declare function reshardFleet(client: PgClient, opts: {
+    targetShards: number;
+}): Promise<ReshardResult>;
+
+declare const FLEET_VERSION = "0.0.0";
+
+export { type AppliedInvalidation, type BalancerLease, type CommitChannelClient, DEFAULT_NUM_SHARDS, DensityViolationError, FLEET_VERSION, FLEET_WRITER_SESSION_TIMEOUTS, FencedError, type FleetHandles, type FleetPrep, type FleetRuntimeOptions, FrontierMonitor, type FrontierStats, IDEMPOTENCY_VALUE_CAP_BYTES, type IdempotencyReplay, LeaseManager, type LeaseManagerOptions, LeaseMonitor, type LeaseMonitorDeps, type LeaseRow, type LeaseState, NUM_SHARDS_GLOBAL_KEY, NotifyingFanoutAdapter, type PromotionRunDeps, REPLICA_DB_FILENAME, type RelinquishDeps, ReplicaTailer, type ReplicaTailerOptions, type ReplicaWaiter, ReshardFleetLiveError, ReshardNotAFleetError, type ReshardResult, ReshardVerificationError, ShardLeaseBalancer, type ShardLeaseBalancerDeps, type StablePrefixTs, type StartFleetNodeDeps, SwitchableDocStore, WriteForwarder, type WriteForwarderOptions, acquireShardAsWriter, createAsyncChain, deriveFlushesPerSec, fleetApplicationName, fleetMultiWriterEnabled, groupCommitEnabled, installCommitGuard, prepareFleetNode, relinquish, rendezvousOwner, rendezvousWeight, reshardFleet, runPromotion, stablePrefixFromFrontier, startFleetNode };