@humwick/server 0.0.0-stage → 0.130.0

package/src/db/gateway.ts

@@ -0,0 +1,513 @@
+// The unified async DB gateway (ADR 0001 §3.3/§3.7.1/§3.8, S2.3 #1878) — the type-level barrier.
+//
+// This is the SOLE SANCTIONED public DB access surface. It folds the already-landed writer seam
+// (S2.1 #1871: writer-gateway + the write-ops registry) and reader pool (S2.2 #1872: reader-pool +
+// the read-ops registry) into ONE async facade — `getGateway()` returns a `DbGateway` whose only
+// operations are `read`/`write`/`tx`/`writeBatch`/`coalesce`, each a Promise of plain data.
+//
+// THE TYPE-LEVEL / MODULE BARRIER (deliverable point 2; ADR §3.3 line ~122 "The ONLY thing exported
+// to feature code. No Database, no getDb"). This module deliberately exports ONLY the op surface, the
+// per-call option/error types, and lifecycle. It NEVER exports the raw `bun:sqlite` `Database` handle,
+// `getDb`, `setDb`, or `writeTransaction`, and no `DbGateway` method returns a handle — so a
+// synchronous `.run()` on the event loop (the freeze class, #1868/#1765/#1847) is UNREPRESENTABLE
+// *through the gateway surface*.
+//
+// THE "UNREPRESENTABLE" GUARANTEE IS DELIVERED BY TWO LAYERS (ADR §3.3) — because no TYPE-level
+// construct alone can make a handle's methods truly unreachable against a determined narrower or an
+// explicit `any`/cast (proven across the S2.3 barrier-hardening review: a caller-chosen result generic
+// is launderable via union/intersection; even a fixed `unknown` return can be narrowed back to a real
+// callable with a `typeof`-type-guard). So the barrier is:
+//   (a) TYPE LAYER (this module) — the ACCIDENTAL and the NAMED handle paths are impossible: there is no
+//       caller-chosen result type on the write family (removing it closed the naming/union/intersection
+//       class), no exported `Database`/`getDb`, and the write family's FIXED result type is `DbValue`
+//       (structured-clone-safe data). Against the determined-narrower probe, `v: DbValue` narrows a
+//       `"run" in v && typeof v.run === "function"` guard to `never`, so `v.run(...)` is NOT callable —
+//       strictly better than `unknown`. What remains is only a DELIBERATE false type-guard (narrow to
+//       `never`) or an explicit `as any`/cast — an accepted LOW, not an accident.
+//   (b) RUNTIME LAYER (S4 #1880) — makes a handle UN-OBTAINABLE at runtime: `getDb()` unexported and
+//       `bun:sqlite` banned outside the allowlisted bootstrap layer. So even a deliberate false type-
+//       guard or `as any` yields plain DATA with no real `.run()` — a call throws, it does not touch
+//       the DB on the loop. `getDb()` stays a DEPRECATED INTERNAL escape hatch (see its JSDoc) only
+//       until the ~1298 S3 (#1870) callsites are drained; it is DELETED at S4 (#1880). Feature code
+//       migrated in S3 imports from HERE, never from `connection.ts`.
+//
+// THE IDEMPOTENCY CONTRACT (deliverable point 3; H5 §3.7.1). The write surface carries `WriteOpts`
+// with `idempotencyKey`; the writer executor REQUIRES it for any op the registry declares
+// non-idempotent and throws `WriteRetrySafetyError` structurally otherwise — so every S3 caller
+// inherits the phantom-failure guarantee ("a write may be committed even when reported as failed";
+// reconcile via the key, never blind-retry) for free by routing through this surface.
+//
+// TWO BACKENDS behind one interface (§3.8):
+//   - in-process (the Phase-0 DEFAULT, §5/§7): every op runs synchronously against the ambient main
+//     connection (`getDb()`), wrapped in a resolved Promise. Behaviorally identical to today's sync
+//     path, so this whole module SHIPS GREEN with ZERO callsite moves. Under `bun test` the in-process
+//     backend still round-trips args/results/errors through the SAME marshaling path as the worker
+//     (H1 §3.8.1), so the default suite fails exactly where production would.
+//   - worker-backed (a file DB, gated on explicitly, §7 Phase 1/2): writes to the size-1 writer pool,
+//     reads to the reader pool. Off the loop; proven by the file-backed integration suite. Production
+//     rollout flips per-domain in S3 (§11.5) — this module does NOT turn it on at bootstrap.
+//
+// THE TWO BACKENDS ARE SELECTED PER HALF (#1960 T1). `initGateway` takes `readerBackend` / `writerBackend`
+// independently (with `backend` kept as the both-halves shorthand); BOTH default to in-process, so this
+// change is behavior-preserving by construction. The split exists because the halves are different risk
+// classes, and coupling them is what blocked the rollout:
+//   - READS are safe to offload. Under WAL a reader takes no write lock, so a worker reader cannot block
+//     or be blocked by the writer, and no main-thread state changes. This is ADR §7 Phase 1 verbatim
+//     ("Route reader ops through the reader pool in production; keep writes in-process on the loop
+//     initially") — and it accounts for ~55% of measured on-loop block-ms on prod.
+//   - WRITES are not. A worker WRITER owns the sole RW connection, so its bootstrap calls `closeDb()`
+//     and every surviving main-thread `getDb()` callsite — ~1380 of them, `/health` included — starts
+//     throwing. That is the S3 burn-down (#1870), not a config flip.
+// So a reader-only flip must leave the writer half COMPLETELY untouched: same in-process writer, same
+// live ambient connection, `closeDb()` never called by this module. Everything keyed off "is the main RW
+// connection still ours?" (`gatewayBackend()`, the writer fault seam, the writer self-heal path) is
+// therefore keyed off the WRITER half specifically, never off "either half is a worker".
+
+import { errMessage } from "@humwick/sdk";
+import { getDbPath } from "./connection.ts";
+// Op-timing capture source (#1882 / ADR §5). One-way dependency — loop-block-attribution imports
+// event-loop-lag + config only, never the gateway/writer stack, so this closes no cycle.
+import { withLoopFrameCapture } from "../loop-block-attribution.ts";
+// One-way dependency (the seam module imports nothing from the writer stack), so pushing the backend
+// in from here cannot close the cycle `gateway → writer-gateway → write-ops → <domain> → seam`.
+import { setWriterFaultsDeliverable } from "./writer-fault-seam.ts";
+import type { ReadArgs, ReadOp, ReadResult } from "./read-ops.ts";
+import {
+  createReaderGateway,
+  ReaderOverloadError,
+  type ReaderGateway,
+  type ReaderGatewayStats,
+} from "./reader-pool.ts";
+import {
+  dbCoalesce,
+  dbTx,
+  dbWrite,
+  dbWriteBatch,
+  initWriter,
+  isWriterInitialized,
+  shutdownWriter,
+  WriteIndeterminateError,
+  WriterOverloadedError,
+  WriteRetrySafetyError,
+  writerStats,
+  type CoalescedEntry,
+  type InitWriterOptions,
+  type WriteOpts,
+  type WriterStats,
+} from "./writer-gateway.ts";
+
+// ── Re-exported sanctioned surface (op types, per-call opts, and the error taxonomy) ───────────────
+// Feature code migrated in S3 imports everything it needs to reach the DB from THIS module — never a
+// raw handle. The re-exports are deliberately scoped to the op surface: types describing ops, the
+// per-call options, and the errors a caller branches on. No `Database`/`getDb`/`writeTransaction`.
+export type { ReadOp, ReadArgs, ReadResult } from "./read-ops.ts";
+export type { WriteOpts, CoalescedEntry, WriterStats } from "./writer-gateway.ts";
+export type { ReaderGatewayStats } from "./reader-pool.ts";
+export {
+  WriteRetrySafetyError,
+  WriterOverloadedError,
+  WriteIndeterminateError,
+  ReaderOverloadError,
+};
+
+/**
+ * A registered writer-op name. Today the writer registry (`WRITER_OPS`) is typed as a name→spec map
+ * whose per-op arg/result types are erased to `unknown`, so this is `string`; the per-op TYPED façade
+ * (`db.messages.send(input)` desugaring to `write("messages.send", input)`) is the hand-written
+ * wrapper layer S3 adds (§11.4). The barrier does not depend on this narrowing — no `WriteOp` value
+ * can ever name a handle; a write is always data-in / data-out.
+ */
+export type WriteOp = string;
+
+/** Per-read options (attribution callsite, §5/H7). Reads are pure, retry-safe, and need no key. */
+export interface ReadOptions {
+  /** Build-time `file:line` for >50 ms loop-gap attribution (Pillar 3 / #1882). */
+  callsite?: string;
+}
+
+/**
+ * A structured-clone-safe result value — the recursive data type a gateway op result is built from.
+ * Covers primitives, `null`/`undefined`, `bigint`, BLOB bytes, arrays, and plain-object rows, and
+ * DELIBERATELY EXCLUDES functions / class instances carrying methods (a `Database` is not a `DbValue`).
+ * S3's typed op wrappers (§11.4) type each write op's result as a `DbValue`-derived shape; today the
+ * write family returns a fixed `DbValue` (see below) and this is exported as the target data type.
+ */
+export type DbValue =
+  | string
+  | number
+  | boolean
+  | bigint
+  | null
+  | undefined
+  | Uint8Array
+  | readonly DbValue[]
+  | { readonly [key: string]: DbValue };
+
+// THE WRITE FAMILY HAS NO CALLER-CHOSEN RESULT TYPE PARAMETER AND RETURNS A FIXED `DbValue` — the
+// load-bearing type-layer decision (ADR §3.3), reached after four barrier-hardening review cycles proved
+// that no type construct alone makes a handle truly unrepresentable:
+//   1. `write<R>` (unconstrained)                 → `write<Database>()` names a handle outright.
+//   2. `write<R extends DbValue>`                  → defeated by INTERSECTION: `Database & DbValue` is
+//      assignable to `DbValue` (an intersection `X & DbValue` always is), so it satisfied the bound
+//      while keeping `Database`'s callable `.run`/`.query`.
+//   3. `write<R extends Record<keyof R, DbValue>>` → defeated by UNION: `keyof (Database | { id: number })`
+//      is `never`, so the bound collapses to `Record<never, DbValue>` = `{}` (vacuously satisfied),
+//      then `const v = await write(...); if ("run" in v) v.run(...)` narrows the union back to the handle.
+//   (The structural self-referential `R extends NoHandles<R>` is separately rejected by TS as a circular
+//    constraint, TS2313.)
+//   4. Fixed `unknown` return (no generic)         → closes the NAMING/union/intersection class (naming a
+//      result type is now an arity error), but a DETERMINED narrower still rebuilds a callable off
+//      `unknown`: `if (typeof v === "object" && v !== null && "run" in v && typeof v.run === "function")
+//      v.run(...)` type-checks, no cast.
+// So the write family drops `<R>` entirely (mirroring `read`'s registry-fixed, NON-caller-chosen
+// `ReadResult<K>`) AND fixes the return type to `DbValue` (structured-clone-safe data). Against the
+// step-4 probe, `v: DbValue` narrows `typeof v.run === "function"` to `never`, so `v.run(...)` is NOT
+// callable — strictly better than `unknown`. The ONLY residual is a DELIBERATE false type-guard (narrow
+// to `never`) or an explicit `as any`/cast — an accepted LOW, backstopped by the runtime layer (S4
+// #1880), NOT a nameable/accidental path. S3 later REFINES this fixed `DbValue` to a per-op result type
+// derived from the write registry — `write<K extends WriteOp>(op: K, …): Promise<WriteResult<K>>`,
+// exactly mirroring `ReadResult<K>` — precise typing WITHOUT ever being caller-selectable. (The write
+// registry does not yet carry per-op result types; that typed-op-map is S3 §11.4 work, so a fixed
+// `DbValue` is the correct interim.)
+
+/** Which backend a `DbGateway` is running against (§3.8). */
+export type GatewayBackend = "in-process" | "worker";
+
+/**
+ * The unified async DB gateway — the ONLY thing feature code touches (ADR §3.3). Every method returns
+ * a Promise of plain, structured-clone-safe data; NONE returns a `Database` handle. That is the
+ * type-level barrier: you cannot obtain a raw connection through this type, so a synchronous `.run()`
+ * on the loop is unrepresentable here.
+ */
+export interface DbGateway {
+  /**
+   * Dispatch a registered READ op off the loop (reader pool in production, in-process in `:memory:`).
+   * Pure and retry-safe; resolves the result or rejects with the reconstructed typed error.
+   */
+  read<K extends ReadOp>(op: K, args: ReadArgs<K>, opts?: ReadOptions): Promise<ReadResult<K>>;
+  /**
+   * Route a single WRITE through the serialized writer queue. Resolves only AFTER the commit durably
+   * lands (INV-1), so a read issued after it resolves sees the write. `opts.idempotencyKey` is REQUIRED
+   * for any op the registry declares non-idempotent (H5 §3.7.1) — a keyless one rejects with
+   * `WriteRetrySafetyError` before anything is written. The result is a FIXED `DbValue` (structured-
+   * clone-safe data) — there is NO caller-chosen result generic (any bound on one is launderable back to
+   * a handle; see the rationale above `DbGateway`). A caller narrows it to the op's row shape (cast, or
+   * S3's typed op wrapper); a handle method is not reachable off `DbValue` even via a `typeof` guard
+   * (it narrows to `never`), short of a deliberate false guard / `as any` — the accepted LOW the S4
+   * #1880 runtime ratchet backstops.
+   */
+  write(op: WriteOp, args: unknown, opts?: WriteOpts): Promise<DbValue>;
+  /**
+   * An atomic multi-statement unit — semantically identical to `write` (the op body already runs inside
+   * one `BEGIN IMMEDIATE` on the writer thread, §3.4), named separately so a caller reading the code
+   * can see the unit is atomic. Interactive/loop-driven transactions are unsupported by design.
+   */
+  tx(op: WriteOp, args: unknown, opts?: WriteOpts): Promise<DbValue>;
+  /**
+   * Coalesce one caller's N-arg list into ONE writer job with per-caller SAVEPOINT isolation (H3
+   * §3.9.1): one `BEGIN IMMEDIATE` amortizes the lock + fsync, but a throw from entry i rolls back only
+   * that entry. Returns a per-entry `result | error` array aligned to `argsList` (each result `DbValue`).
+   */
+  writeBatch(op: WriteOp, argsList: readonly unknown[], opts?: WriteOpts): Promise<CoalescedEntry<DbValue>[]>;
+  /**
+   * Buffer this call with other same-op calls made in the SAME tick and flush them as one coalesced
+   * writer job (§3.9), each caller's promise settling INDEPENDENTLY from its own savepoint. Amortizes
+   * the thread hop over the hottest paths (message send, outbox append) without a timer widening the
+   * durability window (§11.3).
+   */
+  coalesce(op: WriteOp, args: unknown, opts?: WriteOpts): Promise<DbValue>;
+  /** Live backend + writer/reader stats (queue depth, wedged, pool size) — surfaced on `/health`. */
+  readonly stats: DbGatewayStats;
+}
+
+export interface DbGatewayStats {
+  /**
+   * The WRITER backend — the historical meaning of this field, retained so existing readers keep
+   * working across the reader/writer split (#1960 T1). It is what `gatewayBackend()` reports and what
+   * "is the main RW connection still ours?" hinges on. For the reader half read `readerBackend` (or
+   * `reader.backend`); the two can now differ.
+   */
+  backend: GatewayBackend;
+  /** The READ path's backend — independent of `writerBackend` since #1960 T1. */
+  readerBackend: GatewayBackend;
+  /** The WRITE path's backend — the same value as `backend`, named explicitly. */
+  writerBackend: GatewayBackend;
+  writer: WriterStats;
+  reader: ReaderGatewayStats | { backend: "uninitialized" };
+}
+
+export interface InitGatewayOptions {
+  /** DB path; defaults to the live `getDbPath()`. Only consulted when a half runs on a worker. */
+  dbPath?: string;
+  /**
+   * Shorthand that sets BOTH halves at once. Defaults to `"in-process"` — the Phase-0 no-op that runs
+   * every op synchronously against the ambient main connection (so bootstrap spawns NO worker threads
+   * and behavior is unchanged). `"worker"` requires a file DB and stands up the writer + reader pools;
+   * it is used by the integration suite and by the per-domain S3 rollout, never at Phase-0 bootstrap.
+   *
+   * `readerBackend` / `writerBackend` override this per half — see them for the split rationale.
+   */
+  backend?: GatewayBackend;
+  /**
+   * The READ path's backend, overriding `backend`. Defaults to `backend ?? "in-process"`.
+   *
+   * THE POINT OF THE SPLIT (#1960 T1 / ADR §7 Phase 1). Reads are the safe half to offload: under WAL a
+   * reader takes no write lock and cannot block or be blocked by the writer, so a worker-backed reader
+   * changes NOTHING about write behavior. The writer half is a different risk class entirely — the
+   * worker writer owns the sole RW connection, so its bootstrap calls `closeDb()` and every surviving
+   * main-thread `getDb()` callsite (incl. `/health`) starts throwing. Keeping the writer in-process
+   * while the reader moves off-loop is therefore the only landable first step, and before this split it
+   * was not even expressible: one `backend` flag flipped both halves together.
+   */
+  readerBackend?: GatewayBackend;
+  /**
+   * The WRITE path's backend, overriding `backend`. Defaults to `backend ?? "in-process"`.
+   *
+   * CAUTION: a worker writer takes ownership of the sole RW connection — its callers are expected to
+   * `closeDb()` first (see the module header and `initWriter`). Leave this `"in-process"` unless you
+   * are deliberately doing that; a reader-only flip must NOT touch it.
+   */
+  writerBackend?: GatewayBackend;
+  /** Writer-pool tuning (queue high-water, hard cap, writer-job deadline) — see `InitWriterOptions`. */
+  writer?: Omit<InitWriterOptions, "path">;
+  /** Reader-pool tuning (size, queue high-water, per-job timeout). */
+  reader?: { size?: number; queueHighWater?: number; timeoutMs?: number };
+}
+
+/** The resolved per-half backend selection — what `initGateway` actually stands up. */
+export interface ResolvedGatewayBackends {
+  reader: GatewayBackend;
+  writer: GatewayBackend;
+}
+
+/**
+ * Resolve the per-half backends from the options: the specific `readerBackend`/`writerBackend` wins,
+ * then the `backend` shorthand, then the in-process default. Pure, so the selection matrix is testable
+ * without standing up pools or spawning threads (mirrors `resolveReaderBackend` in reader-pool.ts).
+ */
+export function resolveGatewayBackends(options: InitGatewayOptions = {}): ResolvedGatewayBackends {
+  const both = options.backend ?? "in-process";
+  return { reader: options.readerBackend ?? both, writer: options.writerBackend ?? both };
+}
+
+// ── Backend state ───────────────────────────────────────────────────────────────────────────────
+
+let reader: ReaderGateway | undefined;
+// The two halves are tracked SEPARATELY (#1960 T1). Both default to in-process, so a cold/plain
+// bootstrap is byte-for-byte the pre-split behavior.
+let currentReaderBackend: GatewayBackend = "in-process";
+let currentWriterBackend: GatewayBackend = "in-process";
+// The file path a WORKER WRITER was stood up against, RETAINED here so a writer-only re-init
+// (ensureInit self-heal after a lone shutdownWriter) can reconstruct the worker writer WITHOUT
+// depending on `getDbPath()` — worker-WRITER bootstrap intentionally calls `closeDb()` (the worker owns
+// the sole RW connection), which clears `getDbPath()`, so relying on it would silently re-init the
+// writer in-process against a torn-down main handle (HIGH-1, codex-terra L1 review). Deliberately
+// tracks the WRITER only: a worker READER never closes the main handle, so an in-process writer under a
+// worker reader must still self-heal to `":memory:"` (= the ambient `getDb()`), never to a file path.
+let writerWorkerDbPath: string | undefined;
+
+function replaceReader(next: ReaderGateway): void {
+  const previous = reader;
+  reader = next;
+  // Tear the old reader gateway down out of band (mirrors initWriter's `void shutdownWriter()`), so
+  // re-init stays synchronous. A no-op for the in-process backend (its destroy resolves immediately).
+  if (previous) void previous.destroy().catch((error) => console.error(`[gateway] reader teardown failed: ${errMessage(error)}`));
+}
+
+/**
+ * Stand up the unified gateway. Idempotent-friendly: re-calling it replaces the backend (tearing the
+ * old one down). Chooses in-process for BOTH halves by default — the Phase-0 no-op — so a plain
+ * `getGateway()` never spawns worker threads. Pass `{ backend: "worker" }` (file DB) to route both
+ * families through the real pools, or `{ readerBackend: "worker" }` alone for the Phase-R shape:
+ * reads off the loop, writes still on the ambient main connection.
+ *
+ * THE TWO HALVES ARE STOOD UP INDEPENDENTLY and neither reaches into the other's state. In particular
+ * this function NEVER touches the main connection: `closeDb()` is the CALLER's step, required only for
+ * a worker WRITER (which then owns the sole RW connection). So `{ readerBackend: "worker" }` leaves the
+ * writer exactly as a default init leaves it — in-process, running op bodies against the live ambient
+ * `getDb()` — and the ~1380 raw-handle callsites (incl. `/health`) keep working untouched.
+ */
+export function initGateway(options: InitGatewayOptions = {}): void {
+  const { reader: readerB, writer: writerB } = resolveGatewayBackends(options);
+  const dbPath = options.dbPath ?? getDbPath();
+  if ((readerB === "worker" || writerB === "worker") && (!dbPath || dbPath === ":memory:")) {
+    const halves = [readerB === "worker" ? "reader" : undefined, writerB === "worker" ? "writer" : undefined].filter(Boolean).join("+");
+    throw new Error(
+      `gateway worker backend requires a file-backed database, got ${String(dbPath)} — the worker ` +
+        `pools cannot see a :memory: DB (every :memory: handle is a distinct empty DB, §3.5); ` +
+        `requested worker half(s): ${halves}`,
+    );
+  }
+  // ── WRITER half ─────────────────────────────────────────────────────────────────────────────────
+  // `initWriter` picks its backend from the path: a file → the worker pool, `":memory:"` → in-process.
+  // The in-process writer holds no connection of its own and runs the op against the ambient `getDb()`
+  // (the real main handle, file or memory) — which is why an in-process writer is passed `":memory:"`
+  // even when the process is on a file DB, and why it is unaffected by a worker-backed reader.
+  initWriter({ ...options.writer, path: writerB === "worker" ? (dbPath as string) : ":memory:" });
+  // RETAIN for writer-only self-heal (HIGH-1) — getDbPath() is cleared by a worker writer's closeDb().
+  writerWorkerDbPath = writerB === "worker" ? (dbPath as string) : undefined;
+  // ── READER half ─────────────────────────────────────────────────────────────────────────────────
+  // Force the backend rather than letting it fall out of the path, so a file-DB server in Phase 0 still
+  // runs every read synchronously on the main connection (no worker spawned, no callsite moved).
+  replaceReader(
+    readerB === "worker"
+      ? createReaderGateway({
+          dbPath,
+          backend: "worker",
+          size: options.reader?.size,
+          queueHighWater: options.reader?.queueHighWater,
+          timeoutMs: options.reader?.timeoutMs,
+        })
+      : createReaderGateway({ backend: "in-process" }),
+  );
+  currentReaderBackend = readerB;
+  currentWriterBackend = writerB;
+  // An in-transaction crash seam is a main-thread closure; once op bodies run on the WRITER thread it
+  // can never be delivered, so arming one must FAIL rather than silently inject nothing (L-C #1899).
+  // Keyed on the WRITER half only — the seam is armed inside write-op bodies, so a worker reader leaves
+  // fault delivery intact.
+  setWriterFaultsDeliverable(writerB === "in-process");
+}
+
+/** Tear the gateway down (both pools). After this, the next `getGateway()` lazily re-inits in-process. */
+export async function shutdownGateway(): Promise<void> {
+  const previousReader = reader;
+  reader = undefined;
+  currentReaderBackend = "in-process";
+  currentWriterBackend = "in-process";
+  writerWorkerDbPath = undefined;
+  setWriterFaultsDeliverable(true); // back to in-process: op bodies run on the arming thread again
+  await shutdownWriter();
+  await previousReader?.destroy();
+}
+
+/**
+ * Tear down JUST the reader half — terminates any worker-pool threads and replaces them with a fresh
+ * in-process reader. The writer is left COMPLETELY untouched (#1960 T2 server teardown).
+ *
+ * Deliberately NOT `shutdownGateway()`: that also calls `shutdownWriter()`, which unconditionally
+ * REJECTS every write still queued at the writer (writer-gateway.ts) — a needless side effect on a
+ * clean stop, since Phase-R never puts the writer on a worker (it stays in-process always). This is
+ * the shutdown counterpart the design pass calls for (§1.5): "worker threads must be torn down on
+ * shutdown or a restart can leave orphaned threads holding WAL read marks." Safe to call even when the
+ * reader was never worker-backed — the in-process reader's `destroy()` resolves immediately.
+ */
+export async function shutdownGatewayReader(): Promise<void> {
+  const previous = reader;
+  reader = createReaderGateway({ backend: "in-process" });
+  currentReaderBackend = "in-process";
+  await previous?.destroy();
+}
+
+/** Whether the gateway has been stood up (some callers guard bootstrap ordering on this). */
+export function isGatewayInitialized(): boolean {
+  return reader !== undefined;
+}
+
+/**
+ * The live WRITER backend. Domains whose post-commit main-thread work is not yet worker-safe (e.g.
+ * getDb-backed effect delivery) read this to refuse rather than commit-then-silently-drop.
+ *
+ * DELIBERATELY THE WRITER HALF, not "either half" (#1960 T1). Every caller is really asking "is the
+ * main RW connection still ours?" — `events.ts`'s keyless-append guard and `managed-policy.ts`'s
+ * worker-safe builder both branch on that, and it is the WRITER flip that surrenders the connection.
+ * A worker-backed READER changes nothing for them, so they must not start refusing when reads move off
+ * the loop. Use `readerBackend()` for the read half.
+ */
+export function gatewayBackend(): GatewayBackend {
+  return currentWriterBackend;
+}
+
+/** The live READ path backend — independent of the writer since #1960 T1. */
+export function readerBackend(): GatewayBackend {
+  return currentReaderBackend;
+}
+
+/** The live WRITE path backend — the same value as `gatewayBackend()`, named explicitly. */
+export function writerBackend(): GatewayBackend {
+  return currentWriterBackend;
+}
+
+function ensureInit(): void {
+  if (reader === undefined) {
+    // Cold gateway: stand BOTH halves up (in-process by default).
+    initGateway();
+    return;
+  }
+  // The reader and writer are normally stood up AND torn down together by
+  // initGateway()/shutdownGateway(), but the writer CAN be torn down on its own (`shutdownWriter()` —
+  // used by the writer suite's afterEach and reachable directly), leaving `reader` defined while the
+  // writer backend is undefined. A reader-only sentinel then skips re-init and the next write hits
+  // `requireBackend()` → "writer gateway not initialized" — the failure L1 (#1875) surfaced once feature
+  // writes began routing through `getGateway().write/coalesce(...)`. Restore JUST the writer, matching
+  // the live backend, so a lone shutdownWriter() self-heals WITHOUT disturbing the reader (never
+  // downgrading a worker-backed reader to in-process).
+  if (!isWriterInitialized()) {
+    // Reconstruct the writer against the RETAINED WRITER worker path (never getDbPath(), which closeDb()
+    // clears at worker-writer bootstrap — HIGH-1). For in-process, ":memory:" selects the in-process
+    // writer. Keyed on the WRITER half so a worker READER never drags the writer onto a worker.
+    initWriter({ path: currentWriterBackend === "worker" ? writerWorkerDbPath : ":memory:" });
+  }
+}
+
+function requireReader(): ReaderGateway {
+  ensureInit();
+  return reader!;
+}
+
+function gatewayStats(): DbGatewayStats {
+  return {
+    backend: currentWriterBackend, // historical alias for the writer half — see DbGatewayStats
+    readerBackend: currentReaderBackend,
+    writerBackend: currentWriterBackend,
+    writer: writerStats(),
+    reader: reader ? reader.stats : { backend: "uninitialized" },
+  };
+}
+
+// The stable facade singleton. Its methods read the live module globals, so an `initGateway()` that
+// swaps the backend is reflected without handing callers a new object.
+// On-loop-block capture (#1882 / ADR §5) is placed where each op body actually RUNS on the loop:
+//  - READS: the in-process reader runs the op body INLINE inside `requireReader().read(...)` (see
+//    reader-pool.ts), i.e. synchronously in this facade call — so `withLoopFrameCapture` times it here.
+//  - WRITES: `dbWrite`/`dbTx`/`dbWriteBatch`/`dbCoalesce` only ENQUEUE synchronously; the op body runs
+//    later in the writer drain microtask (`kickDrain`). Timing it at this facade would capture only the
+//    ~0ms enqueue (the review-r1 MED: writes were blind). So write capture lives in `dispatchInProcess`
+//    (writer-gateway.ts), with the callsite pinned onto the submission in THIS (the caller's) context.
+//  A half running on a worker attributes no on-loop block for its own family: the op body runs off-thread
+//  and the reader/enqueue synchronous portion is below the record floor. The halves are independent, so
+//  under a worker reader + in-process writer, write capture stays live and read capture goes quiet.
+const GATEWAY: DbGateway = {
+  read<K extends ReadOp>(op: K, args: ReadArgs<K>, opts?: ReadOptions): Promise<ReadResult<K>> {
+    return withLoopFrameCapture({ op, callsite: opts?.callsite }, () => requireReader().read(op, args, opts));
+  },
+  write(op: WriteOp, args: unknown, opts?: WriteOpts): Promise<DbValue> {
+    ensureInit();
+    return dbWrite<DbValue>(op, args, opts);
+  },
+  tx(op: WriteOp, args: unknown, opts?: WriteOpts): Promise<DbValue> {
+    ensureInit();
+    return dbTx<DbValue>(op, args, opts);
+  },
+  writeBatch(op: WriteOp, argsList: readonly unknown[], opts?: WriteOpts): Promise<CoalescedEntry<DbValue>[]> {
+    ensureInit();
+    return dbWriteBatch<DbValue>(op, argsList, opts);
+  },
+  coalesce(op: WriteOp, args: unknown, opts?: WriteOpts): Promise<DbValue> {
+    ensureInit();
+    return dbCoalesce<DbValue>(op, args, opts);
+  },
+  get stats(): DbGatewayStats {
+    return gatewayStats();
+  },
+};
+
+/**
+ * The process-wide DB gateway — the sole sanctioned DB entry point (ADR §3.3). Lazily stands up the
+ * in-process backend on first use if `initGateway()` was not called explicitly, so a caller never sees
+ * an uninitialized gateway. The returned facade is stable across `initGateway()` re-inits.
+ */
+export function getGateway(): DbGateway {
+  ensureInit();
+  return GATEWAY;
+}

