@ultimat3/db 1.2.0 → 2.0.0

package/src/observe.ts

@@ -0,0 +1,90 @@
+// Single responsibility: the seam a diagnostic hangs statements off. One installed observer,
+// process-wide, read through one accessor — so the funnels every statement already passes through
+// pay a single `undefined` check when nothing is installed (axiom 6). Nothing here knows what an
+// entity, a request or a span is: `db` is tier 1 and the detector that consumes this is tier 5.
+
+/**
+ * What the layer that compiled the statement knows and the driver cannot: which entity and which
+ * repository operation. It is the difference between "50× `select … where id = $1`" and "50×
+ * `findById` on `members`" in a diagnostic's report.
+ *
+ * Produced by `@ultimat3/entity`'s `postgresRepo` (tier 2, so importing this is downward): it is
+ * the last caller that still knows the entity and the operation by the time the SQL exists, and it
+ * declares both through `withStatementAttribution` (`attribution.ts`) around each repository call.
+ * Hand-written SQL, a migration, a health probe and the job queue's own statements are unattributed
+ * — nothing above them knows an entity to name — which is why the field is optional rather than
+ * required, and why a diagnostic must fall back to the statement text.
+ */
+export interface StatementAttribution {
+  /** Entity name as declared, e.g. `members` — never a table name. */
+  readonly entity: string;
+  /** Repository operation that compiled the statement, e.g. `findById`. */
+  readonly op: string;
+}
+
+/** One settled statement. Emitted after it resolved or rejected, never before it was sent. */
+export interface StatementEvent {
+  /** The statement as sent, parameters still as `$1..$n`. Safe to log; values are separate. */
+  readonly text: string;
+  /** Bound parameters, in order. May carry user data — a consumer that logs must redact. */
+  readonly values: readonly unknown[];
+  /** Wall time from send to settle, from `performance.now()`. */
+  readonly durationMs: number;
+  /** Rows returned by a read, rows affected by a write, `0` when the statement threw. */
+  readonly rows: number;
+  /** The rejection, already wrapped as `X_DB_UNAVAILABLE` by the funnel. */
+  readonly error?: unknown;
+  /**
+   * Who compiled this statement, absent when nothing above the SQL knew — see
+   * `StatementAttribution`. Stamped by the funnel from the scope open at send time, for the same
+   * reason `expected` is: a diagnostic that judges a whole request runs long after every scope in
+   * it closed.
+   */
+  readonly attribution?: StatementAttribution | undefined;
+  /**
+   * The reason of the innermost `expectedQueryLoop()` this statement was issued inside, absent
+   * outside every such scope. Stamped by the funnel at settle time rather than read later, because
+   * a diagnostic that judges a whole request at the end of it runs long after the scope closed. A
+   * detector counting repeats must not warn about these; everything that only measures — the span,
+   * the timeline, a metric — treats them like any other statement.
+   */
+  readonly expected?: string | undefined;
+}
+
+/**
+ * A diagnostic. `onStatement` runs synchronously on the caller's stack once the statement has
+ * settled, so it must not await anything and must not issue SQL — a statement issued from here
+ * re-enters the funnel and observes itself.
+ *
+ * A throw propagates to whoever ran the statement, deliberately: strict test mode is an observer
+ * that fails the test the N+1 happened in, and swallowing here would make that impossible. An
+ * observer that only reports must therefore not throw.
+ */
+export interface StatementObserver {
+  onStatement(event: StatementEvent): void;
+}
+
+let installed: StatementObserver | undefined;
+
+/**
+ * Install the process-wide observer. `setStatementObserver(undefined)` uninstalls, which is the
+ * production state and the state every test must leave behind. The `setDbClient` shape, for the
+ * same reason: the thing being replaced is ambient, so the seam is a setter and not a parameter
+ * threaded through `db()`, `withTransaction()` and both drivers.
+ *
+ * One observer, not a list — a second registration replaces the first. A fan-out array would make
+ * "which diagnostic saw this statement" order-dependent, and the one consumer that needs several
+ * (the dev server) composes them itself, in its own order, where that order is reviewable.
+ */
+export function setStatementObserver(observer: StatementObserver | undefined): void {
+  installed = observer;
+}
+
+/**
+ * The installed observer, or `undefined` when there is none. Read once per statement and guarded
+ * at the call site rather than notified through a wrapper, so an uninstalled seam costs one
+ * property read and one branch — no event object is allocated for nobody to receive.
+ */
+export function statementObserver(): StatementObserver | undefined {
+  return installed;
+}

