@ultimat3/db 25.0.0 → 25.2.0

package/CLAUDE.md

@@ -100,8 +100,8 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - **`expected-loop.ts` is the ONLY suppression**: `expectedQueryLoop(reason, fn)`, innermost reason,
   blank is `X_INVARIANT`; the funnel stamps `expected`; it suppresses a verdict, never a statement.
   The framework's own loops declare themselves (`migrate()`, `rollback()`, admin's `search.ts`).
-- `@ultimat3/jobs` never imports this package; its statements pass the observer only as
-  `packages/cli/src/runtime-queue.ts` wraps a real client for its `PgExecutor`, unattributed.
+- `@ultimat3/jobs` never imports this package; its statements pass the observer through
+  `dbExecutor` (`db-executor.ts`, the ONE `PgExecutor` builder; the CLI binds it), unattributed.
 
 ## Migrations
 

package/README.md

@@ -28,6 +28,7 @@ await withTransaction(async (tx) => {
 | `sql` / `raw` / `identifier` / `literal` / `join` | fragment builders |
 | `shellInertIdentifier()` | `As of 2026-08-26`: a quoted identifier that is also inert wherever a human PASTES it — or `null`. The one screen a catalog name goes through before it reaches a `fix:`. `identifier()` answers about SQL and **accepts** a backtick and a `$`, which are exactly what a shell substitutes inside double quotes, so a column called `$(id)` inside `x db gen "add $(id)"` runs `id` on paste |
 | `db()` / `baseClient()` / `setDbClient()` | the ambient client; `db()` returns the open tx if any |
+| `dbExecutor(client = db)` | the client as `@ultimat3/core`'s `PgExecutor` (`query(text, values)`) — what a jobs, idempotency, notify or MCP confirmation store takes. The client is resolved per statement: the default reaches the boot's client even when declared at module scope, and joins an open `withTransaction`; `() => pool` pins one pool whatever transaction is open |
 | `DbTx.origin` | `As of 2026-08`: the client the transaction was **opened on** — `options.client` or `baseClient()`, never the reservation it runs statements through. `@ultimat3/entity` compares a pinned repository's client against it, so a pinned repo joins its own shard's transaction instead of being refused |
 | `withTransaction()` / `currentTx()` | transaction scope; `currentTx()` is the outbox seam. `{ retry: n }` (`As of 2026-08`) re-runs `fn` from the top on a `40001`/`40P01` and on nothing else — default 0, so `fn` must be idempotent before you ask for it. Each re-run **waits first**, `As of 2026-08-23`: exponential from 10ms, capped at 500ms, full jitter (`@ultimat3/core`'s `backoffDelay`). A budget of 0 waits not at all. **A transaction the server aborted is reported as one**, `As of 2026-10-02` → [Transactions that end badly](#transactions-that-end-badly) |
 | `liveTxConnection()` | the connection of the transaction still **open** on this async context, or `undefined`. `currentTx()` keeps answering a finished scope's handle to a promise chain the body forgot to await; this is the one that says whether a statement sent now is really inside a transaction. `@ultimat3/action` reads it before binding an idempotency settlement to a commit |
@@ -112,7 +113,8 @@ the transaction untouched.
 `As of 2026-07`: a bug in one defence must not become a write, so `db.query` on the MCP dev
 server stacks independent layers rather than trusting a single gate. This package owns the two
 layers that are Postgres facts rather than MCP facts — the tool-boundary layers (pre-parse scan,
-policy) live above it, and `@ultimat3/mcp` never imports this package directly.
+policy) live above it, and `@ultimat3/mcp` imports nothing of this package but one lexer rule,
+`endOfBlockComment` (a nested `/* */` ends where Postgres ends it, `null` when it never closes).
 
 ```ts
 import { ensureReadOnlyRole, readOnlyQuery } from '@ultimat3/db';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "25.0.0",
+  "version": "25.2.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.0.0"
+    "@ultimat3/core": "25.2.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/db-executor.ts

@@ -0,0 +1,24 @@
+// Single responsibility: a `DbClient` as `@ultimat3/core`'s structural `PgExecutor` — the
+// `query(text, values)` seam the jobs queue, the outbox, the idempotency, notify and MCP
+// confirmation stores take. The ONE builder: the boot and an app both build theirs here.
+
+import type { PgExecutor } from '@ultimat3/core';
+import { type DbClient, db } from './client';
+import type { SqlFragment } from './sql';
+
+/**
+ * The client is resolved per STATEMENT, never at the call. Default `db`: the installed client, so
+ * an executor declared at module scope — before boot installs one — still reaches the boot's, and
+ * inside `withTransaction` the transaction's own connection, so a store's row commits or rolls
+ * back with the business rows. Pass `() => client` for a store that must stay on one pool whatever
+ * transaction is open (the boot's queue and idempotency reservations).
+ *
+ * The fragment is assembled by hand rather than through `sql`` `: a store hands over `$1..$n`
+ * text it wrote itself plus already-bound values, so there is nothing to interpolate or guard.
+ */
+export function dbExecutor(client: () => DbClient = db): PgExecutor {
+  return {
+    query: <R>(text: string, values: readonly unknown[]): Promise<readonly R[]> =>
+      client().query<R>({ text, values } satisfies SqlFragment),
+  };
+}

package/src/dependent-view.ts

@@ -21,7 +21,7 @@
 import type { DbClient } from './client';
 import { migrationViewDepends } from './migration-errors';
 import { identifier, join, sql } from './sql';
-import { IDENTIFIER_PART, noiseAt } from './sql-scan';
+import { foldIdentifier, IDENTIFIER_CHAR, noiseAt } from './sql-scan';
 import { statementsOf } from './statement-split';
 
 /** One `alter table <table> alter column <column> type …`, as the catalog spells both names. */
@@ -44,7 +44,7 @@ interface SqlWord {
 
 /**
  * The names in one statement, in order, folded the way Postgres folds them: an unquoted identifier
- * to lower case, a quoted one verbatim. Comments, string literals and dollar-quoted bodies
+ * to lower case in ASCII only (`foldIdentifier`), a quoted one verbatim. Comments, string literals and dollar-quoted bodies
  * contribute nothing, through this package's one lexer — `-- alter column` is prose and
  * `'alter column'` is data.
  */
@@ -60,13 +60,13 @@ function wordsOf(statement: string): readonly SqlWord[] {
       at = noise.end;
       continue;
     }
-    if (!IDENTIFIER_PART.test(statement[at] ?? '')) {
+    if (!IDENTIFIER_CHAR.test(statement[at] ?? '')) {
       at += 1;
       continue;
     }
     let end = at;
-    while (end < statement.length && IDENTIFIER_PART.test(statement[end] ?? '')) end += 1;
-    words.push({ text: statement.slice(at, end).toLowerCase(), quoted: false });
+    while (end < statement.length && IDENTIFIER_CHAR.test(statement[end] ?? '')) end += 1;
+    words.push({ text: foldIdentifier(statement.slice(at, end)), quoted: false });
     at = end;
   }
   return words;

package/src/index.ts

@@ -30,6 +30,7 @@ export type {
 export { baseClient, db, isReservable, postgresClient, setDbClient } from './client';
 export type { ColumnDefaultLike } from './column-default';
 export { defaultExpression } from './column-default';
+export { dbExecutor } from './db-executor';
 export type { DbHealthReport } from './db-health';
 export { checkDb } from './db-health';
 export {
@@ -198,6 +199,7 @@ export {
   sql,
 } from './sql';
 export { stripSqlNoise } from './sql-noise';
+export { dollarTagAt, endOfBlockComment } from './sql-scan';
 export type { DbSqlStateCode } from './sqlstate';
 export { DB_SQLSTATE_CODES, isRetryableState, SQLSTATE, sqlState, sqlStateCode } from './sqlstate';
 export { statementFingerprint, statementKind, statementVerb } from './statement-shape';

package/src/retype-dependents.ts

@@ -22,7 +22,7 @@ import { addCheck, dropCheck } from './check-ddl';
 import type { Plan } from './foreign-key-plan';
 import { asDeclared, createIndex, dropIndex } from './index-ddl';
 import type { CheckDescription, IndexDescription, TableDescription } from './introspect';
-import { IDENTIFIER_PART, noiseAt } from './sql-scan';
+import { IDENTIFIER_CHAR, noiseAt } from './sql-scan';
 
 /**
  * Whether `expression` reads `column`, over-approximating on purpose.
@@ -52,12 +52,12 @@ export function referencesColumn(expression: string, column: string): boolean {
       at = noise.end;
       continue;
     }
-    if (!IDENTIFIER_PART.test(expression[at] ?? '')) {
+    if (!IDENTIFIER_CHAR.test(expression[at] ?? '')) {
       at += 1;
       continue;
     }
     let end = at;
-    while (end < expression.length && IDENTIFIER_PART.test(expression[end] ?? '')) end += 1;
+    while (end < expression.length && IDENTIFIER_CHAR.test(expression[end] ?? '')) end += 1;
     if (expression.slice(at, end).toLowerCase() === wanted) return true;
     at = end;
   }

package/src/sql-scan.ts

@@ -3,10 +3,27 @@
 // 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_$]/;
+/**
+ * Postgres's `ident_start`/`dolq_start`: any non-ASCII character too (`\200-\377` per UTF-8 byte),
+ * so `$é$` opens a body and `é$x$` is one name — read against a server, `sql-scan.test.ts`.
+ */
+const IDENTIFIER_START = /[A-Za-z_\u0080-\uffff]/;
+/** A tag's `dolq_cont`: an identifier character without the `$`, non-ASCII included. */
+const TAG_PART = /[A-Za-z0-9_\u0080-\uffff]/;
+/**
+ * `ident_cont`: the one class every word scan in this package reads a name with. `$` is legal
+ * after the first character (`a$b` is one name, not three) and so is any non-ASCII one — an
+ * ASCII-only scan found `col` inside `écol` and never found `prénom` at all.
+ */
+export const IDENTIFIER_CHAR = /[A-Za-z0-9_$\u0080-\uffff]/;
+
+/**
+ * An unquoted name as a UTF8 server stores it: ASCII folded to lower case and nothing else —
+ * `Évent` stays `Évent` (read against a server, `dependent-view.test.ts`). `toLowerCase()` folded
+ * the `É` too and named a column the catalog does not hold.
+ */
+export const foldIdentifier = (name: string): string =>
+  name.replace(/[A-Z]+/g, (run) => run.toLowerCase());
 
 export type NoiseKind = 'line-comment' | 'block-comment' | 'string' | 'identifier' | 'dollar-body';
 
@@ -23,11 +40,13 @@ function skipLineComment(script: string, index: number): number {
 }
 
 /**
- * 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.
+ * Past a block comment opening at `index`, or `null` when it never closes. 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. Exported for `@ultimat3/mcp`'s read-only check, which REFUSES an unclosed
+ * comment where this lexer runs it to the end: one rule for where a comment ends, two readers.
  */
-function skipBlockComment(script: string, index: number): number {
+export function endOfBlockComment(script: string, index: number): number | null {
   let depth = 0;
   let at = index;
   while (at < script.length) {
@@ -46,9 +65,13 @@ function skipBlockComment(script: string, index: number): number {
     }
     at += 1;
   }
-  return script.length;
+  return null;
 }
 
+/** An unclosed comment runs to the end: Postgres reports that syntax error, not this lexer. */
+const skipBlockComment = (script: string, index: number): number =>
+  endOfBlockComment(script, index) ?? 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
@@ -84,7 +107,7 @@ function skipQuoted(script: string, index: number, quote: string, escapes: boole
  */
 function insideIdentifier(script: string, index: number): boolean {
   let at = index - 1;
-  while (at >= 0 && IDENTIFIER_TAIL.test(script[at] ?? '')) at -= 1;
+  while (at >= 0 && IDENTIFIER_CHAR.test(script[at] ?? '')) at -= 1;
   const first = script[at + 1];
   return at + 1 < index && first !== undefined && IDENTIFIER_START.test(first);
 }
@@ -104,7 +127,7 @@ export function dollarTagAt(script: string, index: number): string | 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);
+    const valid = at === index + 1 ? IDENTIFIER_START.test(char) : TAG_PART.test(char);
     if (!valid) break;
     at += 1;
   }
@@ -125,7 +148,9 @@ 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);
+  // `IDENTIFIER_CHAR`, never an ASCII-only class: `éE` and `a$E` are names to Postgres,
+  // and reading their `E` as a prefix let a `\'` swallow the `;` before a `drop table`.
+  return before === undefined || !IDENTIFIER_CHAR.test(before);
 }
 
 /**