@ultimat3/db 1.2.0 → 3.0.0

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;
+}

package/src/sql-scan.ts

@@ -0,0 +1,159 @@
+// Single responsibility: name the span of SQL text starting at one offset — a comment, a literal,
+// a quoted identifier, a dollar-quoted body, or none of them. One scanner, because a splitter that
+// disagreed with a guard about where a literal ends is a `;` sent as data or a `delete` read as
+// prose, and the two answers must be the same answer.
+
+const IDENTIFIER_START = /[A-Za-z_]/;
+export const IDENTIFIER_PART = /[A-Za-z0-9_]/;
+/** `$` is legal in an identifier after the first character — `a$b` is one name, not three. */
+const IDENTIFIER_TAIL = /[A-Za-z0-9_$]/;
+
+export type NoiseKind = 'line-comment' | 'block-comment' | 'string' | 'identifier' | 'dollar-body';
+
+/** A span that is not code: what it is, and the offset just past it. */
+export interface NoiseSpan {
+  readonly kind: NoiseKind;
+  readonly end: number;
+}
+
+/** Past a `--` comment, including the newline that ends it. */
+function skipLineComment(script: string, index: number): number {
+  const newline = script.indexOf('\n', index);
+  return newline === -1 ? script.length : newline + 1;
+}
+
+/**
+ * Past a block comment. Postgres **nests** them, so the depth is counted rather than matched to
+ * the first terminator — a commented-out block that itself contains a comment closes once, and
+ * every `;` after that point would otherwise be read as data.
+ */
+function skipBlockComment(script: string, index: number): number {
+  let depth = 0;
+  let at = index;
+  while (at < script.length) {
+    const char = script[at];
+    const next = script[at + 1];
+    if (char === '/' && next === '*') {
+      depth += 1;
+      at += 2;
+      continue;
+    }
+    if (char === '*' && next === '/') {
+      depth -= 1;
+      at += 2;
+      if (depth === 0) return at;
+      continue;
+    }
+    at += 1;
+  }
+  return script.length;
+}
+
+/**
+ * Past a run closing on `quote`, where a doubled quote is an escaped one — `'it''s'` and
+ * `"a""b"` are each one token. `escapes` is the `E''` dialect, the only one where a backslash
+ * escapes the character after it; a standard-conforming string carries it as data.
+ */
+function skipQuoted(script: string, index: number, quote: string, escapes: boolean): number {
+  let at = index + 1;
+  while (at < script.length) {
+    const char = script[at];
+    if (escapes && char === '\\') {
+      at += 2;
+      continue;
+    }
+    if (char === quote) {
+      if (script[at + 1] === quote) {
+        at += 2;
+        continue;
+      }
+      return at + 1;
+    }
+    at += 1;
+  }
+  return script.length;
+}
+
+/**
+ * Whether the `$` at `index` continues an identifier instead of opening a delimiter.
+ *
+ * The run before it is walked to its start rather than one character being read, because the
+ * answer is what that run *began* as: `foo$tag$` is the single identifier Postgres reads it as
+ * (`$` is legal after the first character), while `$1$tag$` is a bound parameter followed by a
+ * real delimiter — a run opening with a digit or a `$` cannot be an identifier at all.
+ */
+function insideIdentifier(script: string, index: number): boolean {
+  let at = index - 1;
+  while (at >= 0 && IDENTIFIER_TAIL.test(script[at] ?? '')) at -= 1;
+  const first = script[at + 1];
+  return at + 1 < index && first !== undefined && IDENTIFIER_START.test(first);
+}
+
+/**
+ * The `$tag$` opening a dollar-quoted body at `index`, or `null`. A tag is an identifier or
+ * empty, which is what keeps a bound parameter out: `$1` cannot open a body, so `where "id" = $1`
+ * never swallows the rest of the script.
+ *
+ * A delimiter also needs separating from the identifier before it, or `select foo$tag$; select
+ * 2;` is one statement to us and two to the server — which answers `cannot insert multiple
+ * commands into a prepared statement`.
+ */
+export function dollarTagAt(script: string, index: number): string | null {
+  if (script[index] !== '$') return null;
+  if (insideIdentifier(script, index)) return null;
+  let at = index + 1;
+  while (at < script.length) {
+    const char = script[at] ?? '';
+    const valid = at === index + 1 ? IDENTIFIER_START.test(char) : IDENTIFIER_PART.test(char);
+    if (!valid) break;
+    at += 1;
+  }
+  return script[at] === '$' ? script.slice(index, at + 1) : null;
+}
+
+/** Past the body `tag` opened, up to and including the matching close. */
+function skipDollarBody(script: string, index: number, tag: string): number {
+  const close = script.indexOf(tag, index + tag.length);
+  return close === -1 ? script.length : close + tag.length;
+}
+
+/**
+ * Whether the `'` at `index` opens an `E''` string. The prefix is a whole token, so a trailing
+ * `e` on an identifier does not turn the literal beside it into an escape string.
+ */
+function escapesAt(script: string, index: number): boolean {
+  const prefix = script[index - 1];
+  if (prefix !== 'E' && prefix !== 'e') return false;
+  const before = script[index - 2];
+  return before === undefined || !IDENTIFIER_PART.test(before);
+}
+
+/**
+ * The non-code span starting at `index`, or `null` when `index` is code.
+ *
+ * Source order is the whole point: a caller that asked "is there a comment anywhere" before
+ * "where do the literals end" reads the `--` in `select '--'; delete from posts` as a comment and
+ * erases a live statement. Walking forward one span at a time cannot make that mistake, because
+ * by the time the `--` is reached it is already inside the literal that was scanned first.
+ *
+ * A span left unterminated ends at the end of the text rather than being refused: Postgres names
+ * that syntax error precisely, and a second SQL parser competing with it would only report the
+ * same fault in worse words.
+ */
+export function noiseAt(script: string, index: number): NoiseSpan | null {
+  const char = script[index];
+  if (char === '-' && script[index + 1] === '-') {
+    return { kind: 'line-comment', end: skipLineComment(script, index) };
+  }
+  if (char === '/' && script[index + 1] === '*') {
+    return { kind: 'block-comment', end: skipBlockComment(script, index) };
+  }
+  if (char === "'") {
+    return { kind: 'string', end: skipQuoted(script, index, char, escapesAt(script, index)) };
+  }
+  if (char === '"') {
+    return { kind: 'identifier', end: skipQuoted(script, index, char, false) };
+  }
+  const tag = dollarTagAt(script, index);
+  return tag === null ? null : { kind: 'dollar-body', end: skipDollarBody(script, index, tag) };
+}