package/src/pglite-branch.ts

@@ -5,6 +5,7 @@
 
 import { cp, mkdir, rm, stat } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
+import { systemClock } from '@ultimat3/core';
 import type { BranchInfo } from './branch';
 import { assertBranchName } from './branch';
 import { branchExists, dbNotImplemented, dbUnavailable } from './errors';
@@ -77,7 +78,7 @@ export async function branchPglite(
 
   return {
     name: branch,
-    createdAt: (options.now ?? new Date()).toISOString(),
+    createdAt: (options.now ?? systemClock.now()).toISOString(),
     dataDir: to,
     sizeBytes: await directorySize(to),
   };

package/src/pglite-turns.ts

@@ -5,10 +5,15 @@
 // gives `withTransaction` and `readOnlyQuery` on a real server.
 
 /**
- * Gives the connection back. Idempotent for free: it is a settled promise's `resolve`, not a
- * counter, so a second call cannot hand out a second turn — the next caller is already awake.
+ * Gives the connection back. `release()` is idempotent for free: it is a settled promise's
+ * `resolve`, not a counter, so a second call cannot hand out a second turn — the next caller is
+ * already awake. `Disposable`, so `using turn = await queue.take()` gives it back on every exit
+ * path — the same shape as `DbConnection` in `client.ts`, and `[Symbol.dispose]` is `release()`
+ * itself, never a second code path.
  */
-export type Turn = () => void;
+export interface Turn extends Disposable {
+  release(): void;
+}
 
 export interface TurnQueue {
   /** Wait for the connection, then keep it until the returned `Turn` is called. */
@@ -35,16 +40,14 @@ export function createTurnQueue(): TurnQueue {
     // other, not both read the same tail and run at once.
     tail = mine.then(() => held);
     await mine;
-    return release;
+    return { release, [Symbol.dispose]: release };
   }
 
   async function run<T>(work: () => Promise<T>): Promise<T> {
-    const turn = await take();
-    try {
-      return await work();
-    } finally {
-      turn();
-    }
+    // `using`, not `try`/`finally`: the turn must go back on every exit path, including one a
+    // future edit adds above a hand-rolled `finally` that forgot it — see `client.ts`.
+    using _turn = await take();
+    return await work();
   }
 
   return { take, run };

package/src/pglite.ts

@@ -3,11 +3,15 @@
 // The module is resolved at first query and never at import: it is an OPTIONAL peer, and an image
 // that only ever talks to a managed Postgres must not carry 26 MB of WASM it will never load.
 
+import { statementAttribution } from './attribution';
 import type { DbConnection, ReservableClient } from './client';
 import { DbError, dbUnavailable } from './errors';
+import { expectedQueryLoopReason } from './expected-loop';
+import { statementObserver } from './observe';
 import { createTurnQueue } from './pglite-turns';
 import type { SqlFragment } from './sql';
-import { currentTx } from './transaction';
+import { withStatementSpan } from './statement-span';
+import { inLiveTx } from './transaction';
 
 /** What PGlite answers with. `rows` is empty for a write, which is why the count is separate. */
 export interface PgliteResult {
@@ -106,6 +110,17 @@ export interface PgliteClient extends ReservableClient {
   close(): Promise<void>;
 }
 
+// PGlite counts MODIFIED rows, so a SELECT that returned rows still reports `affectedRows: 0` —
+// `??` would answer 0 for every read and disagree with `PostgresClient.execute`. A write that
+// modified nothing returned no rows either, so falling back to the row count stays 0 there. One
+// definition, shared: `execute()` and the observer's event must not disagree about how many rows a
+// statement accounted for.
+function rowsOf(result: PgliteResult): number {
+  return result.affectedRows !== undefined && result.affectedRows > 0
+    ? result.affectedRows
+    : result.rows.length;
+}
+
 /** Lazily boots: constructing a client opens nothing, exactly like `createPostgresClient`. */
 export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
   // One in-flight boot, shared. PGlite takes seconds to start, so two concurrent first queries
@@ -122,7 +137,8 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
     return booting;
   }
 
-  async function statement(driver: PgliteDriver, fragment: SqlFragment): Promise<PgliteResult> {
+  /** The send itself: one statement on the session, every driver failure typed on the way out. */
+  async function send(driver: PgliteDriver, fragment: SqlFragment): Promise<PgliteResult> {
     try {
       return await driver.query(fragment.text, fragment.values);
     } catch (error) {
@@ -130,6 +146,56 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
     }
   }
 
+  /**
+   * The funnel — queued, in-transaction and pinned statements all arrive here, so the observer
+   * hangs off this one function and nowhere else. Uninstalled it costs one property read and one
+   * branch: no clock read, no span, no event object, and `send` receives exactly the call
+   * `statement` made before the seam existed (axiom 6). Same shape as `runOn` in `client.ts`, one
+   * driver up.
+   */
+  async function statement(driver: PgliteDriver, fragment: SqlFragment): Promise<PgliteResult> {
+    const observer = statementObserver();
+    if (observer === undefined) return send(driver, fragment);
+    // Read here for the same reason as `runOn`: the scope is gone by the time a per-request
+    // detector judges what it collected, so the reason travels with the statement it defends.
+    const expected = expectedQueryLoopReason();
+    // And the pair `postgresRepo` left above this frame, for the same reason again: it is what
+    // reports a repository loop as "50× findById on members" rather than as fifty rows of SQL.
+    const attribution = statementAttribution();
+    const started = performance.now();
+    let result: PgliteResult;
+    try {
+      // The span wraps the send and nothing else, so its duration is the statement's and the
+      // observer's own work is not charged to the database.
+      result = await withStatementSpan(fragment.text, () => send(driver, fragment));
+    } catch (error) {
+      // The failing path is observed too — the error is already `X_DB_UNAVAILABLE`, and a throw
+      // from `onStatement` replaces it, which is why `observe.ts` says a reporting-only observer
+      // must not throw.
+      observer.onStatement({
+        text: fragment.text,
+        values: fragment.values,
+        durationMs: performance.now() - started,
+        rows: 0,
+        error,
+        attribution,
+        expected,
+      });
+      throw error;
+    }
+    // Outside the `try` deliberately: a throw from `onStatement` is the observer's, not the
+    // database's, and catching it above would report a statement that succeeded as failed.
+    observer.onStatement({
+      text: fragment.text,
+      values: fragment.values,
+      durationMs: performance.now() - started,
+      rows: rowsOf(result),
+      attribution,
+      expected,
+    });
+    return result;
+  }
+
   async function run(fragment: SqlFragment): Promise<PgliteResult> {
     const driver = await connect();
     // A statement issued inside an open transaction is already inside it — there is one
@@ -137,18 +203,17 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
     // inside of would hang. `handle.enqueue(input, { outbox: false })` within `withTransaction`
     // is the shape that reaches this line; on a pooled server it would get its own connection,
     // and here it joins the caller's transaction because a second connection does not exist.
-    if (currentTx() !== undefined) return statement(driver, fragment);
+    //
+    // The fence is the transaction's LIVENESS, never the ALS store's presence: the store rides
+    // into every promise chain started inside `withTransaction`, so a statement the app forgot to
+    // `await` still found one after COMMIT, skipped the queue, and landed inside whichever unit of
+    // work held the session next — a stray statement in someone else's transaction, committed or
+    // rolled back with it, with no error anywhere. A closed scope falls through and takes its own
+    // turn, exactly as `client.ts`'s released pin sends a late statement back to the pool.
+    if (inLiveTx()) return statement(driver, fragment);
     return turns.run(() => statement(driver, fragment));
   }
 
-  // PGlite counts MODIFIED rows, so a SELECT that returned rows still reports `affectedRows: 0` —
-  // `??` would answer 0 for every read and disagree with `PostgresClient.execute`. A write that
-  // modified nothing returned no rows either, so falling back to the row count stays 0 there.
-  const rowsOf = (result: PgliteResult): number =>
-    result.affectedRows !== undefined && result.affectedRows > 0
-      ? result.affectedRows
-      : result.rows.length;
-
   return {
     async query<T>(fragment: SqlFragment): Promise<readonly T[]> {
       return (await run(fragment)).rows as readonly T[];
@@ -172,15 +237,20 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
       // statement queues like any other caller and waits for its own turn.
       const on = (fragment: SqlFragment): Promise<PgliteResult> =>
         held ? statement(driver, fragment) : turns.run(() => statement(driver, fragment));
+      // Idempotent for free: `turn.release()` is a settled promise's `resolve`, not a counter, so
+      // a second call cannot hand out a second turn (`pglite-turns.ts`). `[Symbol.dispose]` below
+      // is that same call.
+      const release = (): void => {
+        held = false;
+        turn.release();
+      };
       return {
         query: async <T>(fragment: SqlFragment) => (await on(fragment)).rows as readonly T[],
         one: async <T>(fragment: SqlFragment) =>
           ((await on(fragment)).rows[0] as T | undefined) ?? null,
         execute: async (fragment: SqlFragment) => rowsOf(await on(fragment)),
-        release: () => {
-          held = false;
-          turn();
-        },
+        release,
+        [Symbol.dispose]: release,
       };
     },
     async ping(): Promise<void> {

package/src/readonly-query.ts

@@ -4,8 +4,10 @@
 // meant to ask for.
 
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
-import { stripSqlNoise } from './readonly';
+import { multipleStatements } from './errors';
 import { identifier, raw, sql } from './sql';
+import { stripSqlNoise } from './sql-noise';
+import { statementsOf } from './statement-split';
 
 /** Default per-statement ceiling for an agent-authored read. */
 export const READONLY_TIMEOUT_MS = 5_000;
@@ -70,18 +72,29 @@ function cursorable(statement: string): boolean {
  * to keep right.
  *
  * Deliberately does not use `withTransaction`: it nests into an ambient transaction with a
- * `SAVEPOINT`, and a savepoint inside a read-write transaction is not read-only. Deliberately
- * does not wrap the connection in `readOnly()` either: that guard's regex would refuse our own
- * `SET LOCAL` statements, and `BEGIN READ ONLY` is a stronger, Postgres-enforced backstop.
+ * `SAVEPOINT`, and a savepoint inside a read-write transaction is not read-only. It runs no
+ * mutating-keyword scan of its own either — `BEGIN READ ONLY` is the server refusing the write,
+ * which is stronger than any regex, and this package deliberately ships no second answer to "is
+ * this SQL a write?" (`@ultimat3/mcp`'s parse guard is layer 3, and it is the only one).
  */
 export async function readOnlyQuery<T>(
   statement: string,
   options: ReadOnlyQueryOptions = {},
 ): Promise<ReadOnlyQueryResult<T>> {
+  // ONE statement, decided before anything is opened. Not a second mutating-keyword scan — a
+  // different question, and the one the guards below depend on: only the first command of a text
+  // is bounded by them, so `select 1; set statement_timeout = 0` undid the timeout this function
+  // had just installed while `guards` went on reporting `timeout:5000ms`. `statementsOf` is the
+  // package's one splitter, so a `;` inside a literal, a comment or a dollar-quoted body is data.
+  const statements = statementsOf(statement);
+  if (statements.length > 1) throw multipleStatements(statement, statements.length);
+
   const client = options.client ?? baseClient();
   // A pooled BEGIN that lands on a different physical connection than the query that follows is
   // not a transaction at all, so a reservable client must pin one connection for the sequence.
-  const reserved: DbConnection | undefined = isReservable(client)
+  // Held by a `using` declaration, the same shape as `withTransaction` — the pin comes back on
+  // every exit path, and no future edit can move a statement above the guard that returns it.
+  using reserved: DbConnection | undefined = isReservable(client)
     ? await client.reserve()
     : undefined;
   const connection: DbClient = reserved ?? client;
@@ -122,8 +135,6 @@ export async function readOnlyQuery<T>(
     // Best-effort: the caller needs the original error, never the rollback's.
     await connection.execute(raw('ROLLBACK')).catch(() => undefined);
     throw error;
-  } finally {
-    reserved?.release();
   }
 }
 
@@ -146,7 +157,8 @@ async function readRows<T>(
 ): Promise<readonly T[]> {
   if (fetch === undefined || !cursorable(statement)) return connection.query<T>(raw(statement));
 
-  // A trailing `;` would close `DECLARE` before its query and turn one statement into two.
+  // A trailing `;` would close `DECLARE` before its query and turn one statement into two. An
+  // EMBEDDED one is refused up in `readOnlyQuery`, before the transaction opens.
   const query = statement.trim().replace(/;\s*$/, '');
   await connection.execute(raw(`DECLARE ${CURSOR_NAME} NO SCROLL CURSOR FOR ${query}`));
   const rows = await connection.query<T>(raw(`FETCH FORWARD ${fetch} FROM ${CURSOR_NAME}`));

package/src/snapshot-json.ts

@@ -0,0 +1,84 @@
+// Single responsibility: serialise a `SchemaDescription` as the JSON Biome would have printed.
+// `x db gen` writes this file into an app whose `lint` step is `biome check .`, so a serialiser
+// that is not a fixed point of the formatter is a framework that fails its own gate — which
+// `JSON.stringify(…, null, 2)` was, on every snapshot carrying a one-element array.
+
+import type { SchemaDescription } from './introspect';
+
+/** What `x new` writes into the scaffold's `biome.json`, and what this repo's own config sets. */
+const LINE_WIDTH = 100;
+const INDENT = 2;
+
+/**
+ * Biome's two JSON rules, measured against 2.5.5 and the whole of this module:
+ *
+ * - an **object** keeps the source's shape — a line break after `{` stays broken, and `{}` stays
+ *   inline — so emitting every non-empty object broken is stable by construction;
+ * - an **array** collapses onto one line when every element is already on one line and the whole
+ *   line fits, *counting the trailing comma*, at `<= LINE_WIDTH`.
+ *
+ * So the only arithmetic is the array's, and the only thing that can force an array open is a
+ * non-empty object inside it.
+ */
+function expands(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(expands);
+  if (typeof value === 'object' && value !== null) return Object.keys(value).length > 0;
+  return false;
+}
+
+function inline(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(inline).join(', ')}]`;
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return '{}';
+    const members = entries.map(([key, each]) => `${JSON.stringify(key)}: ${inline(each)}`);
+    return `{ ${members.join(', ')} }`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * `column` is what the line already holds before this value; `trailing` is what follows it on the
+ * same line — 1 for the comma of a member that is not the last. Both exist only for the array rule.
+ */
+function print(value: unknown, depth: number, column: number, trailing: number): string {
+  const pad = ' '.repeat(depth * INDENT);
+  const inner = ' '.repeat((depth + 1) * INDENT);
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    const one = inline(value);
+    if (!expands(value) && column + one.length + trailing <= LINE_WIDTH) return one;
+    const items = value.map((each, index) => {
+      const comma = index === value.length - 1 ? '' : ',';
+      return `${inner}${print(each, depth + 1, inner.length, comma.length)}${comma}`;
+    });
+    return `[\n${items.join('\n')}\n${pad}]`;
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return '{}';
+    const members = entries.map(([key, each], index) => {
+      const label = `${JSON.stringify(key)}: `;
+      const comma = index === entries.length - 1 ? '' : ',';
+      const printed = print(each, depth + 1, inner.length + label.length, comma.length);
+      return `${inner}${label}${printed}${comma}`;
+    });
+    return `{\n${members.join('\n')}\n${pad}}`;
+  }
+
+  return JSON.stringify(value);
+}
+
+/**
+ * The sidecar's bytes, trailing newline included.
+ *
+ * Round-tripped through `JSON.parse(JSON.stringify(…))` first so the printer walks exactly the
+ * value the reader will parse back: an `undefined` field disappears here rather than reaching a
+ * printer that has no spelling for it.
+ */
+export function snapshotJson(snapshot: SchemaDescription): string {
+  const plain: unknown = JSON.parse(JSON.stringify(snapshot));
+  return `${print(plain, 0, 0, 0)}\n`;
+}

package/src/snapshot-parse.ts

@@ -0,0 +1,99 @@
+// Single responsibility: turn the JSON of a `<id>.snapshot.json` sidecar into a `SchemaDescription`
+// or into nothing. It lives beside the type it validates, because "what a valid snapshot is" is
+// this package's answer and the reader on disk is `@ultimat3/cli`'s — two owners of that question
+// is a sidecar one of them accepts and the other cannot use.
+
+import type {
+  ColumnDescription,
+  ForeignKeyDescription,
+  IndexDescription,
+  SchemaDescription,
+  TableDescription,
+} from './introspect';
+
+type Row = Record<string, unknown>;
+
+const isRow = (value: unknown): value is Row =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const str = (value: unknown): value is string => typeof value === 'string';
+const bool = (value: unknown): value is boolean => typeof value === 'boolean';
+const nullableStr = (value: unknown): value is string | null => value === null || str(value);
+const strings = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every(str);
+
+/** `null` is Postgres' own default; anything else must be one of the two directions. */
+const order = (value: unknown): value is 'asc' | 'desc' | null =>
+  value === null || value === 'asc' || value === 'desc';
+
+function column(value: unknown): ColumnDescription | undefined {
+  if (!isRow(value)) return undefined;
+  const { name, dataType, nullable, default: fallback, position } = value;
+  if (!str(name) || !str(dataType) || !bool(nullable) || !nullableStr(fallback)) return undefined;
+  if (typeof position !== 'number') return undefined;
+  return { name, dataType, nullable, default: fallback, position };
+}
+
+function index(value: unknown): IndexDescription | undefined {
+  if (!isRow(value)) return undefined;
+  const { name, columns, unique, primary, where, order: direction } = value;
+  if (!str(name) || !strings(columns) || !bool(unique) || !bool(primary)) return undefined;
+  // Written by 1.2.0 onwards. A sidecar from before it carries neither, and the total, ascending
+  // reading is what that generation actually emitted — so an older file stays readable rather
+  // than being discarded whole, which would refuse to generate against every existing app.
+  if (!(where === undefined || nullableStr(where))) return undefined;
+  if (!(direction === undefined || order(direction))) return undefined;
+  return {
+    name,
+    columns,
+    unique,
+    primary,
+    where: where === undefined ? null : where,
+    order: direction === undefined ? null : direction,
+  };
+}
+
+function foreignKey(value: unknown): ForeignKeyDescription | undefined {
+  if (!isRow(value)) return undefined;
+  const { name, columns, referencedTable, referencedColumns, onDelete } = value;
+  if (!str(name) || !strings(columns) || !str(referencedTable)) return undefined;
+  if (!strings(referencedColumns) || !nullableStr(onDelete)) return undefined;
+  return { name, columns, referencedTable, referencedColumns, onDelete };
+}
+
+/** `undefined` from any member rejects the whole list — a partial table is not a smaller one. */
+function all<T>(value: unknown, one: (item: unknown) => T | undefined): readonly T[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const parsed: T[] = [];
+  for (const item of value) {
+    const each = one(item);
+    if (each === undefined) return undefined;
+    parsed.push(each);
+  }
+  return parsed;
+}
+
+function tableOf(value: unknown): TableDescription | undefined {
+  if (!isRow(value)) return undefined;
+  const { schema, name, primaryKey } = value;
+  if (!str(schema) || !str(name) || !strings(primaryKey)) return undefined;
+  const columns = all(value['columns'], column);
+  const indexes = all(value['indexes'], index);
+  const foreignKeys = all(value['foreignKeys'], foreignKey);
+  if (columns === undefined || indexes === undefined || foreignKeys === undefined) return undefined;
+  return { schema, name, columns, primaryKey, indexes, foreignKeys };
+}
+
+/**
+ * The snapshot `value` describes, or `undefined` if it describes anything else.
+ *
+ * Every nested field is parsed, not asserted: `{"tables":[null]}` is syntactically valid JSON that
+ * an `Array.isArray(tables)` check accepted and a cast then called a `SchemaDescription`, so the
+ * first `table.columns` in the diff threw on a truncated or hand-edited sidecar rather than
+ * regenerating it. A file that will not parse is *absent* — which the caller already handles.
+ */
+export function parseSnapshot(value: unknown): SchemaDescription | undefined {
+  if (!isRow(value)) return undefined;
+  const tables = all(value['tables'], tableOf);
+  return tables === undefined ? undefined : { tables };
+}

package/src/sql-noise.ts

@@ -0,0 +1,40 @@
+// Single responsibility: blank everything a keyword could legitimately hide inside — comments,
+// literals, quoted identifiers, dollar-quoted bodies — so a reader judging SQL text sees the
+// operation and not the prose around it. Two readers share it (`readOnlyQuery`'s cursorable check,
+// the destructive rail), and one wrong answer here is a wrong answer in both.
+
+import { noiseAt } from './sql-scan';
+
+/** What each blanked span leaves behind. A quote pair stays a token; a comment becomes a gap. */
+const BLANK: Readonly<Record<string, string>> = {
+  'line-comment': ' ',
+  'block-comment': ' ',
+  'dollar-body': ' ',
+  string: " '' ",
+  identifier: ' "" ',
+};
+
+/**
+ * Comments, literals, quoted identifiers and dollar-quoted bodies, each replaced by whitespace or
+ * an empty quote pair.
+ *
+ * Scanned in source order rather than by a sequence of replacements, and that ordering is the
+ * whole guard: blanking comments first reads the `--` in `select '--'; delete from posts` as a
+ * comment and erases the `delete` with it, so anything reading the blanked text sees a SELECT
+ * where a mutating statement was. `sql-noise.test.ts` pins that case and the four beside it.
+ */
+export function stripSqlNoise(text: string): string {
+  let out = '';
+  let index = 0;
+  while (index < text.length) {
+    const noise = noiseAt(text, index);
+    if (noise === null) {
+      out += text[index];
+      index += 1;
+      continue;
+    }
+    out += BLANK[noise.kind] ?? ' ';
+    index = noise.end;
+  }
+  return out;
+}