package/src/db/generation-launch.ts

@@ -0,0 +1,82 @@
+// #3043 — the params one generation of an agent launched with. A restart rotates the spawnRequestId
+// without writing an agent.spawn row (#1065), so a successor's launch is its restart's `restartSpawn`.
+import { isRecord, isReportVerbosity, projectRoleProvenanceFrom, type ProjectRoleProvenance, type ReportVerbosity } from "@humwick/sdk";
+import { parseJson } from "../utils";
+import { getDb } from "./connection.ts";
+import { hydrateCommandAgentProfile } from "./command-agent-profiles.ts";
+
+export const GENERATION_LAUNCH_PARAMS_SQL = `
+  SELECT params, agent_profile_hash FROM (
+    SELECT params, agent_profile_hash, created_at FROM commands INDEXED BY idx_commands_type_correlation_created WHERE type = 'agent.spawn' AND correlation_id = ?1
+    UNION ALL
+    SELECT json_extract(params, '$.restartSpawn') AS params, NULL AS agent_profile_hash, created_at FROM commands INDEXED BY idx_commands_relaunch_agent
+    WHERE type IN ('agent.restart', 'agent.resume') AND json_valid(params) AND json_extract(params, '$.agentId') = ?2
+      AND json_extract(params, '$.restartSpawn.spawnRequestId') = ?1
+  )
+  ORDER BY created_at DESC
+  LIMIT 1
+`;
+
+/** The `agent.spawn` params of `spawnRequestId`, or the `restartSpawn` of the restart/resume of
+ *  `agentId` that launched it (read through the #2712 relaunch-by-agent index). */
+export function generationLaunchParams(spawnRequestId: string | undefined, agentId: string | undefined): Record<string, unknown> | undefined {
+  if (!spawnRequestId) return undefined;
+  try {
+    const row = getDb().query(GENERATION_LAUNCH_PARAMS_SQL).get(spawnRequestId, agentId ?? null) as { params: string | null; agent_profile_hash: string | null } | undefined;
+    const params = row?.params ? parseJson<unknown>(row.params, undefined) : undefined;
+    return isRecord(params) ? hydrateCommandAgentProfile(params, row?.agent_profile_hash) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface SpawnRegistrationMeta { reportVerbosity?: ReportVerbosity; projectRole?: ProjectRoleProvenance; workflowRunId?: string; harnessSubagentsOverride?: boolean | null; dispatchRationale?: string; dispatchDecision?: AgentDispatchDecision }
+
+/** #3327 — the bounded slice of a dispatch decision an agent keeps: enough to render "Why this model" without the full factors. */
+export interface AgentDispatchDecision { target: Record<string, unknown>; pinned: boolean; rationale: string; warnings: string[]; ranking?: unknown[]; preferences?: Record<string, unknown>; policyRevision?: number; evaluatedAt?: number }
+
+/** Accepts the full decision (launch params) or the bounded one (an earlier registration's meta). */
+export function boundedDispatchDecision(raw: unknown): AgentDispatchDecision | undefined {
+  if (!isRecord(raw) || typeof raw.rationale !== "string" || !raw.rationale || !isRecord(raw.target)) return undefined;
+  const factors = isRecord(raw.factors) ? raw.factors : raw;
+  const ranking = Array.isArray(raw.ranking) ? raw.ranking : Array.isArray(factors.ranking) ? factors.ranking : undefined;
+  return {
+    target: raw.target,
+    pinned: raw.pinned === true,
+    rationale: raw.rationale,
+    warnings: Array.isArray(raw.warnings) ? raw.warnings.filter((w): w is string => typeof w === "string").slice(0, 5) : [],
+    ...(ranking?.length ? { ranking: ranking.slice(0, 5) } : {}),
+    ...(isRecord(factors.preferences) ? { preferences: factors.preferences } : {}),
+    ...(typeof factors.policyRevision === "number" ? { policyRevision: factors.policyRevision } : {}),
+    ...(typeof factors.evaluatedAt === "number" ? { evaluatedAt: factors.evaluatedAt } : {}),
+  };
+}
+
+/** The spawn-chosen facts registration stamps onto a child's meta (#1037 report verbosity, #3043 the
+ *  project role and its commit, #3045 the workflow run that spawned it, #3327 why its model was chosen), from launch params or meta. */
+export function spawnRegistrationMeta(source: Record<string, unknown> | undefined): SpawnRegistrationMeta {
+  if (!source) return {};
+  const projectRole = projectRoleProvenanceFrom(source.projectRole);
+  const decision = boundedDispatchDecision(source.dispatchDecision);
+  const rationale = decision?.rationale ?? source.dispatchRationale;
+  return {
+    ...(isReportVerbosity(source.reportVerbosity) ? { reportVerbosity: source.reportVerbosity } : {}),
+    ...(projectRole ? { projectRole } : {}),
+    ...(typeof source.workflowRunId === "string" && source.workflowRunId ? { workflowRunId: source.workflowRunId } : {}),
+    ...(typeof source.harnessSubagentsOverride === "boolean" || source.harnessSubagentsOverride === null ? { harnessSubagentsOverride: source.harnessSubagentsOverride } : {}),
+    ...(typeof rationale === "string" && rationale ? { dispatchRationale: rationale } : {}),
+    ...(decision ? { dispatchDecision: decision } : {}),
+  };
+}
+
+/** #3045 — the workflow run a step agent works for: its lifecycle and reports go to the run, not the spawner. */
+export function workflowRunIdOf(agent: { meta?: Record<string, unknown> } | null | undefined): string | undefined {
+  const runId = agent?.meta?.workflowRunId;
+  return typeof runId === "string" && runId ? runId : undefined;
+}
+
+export function readSpawnRegistrationMeta(spawnRequestId: string | undefined, agentId?: string): SpawnRegistrationMeta {
+  const launch = generationLaunchParams(spawnRequestId, agentId);
+  // null records profile inheritance; the effective runtime boolean cannot recover that choice.
+  return { ...spawnRegistrationMeta(launch), ...(launch ? { harnessSubagentsOverride: typeof launch.harnessSubagents === "boolean" ? launch.harnessSubagents : null } : {}) };
+}

package/src/db/guides-search.ts

@@ -0,0 +1,18 @@
+import { getDb } from "./connection";
+import type { Guide } from "@humwick/sdk";
+import { ftsQuery } from "../search-query";
+
+function searchGuides({ guides, query }: { guides: Guide[]; query: string }): Guide[] {
+  const match = ftsQuery(query);
+  if (!match) return [];
+  const db = getDb();
+  try {
+    db.run("CREATE VIRTUAL TABLE temp.bundled_guide_search USING fts5(title, summary, tags, body)");
+    const insert = db.query("INSERT INTO temp.bundled_guide_search(rowid, title, summary, tags, body) VALUES (?, ?, ?, ?, ?)");
+    db.transaction(() => guides.forEach((guide, i) => insert.run(i + 1, guide.title, guide.summary, guide.tags.join(" "), guide.body)))();
+    const hits = db.query("SELECT rowid FROM temp.bundled_guide_search WHERE bundled_guide_search MATCH ? ORDER BY bm25(bundled_guide_search), rowid").all(match) as { rowid: number }[];
+    return hits.map(hit => guides[hit.rowid - 1]!);
+  } finally { db.run("DROP TABLE IF EXISTS temp.bundled_guide_search"); }
+}
+
+export const GUIDE_READ_OPS = { "guides.search": searchGuides };