@helipod/fleet 0.1.0

package/dist/index.js

@@ -0,0 +1,2514 @@
+// src/lease.ts
+import { DEFAULT_SHARD } from "@helipod/id-codec";
+var SHARD_ID = DEFAULT_SHARD;
+var DEFAULT_LEASE_TTL_MS = 15e3;
+var DEFAULT_RETRY_MS = 2e3;
+var IDEMPOTENCY_VALUE_CAP_BYTES = 64 * 1024;
+var IDEMPOTENCY_TTL_INTERVAL = "1 hour";
+function toBigIntOrZero(v) {
+  if (v === null || v === void 0) return 0n;
+  return typeof v === "bigint" ? v : BigInt(v);
+}
+function isLockTimeoutError(e) {
+  if (e && typeof e === "object") {
+    if (e.code === "55P03") return true;
+    const msg = e.message;
+    if (typeof msg === "string" && /lock[_ ]?timeout|lock_not_available/i.test(msg)) return true;
+  }
+  return false;
+}
+function rowToLeaseRow(row) {
+  return {
+    epoch: row.epoch,
+    writerUrl: row.writer_url,
+    writerAppName: row.writer_app_name ?? null,
+    expiresAt: row.expires_at,
+    frontierTs: toBigIntOrZero(row.frontier_ts),
+    prevTs: toBigIntOrZero(row.prev_ts)
+  };
+}
+var LeaseManager = class {
+  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`. */
+  advertiseUrl;
+  applicationName;
+  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. */
+  ttlMs;
+  /** `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. */
+  ttlMsSql;
+  timer = null;
+  stopped = false;
+  /** 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. */
+  lastEpochByShard = /* @__PURE__ */ new Map();
+  constructor(client, opts) {
+    this.client = client;
+    this.advertiseUrl = opts.advertiseUrl;
+    this.applicationName = opts.applicationName ?? null;
+    this.retryMs = opts.retryMs ?? DEFAULT_RETRY_MS;
+    this.ttlMs = opts.ttlMs ?? DEFAULT_LEASE_TTL_MS;
+    const rounded = Math.round(this.ttlMs);
+    this.ttlMsSql = Number.isFinite(rounded) && rounded > 0 ? rounded : DEFAULT_LEASE_TTL_MS;
+  }
+  /**
+   * 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). */
+  async ddl(stmt) {
+    try {
+      await this.client.query(stmt);
+    } catch (e) {
+      const code = e?.code;
+      if (code !== "23505" && code !== "42P07" && code !== "42710") throw e;
+    }
+  }
+  async setup(shardIds = [], documentsExist = false) {
+    await this.ddl(`
+      CREATE TABLE IF NOT EXISTS shard_leases (
+        shard_id        TEXT PRIMARY KEY,
+        epoch           BIGINT NOT NULL,
+        writer_url      TEXT,
+        writer_app_name TEXT,
+        expires_at      TIMESTAMPTZ NOT NULL,
+        frontier_ts     BIGINT NOT NULL DEFAULT 0,
+        prev_ts         BIGINT NOT NULL DEFAULT 0
+      )
+    `);
+    await this.ddl(`
+      CREATE TABLE IF NOT EXISTS fleet_nodes (
+        advertise_url TEXT PRIMARY KEY,
+        epoch         BIGINT NOT NULL,
+        expires_at    TIMESTAMPTZ NOT NULL
+      )
+    `);
+    await this.ddl(`
+      CREATE TABLE IF NOT EXISTS fleet_idempotency (
+        key        TEXT PRIMARY KEY,
+        commit_ts  BIGINT NOT NULL,
+        value_json TEXT,
+        oversized  BOOLEAN NOT NULL DEFAULT false,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      )
+    `);
+    if (shardIds.length === 0) return;
+    const frontierSeed = this.frontierSeedExpr(documentsExist);
+    const params = [];
+    const values = shardIds.map((shardId, i) => {
+      params.push(shardId);
+      return `($${i + 1}, 0, NULL, NULL, now(), ${frontierSeed}, 0)`;
+    });
+    await this.client.query(
+      `INSERT INTO shard_leases (shard_id, epoch, writer_url, writer_app_name, expires_at, frontier_ts, prev_ts)
+       VALUES ${values.join(", ")}
+       ON CONFLICT (shard_id) DO NOTHING`,
+      params
+    );
+  }
+  /**
+   * 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.
+   */
+  frontierSeedExpr(documentsExist) {
+    return documentsExist ? `(SELECT COALESCE(MAX(ts), 0) FROM documents)` : `0`;
+  }
+  /**
+   * 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`.
+   */
+  async heartbeatPresence() {
+    await this.client.query(
+      `INSERT INTO fleet_nodes (advertise_url, epoch, expires_at)
+       VALUES ($1, 1, now() + interval '${this.ttlMsSql} milliseconds')
+       ON CONFLICT (advertise_url) DO UPDATE SET
+         epoch = fleet_nodes.epoch + 1,
+         expires_at = now() + interval '${this.ttlMsSql} milliseconds'`,
+      [this.advertiseUrl]
+    );
+  }
+  /**
+   * 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.
+   */
+  async liveNodes() {
+    const rows = await this.client.query(
+      `SELECT advertise_url AS url FROM fleet_nodes WHERE expires_at >= now()
+       UNION
+       SELECT writer_url AS url FROM shard_leases WHERE writer_url IS NOT NULL AND expires_at >= now()`
+    );
+    return rows.map((r) => r.url).filter((u) => typeof u === "string" && u.length > 0);
+  }
+  /**
+   * 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.
+   */
+  async readShardOwnership() {
+    const rows = await this.client.query(
+      `SELECT shard_id, writer_url, (expires_at < now()) AS expired FROM shard_leases`
+    );
+    const map = /* @__PURE__ */ new Map();
+    for (const r of rows) {
+      map.set(r.shard_id, {
+        writerUrl: r.writer_url ?? null,
+        expired: r.expired === true
+      });
+    }
+    return map;
+  }
+  /**
+   * 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).
+   */
+  async selfFence(shardId) {
+    const epoch = this.currentEpoch(shardId);
+    if (epoch === null) return;
+    await this.client.query(
+      `UPDATE shard_leases SET
+         epoch = epoch + 1,
+         writer_url = NULL,
+         writer_app_name = NULL,
+         frontier_ts = GREATEST(frontier_ts, (SELECT nextval('helipod_ts')))
+       WHERE shard_id = $1 AND epoch = $2`,
+      [shardId, epoch]
+    );
+  }
+  /**
+   * 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 = SHARD_ID) {
+    return this.lastEpochByShard.get(shardId) ?? 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() {
+    return [...this.lastEpochByShard].map(([shardId, epoch]) => ({ shardId, epoch }));
+  }
+  /**
+   * 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) {
+    this.lastEpochByShard.delete(shardId);
+  }
+  /**
+   * 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.
+   */
+  async tryAcquire(shardId = SHARD_ID, slot = 0, seedFrontierFromDocuments = false) {
+    const acquired = this.client.tryAcquireShardLock ? await this.client.tryAcquireShardLock(slot) : await this.client.tryAcquireWriterLock();
+    if (!acquired) return null;
+    const frontierSeed = this.frontierSeedExpr(seedFrontierFromDocuments);
+    const rows = await this.client.query(
+      `INSERT INTO shard_leases (shard_id, epoch, writer_url, writer_app_name, expires_at, frontier_ts, prev_ts)
+       VALUES ($1, 1, $2, $3, now() + interval '${this.ttlMsSql} milliseconds', ${frontierSeed}, 0)
+       ON CONFLICT (shard_id) DO UPDATE SET
+         epoch = shard_leases.epoch + 1,
+         writer_url = $2,
+         writer_app_name = $3,
+         expires_at = now() + interval '${this.ttlMsSql} milliseconds'
+       RETURNING epoch, writer_url, frontier_ts`,
+      [shardId, this.advertiseUrl, this.applicationName]
+    );
+    const row = rows[0];
+    if (!row) throw new Error("shard_leases upsert returned no row");
+    const state = {
+      epoch: row.epoch,
+      writerUrl: row.writer_url,
+      // On a re-acquire this is the frontier an interim owner left; on a fresh INSERT it's the seed
+      // (`frontierSeed` — store max or 0). Feeds `runtime.observeWriteTimestamp` at every acquisition.
+      frontierTs: toBigIntOrZero(row.frontier_ts)
+    };
+    this.lastEpochByShard.set(shardId, state.epoch);
+    return state;
+  }
+  /**
+   * 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.
+   */
+  async heartbeat(epoch, shardId = SHARD_ID) {
+    const rows = await this.client.query(
+      `UPDATE shard_leases SET expires_at = now() + interval '${this.ttlMsSql} milliseconds'
+       WHERE shard_id = $1 AND epoch = $2
+       RETURNING epoch`,
+      [shardId, epoch]
+    );
+    return rows.length;
+  }
+  /**
+   * 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.
+   */
+  async heartbeatAll() {
+    const pairs = this.heldPairs();
+    if (pairs.length === 0) return { updated: 0, expected: 0, fencedShardIds: [] };
+    const { clause, params } = this.tupleInClause(pairs, 0);
+    const rows = await this.client.query(
+      `UPDATE shard_leases SET expires_at = now() + interval '${this.ttlMsSql} milliseconds'
+       WHERE (shard_id, epoch) IN (${clause})
+       RETURNING shard_id`,
+      params
+    );
+    const renewedIds = new Set(rows.map((r) => r.shard_id));
+    const fencedShardIds = pairs.filter((p) => !renewedIds.has(p.shardId)).map((p) => p.shardId);
+    return { updated: rows.length, expected: pairs.length, fencedShardIds };
+  }
+  /**
+   * 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.
+   */
+  async isExpired(shardId = SHARD_ID) {
+    const rows = await this.client.query(
+      `SELECT 1 FROM shard_leases WHERE shard_id = $1 AND expires_at < now()`,
+      [shardId]
+    );
+    return rows.length > 0;
+  }
+  /**
+   * 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).
+   */
+  async evictExpired(shardId = SHARD_ID) {
+    try {
+      return await this.client.transaction(async (tx) => {
+        await tx.query(`SET LOCAL lock_timeout = '2s'`);
+        const sel = await tx.query(
+          `SELECT writer_app_name FROM shard_leases WHERE shard_id = $1 AND expires_at < now() FOR UPDATE`,
+          [shardId]
+        );
+        if (sel.length === 0) return { fenced: false, oldAppName: null };
+        const oldAppName = sel[0].writer_app_name ?? null;
+        await tx.query(
+          `UPDATE shard_leases SET
+             epoch = epoch + 1,
+             writer_url = NULL,
+             writer_app_name = NULL,
+             frontier_ts = GREATEST(frontier_ts, (SELECT nextval('helipod_ts')))
+           WHERE shard_id = $1`,
+          [shardId]
+        );
+        return { fenced: true, oldAppName };
+      });
+    } catch (e) {
+      if (isLockTimeoutError(e)) return { fenced: false, oldAppName: null };
+      throw e;
+    }
+  }
+  /**
+   * 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.
+   */
+  async terminateBackend(appName) {
+    await this.client.query(
+      `SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+       WHERE (application_name = $1 OR application_name LIKE $1 || '-commit-%') AND pid <> pg_backend_pid()`,
+      [appName]
+    );
+  }
+  /**
+   * 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.
+   */
+  async maybeEvictWedged() {
+    if (!await this.isExpired()) return;
+    const { fenced, oldAppName } = await this.evictExpired();
+    if (fenced && oldAppName !== null) await this.terminateBackend(oldAppName);
+  }
+  /** 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) {
+    this.stopped = false;
+    const schedule = () => {
+      if (this.stopped) return;
+      this.timer = setTimeout(attempt, this.retryMs);
+    };
+    const attempt = () => {
+      if (this.stopped) return;
+      void (async () => {
+        try {
+          const state = await this.tryAcquire();
+          if (this.stopped) return;
+          if (state) {
+            onAcquired(state);
+            return;
+          }
+          await this.maybeEvictWedged();
+        } catch {
+        }
+        schedule();
+      })();
+    };
+    this.timer = setTimeout(attempt, this.retryMs);
+  }
+  /** Cancels any pending acquireLoop() retry. */
+  stop() {
+    this.stopped = true;
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+  /**
+   * 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.
+   */
+  async seedFrontier(epoch, maxTs, shardId = SHARD_ID) {
+    await this.client.query(
+      `UPDATE shard_leases SET frontier_ts = GREATEST(frontier_ts, $1) WHERE shard_id = $2 AND epoch = $3`,
+      [maxTs, shardId, epoch]
+    );
+  }
+  /**
+   * 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.
+   */
+  async seedFrontierAll(maxTs) {
+    const pairs = this.heldPairs();
+    if (pairs.length === 0) return;
+    const { clause, params } = this.tupleInClause(pairs, 1);
+    await this.client.query(
+      `UPDATE shard_leases SET frontier_ts = GREATEST(frontier_ts, $1) WHERE (shard_id, epoch) IN (${clause})`,
+      [maxTs, ...params]
+    );
+  }
+  /**
+   * 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.
+   */
+  async closeIdleFrontiers(runExclusiveOnShard) {
+    const pairs = this.heldPairs();
+    const tsRows = await this.client.query(`SELECT nextval('helipod_ts') AS ts`);
+    const newTs = toBigIntOrZero(tsRows[0]?.ts);
+    for (const { shardId, epoch } of pairs) {
+      await runExclusiveOnShard(shardId, async () => {
+        await this.client.query(
+          `UPDATE shard_leases SET frontier_ts = GREATEST(frontier_ts, $1)
+           WHERE shard_id = $2 AND epoch = $3 AND frontier_ts < $1`,
+          [newTs, shardId, epoch]
+        );
+      });
+    }
+    return newTs;
+  }
+  /**
+   * 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.
+   */
+  async bumpOrphanFrontiers(ceiling) {
+    await this.client.query(
+      `UPDATE shard_leases SET frontier_ts = GREATEST(frontier_ts, $1)
+       WHERE writer_url IS NULL AND frontier_ts < $1`,
+      [ceiling]
+    );
+  }
+  /** 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). */
+  async read(shardId = SHARD_ID) {
+    const rows = await this.client.query(
+      `SELECT epoch, writer_url, writer_app_name, expires_at, frontier_ts, prev_ts
+       FROM shard_leases WHERE shard_id = $1`,
+      [shardId]
+    );
+    const row = rows[0];
+    if (!row) return null;
+    return rowToLeaseRow(row);
+  }
+  /** 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. */
+  async readAllFrontiers() {
+    const rows = await this.client.query(
+      `SELECT shard_id, frontier_ts FROM shard_leases ORDER BY frontier_ts ASC, shard_id ASC`
+    );
+    return rows.map((r) => ({ shardId: r.shard_id, frontierTs: toBigIntOrZero(r.frontier_ts) }));
+  }
+  /**
+   * 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.
+   */
+  async lookupIdempotency(key) {
+    const rows = await this.client.query(
+      `SELECT commit_ts, value_json, oversized FROM fleet_idempotency WHERE key = $1`,
+      [key]
+    );
+    const row = rows[0];
+    if (!row) return null;
+    const raw = row.value_json;
+    return {
+      commitTs: toBigIntOrZero(row.commit_ts),
+      hasValue: raw !== null && raw !== void 0,
+      value: raw !== null && raw !== void 0 ? JSON.parse(raw) : null,
+      oversized: row.oversized === true
+    };
+  }
+  /**
+   * 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.
+   */
+  async recordIdempotencyValue(key, value) {
+    const json = JSON.stringify(value ?? null);
+    if (Buffer.byteLength(json, "utf8") > IDEMPOTENCY_VALUE_CAP_BYTES) {
+      await this.client.query(
+        `UPDATE fleet_idempotency SET value_json = NULL, oversized = true WHERE key = $1`,
+        [key]
+      );
+      return;
+    }
+    await this.client.query(
+      `UPDATE fleet_idempotency SET value_json = $1, oversized = false WHERE key = $2`,
+      [json, key]
+    );
+  }
+  /**
+   * 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).
+   */
+  async sweepIdempotency() {
+    await this.client.query(`DELETE FROM fleet_idempotency WHERE created_at < now() - interval '${IDEMPOTENCY_TTL_INTERVAL}'`);
+  }
+  /**
+   * 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.
+   */
+  tupleInClause(pairs, offset) {
+    const tuples = [];
+    const params = [];
+    for (const { shardId, epoch } of pairs) {
+      const a = offset + params.length + 1;
+      const b = offset + params.length + 2;
+      tuples.push(`($${a}, $${b})`);
+      params.push(shardId, epoch);
+    }
+    return { clause: tuples.join(", "), params };
+  }
+};
+
+// src/lease-monitor.ts
+var DEFAULT_PROBE_MS = 5e3;
+var DEFAULT_MAX_MISSES = 3;
+var LeaseMonitor = class {
+  probe;
+  onExit;
+  probeMs;
+  maxMisses;
+  probeTimeoutMs;
+  timer = null;
+  misses = 0;
+  inFlight = false;
+  exited = false;
+  stopped = false;
+  constructor(deps) {
+    this.probe = deps.probe;
+    this.onExit = deps.onExit;
+    this.probeMs = deps.probeMs ?? DEFAULT_PROBE_MS;
+    this.maxMisses = deps.maxMisses ?? DEFAULT_MAX_MISSES;
+    this.probeTimeoutMs = deps.probeTimeoutMs ?? this.probeMs;
+  }
+  /** Begin probing every `probeMs`. Idempotent; a no-op once stopped or after exit. */
+  start() {
+    if (this.timer !== null || this.stopped || this.exited) return;
+    this.timer = setInterval(() => void this.tick(), this.probeMs);
+  }
+  async tick() {
+    if (this.stopped || this.exited || this.inFlight) return;
+    this.inFlight = true;
+    let timeoutHandle = null;
+    try {
+      const probeSettled = Promise.resolve().then(() => this.probe()).then(() => "success");
+      const timedOutMarker = new Promise((resolve) => {
+        timeoutHandle = setTimeout(() => resolve("timeout"), this.probeTimeoutMs);
+      });
+      const result = await Promise.race([probeSettled, timedOutMarker]);
+      if (this.stopped || this.exited) return;
+      if (result === "timeout") {
+        this.recordMiss("timed out");
+      } else {
+        this.misses = 0;
+      }
+    } catch {
+      if (this.stopped || this.exited) return;
+      this.recordMiss("failed");
+    } finally {
+      if (timeoutHandle !== null) clearTimeout(timeoutHandle);
+      this.inFlight = false;
+    }
+  }
+  recordMiss(mode) {
+    this.misses += 1;
+    if (this.misses > this.maxMisses) {
+      this.fireExit(`writer lease probe ${mode} (${this.misses} consecutive times)`);
+    }
+  }
+  /** DEFINITIVE lease loss (pinned connection closed/errored) → exit immediately. */
+  connectionLost() {
+    if (this.stopped || this.exited) return;
+    this.fireExit("writer lease lost: database connection closed");
+  }
+  /** 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) {
+    if (this.stopped || this.exited) return;
+    this.fireExit(`writer lease fenced: ${reason ?? "epoch superseded by another node"}`);
+  }
+  fireExit(reason) {
+    if (this.exited) return;
+    this.exited = true;
+    this.clearTimer();
+    this.onExit(reason);
+  }
+  /** Halt all probing and disarm exit — graceful shutdown or promotion hand-off. */
+  stop() {
+    this.stopped = true;
+    this.clearTimer();
+  }
+  clearTimer() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+};
+
+// src/fenced-error.ts
+var FencedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FencedError";
+  }
+};
+
+// src/commit-notifier.ts
+var COMMIT_CHANNEL = "helipod_commits";
+var NotifyingFanoutAdapter = class {
+  constructor(inner, client) {
+    this.inner = inner;
+    this.client = client;
+  }
+  inner;
+  client;
+  publish(payload) {
+    this.inner.publish(payload);
+    void this.client.notify(COMMIT_CHANNEL, String(payload.commitTs)).catch(() => {
+    });
+  }
+  subscribe(listener) {
+    return this.inner.subscribe(listener);
+  }
+};
+
+// src/forwarder.ts
+import { DEFAULT_SHARD as DEFAULT_SHARD2 } from "@helipod/id-codec";
+import { isHelipodError, helipodErrorFromJSON, NOT_SHARD_OWNER_CODE } from "@helipod/errors";
+function trimTrailingSlash(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+var RYOW_WAIT_MS = 5e3;
+var WriteForwarder = class {
+  constructor(lease, opts) {
+    this.lease = lease;
+    this.opts = opts;
+  }
+  lease;
+  opts;
+  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. */
+  warnedMissingCommitTs = false;
+  warnedUnparseableCommitTs = false;
+  /** 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. */
+  writerUrlCache = /* @__PURE__ */ new Map();
+  /** 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) {
+    this.tailer = t;
+  }
+  /** 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() {
+    this.tailer?.release();
+  }
+  /**
+   * 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).
+   */
+  async waitForReplica(commitTs) {
+    if (!this.tailer || commitTs === 0n) return;
+    await this.tailer.waitFor(commitTs, RYOW_WAIT_MS);
+  }
+  /**
+   * 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 = DEFAULT_SHARD2) {
+    return this.lease.currentEpoch(shardId) !== null;
+  }
+  async forward(kind, path, args, identity, shardId = DEFAULT_SHARD2, dedup) {
+    const body = {
+      path,
+      args,
+      identity,
+      kind,
+      shardId,
+      forwarded: true,
+      idempotencyKey: crypto.randomUUID(),
+      ...dedup ? { clientId: dedup.clientId, seq: dedup.seq } : {}
+    };
+    const first = await this.writerUrlFor(shardId);
+    let result;
+    try {
+      result = await this.post(first, body);
+    } catch (firstErr) {
+      const shouldRetry = !isHelipodError(firstErr) || firstErr.code === NOT_SHARD_OWNER_CODE;
+      if (!shouldRetry) throw firstErr;
+      let second;
+      try {
+        second = await this.refreshWriterUrlFor(shardId);
+      } catch {
+        throw firstErr;
+      }
+      result = await this.post(second, body);
+    }
+    if (result.clientReplay) {
+      return { value: result.clientReplay.value ?? null, replay: result.clientReplay };
+    }
+    await this.waitForReplicaCatchUp(path, result.commitTs);
+    return {
+      value: result.value,
+      // `commitTs` is stringified over the wire (bigints don't survive JSON) — coerced to `number`
+      // here to match the `WriteRouter` seam's contract (consistent with how every other commitTs
+      // consumer at this precision layer already converts, e.g. `Number(r.oplog?.commitTs ?? 0)` in
+      // `runtime-embedded`'s sync path). The RYOW wait above already parsed the STRING via `BigInt`
+      // directly, so full precision was preserved for the one place that actually needs it.
+      commitTs: result.commitTs !== void 0 ? Number(result.commitTs) : void 0,
+      shardId: result.shardId
+    };
+  }
+  /** Discover shard `shardId`'s current writer URL — cached after the first read. */
+  async writerUrlFor(shardId) {
+    const cached = this.writerUrlCache.get(shardId);
+    if (cached !== void 0) return cached;
+    return this.refreshWriterUrlFor(shardId);
+  }
+  /** 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. */
+  async refreshWriterUrlFor(shardId) {
+    const state = await this.lease.read(shardId);
+    if (!state) throw new Error(`fleet: no writer lease found for shard '${shardId}' \u2014 cannot forward write`);
+    this.writerUrlCache.set(shardId, state.writerUrl);
+    return state.writerUrl;
+  }
+  async post(writerUrl, body) {
+    const res = await fetch(`${trimTrailingSlash(writerUrl)}/_fleet/run`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${this.opts.adminKey}` },
+      body: JSON.stringify(body)
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+      parsed = text ? JSON.parse(text) : {};
+    } catch {
+      parsed = {};
+    }
+    if (!res.ok || parsed.error !== void 0) {
+      if (parsed.errorJson) throw helipodErrorFromJSON(parsed.errorJson);
+      throw new Error(parsed.error ?? `fleet: writer /_fleet/run returned HTTP ${res.status}`);
+    }
+    return { value: parsed.value ?? null, commitTs: parsed.commitTs, shardId: parsed.shardId, clientReplay: parsed.clientReplay };
+  }
+  /** 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). */
+  async waitForReplicaCatchUp(path, commitTsStr) {
+    if (!this.tailer) return;
+    if (commitTsStr === void 0) {
+      if (!this.warnedMissingCommitTs) {
+        this.warnedMissingCommitTs = true;
+        console.warn(
+          `fleet: writer's /_fleet/run response for ${path} had no commitTs \u2014 skipping read-your-own-writes wait`
+        );
+      }
+      return;
+    }
+    let commitTs;
+    try {
+      commitTs = BigInt(commitTsStr);
+    } catch {
+      if (!this.warnedUnparseableCommitTs) {
+        this.warnedUnparseableCommitTs = true;
+        console.warn(
+          `fleet: writer's /_fleet/run response for ${path} had an unparseable commitTs ${JSON.stringify(commitTsStr)} \u2014 skipping read-your-own-writes wait`
+        );
+      }
+      return;
+    }
+    if (commitTs === 0n) return;
+    const outcome = await this.tailer.waitFor(commitTs, RYOW_WAIT_MS);
+    if (outcome === "timeout") {
+      console.warn(
+        `fleet: read-your-own-writes wait timed out after ${RYOW_WAIT_MS}ms for ${path} at commitTs ${commitTs}`
+      );
+    }
+  }
+};
+
+// src/balancer.ts
+import { DEFAULT_SHARD as DEFAULT_SHARD3, shardIdList } from "@helipod/id-codec";
+
+// src/rendezvous.ts
+var U64_MASK = 0xffffffffffffffffn;
+var FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+var FNV_PRIME = 0x100000001b3n;
+var utf8 = new TextEncoder();
+function fnv1a64(bytes) {
+  let h = FNV_OFFSET_BASIS;
+  for (let i = 0; i < bytes.length; i++) {
+    h ^= BigInt(bytes[i]);
+    h = h * FNV_PRIME & U64_MASK;
+  }
+  return h;
+}
+function rendezvousWeight(shardId, advertiseUrl) {
+  return fnv1a64(utf8.encode(`${shardId}\0${advertiseUrl}`));
+}
+function rendezvousOwner(shardId, liveUrls) {
+  let bestUrl = "";
+  let bestWeight = -1n;
+  for (const url of liveUrls) {
+    const w = rendezvousWeight(shardId, url);
+    if (w > bestWeight || w === bestWeight && url < bestUrl) {
+      bestWeight = w;
+      bestUrl = url;
+    }
+  }
+  return bestUrl;
+}
+
+// src/balancer.ts
+var DEFAULT_BEAT_MS = 2e3;
+var ShardLeaseBalancer = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.shards = shardIdList(deps.numShards);
+    this.multiWriter = deps.multiWriter ?? false;
+    this.beatMs = deps.beatMs ?? DEFAULT_BEAT_MS;
+    this.log = deps.log ?? ((m) => console.error(m));
+  }
+  deps;
+  shards;
+  multiWriter;
+  beatMs;
+  log;
+  timer = null;
+  stopped = false;
+  running = false;
+  /** 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). */
+  previousLiveSet = null;
+  /** 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() {
+    if (this.timer !== null || this.stopped) return;
+    this.timer = setInterval(() => void this.tick(), this.beatMs);
+  }
+  stop() {
+    this.stopped = true;
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  /** 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. */
+  async liveCandidates() {
+    const live = await this.deps.lease.liveNodes();
+    const set = new Set(live);
+    set.add(this.deps.myUrl);
+    const urls = [...set];
+    return { urls, canonical: [...set].sort().join(",") };
+  }
+  /** 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`. */
+  targetsFor(liveUrls) {
+    if (!this.multiWriter) return new Set(this.shards);
+    const targets = /* @__PURE__ */ new Set();
+    for (const s of this.shards) {
+      if (rendezvousOwner(s, liveUrls) === this.deps.myUrl) targets.add(s);
+    }
+    return targets;
+  }
+  /** 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). */
+  acquirable(shardId, ownership) {
+    const o = ownership.get(shardId);
+    return o === void 0 || o.writerUrl === null || o.expired;
+  }
+  /**
+   * 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.
+   */
+  async acquireTargetsNow() {
+    const { urls, canonical } = await this.liveCandidates();
+    const ownership = await this.deps.lease.readShardOwnership();
+    const targets = this.targetsFor(urls);
+    for (const s of this.shards) {
+      if (targets.has(s) && !this.deps.isHeld(s) && this.acquirable(s, ownership)) {
+        await this.deps.tryAcquireShard(s);
+      }
+    }
+    this.previousLiveSet = canonical;
+  }
+  /** 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. */
+  async tick() {
+    if (this.stopped || this.running) return;
+    this.running = true;
+    try {
+      await this.deps.lease.heartbeatPresence();
+      const { urls, canonical } = await this.liveCandidates();
+      const stable = canonical === this.previousLiveSet;
+      this.previousLiveSet = canonical;
+      const ownership = await this.deps.lease.readShardOwnership();
+      const targets = this.targetsFor(urls);
+      if (!this.deps.isWriterish()) {
+        if (this.multiWriter) {
+          const wantsPromotion = [...targets].some(
+            (s) => s !== DEFAULT_SHARD3 && this.acquirable(s, ownership)
+          );
+          if (wantsPromotion) await this.deps.requestPromotion();
+        }
+        return;
+      }
+      for (const s of this.shards) {
+        if (targets.has(s) && !this.deps.isHeld(s) && this.acquirable(s, ownership)) {
+          await this.deps.tryAcquireShard(s);
+        }
+      }
+      if (this.multiWriter && stable) {
+        for (const s of this.shards) {
+          if (this.deps.isHeld(s) && !targets.has(s)) {
+            await this.deps.releaseShard(s);
+          }
+        }
+      }
+      if (this.deps.sweepIdempotency) {
+        try {
+          await this.deps.sweepIdempotency();
+        } catch (e) {
+          this.log(`fleet: idempotency sweep failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+      }
+    } catch (e) {
+      this.log(`fleet: balancer tick failed: ${e instanceof Error ? e.message : String(e)}`);
+    } finally {
+      this.running = false;
+    }
+  }
+};
+
+// src/node.ts
+import { rmSync } from "fs";
+import { join } from "path";
+import { NodePgClient, PostgresDocStore } from "@helipod/docstore-postgres";
+import { SqliteDocStore, NodeSqliteAdapter, BunSqliteAdapter } from "@helipod/docstore-sqlite";
+import { CommitGuardRejection } from "@helipod/errors";
+import { DEFAULT_SHARD as DEFAULT_SHARD4, shardIdList as shardIdList2 } from "@helipod/id-codec";
+import {
+  InMemoryWriteFanoutAdapter,
+  clientReceiptsGuard
+} from "@helipod/runtime-embedded";
+
+// src/switchable-store.ts
+var SwitchableDocStore = class {
+  delegate;
+  constructor(initial) {
+    this.delegate = initial;
+  }
+  /** Atomically repoint all future calls at `next`. Does not touch the outgoing delegate. */
+  swapTo(next) {
+    this.delegate = next;
+  }
+  /** The delegate current calls are being forwarded to. */
+  current() {
+    return this.delegate;
+  }
+  async setupSchema(options) {
+    const d = this.delegate;
+    return d.setupSchema(options);
+  }
+  async write(documents, indexUpdates, conflictStrategy, shardId) {
+    const d = this.delegate;
+    return d.write(documents, indexUpdates, conflictStrategy, shardId);
+  }
+  async commitWrite(documents, indexUpdates, shardId, opts) {
+    const d = this.delegate;
+    return d.commitWrite(documents, indexUpdates, shardId, opts);
+  }
+  async commitWriteBatch(units, shardId) {
+    const d = this.delegate;
+    return d.commitWriteBatch(units, shardId);
+  }
+  /** 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) {
+    const d = this.delegate;
+    return d.addCommitGuard(guard);
+  }
+  async get(id, readTimestamp) {
+    const d = this.delegate;
+    return d.get(id, readTimestamp);
+  }
+  async *index_scan(indexId, tableId, readTimestamp, interval, order, limit) {
+    const d = this.delegate;
+    yield* d.index_scan(indexId, tableId, readTimestamp, interval, order, limit);
+  }
+  async *load_documents(range, order, limit) {
+    const d = this.delegate;
+    yield* d.load_documents(range, order, limit);
+  }
+  async previous_revisions(queries) {
+    const d = this.delegate;
+    return d.previous_revisions(queries);
+  }
+  async scan(tableId, readTimestamp) {
+    const d = this.delegate;
+    return d.scan(tableId, readTimestamp);
+  }
+  async count(tableId) {
+    const d = this.delegate;
+    return d.count(tableId);
+  }
+  async maxTimestamp() {
+    const d = this.delegate;
+    return d.maxTimestamp();
+  }
+  async getGlobal(key) {
+    const d = this.delegate;
+    return d.getGlobal(key);
+  }
+  async writeGlobal(key, value) {
+    const d = this.delegate;
+    return d.writeGlobal(key, value);
+  }
+  async writeGlobalIfAbsent(key, value) {
+    const d = this.delegate;
+    return d.writeGlobalIfAbsent(key, value);
+  }
+  // ── Client mutation receipts (the Receipted Outbox, verdict §(c)) — pass-through ──────────────
+  async getClientVerdict(identity, clientId, seq) {
+    const d = this.delegate;
+    return d.getClientVerdict(identity, clientId, seq);
+  }
+  async getClientFloor(identity, clientId) {
+    const d = this.delegate;
+    return d.getClientFloor(identity, clientId);
+  }
+  async recordClientVerdict(identity, clientId, seq, record) {
+    const d = this.delegate;
+    return d.recordClientVerdict(identity, clientId, seq, record);
+  }
+  async updateClientVerdictValue(identity, clientId, seq, value) {
+    const d = this.delegate;
+    return d.updateClientVerdictValue(identity, clientId, seq, value);
+  }
+  async pruneClientMutations(identity, clientId, opts) {
+    const d = this.delegate;
+    return d.pruneClientMutations(identity, clientId, opts);
+  }
+  async sweepExpiredClientMutations(beforeMs) {
+    const d = this.delegate;
+    return d.sweepExpiredClientMutations(beforeMs);
+  }
+  close() {
+    const d = this.delegate;
+    return d.close();
+  }
+};
+
+// src/replica-tailer.ts
+import { decodeStorageTableId, encodeStorageTableId } from "@helipod/id-codec";
+
+// src/stable-prefix.ts
+function stablePrefixFromFrontier(raw) {
+  return raw;
+}
+
+// src/replica-tailer.ts
+var COMMIT_CHANNEL2 = "helipod_commits";
+var DEFAULT_POLL_MS = 1e3;
+var DEFAULT_BATCH_SIZE = 1e3;
+var DEFAULT_NUM_SHARDS = 1;
+function docDedupeKey(id) {
+  return `${encodeStorageTableId(id.tableNumber)}|${Buffer.from(id.internalId).toString("hex")}`;
+}
+function docLabel(id) {
+  return `table=${encodeStorageTableId(id.tableNumber)} internalId=${Buffer.from(id.internalId).toString("hex")}`;
+}
+function toBigInt(v) {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number" || typeof v === "string") return BigInt(v);
+  throw new Error(`fleet: expected shard_leases.frontier_ts to be a BIGINT-like value, got ${typeof v}`);
+}
+var DensityViolationError = class extends Error {
+  constructor(docId, expectedPrevTs, actualHeadTs) {
+    super(
+      `fleet: replica density violation for doc (${docLabel(docId)}) \u2014 expected prev_ts ${expectedPrevTs === null ? "null (insert \u2014 replica must have no live head)" : String(expectedPrevTs)}, but the replica's actual head ts is ${actualHeadTs === null ? "null (no live head)" : String(actualHeadTs)}. A commit touching this document was skipped between the primary and this replica; delete <replica path>/fleet-replica.db to re-bootstrap.`
+    );
+    this.docId = docId;
+    this.expectedPrevTs = expectedPrevTs;
+    this.actualHeadTs = actualHeadTs;
+    this.name = "DensityViolationError";
+  }
+  docId;
+  expectedPrevTs;
+  actualHeadTs;
+};
+var ReplicaTailer = class {
+  constructor(client, primary, replica, opts) {
+    this.client = client;
+    this.primary = primary;
+    this.replica = replica;
+    this.mode = opts.mode ?? "replica";
+    this.pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+    this.batchSize = opts.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.numShards = opts.numShards ?? DEFAULT_NUM_SHARDS;
+    this.onInvalidation = opts.onInvalidation;
+  }
+  client;
+  primary;
+  replica;
+  mode;
+  pollMs;
+  batchSize;
+  numShards;
+  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. */
+  wm = stablePrefixFromFrontier(0n);
+  /** 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). */
+  lastF = null;
+  timer;
+  unlisten;
+  stopped = true;
+  /** 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. */
+  draining = false;
+  waiters = /* @__PURE__ */ new Set();
+  /** 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() {
+    return this.wm;
+  }
+  /**
+   * 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).
+   */
+  async readFrontier() {
+    const rows = await this.client.query(
+      `SELECT COALESCE(MIN(frontier_ts), 0) AS min_frontier, COUNT(*) AS n FROM shard_leases`
+    );
+    const row = rows[0];
+    const count = row === void 0 ? 0 : Number(toBigInt(row.n));
+    if (count < this.numShards) return stablePrefixFromFrontier(0n);
+    const raw = row === void 0 ? 0n : toBigInt(row.min_frontier);
+    const f = stablePrefixFromFrontier(raw);
+    if (this.lastF !== null && f < this.lastF) {
+      throw new Error(
+        `fleet: frontier regression detected \u2014 min(shard_leases.frontier_ts) went from ${this.lastF} to ${f}. F must be monotonically non-decreasing; this indicates a lease row was corrupted or hand-tampered.`
+      );
+    }
+    this.lastF = f;
+    return f;
+  }
+  /**
+   * @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.
+   */
+  async start(seedWm) {
+    this.stopped = false;
+    if (this.mode === "invalidateOnly") {
+      if (seedWm !== void 0) {
+        this.wm = stablePrefixFromFrontier(seedWm);
+      } else {
+        this.wm = await this.readFrontier();
+      }
+    } else {
+      this.wm = stablePrefixFromFrontier(await this.replica.maxTimestamp());
+      const target = await this.readFrontier();
+      while (!this.stopped && this.wm < target) {
+        await this.tick();
+      }
+    }
+    if (this.stopped) return;
+    try {
+      this.unlisten = await this.client.listen(COMMIT_CHANNEL2, () => {
+        void this.tick();
+      });
+    } catch {
+      this.unlisten = void 0;
+    }
+    if (this.stopped) {
+      if (this.unlisten !== void 0) {
+        const unlisten = this.unlisten;
+        this.unlisten = void 0;
+        await unlisten();
+      }
+      return;
+    }
+    this.timer = setInterval(() => void this.tick(), this.pollMs);
+  }
+  async stop() {
+    this.stopped = true;
+    if (this.timer !== void 0) {
+      clearInterval(this.timer);
+      this.timer = void 0;
+    }
+    if (this.unlisten !== void 0) {
+      const unlisten = this.unlisten;
+      this.unlisten = void 0;
+      await unlisten();
+    }
+  }
+  /** 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, timeoutMs) {
+    if (this.wm >= ts) return Promise.resolve("reached");
+    return new Promise((resolve) => {
+      const waiter = {
+        ts,
+        settle: (outcome) => {
+          clearTimeout(waiter.timer);
+          this.waiters.delete(waiter);
+          resolve(outcome);
+        },
+        timer: setTimeout(() => waiter.settle("timeout"), timeoutMs)
+      };
+      this.waiters.add(waiter);
+    });
+  }
+  /** 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() {
+    for (const w of [...this.waiters]) w.settle("released");
+  }
+  wakeSatisfiedWaiters() {
+    for (const w of [...this.waiters]) {
+      if (this.wm >= w.ts) w.settle("reached");
+    }
+  }
+  async tick() {
+    if (this.stopped || this.draining) return;
+    this.draining = true;
+    try {
+      await this.drainOnce();
+    } catch (e) {
+      if (e instanceof DensityViolationError) {
+        console.error(e.message);
+        await this.stop();
+        return;
+      }
+      throw e;
+    } finally {
+      this.draining = false;
+    }
+  }
+  /** 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. */
+  async drainOnce() {
+    const F = await this.readFrontier();
+    if (F <= this.wm) return;
+    const { docs, cappedAt } = await this.pullDocs(this.wm, F);
+    const appliedMax = stablePrefixFromFrontier(cappedAt ?? F);
+    const indexRows = await this.client.query(
+      `SELECT index_id, key, ts, table_id, internal_id, deleted FROM indexes WHERE ts > $1 AND ts <= $2 ORDER BY ts ASC`,
+      [this.wm, appliedMax]
+    );
+    if (docs.length === 0 && indexRows.length === 0) {
+      this.wm = appliedMax;
+      this.wakeSatisfiedWaiters();
+      return;
+    }
+    if (this.mode === "replica") {
+      const indexWrites = indexRows.map((r) => {
+        const deleted = r.deleted;
+        const value = deleted ? { type: "Deleted" } : {
+          type: "NonClustered",
+          docId: {
+            tableNumber: decodeStorageTableId(r.table_id),
+            internalId: r.internal_id
+          }
+        };
+        return {
+          ts: r.ts,
+          update: { indexId: r.index_id, key: r.key, value }
+        };
+      });
+      await this.assertDensity(docs);
+      await this.replica.write(docs, indexWrites, "Overwrite");
+    }
+    const tableIds = /* @__PURE__ */ new Set();
+    for (const r of indexRows) if (r.table_id !== null) tableIds.add(String(r.table_id));
+    const writtenTables = [...tableIds];
+    const writtenKeys = indexRows.map((r) => ({ indexId: String(r.index_id), key: r.key }));
+    const seenDocs = /* @__PURE__ */ new Set();
+    const writtenDocs = [];
+    for (const d of docs) {
+      const dedupeKey = docDedupeKey(d.id);
+      if (seenDocs.has(dedupeKey)) continue;
+      seenDocs.add(dedupeKey);
+      writtenDocs.push({ tableId: encodeStorageTableId(d.id.tableNumber), internalId: d.id.internalId });
+    }
+    await this.onInvalidation({ newMaxTs: appliedMax, writtenTables, writtenKeys, writtenDocs });
+    this.wm = appliedMax;
+    this.wakeSatisfiedWaiters();
+  }
+  /**
+   * 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).
+   */
+  async assertDensity(docs) {
+    const headTs = /* @__PURE__ */ new Map();
+    for (const d of docs) {
+      const key = docDedupeKey(d.id);
+      let head = headTs.get(key);
+      if (head === void 0) {
+        const existing = await this.replica.get(d.id);
+        head = existing ? existing.ts : null;
+      }
+      if (head !== d.ts) {
+        if (d.prev_ts !== null) {
+          if (head === null || head !== d.prev_ts) throw new DensityViolationError(d.id, d.prev_ts, head);
+        } else if (head !== null) {
+          throw new DensityViolationError(d.id, null, head);
+        }
+      }
+      headTs.set(key, d.ts);
+    }
+  }
+  /**
+   * 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).
+   */
+  async pullDocs(after, upTo) {
+    const docs = [];
+    let cappedAt = null;
+    const gen = this.primary.load_documents({ minInclusive: after + 1n, maxExclusive: upTo + 1n }, "asc");
+    for await (const entry of gen) {
+      if (cappedAt !== null && entry.ts !== cappedAt) break;
+      docs.push(entry);
+      if (cappedAt === null && docs.length >= this.batchSize) cappedAt = entry.ts;
+    }
+    return { docs, cappedAt };
+  }
+};
+
+// src/ranges.ts
+import { keyToPointRange, docKeyToPointRange } from "@helipod/id-codec";
+
+// src/node.ts
+var REPLICA_DB_FILENAME = "fleet-replica.db";
+var DEFAULT_LEASE_TTL_MS2 = 15e3;
+var DEFAULT_NUM_SHARDS2 = 8;
+var FRONTIER_BEAT_MS = 100;
+var FRONTIER_COALESCE_MS = 10;
+var FRONTIER_LAG_WARN_MS = 5e3;
+var FrontierMonitor = class {
+  constructor(lease, opts) {
+    this.lease = lease;
+    this.opts = opts;
+    this.minSinceMs = (opts.now ?? Date.now)();
+  }
+  lease;
+  opts;
+  timer = null;
+  coalesceTimer = null;
+  stopped = false;
+  running = false;
+  cached = null;
+  /** 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. */
+  lastMin = null;
+  minSinceMs;
+  warned = false;
+  /** 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. */
+  replicaLagSinceMs = null;
+  replicaLagWarned = false;
+  get now() {
+    return this.opts.now ?? Date.now;
+  }
+  start() {
+    if (this.stopped || this.timer !== null) return;
+    void this.beat();
+    this.timer = setInterval(() => void this.beat(), this.opts.beatMs ?? FRONTIER_BEAT_MS);
+  }
+  /** 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() {
+    if (this.stopped || this.coalesceTimer !== null) return;
+    this.coalesceTimer = setTimeout(() => {
+      this.coalesceTimer = null;
+      void this.beat();
+    }, this.opts.coalesceMs ?? FRONTIER_COALESCE_MS);
+  }
+  async beat() {
+    if (this.stopped || this.running) return;
+    this.running = true;
+    try {
+      if (this.opts.closeIdle) {
+        if (!this.opts.runExclusiveOnShard) {
+          throw new Error("fleet: FrontierMonitor closeIdle requires a runExclusiveOnShard seam (bug)");
+        }
+        const ceiling = await this.lease.closeIdleFrontiers(this.opts.runExclusiveOnShard);
+        await this.lease.bumpOrphanFrontiers(ceiling);
+      }
+      const rows = await this.lease.readAllFrontiers();
+      if (rows.length === 0) return;
+      const min = rows[0].frontierTs;
+      const pinningShard = rows[0].shardId;
+      const nowMs = this.now();
+      const minBefore = this.lastMin;
+      if (this.lastMin === null || min > this.lastMin) {
+        this.lastMin = min;
+        this.minSinceMs = nowMs;
+        this.warned = false;
+        if (this.opts.closeIdle && minBefore !== null && this.opts.notifyOnAdvance) {
+          try {
+            this.opts.notifyOnAdvance(min);
+          } catch {
+          }
+        }
+      }
+      const lagMs = nowMs - this.minSinceMs;
+      this.cached = { frontier: min, lagMs, pinningShard };
+      const lagWarnMs = this.opts.lagWarnMs ?? FRONTIER_LAG_WARN_MS;
+      if (lagMs > lagWarnMs && !this.warned) {
+        this.warned = true;
+        (this.opts.warn ?? ((m) => console.warn(m)))(
+          `fleet: frontier stuck for ${lagMs}ms at ${min} \u2014 shard '${pinningShard}' is pinning F`
+        );
+      }
+      if (this.opts.tailerWatermark) {
+        const wm = this.opts.tailerWatermark();
+        if (wm < min) {
+          if (this.replicaLagSinceMs === null) this.replicaLagSinceMs = nowMs;
+          const replicaLagMs = nowMs - this.replicaLagSinceMs;
+          if (replicaLagMs > lagWarnMs && !this.replicaLagWarned) {
+            this.replicaLagWarned = true;
+            (this.opts.warn ?? ((m) => console.warn(m)))(
+              `fleet: replica for '${this.lease.advertiseUrl}' lagging ${replicaLagMs}ms behind frontier ${min} (watermark ${wm})`
+            );
+          }
+        } else {
+          this.replicaLagSinceMs = null;
+          this.replicaLagWarned = false;
+        }
+      }
+    } catch {
+    } finally {
+      this.running = false;
+    }
+  }
+  /** 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() {
+    if (this.cached === null) return null;
+    return { ...this.cached, lagMs: this.now() - this.minSinceMs };
+  }
+  stop() {
+    this.stopped = true;
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.coalesceTimer !== null) {
+      clearTimeout(this.coalesceTimer);
+      this.coalesceTimer = null;
+    }
+  }
+};
+function createAsyncChain() {
+  let tail = Promise.resolve();
+  return (op) => {
+    const settled = tail.then(op, op);
+    tail = settled.then(
+      () => void 0,
+      () => void 0
+    );
+    return settled;
+  };
+}
+function fleetProbeMs(ttlMs) {
+  return Math.max(1, Math.round(ttlMs / 3));
+}
+function fleetAcquireRetryMs(ttlMs) {
+  return Math.max(1, Math.round(ttlMs * 2 / 15));
+}
+var FLEET_WRITER_SESSION_TIMEOUTS = { idleInTransactionMs: 5e3, statementMs: 1e4 };
+var FLEET_DEPLOYMENT_ID_KEY = "fleet:deploymentId";
+function deleteReplicaFile(path) {
+  for (const suffix of ["", "-wal", "-shm"]) rmSync(path + suffix, { force: true });
+}
+async function documentsTableExists(client) {
+  const rows = await client.query(`SELECT to_regclass('documents') IS NOT NULL AS present`);
+  return rows[0]?.present === true;
+}
+function fleetApplicationName(advertiseUrl) {
+  let discriminator = advertiseUrl;
+  try {
+    const port = new URL(advertiseUrl).port;
+    if (port) discriminator = port;
+  } catch {
+  }
+  return `helipod-fleet-${discriminator}`;
+}
+function replicaAdapter(path) {
+  const isBun = typeof globalThis.Bun !== "undefined";
+  return isBun ? new BunSqliteAdapter({ path }) : new NodeSqliteAdapter({ path });
+}
+function fleetMultiWriterEnabled() {
+  return /^(1|true|yes)$/i.test(process.env.HELIPOD_FLEET_MULTI_WRITER ?? "");
+}
+function groupCommitEnabled() {
+  return /^(1|true|yes)$/i.test(process.env.HELIPOD_GROUP_COMMIT ?? "");
+}
+async function openReplicaFile(replicaPath) {
+  try {
+    const replica = new SqliteDocStore(replicaAdapter(replicaPath));
+    await replica.setupSchema();
+    return replica;
+  } catch (e) {
+    console.warn(
+      `fleet: local replica at ${replicaPath} failed to open (${e instanceof Error ? e.message : String(e)}) \u2014 deleting and rebuilding from the primary`
+    );
+    deleteReplicaFile(replicaPath);
+    const replica = new SqliteDocStore(replicaAdapter(replicaPath));
+    await replica.setupSchema();
+    return replica;
+  }
+}
+async function openSyncReplica(replicaPath) {
+  const replica = await openReplicaFile(replicaPath);
+  return { replica, switchable: new SwitchableDocStore(replica) };
+}
+async function reconcileReplicaIdentity(deps) {
+  const { pgStore, replicaPath } = deps;
+  let primaryId = await pgStore.getGlobal(FLEET_DEPLOYMENT_ID_KEY);
+  if (primaryId === null) {
+    await pgStore.writeGlobalIfAbsent(FLEET_DEPLOYMENT_ID_KEY, crypto.randomUUID());
+    primaryId = await pgStore.getGlobal(FLEET_DEPLOYMENT_ID_KEY);
+  }
+  const replicaId = await deps.replica.getGlobal(FLEET_DEPLOYMENT_ID_KEY);
+  if (replicaId === primaryId) {
+    return { replica: deps.replica, switchable: deps.switchable };
+  }
+  const hasData = await deps.replica.maxTimestamp() > 0n;
+  if (replicaId === null && !hasData) {
+    await deps.replica.writeGlobalIfAbsent(FLEET_DEPLOYMENT_ID_KEY, primaryId);
+    return { replica: deps.replica, switchable: deps.switchable };
+  }
+  console.warn(
+    `fleet: local replica at ${replicaPath} does not match the primary's deployment id (foreign replica, or predates identity stamping) \u2014 deleting and rebuilding from the primary`
+  );
+  await deps.replica.close();
+  deleteReplicaFile(replicaPath);
+  const freshReplica = await openReplicaFile(replicaPath);
+  await freshReplica.writeGlobalIfAbsent(FLEET_DEPLOYMENT_ID_KEY, primaryId);
+  deps.switchable.swapTo(freshReplica);
+  return { replica: freshReplica, switchable: deps.switchable };
+}
+async function prepareFleetNode(deps) {
+  const leaseTtlMs = deps.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS2;
+  const numShards = deps.numShards ?? DEFAULT_NUM_SHARDS2;
+  const shards = shardIdList2(numShards);
+  const applicationName = fleetApplicationName(deps.advertiseUrl);
+  const client = new NodePgClient({
+    connectionString: deps.databaseUrl,
+    applicationName,
+    sessionTimeouts: FLEET_WRITER_SESSION_TIMEOUTS,
+    // Per-shard commit-connection pool (B2a, D1): one dedicated connection per shard for `commitWrite`
+    // transactions, so different shards' commits run as genuinely concurrent Postgres transactions
+    // (the pinned connection keeps heartbeats/eviction/setup/queries + LISTEN). Each slot's advisory
+    // lock is taken on its own connection, so a shard's connection death releases exactly that shard.
+    commitPool: { shards }
+  });
+  const pgStore = new PostgresDocStore(client, { readOnly: true });
+  const lease = new LeaseManager(client, {
+    advertiseUrl: deps.advertiseUrl,
+    applicationName,
+    ttlMs: leaseTtlMs,
+    retryMs: fleetAcquireRetryMs(leaseTtlMs)
+  });
+  const forwarder = new WriteForwarder(lease, { adminKey: deps.adminKey, selfUrl: deps.advertiseUrl });
+  const fanoutAdapter = new NotifyingFanoutAdapter(new InMemoryWriteFanoutAdapter(), client);
+  const documentsExist = await documentsTableExists(client);
+  await lease.setup(shards, documentsExist);
+  await lease.heartbeatPresence();
+  const acquired = await lease.tryAcquire(DEFAULT_SHARD4, 0, documentsExist);
+  const multiWriter = fleetMultiWriterEnabled();
+  const replicaPath = join(deps.dataDir, REPLICA_DB_FILENAME);
+  const beforeNotify = (commitTs) => forwarder.waitForReplica(commitTs);
+  const groupCommit = groupCommitEnabled();
+  const stablePrefix = async () => {
+    const rows = await lease.readAllFrontiers();
+    return rows.length > 0 ? rows[0].frontierTs : null;
+  };
+  if (acquired) {
+    pgStore.setWritable();
+    forwarder.promote();
+    if (multiWriter) {
+      const { replica: replica2, switchable: switchable2 } = await openSyncReplica(replicaPath);
+      return {
+        client,
+        pgStore,
+        replica: replica2,
+        switchable: switchable2,
+        replicaPath,
+        lease,
+        forwarder,
+        role: "writer",
+        numShards,
+        runtimeOptions: {
+          store: pgStore,
+          writeRouter: forwarder,
+          deferDrivers: false,
+          fanoutAdapter,
+          numShards,
+          queryStore: switchable2,
+          beforeNotify,
+          groupCommit,
+          stablePrefix,
+          externalReceiptsGuard: true
+        }
+      };
+    }
+    return {
+      client,
+      pgStore,
+      lease,
+      forwarder,
+      role: "writer",
+      numShards,
+      runtimeOptions: { store: pgStore, writeRouter: forwarder, deferDrivers: false, fanoutAdapter, numShards, groupCommit, stablePrefix, externalReceiptsGuard: true }
+    };
+  }
+  const { replica, switchable } = await openSyncReplica(replicaPath);
+  if (multiWriter) {
+    return {
+      client,
+      pgStore,
+      replica,
+      switchable,
+      replicaPath,
+      lease,
+      forwarder,
+      role: "sync",
+      numShards,
+      runtimeOptions: {
+        // `receiptsStore: pgStore` — the Connect handshake classifies/prunes against the PRIMARY, not
+        // the replica (which carries no receipts). Redundant here (`store` IS `pgStore` for a hybrid),
+        // but set explicitly so the sync-node invariant is uniform across both sync shapes.
+        store: pgStore,
+        writeRouter: forwarder,
+        deferDrivers: true,
+        fanoutAdapter,
+        numShards,
+        queryStore: switchable,
+        receiptsStore: pgStore,
+        beforeNotify,
+        groupCommit,
+        stablePrefix,
+        externalReceiptsGuard: true
+      }
+    };
+  }
+  return {
+    client,
+    pgStore,
+    replica,
+    switchable,
+    replicaPath,
+    lease,
+    forwarder,
+    role: "sync",
+    numShards,
+    runtimeOptions: { store: switchable, writeRouter: forwarder, deferDrivers: true, fanoutAdapter, numShards, receiptsStore: pgStore, groupCommit, stablePrefix, externalReceiptsGuard: true }
+  };
+}
+function defaultFleetExit(reason) {
+  console.error(`fleet: ${reason} \u2014 exiting so this node restarts and rejoins as a sync replica`);
+  process.exit(1);
+}
+async function runPromotion(deps) {
+  try {
+    await deps.promote();
+    deps.startMonitor();
+    deps.firePromoted();
+  } catch (e) {
+    deps.onExit(`promotion failed (${e instanceof Error ? e.message : String(e)})`);
+  }
+}
+async function promoteFleetNode(deps) {
+  deps.runtime.observeTimestamp(await deps.pgStore.maxTimestamp());
+  deps.pgStore.setWritable();
+  deps.switchable.swapTo(deps.pgStore);
+  deps.forwarder.promote();
+  await deps.tailer.stop();
+  await deps.replica.close();
+  await deps.runtime.startDrivers();
+}
+function installCommitGuard(pgStore, lease, onFenced) {
+  return pgStore.addCommitGuard(async (q, units, shardId) => {
+    const epoch = lease.currentEpoch(shardId);
+    if (epoch === null) {
+      onFenced(shardId, `commit guard invoked with no acquired epoch for shard '${shardId}'`);
+      throw new FencedError(`commit fenced: this node has not acquired a shard_leases epoch for shard '${shardId}'`);
+    }
+    const tsN = units[units.length - 1].ts;
+    const rows = await q.query(
+      `UPDATE shard_leases SET prev_ts = frontier_ts, frontier_ts = GREATEST(frontier_ts, $1) WHERE shard_id = $2 AND epoch = $3 RETURNING epoch`,
+      [tsN, shardId, epoch]
+    );
+    if (rows.length === 0) {
+      onFenced(shardId, `commit guard found 0 rows for shard '${shardId}' epoch ${epoch} \u2014 superseded by another writer`);
+      throw new FencedError(`commit fenced: epoch no longer current for shard '${shardId}'`);
+    }
+    for (let i = 0; i < units.length; i++) {
+      const unit = units[i];
+      if (unit.meta?.idempotencyKey) {
+        try {
+          await q.query(`INSERT INTO fleet_idempotency (key, commit_ts) VALUES ($1, $2)`, [
+            unit.meta.idempotencyKey,
+            unit.ts
+          ]);
+        } catch (e) {
+          if (e.code === "23505") {
+            throw new CommitGuardRejection(i, "FLEET_IDEMPOTENCY_CONFLICT", `key=${unit.meta.idempotencyKey}`, {
+              cause: e
+            });
+          }
+          throw e;
+        }
+      }
+    }
+  });
+}
+function relinquish(deps, shardId, reason, opts = {}) {
+  if (deps.lease.currentEpoch(shardId) === null) return;
+  deps.lease.forgetShard(shardId);
+  const log = deps.log ?? ((m) => console.error(m));
+  log(
+    `fleet: relinquish shard='${shardId}' reason='${reason}'` + (opts.connectionLost ? " (via commit-connection loss \u2014 its slot lock is already gone)" : "")
+  );
+  if (shardId === DEFAULT_SHARD4) {
+    log(`fleet: relinquished the default shard \u2014 stopping drivers (scheduler/workflow/cron/reaper)`);
+    deps.onDefaultRelinquished?.();
+  }
+  if (opts.connectionLost) return;
+  const slot = deps.shards.indexOf(shardId);
+  if (slot < 0 || !deps.client.releaseShardLock) return;
+  void deps.client.releaseShardLock(slot).catch((e) => {
+    log(
+      `fleet: releaseShardLock(${slot}) for shard '${shardId}' failed: ${e instanceof Error ? e.message : String(e)}`
+    );
+  });
+}
+async function acquireShardAsWriter(lease, shardId, slot, retryMs, seedFrontierFromDocuments = false) {
+  const deadline = Date.now() + Math.max(1, retryMs) * 75;
+  for (; ; ) {
+    const state = await lease.tryAcquire(shardId, slot, seedFrontierFromDocuments);
+    if (state) return;
+    if (await lease.isExpired(shardId)) {
+      const { fenced, oldAppName } = await lease.evictExpired(shardId);
+      if (fenced && oldAppName !== null) await lease.terminateBackend(oldAppName);
+    }
+    if (Date.now() > deadline) {
+      throw new Error(`fleet: could not acquire shard '${shardId}' (slot ${slot}) lease within the deadline`);
+    }
+    await new Promise((r) => setTimeout(r, Math.max(1, retryMs)));
+  }
+}
+function deriveFlushesPerSec(prevReadMs, prevFlushCount, nowMs, nowFlushCount) {
+  if (prevReadMs === null || nowMs <= prevReadMs) return 0;
+  return Math.max(0, (nowFlushCount - prevFlushCount) / ((nowMs - prevReadMs) / 1e3));
+}
+async function startFleetNode(deps) {
+  const { client, pgStore, runtime, lease, forwarder, switchable, replicaPath } = deps;
+  const numShards = deps.numShards ?? 1;
+  const shards = shardIdList2(numShards);
+  let replica = deps.replica;
+  const onExit = deps.onExit ?? defaultFleetExit;
+  const promotedCbs = [];
+  let frontierMonitor = null;
+  let unsubscribeCommits = null;
+  let unregisterCommitGuard = null;
+  let unregisterReceiptsGuard = null;
+  let lastGroupCommitReadMs = null;
+  let lastFlushCount = 0;
+  const groupCommitStats = () => {
+    const stats = runtime.groupCommitStats();
+    const now = Date.now();
+    const flushesPerSec = deriveFlushesPerSec(lastGroupCommitReadMs, lastFlushCount, now, stats.flushCount);
+    lastGroupCommitReadMs = now;
+    lastFlushCount = stats.flushCount;
+    return { ...stats, flushesPerSec };
+  };
+  const firePromoted = () => {
+    for (const cb of promotedCbs) {
+      try {
+        cb();
+      } catch {
+      }
+    }
+  };
+  let writerish = forwarder.isLocalWriter();
+  let promoting = false;
+  let doPromote = () => {
+  };
+  const chainDriverOp = createAsyncChain();
+  const startDriversChained = () => chainDriverOp(() => runtime.startDrivers());
+  const stopDriversOnlyChained = () => chainDriverOp(() => runtime.stopDriversOnly());
+  const relinquishDeps = {
+    lease,
+    client,
+    shards,
+    onDefaultRelinquished: () => void stopDriversOnlyChained()
+  };
+  const tryAcquireShard = async (shardId) => {
+    const slot = shards.indexOf(shardId);
+    if (slot < 0) return false;
+    let state = await lease.tryAcquire(shardId, slot, true);
+    if (!state && await lease.isExpired(shardId)) {
+      const { fenced, oldAppName } = await lease.evictExpired(shardId);
+      if (fenced && oldAppName !== null) await lease.terminateBackend(oldAppName);
+      state = await lease.tryAcquire(shardId, slot, true);
+    }
+    if (!state) return false;
+    runtime.observeWriteTimestamp(state.frontierTs);
+    if (shardId === DEFAULT_SHARD4) void startDriversChained();
+    return true;
+  };
+  const releaseShard = async (shardId) => {
+    const fenced = await runtime.tryRunExclusiveOnShard(shardId, async () => {
+      await lease.selfFence(shardId);
+    });
+    if (!fenced) return;
+    relinquish(relinquishDeps, shardId, "balancer graceful release (no longer a rendezvous target)");
+  };
+  const multiWriter = fleetMultiWriterEnabled();
+  const balancer = new ShardLeaseBalancer({
+    lease,
+    myUrl: lease.advertiseUrl,
+    numShards,
+    multiWriter,
+    isHeld: (shardId) => lease.currentEpoch(shardId) !== null,
+    isWriterish: () => writerish,
+    tryAcquireShard,
+    releaseShard,
+    requestPromotion: async () => {
+      doPromote();
+    },
+    // Fleet B3, D3: reclaim expired `fleet_idempotency` rows on every writer-ish beat (cheap indexed
+    // delete) — see `LeaseManager.sweepIdempotency`. The balancer runs `sweepIdempotency` only while
+    // `isWriterish()`; a pure sync node holds no writer-side state to sweep.
+    sweepIdempotency: () => lease.sweepIdempotency(),
+    beatMs: fleetAcquireRetryMs(lease.ttlMs)
+  });
+  const invalidationSink = async (inv) => {
+    try {
+      runtime.observeTimestamp(inv.newMaxTs);
+      const ranges = [
+        ...inv.writtenKeys.map((k) => keyToPointRange(k.indexId, k.key)),
+        ...inv.writtenDocs.map((d) => docKeyToPointRange(d.tableId, d.internalId))
+      ];
+      const commitTs = Number(inv.newMaxTs);
+      await runtime.handler.notifyWrites({
+        tables: inv.writtenTables,
+        ranges,
+        commitTs
+      });
+      runtime.notifyExternalCommit({ tables: inv.writtenTables, ranges, commitTs });
+    } catch (e) {
+      console.error("fleet: replica invalidation failed", e);
+    }
+  };
+  const startHybridTailer = async () => {
+    if (!replica || !switchable || !replicaPath) {
+      throw new Error(
+        "fleet: hybrid boot requires a replica + switchable store + replicaPath (bug: prepareFleetNode multi-writer path must provide them)"
+      );
+    }
+    await pgStore.setupSchema();
+    const reconciled2 = await reconcileReplicaIdentity({ pgStore, replica, switchable, replicaPath });
+    replica = reconciled2.replica;
+    const t = new ReplicaTailer(client, pgStore, replica, { numShards, onInvalidation: invalidationSink });
+    await t.start();
+    forwarder.attachTailer(t);
+    return t;
+  };
+  let hybridTailer = null;
+  let monitor = null;
+  const startWriterMonitor = () => {
+    monitor = new LeaseMonitor({
+      // Heartbeat-as-probe (Fenced Frontier B1, D2): one round-trip serves liveness-probe + TTL
+      // maintenance + fence verification — NEVER pg_try_advisory_lock (re-entrant on the holding
+      // session). `lease.currentEpoch()` is read live so a re-promotion's epoch bump is honored.
+      probe: async () => {
+        await lease.heartbeatPresence();
+        if (lease.heldPairs().length === 0) return;
+        const { fencedShardIds } = await lease.heartbeatAll();
+        for (const fencedShardId of fencedShardIds) {
+          relinquish(
+            relinquishDeps,
+            fencedShardId,
+            "batched heartbeat found a superseded epoch"
+          );
+        }
+      },
+      onExit: (reason) => onExit(`writer lease lost: ${reason}`),
+      // Probe cadence scales with the lease TTL (same knob the LeaseManager stamps expires_at from),
+      // so a live writer always renews several times per TTL — a shortened TTL (e.g. the wedged-writer
+      // E2E's 4000ms) must not let a HEALTHY writer's own lease expire between probes. At the default
+      // 15000ms TTL this is exactly the historical 5000ms probe.
+      probeMs: fleetProbeMs(lease.ttlMs)
+    });
+    monitor.start();
+  };
+  client.onConnectionLost?.(() => monitor?.connectionLost());
+  client.onShardConnectionLost?.(
+    (shardId) => relinquish(relinquishDeps, shardId, "commit connection lost", { connectionLost: true })
+  );
+  const armWriter = async (seed) => {
+    await balancer.acquireTargetsNow();
+    if (seed) await lease.seedFrontierAll(await pgStore.maxTimestamp());
+    unregisterReceiptsGuard?.();
+    const receiptsGuard = clientReceiptsGuard();
+    unregisterReceiptsGuard = pgStore.addCommitGuard(async (q, units, shardId) => {
+      await receiptsGuard(q, units, shardId);
+    });
+    unregisterCommitGuard?.();
+    unregisterCommitGuard = installCommitGuard(
+      pgStore,
+      lease,
+      (fencedShardId, reason) => relinquish(relinquishDeps, fencedShardId, reason)
+    );
+    const closeIdle = numShards > 1;
+    frontierMonitor = new FrontierMonitor(lease, {
+      closeIdle,
+      runExclusiveOnShard: (shardId, fn) => runtime.tryRunExclusiveOnShard(shardId, fn),
+      // D4 — replica-lag warning: a hybrid writer keeps a local read-replica tailer (`hybridTailer`,
+      // already started above/on the prior sync boot by the time `armWriter` runs) even though it
+      // commits to the primary — watch ITS watermark against F too. A non-hybrid writer has no
+      // replica (reads the primary directly), so this is omitted there — nothing to lag.
+      tailerWatermark: multiWriter ? () => hybridTailer.watermark() : void 0,
+      // T3.5: wake every follower's LISTEN the instant an idle/orphan shard close (silently, by bare
+      // UPDATE) actually un-pins F — reusing the SAME channel `NotifyingFanoutAdapter` NOTIFYs on a
+      // real commit, so a `ReplicaTailer` armed on either wakes identically. Fire-and-forget +
+      // swallow, exactly like `NotifyingFanoutAdapter.publish`'s own NOTIFY: a transient connection
+      // hiccup here must not break this beat — the poll fallback remains the correctness backstop.
+      notifyOnAdvance: (ceiling) => {
+        void client.notify(COMMIT_CHANNEL, String(ceiling)).catch(() => {
+        });
+      }
+    });
+    frontierMonitor.start();
+    if (closeIdle) {
+      unsubscribeCommits = runtime.writeFanoutAdapter?.subscribe(() => frontierMonitor?.triggerCoalesced()) ?? null;
+    }
+  };
+  if (forwarder.isLocalWriter()) {
+    if (multiWriter) hybridTailer = await startHybridTailer();
+    await armWriter(true);
+    startWriterMonitor();
+    balancer.start();
+    await pgStore.writeGlobalIfAbsent(FLEET_DEPLOYMENT_ID_KEY, crypto.randomUUID());
+    return {
+      role: () => "writer",
+      writerUrl: async () => (await lease.read())?.writerUrl ?? "",
+      onPromoted: (cb) => promotedCbs.push(cb),
+      frontierStats: () => frontierMonitor?.stats() ?? null,
+      groupCommitStats,
+      isLocalWriter: (shardId) => forwarder.isLocalWriter(shardId),
+      idempotencyLookup: (key) => lease.lookupIdempotency(key),
+      idempotencyRecordValue: (key, value) => lease.recordIdempotencyValue(key, value),
+      stop: async () => {
+        monitor?.stop();
+        balancer.stop();
+        frontierMonitor?.stop();
+        unsubscribeCommits?.();
+        unregisterCommitGuard?.();
+        lease.stop();
+        await hybridTailer?.stop();
+        if (hybridTailer) await switchable?.close();
+      }
+    };
+  }
+  if (!replica || !switchable || !replicaPath) {
+    throw new Error(
+      "fleet: sync node start requires a replica + switchable store + replicaPath (bug: prepareFleetNode sync boot must provide them)"
+    );
+  }
+  await pgStore.setupSchema();
+  const reconciled = await reconcileReplicaIdentity({ pgStore, replica, switchable, replicaPath });
+  replica = reconciled.replica;
+  const tailer = new ReplicaTailer(client, pgStore, replica, {
+    // B2a: the ready gate is F = min(frontier_ts) over all N shard rows, and the tailer refuses to
+    // treat a partial `shard_leases` (count < numShards) as ready.
+    numShards,
+    // Same sink the writer-ish derive-only listener uses (D5/T5-c) — observe the ts + fan invalidation
+    // into the sync handler; only the replica-apply (this tailer's default mode) differs.
+    onInvalidation: invalidationSink
+  });
+  await tailer.start();
+  forwarder.attachTailer(tailer);
+  if (multiWriter) hybridTailer = tailer;
+  frontierMonitor = new FrontierMonitor(lease, { closeIdle: false, tailerWatermark: () => tailer.watermark() });
+  frontierMonitor.start();
+  const triggerPromotion = () => {
+    if (promoting) return;
+    promoting = true;
+    void runPromotion({
+      // The lease row (default shard) is already upserted by the tryAcquire() inside acquireLoop when
+      // the election path fires; the balancer path promotes first, then acquires its targets below.
+      promote: async () => {
+        if (multiWriter) {
+          pgStore.setWritable();
+          frontierMonitor?.stop();
+          unsubscribeCommits?.();
+          unsubscribeCommits = null;
+          await armWriter(false);
+          writerish = true;
+          if (lease.currentEpoch(DEFAULT_SHARD4) === null) void stopDriversOnlyChained();
+          return;
+        }
+        await promoteFleetNode({
+          // D4: `startDrivers` routed through the SAME driver chain as every other call site, so this
+          // promotion's step 7 (`await runtime.startDrivers()`) is ordered against any overlapping
+          // `stopDriversOnly()`/`startDrivers()` fired from the balancer or a relinquish, rather than
+          // racing the runtime's own bare call directly.
+          runtime: { observeTimestamp: (ts) => runtime.observeTimestamp(ts), startDrivers: startDriversChained },
+          pgStore,
+          switchable,
+          forwarder,
+          tailer,
+          replica
+        });
+        frontierMonitor?.stop();
+        unsubscribeCommits?.();
+        unsubscribeCommits = null;
+        await armWriter(false);
+        writerish = true;
+        if (lease.currentEpoch(DEFAULT_SHARD4) === null) void stopDriversOnlyChained();
+      },
+      startMonitor: startWriterMonitor,
+      firePromoted,
+      onExit
+    });
+  };
+  doPromote = triggerPromotion;
+  lease.acquireLoop((state) => {
+    runtime.observeWriteTimestamp(state.frontierTs);
+    triggerPromotion();
+    void startDriversChained();
+  });
+  balancer.start();
+  return {
+    role: () => forwarder.isLocalWriter() ? "writer" : "sync",
+    writerUrl: async () => (await lease.read())?.writerUrl ?? "",
+    onPromoted: (cb) => promotedCbs.push(cb),
+    frontierStats: () => frontierMonitor?.stats() ?? null,
+    groupCommitStats,
+    isLocalWriter: (shardId) => forwarder.isLocalWriter(shardId),
+    idempotencyLookup: (key) => lease.lookupIdempotency(key),
+    idempotencyRecordValue: (key, value) => lease.recordIdempotencyValue(key, value),
+    stop: async () => {
+      monitor?.stop();
+      balancer.stop();
+      frontierMonitor?.stop();
+      unsubscribeCommits?.();
+      unregisterCommitGuard?.();
+      lease.stop();
+      await tailer.stop();
+      if (multiWriter) await switchable?.close();
+      await pgStore.close();
+    }
+  };
+}
+
+// src/reshard.ts
+import { DEFAULT_SHARD as DEFAULT_SHARD5, shardIdList as shardIdList3 } from "@helipod/id-codec";
+var NUM_SHARDS_GLOBAL_KEY = "fleet:numShards";
+var ReshardFleetLiveError = class extends Error {
+  liveUrls;
+  constructor(liveUrls) {
+    super(
+      `refusing to reshard: ${liveUrls.length} node(s) still live: ${liveUrls.join(", ")} \u2014 scale the fleet to zero first`
+    );
+    this.name = "ReshardFleetLiveError";
+    this.liveUrls = liveUrls;
+  }
+};
+var ReshardVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReshardVerificationError";
+  }
+};
+var ReshardNotAFleetError = class extends Error {
+  constructor() {
+    super(
+      "this database is not a fleet store (no shard_leases/fleet_nodes tables) \u2014 a fleet is initialized by `helipod serve --fleet`; run the fleet at least once before resharding"
+    );
+    this.name = "ReshardNotAFleetError";
+  }
+};
+function toBigIntOrZero2(v) {
+  if (v === null || v === void 0) return 0n;
+  return typeof v === "bigint" ? v : BigInt(v);
+}
+async function documentsTableExists2(q) {
+  const rows = await q.query(`SELECT to_regclass('documents') IS NOT NULL AS exists`);
+  return rows[0]?.exists === true;
+}
+async function maxDocumentsTs(q) {
+  if (!await documentsTableExists2(q)) return 0n;
+  const rows = await q.query(`SELECT COALESCE(MAX(ts), 0) AS m FROM documents`);
+  return toBigIntOrZero2(rows[0]?.m);
+}
+async function readNumShardsGlobal(q) {
+  const rows = await q.query(`SELECT value FROM persistence_globals WHERE key = $1`, [NUM_SHARDS_GLOBAL_KEY]);
+  const row = rows[0];
+  if (!row) return null;
+  return Number(JSON.parse(row.value));
+}
+function shardIdSet(rows) {
+  return new Set(rows.map((r) => r.shard_id));
+}
+async function reshardFleet(client, opts) {
+  const { targetShards } = opts;
+  if (!Number.isInteger(targetShards) || targetShards < 1) {
+    throw new RangeError(`reshardFleet: targetShards must be an integer >= 1, got ${targetShards}`);
+  }
+  const fleetProbe = await client.query(
+    `SELECT to_regclass('shard_leases') IS NOT NULL AND to_regclass('fleet_nodes') IS NOT NULL AS is_fleet`
+  );
+  if (fleetProbe[0]?.is_fleet !== true) {
+    throw new ReshardNotAFleetError();
+  }
+  const liveRows = await client.query(
+    `SELECT advertise_url AS url FROM fleet_nodes WHERE expires_at >= now()
+     UNION
+     SELECT writer_url AS url FROM shard_leases WHERE writer_url IS NOT NULL AND expires_at >= now()`
+  );
+  const liveUrls = liveRows.map((r) => r.url).filter((u) => typeof u === "string" && u.length > 0);
+  if (liveUrls.length > 0) throw new ReshardFleetLiveError(liveUrls);
+  const laneRows = await client.query(`SELECT shard_id FROM shard_leases`);
+  const currentLanes = shardIdSet(laneRows);
+  const persistedNumShards = await readNumShardsGlobal(client);
+  const previousShards = persistedNumShards ?? currentLanes.size;
+  const target = shardIdList3(targetShards);
+  const targetSet = new Set(target);
+  const created = target.filter((id) => !currentLanes.has(id));
+  const deleted = [...currentLanes].filter((id) => !targetSet.has(id));
+  if (deleted.includes(DEFAULT_SHARD5)) {
+    throw new ReshardVerificationError(`internal invariant violation: "${DEFAULT_SHARD5}" lane marked for deletion`);
+  }
+  await client.transaction(async (tx) => {
+    const seedFragment = await documentsTableExists2(tx) ? `(SELECT COALESCE(MAX(ts), 0) FROM documents)` : `0`;
+    await tx.query(
+      `INSERT INTO persistence_globals (key, value) VALUES ($1, $2)
+       ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value`,
+      [NUM_SHARDS_GLOBAL_KEY, JSON.stringify(String(targetShards))]
+    );
+    for (const shardId of created) {
+      await tx.query(
+        `INSERT INTO shard_leases (shard_id, epoch, writer_url, writer_app_name, expires_at, frontier_ts, prev_ts)
+         VALUES ($1, 0, NULL, NULL, now(), ${seedFragment}, 0)`,
+        [shardId]
+      );
+    }
+    for (const shardId of deleted) {
+      await tx.query(`DELETE FROM shard_leases WHERE shard_id = $1`, [shardId]);
+    }
+    await tx.query(`UPDATE shard_leases SET frontier_ts = GREATEST(frontier_ts, ${seedFragment})`);
+  });
+  const postLaneRows = await client.query(`SELECT shard_id, frontier_ts FROM shard_leases`);
+  const postLaneIds = postLaneRows.map((r) => r.shard_id);
+  const postSet = new Set(postLaneIds);
+  const setMatches = postLaneIds.length === targetShards && target.every((id) => postSet.has(id));
+  if (!setMatches) {
+    throw new ReshardVerificationError(
+      `reshard post-verify failed: expected shard_leases set ${JSON.stringify(target)}, got ${JSON.stringify(postLaneIds)}`
+    );
+  }
+  const frontierValues = postLaneRows.map((r) => toBigIntOrZero2(r.frontier_ts));
+  const minFrontier = frontierValues.reduce((a, b) => b < a ? b : a);
+  const maxTs = await maxDocumentsTs(client);
+  if (minFrontier < maxTs) {
+    throw new ReshardVerificationError(
+      `reshard post-verify failed: min(frontier_ts)=${minFrontier} < MAX(ts)=${maxTs} (the F1 floor)`
+    );
+  }
+  const globalNumShards = await readNumShardsGlobal(client);
+  if (globalNumShards !== targetShards) {
+    throw new ReshardVerificationError(
+      `reshard post-verify failed: fleet:numShards reads back ${globalNumShards}, expected ${targetShards}`
+    );
+  }
+  return {
+    previousShards,
+    newShards: targetShards,
+    created,
+    deleted,
+    frontierFloor: minFrontier.toString()
+  };
+}
+
+// src/index.ts
+var FLEET_VERSION = "0.0.0";
+export {
+  DEFAULT_NUM_SHARDS2 as DEFAULT_NUM_SHARDS,
+  DensityViolationError,
+  FLEET_VERSION,
+  FLEET_WRITER_SESSION_TIMEOUTS,
+  FencedError,
+  FrontierMonitor,
+  IDEMPOTENCY_VALUE_CAP_BYTES,
+  LeaseManager,
+  LeaseMonitor,
+  NUM_SHARDS_GLOBAL_KEY,
+  NotifyingFanoutAdapter,
+  REPLICA_DB_FILENAME,
+  ReplicaTailer,
+  ReshardFleetLiveError,
+  ReshardNotAFleetError,
+  ReshardVerificationError,
+  ShardLeaseBalancer,
+  SwitchableDocStore,
+  WriteForwarder,
+  acquireShardAsWriter,
+  createAsyncChain,
+  deriveFlushesPerSec,
+  docKeyToPointRange,
+  fleetApplicationName,
+  fleetMultiWriterEnabled,
+  groupCommitEnabled,
+  installCommitGuard,
+  keyToPointRange,
+  prepareFleetNode,
+  relinquish,
+  rendezvousOwner,
+  rendezvousWeight,
+  reshardFleet,
+  runPromotion,
+  stablePrefixFromFrontier,
+  startFleetNode
+};
+//# sourceMappingURL=index.js.map