@fuzdev/fuz_app 0.41.1 → 0.42.0

package/dist/auth/CLAUDE.md

@@ -513,9 +513,96 @@ run'` if the seed somehow missed (defensive — migrations always seed).
     `permit_actor_role_active_unique` and installs scope-aware
     `permit_actor_role_scope_active_unique` using the
     `PERMIT_OFFER_SCOPE_SENTINEL_UUID`.
-- Forward-only (no down). Named migrations are preferred so the name
+- Forward-only (no down). Migrations are `{name, up}` objects; the name
   surfaces in error messages.
 
+#### Runner contract (`db/migrate.ts`)
+
+The `schema_version` table stores **one row per applied migration**, keyed
+by `(namespace, name)` with a monotonically-increasing per-namespace
+`sequence` and `applied_at`. `run_migrations` reads applied rows ordered
+by `sequence`, then enforces:
+
+1. **Length check first.** If `applied.length > code.length`, throw
+   `binary-older-than-db` listing the unknown names. Short-circuits
+   before name verify so a binary-older case with a rename in the overlap
+   doesn't fire `name-divergence-at-N` first and send the operator chasing
+   a phantom source-revert.
+2. **Name-prefix verify.** For each `i < applied.length`, assert
+   `applied[i].name === code[i].name`; mismatch throws
+   `name-divergence-at-N` with `at_index`.
+3. **Run the pending tail** (`code[applied.length..]`) inside a single
+   chain transaction; each `INSERT` uses `sequence = max(sequence) + 1`.
+
+**Append-only after first publish.** Once a fuz_app version containing a
+migration is published, the migration's name and position are frozen.
+Pre-publish, anything goes; the cliff is the publish event. Body edits to
+a published migration slip past the runner (no content hashing) — schema-
+snapshot tests in consumers catch these.
+
+`MigrationError` is the only error class thrown from `run_migrations` /
+`baseline`; branch on `.kind` (never on message text). Kinds:
+`binary-older-than-db`, `name-divergence-at-N`, `old-tracker-shape`,
+`migration-failed`, `baseline-name-not-in-code`,
+`baseline-name-out-of-order`, `baseline-namespace-already-populated`.
+
+`baseline(db, ns, names)` is the only sanctioned non-execution path —
+INSERTs tracker rows for a name-prefix of `ns.migrations` without running
+their `up` functions. Used to promote an existing schema (e.g. preserved
+through a tracker-shape upgrade) into the new tracker. Per-namespace
+populated guard lets multi-call cutover scripts resume after partial
+failure. `baseline()` does **not** verify the schema actually matches
+what the named migrations would have produced — pair with a
+schema-assertion script post-baseline.
+
+There is **no programmatic bypass on the main `run_migrations` path**.
+No `--force`, no `skip_verification`. If you need to deviate, reach for
+`baseline()` (named, narrow) or direct SQL on the tracker (operator
+explicitly states intent).
+
+#### Operator recipes (run with the service stopped — these bypass the advisory lock)
+
+**Rename a migration** (typo fix, etc.). This is a coordinated code+SQL
+change, not just SQL:
+
+1. Stop the service. Disable auto-restart for the cutover window.
+2. Run the SQL `UPDATE` first — old code on disk doesn't read `name`, so
+   running this with the old build still deployed is harmless and the
+   safer order.
+3. Deploy the build with the renamed migration in the code array.
+4. Start the service — boot's name-prefix verify passes.
+
+The bad order is "deploy code with new name, then SQL UPDATE" — boot
+fires `name-divergence-at-N` and refuses to start in between.
+
+```sql
+UPDATE schema_version SET name = 'new_name'
+ WHERE namespace = $ns AND name = 'old_name';
+```
+
+**Mark a single migration applied without running it** (extreme repair —
+prefer `baseline()` when promoting a whole prefix):
+
+```sql
+INSERT INTO schema_version (namespace, name, sequence, applied_at)
+VALUES ($ns, $name,
+        (SELECT COALESCE(MAX(sequence), -1) + 1
+           FROM schema_version WHERE namespace = $ns),
+        NOW());
+```
+
+**Reset a namespace** (drop tracker rows; idempotent migrations re-apply
+on next boot):
+
+```sql
+DELETE FROM schema_version WHERE namespace = $ns;
+```
+
+A `set_applied()` / `rename_applied()` helper was considered and
+rejected — even one sanctioned bypass that doesn't name the operator's
+intent invites use as a regular tool. Direct SQL forces the operator to
+consciously violate the contract.
+
 ## Middleware
 
 Side of the chain ordering (concept-level — see the root `../../../CLAUDE.md`

package/dist/auth/migrations.d.ts

@@ -1,17 +1,20 @@
 /**
  * Auth schema migrations.
  *
- * Single v0 migration for the fuz identity system tables.
+ * Ordered list of `{name, up}` migrations for the fuz identity system tables.
  * Consumed by `run_migrations` with namespace `'fuz_auth'`.
  *
- * Collapsed to a single v0 for the 0.1.0 release — no production databases
- * exist, so the prior v0–v6 development iterations are consolidated.
- * Post-0.1.0, each new migration appends as v1, v2, etc.
+ * **Append-only after first publish.** Once a fuz_app version containing a
+ * given migration is published (`npm publish` / `jsr publish`), that
+ * migration's name and position are frozen. Never edit, rename, or reorder —
+ * append only. Pre-publish, anything goes; the cliff is the publish event.
+ * Body edits to a published migration slip past the runner (no content
+ * hashing) and are caught by schema-snapshot tests in consumers.
  *
  * To add a migration, append a new entry to `AUTH_MIGRATIONS`:
  *
  * ```ts
- * // v1: add display_name to account
+ * // v2: add display_name to account
  * {
  *   name: 'account_display_name',
  *   up: async (db) => {
@@ -21,8 +24,7 @@
  * ```
  *
  * Migrations are forward-only (no down). Use `IF NOT EXISTS` / `IF EXISTS`
- * for DDL safety. Named migrations (`{name, up}`) are preferred for
- * debuggability — the name appears in error messages on failure.
+ * for DDL safety. The `name` appears in error messages on failure.
  *
  * @module
  */

package/dist/auth/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA6BH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAEpE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CA6D5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA6BH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAEpE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CA6D5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}

package/dist/auth/migrations.js

@@ -1,17 +1,20 @@
 /**
  * Auth schema migrations.
  *
- * Single v0 migration for the fuz identity system tables.
+ * Ordered list of `{name, up}` migrations for the fuz identity system tables.
  * Consumed by `run_migrations` with namespace `'fuz_auth'`.
  *
- * Collapsed to a single v0 for the 0.1.0 release — no production databases
- * exist, so the prior v0–v6 development iterations are consolidated.
- * Post-0.1.0, each new migration appends as v1, v2, etc.
+ * **Append-only after first publish.** Once a fuz_app version containing a
+ * given migration is published (`npm publish` / `jsr publish`), that
+ * migration's name and position are frozen. Never edit, rename, or reorder —
+ * append only. Pre-publish, anything goes; the cliff is the publish event.
+ * Body edits to a published migration slip past the runner (no content
+ * hashing) and are caught by schema-snapshot tests in consumers.
  *
  * To add a migration, append a new entry to `AUTH_MIGRATIONS`:
  *
  * ```ts
- * // v1: add display_name to account
+ * // v2: add display_name to account
  * {
  *   name: 'account_display_name',
  *   up: async (db) => {
@@ -21,8 +24,7 @@
  * ```
  *
  * Migrations are forward-only (no down). Use `IF NOT EXISTS` / `IF EXISTS`
- * for DDL safety. Named migrations (`{name, up}`) are preferred for
- * debuggability — the name appears in error messages on failure.
+ * for DDL safety. The `name` appears in error messages on failure.
  *
  * @module
  */

package/dist/db/migrate.d.ts

@@ -1,45 +1,59 @@
 /**
- * Version-gated database migration runner.
+ * Identity-tracked database migration runner.
  *
- * Migrations are functions in ordered arrays, grouped by namespace.
- * A `schema_version` table tracks progress per namespace.
+ * Migrations are named `{name, up}` objects in ordered arrays, grouped by
+ * namespace. A `schema_version` table records one row per applied migration —
+ * `(namespace, name, sequence, applied_at)` — and the runner verifies the
+ * applied list is a name-prefix of the code's migration array at boot.
  *
- * **Chain-level transactions**: All pending migrations in a namespace run in a
- * single transaction. Any failure rolls back every migration in that run —
+ * **Append-only after first publish**: once a fuz_app version containing a
+ * given migration is published (`npm publish` / `jsr publish`), that
+ * migration's name and position are frozen. Never edit, rename, or reorder
+ * after publish — append only. Pre-publish, anything goes; the cliff is the
+ * publish event. Edits to a published migration's body slip past the runner
+ * (no content hashing) and are caught by schema-snapshot tests in consumers.
+ *
+ * **Chain-level transactions**: All pending migrations in a namespace run in
+ * a single transaction. Any failure rolls back every migration in that run —
  * no partial-state recovery. This rules out non-transactional DDL (e.g.,
  * `CREATE INDEX CONCURRENTLY`); run those out of band.
  *
- * **Forward-only**: No down-migrations. Schema changes are additive.
- * For pre-release development, collapse migrations into a single v0.
+ * **Chain idempotency, not migration idempotency**: the chain-tx wraps every
+ * migration replayed in a single boot, so an individual migration may
+ * temporarily produce intermediate state that a later migration reverses
+ * (e.g. v0's `PERMIT_INDEXES` recreates an index that v1 drops; chain-tx
+ * hides this from observers). What matters is that the *committed end state*
+ * matches; the in-tx steps may not be individually idempotent against an
+ * arbitrary mid-chain target.
  *
- * **Named migrations**: Migrations can be bare functions or `{name, up}` objects.
- * Names appear in error messages for debuggability.
+ * **Forward-only**: No down-migrations. Schema changes are additive.
  *
- * **Advisory locking**: Per-namespace PostgreSQL advisory locks serialize
- * concurrent migration runs, preventing double-application in multi-instance deployments.
+ * **Advisory locking**: Per-namespace `pg_advisory_lock` reduces contention
+ * in multi-instance deployments — best-effort, not load-bearing. The locks
+ * are session-scoped, but `Db.query` runs against a pool that may check out
+ * a different backend per call, so two concurrent boots can both "hold"
+ * the lock on different sessions. The real serialization comes from chain-
+ * tx atomicity + the `(namespace, name)` PK on `schema_version`: the
+ * loser's INSERT hits a PK violation, the chain-tx rolls back, and the
+ * next boot reads the committed state and proceeds cleanly. Environments
+ * without `pg_advisory_lock` (some PGlite versions) silently fall through.
  *
  * @module
  */
 import type { Db } from './db.js';
 /**
- * A single migration function that receives a `Db` and applies DDL/DML.
- *
- * Runs inside a transaction — throw to rollback.
- */
-export type MigrationFn = (db: Db) => Promise<void>;
-/**
- * A migration: either a bare function or a named object with an `up` function.
+ * A single migration: a name + an `up` function applied inside a transaction.
  *
- * Named migrations include their name in error messages for debuggability.
+ * Throw from `up` to roll back the entire chain.
  */
-export type Migration = MigrationFn | {
+export interface Migration {
     name: string;
-    up: MigrationFn;
-};
+    up: (db: Db) => Promise<void>;
+}
 /**
  * A named group of ordered migrations.
  *
- * Array index = version number: `migrations[0]` is version 0, etc.
+ * Array index = position in the chain. Append-only after publish.
  */
 export interface MigrationNamespace {
     namespace: string;
@@ -48,30 +62,101 @@ export interface MigrationNamespace {
 /** Result of running migrations for a single namespace. */
 export interface MigrationResult {
     namespace: string;
-    from_version: number;
-    to_version: number;
-    migrations_applied: number;
+    /** Migrations applied in this run, in sequence-ascending (execution) order. */
+    applied_names: Array<string>;
+}
+/**
+ * Tagged error vocabulary for {@link run_migrations} and {@link baseline}.
+ *
+ * Callers branch on `.kind` rather than matching error messages — message
+ * text is for operators, not control flow.
+ */
+export type MigrationErrorKind = 'binary-older-than-db' | 'name-divergence-at-N' | 'old-tracker-shape' | 'migration-failed' | 'baseline-name-not-in-code' | 'baseline-name-out-of-order' | 'baseline-namespace-already-populated';
+/** Structured context passed alongside a {@link MigrationError}. */
+export interface MigrationErrorContext {
+    namespace?: string;
+    at_index?: number;
+    unknown_names?: ReadonlyArray<string>;
+    cause?: unknown;
+}
+/**
+ * Tagged error thrown by {@link run_migrations} and {@link baseline}.
+ *
+ * Branch on `.kind`; the message carries an operator-facing remediation hint.
+ */
+export declare class MigrationError extends Error {
+    readonly kind: MigrationErrorKind;
+    readonly namespace?: string;
+    readonly at_index?: number;
+    readonly unknown_names?: ReadonlyArray<string>;
+    constructor(kind: MigrationErrorKind, message: string, context?: MigrationErrorContext);
 }
 /**
  * Run pending migrations for each namespace.
  *
- * Creates the `schema_version` tracking table if it does not exist,
- * then for each namespace: acquires an advisory lock, reads the current
- * version, runs all pending migrations in order inside a single transaction,
- * updates the stored version, and releases the lock.
+ * For each namespace: acquires an advisory lock, reads applied rows ordered
+ * by `sequence`, length-checks (binary-older-than-db short-circuits), name-
+ * prefix-verifies, then runs the pending tail in a single chain transaction.
+ * Each migration's row is INSERTed with `sequence = max(sequence) + 1` for
+ * the namespace.
+ *
+ * **Length check before name verify** is load-bearing: a binary-older case
+ * with a rename in the overlap would otherwise fire `name-divergence-at-N`
+ * first and the operator would chase a phantom source-revert before
+ * discovering the binary is the real problem.
  *
- * **Atomicity**: The pending chain for each namespace runs in one transaction —
- * any failure rolls back every migration that ran in that invocation. The
- * next run starts from the previously-stored version, re-running the whole
- * (fixed) chain. Namespaces are independent: a later namespace's failure
- * does not roll back an earlier namespace that already committed.
+ * **Atomicity**: any failure rolls back every migration that ran in that
+ * invocation. Namespaces are independent: a later namespace's failure does
+ * not roll back an earlier namespace that already committed.
  *
- * **Concurrency**: Uses PostgreSQL advisory locks to serialize concurrent
- * callers on the same namespace. Safe for multi-instance deployments.
+ * **Concurrency**: per-namespace advisory locks reduce contention in
+ * multi-instance deployments but are best-effort on pool drivers (see
+ * module docstring §Advisory locking). Correctness on concurrent boots
+ * falls out of chain-tx atomicity + the `(namespace, name)` PK — the
+ * loser's INSERT triggers PK violation and rollback; subsequent boots
+ * see the committed state.
  *
  * @param db - the database instance
- * @param namespaces - migration namespaces to process in order
- * @returns results per namespace (only includes namespaces that had work to do)
+ * @param namespaces - migration namespaces, processed in the order passed
+ * @returns one result per namespace where work happened (already-up-to-date
+ *   namespaces are omitted)
+ * @throws MigrationError with `kind` of `binary-older-than-db`,
+ *   `name-divergence-at-N`, `old-tracker-shape`, or `migration-failed`
  */
 export declare const run_migrations: (db: Db, namespaces: Array<MigrationNamespace>) => Promise<Array<MigrationResult>>;
+/**
+ * Insert tracker rows for the named migrations of a namespace **without
+ * executing them**.
+ *
+ * Used to promote an existing schema (e.g. produced by a pre-0.42 build,
+ * preserved through a tracker-shape upgrade) into the new identity tracker.
+ * `baseline()` trusts the operator-supplied list — it does not verify that
+ * the schema actually matches what the named migrations would have produced.
+ * Pair with a schema-assertion script post-baseline before re-enabling traffic.
+ *
+ * Contract:
+ * - Probes for the pre-0.42 tracker shape; throws `old-tracker-shape` if
+ *   found (DDL with `IF NOT EXISTS` would otherwise no-op against the old
+ *   table and the INSERT would fail with a confusing column-not-found).
+ * - Creates the new-shape `schema_version` table if missing — cutover
+ *   scripts that just dropped the old-shape table can call `baseline()`
+ *   directly with no separate DDL step.
+ * - Acquires the same per-namespace advisory lock as `run_migrations` (with
+ *   the same try/catch fallback for environments lacking `pg_advisory_lock`).
+ * - Refuses if any tracker rows already exist *for this namespace* — lets
+ *   multi-call baseline scripts resume after partial failure (completed
+ *   namespaces guard themselves while remaining ones still run).
+ * - Verifies the supplied names are a strict prefix of the namespace's
+ *   current migrations array — a name not in the array, or out of order,
+ *   errors before any INSERT.
+ * - Writes sequences `0..N-1` in one transaction.
+ *
+ * @param db - the database instance
+ * @param ns - the namespace whose migrations are being baselined
+ * @param names - prefix of `ns.migrations[].name` to record as already-applied
+ * @throws MigrationError with `kind` of `old-tracker-shape`,
+ *   `baseline-name-not-in-code`, `baseline-name-out-of-order`, or
+ *   `baseline-namespace-already-populated`
+ */
+export declare const baseline: (db: Db, ns: MigrationNamespace, names: ReadonlyArray<string>) => Promise<void>;
 //# sourceMappingURL=migrate.d.ts.map

package/dist/db/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAEhC;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;CAC3B;AA8BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,cAAc,GAC1B,IAAI,EAAE,EACN,YAAY,KAAK,CAAC,kBAAkB,CAAC,KACnC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CA0EhC,CAAC"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAEhC;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC3B,sBAAsB,GACtB,sBAAsB,GACtB,mBAAmB,GACnB,kBAAkB,GAClB,2BAA2B,GAC3B,4BAA4B,GAC5B,sCAAsC,CAAC;AAE1C,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;gBAEnC,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;CAQtF;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,cAAc,GAC1B,IAAI,EAAE,EACN,YAAY,KAAK,CAAC,kBAAkB,CAAC,KACnC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAuFhC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,QAAQ,GACpB,IAAI,EAAE,EACN,IAAI,kBAAkB,EACtB,OAAO,aAAa,CAAC,MAAM,CAAC,KAC1B,OAAO,CAAC,IAAI,CA+Dd,CAAC"}

package/dist/db/migrate.js

@@ -1,38 +1,91 @@
 /**
- * Version-gated database migration runner.
+ * Identity-tracked database migration runner.
  *
- * Migrations are functions in ordered arrays, grouped by namespace.
- * A `schema_version` table tracks progress per namespace.
+ * Migrations are named `{name, up}` objects in ordered arrays, grouped by
+ * namespace. A `schema_version` table records one row per applied migration —
+ * `(namespace, name, sequence, applied_at)` — and the runner verifies the
+ * applied list is a name-prefix of the code's migration array at boot.
  *
- * **Chain-level transactions**: All pending migrations in a namespace run in a
- * single transaction. Any failure rolls back every migration in that run —
+ * **Append-only after first publish**: once a fuz_app version containing a
+ * given migration is published (`npm publish` / `jsr publish`), that
+ * migration's name and position are frozen. Never edit, rename, or reorder
+ * after publish — append only. Pre-publish, anything goes; the cliff is the
+ * publish event. Edits to a published migration's body slip past the runner
+ * (no content hashing) and are caught by schema-snapshot tests in consumers.
+ *
+ * **Chain-level transactions**: All pending migrations in a namespace run in
+ * a single transaction. Any failure rolls back every migration in that run —
  * no partial-state recovery. This rules out non-transactional DDL (e.g.,
  * `CREATE INDEX CONCURRENTLY`); run those out of band.
  *
- * **Forward-only**: No down-migrations. Schema changes are additive.
- * For pre-release development, collapse migrations into a single v0.
+ * **Chain idempotency, not migration idempotency**: the chain-tx wraps every
+ * migration replayed in a single boot, so an individual migration may
+ * temporarily produce intermediate state that a later migration reverses
+ * (e.g. v0's `PERMIT_INDEXES` recreates an index that v1 drops; chain-tx
+ * hides this from observers). What matters is that the *committed end state*
+ * matches; the in-tx steps may not be individually idempotent against an
+ * arbitrary mid-chain target.
  *
- * **Named migrations**: Migrations can be bare functions or `{name, up}` objects.
- * Names appear in error messages for debuggability.
+ * **Forward-only**: No down-migrations. Schema changes are additive.
  *
- * **Advisory locking**: Per-namespace PostgreSQL advisory locks serialize
- * concurrent migration runs, preventing double-application in multi-instance deployments.
+ * **Advisory locking**: Per-namespace `pg_advisory_lock` reduces contention
+ * in multi-instance deployments — best-effort, not load-bearing. The locks
+ * are session-scoped, but `Db.query` runs against a pool that may check out
+ * a different backend per call, so two concurrent boots can both "hold"
+ * the lock on different sessions. The real serialization comes from chain-
+ * tx atomicity + the `(namespace, name)` PK on `schema_version`: the
+ * loser's INSERT hits a PK violation, the chain-tx rolls back, and the
+ * next boot reads the committed state and proceeds cleanly. Environments
+ * without `pg_advisory_lock` (some PGlite versions) silently fall through.
  *
  * @module
  */
+/**
+ * Tagged error thrown by {@link run_migrations} and {@link baseline}.
+ *
+ * Branch on `.kind`; the message carries an operator-facing remediation hint.
+ */
+export class MigrationError extends Error {
+    kind;
+    namespace;
+    at_index;
+    unknown_names;
+    constructor(kind, message, context) {
+        super(message, context?.cause !== undefined ? { cause: context.cause } : undefined);
+        this.name = 'MigrationError';
+        this.kind = kind;
+        this.namespace = context?.namespace;
+        this.at_index = context?.at_index;
+        this.unknown_names = context?.unknown_names;
+    }
+}
 const SCHEMA_VERSION_DDL = `
 CREATE TABLE IF NOT EXISTS schema_version (
-  namespace TEXT PRIMARY KEY,
-  version INTEGER NOT NULL DEFAULT 0,
-  applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  namespace  TEXT        NOT NULL,
+  name       TEXT        NOT NULL,
+  sequence   INTEGER     NOT NULL,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (namespace, name),
+  UNIQUE (namespace, sequence)
 )`;
-/** Normalize a migration to its function and optional name. */
-const resolve_migration = (m) => {
-    if (typeof m === 'function') {
-        return { fn: m, name: null };
-    }
-    return { fn: m.up, name: m.name };
+/**
+ * Detect the pre-0.42 `schema_version` shape (`namespace`, `version`,
+ * `applied_at`). The new-shape DDL uses `IF NOT EXISTS` and would silently
+ * no-op against the old table, so this probe runs before DDL and before any
+ * per-namespace lock.
+ */
+const detect_old_tracker = async (db) => {
+    const row = await db.query_one(`SELECT EXISTS (
+			SELECT 1 FROM information_schema.columns
+			WHERE table_schema = 'public'
+			  AND table_name = 'schema_version'
+			  AND column_name = 'version'
+		) as exists`);
+    return row?.exists ?? false;
 };
+const OLD_TRACKER_HINT = 'Detected fuz_app < 0.42 tracker shape (schema_version.version column exists). ' +
+    'Hint: `DROP TABLE schema_version` and re-run, or call `baseline()` first if ' +
+    'preserving an existing schema.';
 /**
  * Compute a stable int32 advisory lock key from a namespace string.
  *
@@ -45,83 +98,199 @@ const namespace_lock_key = (namespace) => {
     }
     return hash;
 };
+/**
+ * Run `fn` with the namespace's advisory lock held.
+ *
+ * Acquire / release are best-effort and silently fall through in
+ * environments without `pg_advisory_lock` (some PGlite versions). The
+ * `finally` ensures release on any throw from `fn`.
+ */
+const with_namespace_lock = async (db, namespace, fn) => {
+    const lock_key = namespace_lock_key(namespace);
+    try {
+        await db.query('SELECT pg_advisory_lock($1)', [lock_key]);
+    }
+    catch {
+        // Advisory lock not supported — proceed without serialization
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            await db.query('SELECT pg_advisory_unlock($1)', [lock_key]);
+        }
+        catch {
+            // Advisory lock not supported — nothing to release
+        }
+    }
+};
 /**
  * Run pending migrations for each namespace.
  *
- * Creates the `schema_version` tracking table if it does not exist,
- * then for each namespace: acquires an advisory lock, reads the current
- * version, runs all pending migrations in order inside a single transaction,
- * updates the stored version, and releases the lock.
+ * For each namespace: acquires an advisory lock, reads applied rows ordered
+ * by `sequence`, length-checks (binary-older-than-db short-circuits), name-
+ * prefix-verifies, then runs the pending tail in a single chain transaction.
+ * Each migration's row is INSERTed with `sequence = max(sequence) + 1` for
+ * the namespace.
+ *
+ * **Length check before name verify** is load-bearing: a binary-older case
+ * with a rename in the overlap would otherwise fire `name-divergence-at-N`
+ * first and the operator would chase a phantom source-revert before
+ * discovering the binary is the real problem.
  *
- * **Atomicity**: The pending chain for each namespace runs in one transaction —
- * any failure rolls back every migration that ran in that invocation. The
- * next run starts from the previously-stored version, re-running the whole
- * (fixed) chain. Namespaces are independent: a later namespace's failure
- * does not roll back an earlier namespace that already committed.
+ * **Atomicity**: any failure rolls back every migration that ran in that
+ * invocation. Namespaces are independent: a later namespace's failure does
+ * not roll back an earlier namespace that already committed.
  *
- * **Concurrency**: Uses PostgreSQL advisory locks to serialize concurrent
- * callers on the same namespace. Safe for multi-instance deployments.
+ * **Concurrency**: per-namespace advisory locks reduce contention in
+ * multi-instance deployments but are best-effort on pool drivers (see
+ * module docstring §Advisory locking). Correctness on concurrent boots
+ * falls out of chain-tx atomicity + the `(namespace, name)` PK — the
+ * loser's INSERT triggers PK violation and rollback; subsequent boots
+ * see the committed state.
  *
  * @param db - the database instance
- * @param namespaces - migration namespaces to process in order
- * @returns results per namespace (only includes namespaces that had work to do)
+ * @param namespaces - migration namespaces, processed in the order passed
+ * @returns one result per namespace where work happened (already-up-to-date
+ *   namespaces are omitted)
+ * @throws MigrationError with `kind` of `binary-older-than-db`,
+ *   `name-divergence-at-N`, `old-tracker-shape`, or `migration-failed`
  */
 export const run_migrations = async (db, namespaces) => {
+    if (await detect_old_tracker(db)) {
+        throw new MigrationError('old-tracker-shape', OLD_TRACKER_HINT);
+    }
     await db.query(SCHEMA_VERSION_DDL);
     const results = [];
     for (const { namespace, migrations } of namespaces) {
-        const lock_key = namespace_lock_key(namespace);
-        // Acquire advisory lock — serializes concurrent migration runs
-        try {
-            await db.query('SELECT pg_advisory_lock($1)', [lock_key]);
-        }
-        catch {
-            // Advisory lock not supported (e.g. some PGlite versions) — proceed without
-        }
-        try {
-            const row = await db.query_one('SELECT version FROM schema_version WHERE namespace = $1', [namespace]);
-            const current_version = row?.version ?? 0;
-            if (current_version > migrations.length) {
-                throw new Error(`schema_version for "${namespace}" is ${current_version} but only ${migrations.length} migrations exist — was a migration removed?`);
+        await with_namespace_lock(db, namespace, async () => {
+            const applied = await db.query(`SELECT name, sequence FROM schema_version
+				 WHERE namespace = $1
+				 ORDER BY sequence ASC`, [namespace]);
+            // Step 3: length check (short-circuits before name verify)
+            if (applied.length > migrations.length) {
+                const unknown_names = applied.slice(migrations.length).map((r) => r.name);
+                throw new MigrationError('binary-older-than-db', `Namespace "${namespace}": database has ${applied.length} applied migrations ` +
+                    `but the code only knows ${migrations.length}. ` +
+                    `Unknown to this binary: ${unknown_names.map((n) => `"${n}"`).join(', ')}. ` +
+                    `Hint: upgrade the code to a version that includes these migrations; ` +
+                    `if you must downgrade, manually delete the unknown rows from schema_version.`, { namespace, unknown_names });
             }
-            if (current_version === migrations.length) {
-                continue; // up to date
+            // Step 4: name-prefix verify
+            for (let i = 0; i < applied.length; i++) {
+                const applied_name = applied[i].name;
+                const code_name = migrations[i].name;
+                if (applied_name !== code_name) {
+                    throw new MigrationError('name-divergence-at-N', `Namespace "${namespace}": applied[${i}].name = "${applied_name}" ` +
+                        `but code[${i}].name = "${code_name}". ` +
+                        `Hint: the migrations array was reordered or renamed (revert the source ` +
+                        `change), OR row ${i} or earlier was deleted from the tracker ` +
+                        `(re-insert the missing row with a sequence value lower than the rows ` +
+                        `that follow it, or delete from row ${i} onward to re-apply the tail).`, { namespace, at_index: i });
+                }
             }
-            // run all pending migrations in a single transaction — any failure
-            // rolls back the whole pending chain
+            // Step 5: up-to-date case
+            if (applied.length === migrations.length)
+                return;
+            // Step 6: run pending tail in a single chain-tx
+            let next_sequence = applied.length > 0 ? applied[applied.length - 1].sequence + 1 : 0;
+            const applied_names = [];
             await db.transaction(async (tx) => {
-                for (let i = current_version; i < migrations.length; i++) {
-                    const { fn, name } = resolve_migration(migrations[i]);
-                    const label = name != null ? `"${name}"` : '';
+                for (let i = applied.length; i < migrations.length; i++) {
+                    const m = migrations[i];
                     try {
-                        await fn(tx);
-                        await tx.query(`INSERT INTO schema_version (namespace, version, applied_at)
-							 VALUES ($1, $2, NOW())
-							 ON CONFLICT (namespace)
-							 DO UPDATE SET version = $2, applied_at = NOW()`, [namespace, i + 1]);
+                        await m.up(tx);
+                        await tx.query(`INSERT INTO schema_version (namespace, name, sequence)
+							 VALUES ($1, $2, $3)`, [namespace, m.name, next_sequence]);
+                        applied_names.push(m.name);
+                        next_sequence++;
                     }
                     catch (err) {
-                        const name_part = label ? ` ${label}` : '';
-                        throw new Error(`Migration ${namespace}[${i}]${name_part} failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+                        if (err instanceof MigrationError)
+                            throw err;
+                        throw new MigrationError('migration-failed', `Migration ${namespace}["${m.name}"] failed: ` +
+                            `${err instanceof Error ? err.message : String(err)}. ` +
+                            `Hint: fix the migration body and retry; the chain is left at the prior committed version.`, { namespace, at_index: i, cause: err });
                     }
                 }
             });
-            results.push({
-                namespace,
-                from_version: current_version,
-                to_version: migrations.length,
-                migrations_applied: migrations.length - current_version,
-            });
+            results.push({ namespace, applied_names });
+        });
+    }
+    return results;
+};
+/**
+ * Insert tracker rows for the named migrations of a namespace **without
+ * executing them**.
+ *
+ * Used to promote an existing schema (e.g. produced by a pre-0.42 build,
+ * preserved through a tracker-shape upgrade) into the new identity tracker.
+ * `baseline()` trusts the operator-supplied list — it does not verify that
+ * the schema actually matches what the named migrations would have produced.
+ * Pair with a schema-assertion script post-baseline before re-enabling traffic.
+ *
+ * Contract:
+ * - Probes for the pre-0.42 tracker shape; throws `old-tracker-shape` if
+ *   found (DDL with `IF NOT EXISTS` would otherwise no-op against the old
+ *   table and the INSERT would fail with a confusing column-not-found).
+ * - Creates the new-shape `schema_version` table if missing — cutover
+ *   scripts that just dropped the old-shape table can call `baseline()`
+ *   directly with no separate DDL step.
+ * - Acquires the same per-namespace advisory lock as `run_migrations` (with
+ *   the same try/catch fallback for environments lacking `pg_advisory_lock`).
+ * - Refuses if any tracker rows already exist *for this namespace* — lets
+ *   multi-call baseline scripts resume after partial failure (completed
+ *   namespaces guard themselves while remaining ones still run).
+ * - Verifies the supplied names are a strict prefix of the namespace's
+ *   current migrations array — a name not in the array, or out of order,
+ *   errors before any INSERT.
+ * - Writes sequences `0..N-1` in one transaction.
+ *
+ * @param db - the database instance
+ * @param ns - the namespace whose migrations are being baselined
+ * @param names - prefix of `ns.migrations[].name` to record as already-applied
+ * @throws MigrationError with `kind` of `old-tracker-shape`,
+ *   `baseline-name-not-in-code`, `baseline-name-out-of-order`, or
+ *   `baseline-namespace-already-populated`
+ */
+export const baseline = async (db, ns, names) => {
+    if (await detect_old_tracker(db)) {
+        throw new MigrationError('old-tracker-shape', OLD_TRACKER_HINT, { namespace: ns.namespace });
+    }
+    await db.query(SCHEMA_VERSION_DDL);
+    const code_names = ns.migrations.map((m) => m.name);
+    // Validate every supplied name exists in code (catches drift between cutover
+    // script and deployed build before any INSERT).
+    for (const name of names) {
+        if (!code_names.includes(name)) {
+            throw new MigrationError('baseline-name-not-in-code', `baseline: name "${name}" is not in namespace "${ns.namespace}" migrations. ` +
+                `Hint: confirm the deployed fuz_app version matches what the cutover script ` +
+                `was written against — name drift between build and script is the most common cause.`, { namespace: ns.namespace });
         }
-        finally {
-            // Release advisory lock
-            try {
-                await db.query('SELECT pg_advisory_unlock($1)', [lock_key]);
-            }
-            catch {
-                // Advisory lock not supported — nothing to release
-            }
+    }
+    // Validate names are a strict prefix of code_names (catches reordering).
+    for (let i = 0; i < names.length; i++) {
+        if (names[i] !== code_names[i]) {
+            throw new MigrationError('baseline-name-out-of-order', `baseline: namespace "${ns.namespace}" supplied names are not a prefix of ` +
+                `the code's migrations. At position ${i}: supplied "${names[i]}" but code ` +
+                `expects "${code_names[i]}". Hint: re-order the supplied names to match ` +
+                `the code's array order.`, { namespace: ns.namespace, at_index: i });
         }
     }
-    return results;
+    await with_namespace_lock(db, ns.namespace, async () => {
+        const existing = await db.query('SELECT name FROM schema_version WHERE namespace = $1 LIMIT 1', [ns.namespace]);
+        if (existing.length > 0) {
+            throw new MigrationError('baseline-namespace-already-populated', `baseline: namespace "${ns.namespace}" already has tracker rows. ` +
+                `Hint: per-namespace guard for partial-failure resume — completed namespaces ` +
+                `self-skip; if you need to re-baseline, manually ` +
+                `\`DELETE FROM schema_version WHERE namespace = '${ns.namespace}'\` first.`, { namespace: ns.namespace });
+        }
+        await db.transaction(async (tx) => {
+            for (let i = 0; i < names.length; i++) {
+                await tx.query(`INSERT INTO schema_version (namespace, name, sequence)
+					 VALUES ($1, $2, $3)`, [ns.namespace, names[i], i]);
+            }
+        });
+    });
 };

package/dist/db/status.d.ts

@@ -13,11 +13,11 @@ import type { MigrationNamespace } from './migrate.js';
  */
 export interface MigrationStatus {
     namespace: string;
-    /** Current applied version (0 if never migrated). */
-    current_version: number;
-    /** Total available migrations in the namespace. */
-    available_version: number;
-    /** Whether the schema is up to date. */
+    /** Names of migrations recorded in the tracker, sequence-ascending. */
+    applied_names: Array<string>;
+    /** Names of code migrations not yet applied (suffix of the code array). */
+    pending_names: Array<string>;
+    /** Whether `applied_names` is the full code array (no pending work). */
     up_to_date: boolean;
 }
 /**
@@ -41,14 +41,20 @@ export interface DbStatus {
     tables: Array<TableStatus>;
     /** Per-namespace migration status. */
     migrations: Array<MigrationStatus>;
+    /**
+     * True if the pre-0.42 `schema_version` shape (with a `version` column)
+     * was detected. The runner refuses to start in this state — operators
+     * see this flag as their cue to drop the table or call `baseline()`.
+     */
+    old_tracker_shape?: boolean;
 }
 /**
- * Query database status including connectivity, tables, and migration versions.
+ * Query database status including connectivity, tables, and migration state.
  *
  * Designed for CLI `db:status` commands. Does not modify the database.
  *
  * @param db - the database instance
- * @param namespaces - migration namespaces to check versions for
+ * @param namespaces - migration namespaces to check status for
  * @returns a snapshot of database status
  */
 export declare const query_db_status: (db: Db, namespaces?: Array<MigrationNamespace>) => Promise<DbStatus>;

package/dist/db/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,sCAAsC;IACtC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC3B,IAAI,EAAE,EACN,aAAa,KAAK,CAAC,kBAAkB,CAAC,KACpC,OAAO,CAAC,QAAQ,CA8ElB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,QAAQ,KAAG,MA6BnD,CAAC"}
+{"version":3,"file":"status.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,wEAAwE;IACxE,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,sCAAsC;IACtC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AA8BD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC3B,IAAI,EAAE,EACN,aAAa,KAAK,CAAC,kBAAkB,CAAC,KACpC,OAAO,CAAC,QAAQ,CAoFlB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,QAAQ,KAAG,MA4CnD,CAAC"}

package/dist/db/status.js

@@ -6,13 +6,29 @@
  *
  * @module
  */
+const has_table_column = async (db, table_name, column_name) => {
+    const row = await db.query_one(`SELECT EXISTS (
+			SELECT 1 FROM information_schema.columns
+			WHERE table_schema = 'public'
+			  AND table_name = $1
+			  AND column_name = $2
+		) as exists`, [table_name, column_name]);
+    return row?.exists ?? false;
+};
+const has_table = async (db, table_name) => {
+    const row = await db.query_one(`SELECT EXISTS (
+			SELECT 1 FROM information_schema.tables
+			WHERE table_schema = 'public' AND table_name = $1
+		) as exists`, [table_name]);
+    return row?.exists ?? false;
+};
 /**
- * Query database status including connectivity, tables, and migration versions.
+ * Query database status including connectivity, tables, and migration state.
  *
  * Designed for CLI `db:status` commands. Does not modify the database.
  *
  * @param db - the database instance
- * @param namespaces - migration namespaces to check versions for
+ * @param namespaces - migration namespaces to check status for
  * @returns a snapshot of database status
  */
 export const query_db_status = async (db, namespaces) => {
@@ -42,34 +58,42 @@ export const query_db_status = async (db, namespaces) => {
             row_count: result ? parseInt(result.count, 10) : 0,
         });
     }
-    // check migration versions
+    // check migration state
     const migrations = [];
+    let old_tracker_shape;
     if (namespaces?.length) {
-        // check if schema_version table exists
-        const sv_exists = await db.query_one(`SELECT EXISTS (
-				SELECT 1 FROM information_schema.tables
-				WHERE table_schema = 'public' AND table_name = 'schema_version'
-			) as exists`);
-        if (sv_exists?.exists) {
+        const sv_exists = await has_table(db, 'schema_version');
+        // pre-0.42 shape carries a `version` column; new shape carries `name`
+        const old_shape = sv_exists ? await has_table_column(db, 'schema_version', 'version') : false;
+        if (old_shape)
+            old_tracker_shape = true;
+        if (sv_exists && !old_shape) {
             for (const { namespace, migrations: ns_migrations } of namespaces) {
-                const row = await db.query_one('SELECT version FROM schema_version WHERE namespace = $1', [namespace]);
-                const current_version = row?.version ?? 0;
+                const rows = await db.query(`SELECT name FROM schema_version
+					 WHERE namespace = $1
+					 ORDER BY sequence ASC`, [namespace]);
+                const applied_names = rows.map((r) => r.name);
+                const code_names = ns_migrations.map((m) => m.name);
+                // pending = the suffix of code names beyond applied.length (callers
+                // see the boot algorithm's tail without paying for verify here)
+                const pending_names = code_names.slice(applied_names.length);
                 migrations.push({
                     namespace,
-                    current_version,
-                    available_version: ns_migrations.length,
-                    up_to_date: current_version === ns_migrations.length,
+                    applied_names,
+                    pending_names,
+                    up_to_date: applied_names.length === code_names.length && pending_names.length === 0,
                 });
             }
         }
         else {
-            // no schema_version table — all namespaces are at version 0
+            // no tracker, or pre-0.42 shape — every namespace shows as "nothing applied yet"
             for (const { namespace, migrations: ns_migrations } of namespaces) {
+                const code_names = ns_migrations.map((m) => m.name);
                 migrations.push({
                     namespace,
-                    current_version: 0,
-                    available_version: ns_migrations.length,
-                    up_to_date: ns_migrations.length === 0,
+                    applied_names: [],
+                    pending_names: code_names,
+                    up_to_date: code_names.length === 0,
                 });
             }
         }
@@ -79,6 +103,7 @@ export const query_db_status = async (db, namespaces) => {
         table_count: tables.length,
         tables,
         migrations,
+        ...(old_tracker_shape ? { old_tracker_shape: true } : {}),
     };
 };
 /**
@@ -102,12 +127,23 @@ export const format_db_status = (status) => {
             lines.push(`    ${t.name.padEnd(max_name)}  ${t.row_count} rows`);
         }
     }
+    if (status.old_tracker_shape) {
+        lines.push('');
+        lines.push('  Migrations: pre-0.42 schema_version shape detected.');
+        lines.push('    Drop the table and re-run, or call `baseline()` first if preserving the schema.');
+    }
     if (status.migrations.length > 0) {
         lines.push('');
         lines.push('  Migrations:');
         for (const m of status.migrations) {
-            const marker = m.up_to_date ? 'up to date' : `${m.current_version}/${m.available_version}`;
-            lines.push(`    ${m.namespace}: v${m.current_version} (${marker})`);
+            const total = m.applied_names.length + m.pending_names.length;
+            if (m.up_to_date) {
+                lines.push(`    ${m.namespace}: up to date (${m.applied_names.length}/${total})`);
+            }
+            else {
+                const pending_list = m.pending_names.join(', ');
+                lines.push(`    ${m.namespace}: applied ${m.applied_names.length}/${total} (pending: ${pending_list})`);
+            }
         }
     }
     return lines.join('\n');

package/dist/server/app_backend.d.ts

@@ -70,8 +70,9 @@ export interface CreateAppBackendOptions {
     audit_log_config?: AuditLogConfig;
     /**
      * Additional migration namespaces to run after the builtin auth namespace.
-     * Each namespace's own `schema_version` row tracks progress; order is
-     * append-only so forward-only guarantees hold per-namespace.
+     * The shared `schema_version` table records one row per applied migration
+     * (`namespace`, `name`, `sequence`); order is append-only so forward-only
+     * guarantees hold per-namespace.
      *
      * The reserved `'fuz_auth'` namespace is rejected at startup. Omit for no
      * extra namespaces. This is the only place to splice consumer migrations

package/dist/server/app_backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAE/C,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/E,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAiB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAI/F;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oIAAoI;IACpI,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC3D,iEAAiE;IACjE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;IAClC;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAU,SAAS,uBAAuB,KAAG,OAAO,CAAC,UAAU,CAoC7F,CAAC"}
+{"version":3,"file":"app_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAE/C,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/E,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAiB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAI/F;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oIAAoI;IACpI,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC3D,iEAAiE;IACjE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;IAClC;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAU,SAAS,uBAAuB,KAAG,OAAO,CAAC,UAAU,CAoC7F,CAAC"}

package/dist/testing/CLAUDE.md

@@ -81,19 +81,19 @@ Factory builders for parameterized DB tests. Consumer projects pass their
 `init_schema` callback (which calls `run_migrations(db, [AUTH_MIGRATION_NS, ...app_migrations])`);
 factories accept any migration namespace set.
 
-| Helper                                           | Role                                                                                                                                                                                                                    |
-| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `IS_CI`                                          | `process.env.CI === 'true'` — CI detection.                                                                                                                                                                             |
-| `DbFactory` interface                            | `{name, create, close, skip, skip_reason?}`.                                                                                                                                                                            |
-| `reset_pglite(db)`                               | `DROP SCHEMA public CASCADE` + recreate. Reuses a live PGlite instance.                                                                                                                                                 |
-| `create_pglite_factory(init_schema)`             | In-memory; no external deps; `skip: false`. See WASM caching below.                                                                                                                                                     |
-| `create_pg_factory(init_schema, test_url?)`      | PostgreSQL; `skip: true` when `test_url` is missing; drops `schema_version` before `init_schema` so migrations re-evaluate against actual tables; pool is reused + cleaned up across `create()` calls.                  |
-| `AUTH_TRUNCATE_TABLES`                           | `['invite', 'api_token', 'auth_session', 'permit', 'permit_offer', 'actor', 'account']` in FK-safe order. Excludes `audit_log` — unit DB tests don't need to truncate it.                                               |
-| `AUTH_INTEGRATION_TRUNCATE_TABLES`               | `AUTH_TRUNCATE_TABLES + ['audit_log']` — for integration suites that exercise the audit path.                                                                                                                           |
-| `AUTH_DROP_TABLES`                               | Full set from `AUTH_MIGRATIONS` in drop order; call `drop_auth_schema(db)` at the top of `init_schema` on persistent pg databases that may hold stale DDL from previous fuz_app versions.                               |
-| `drop_auth_schema(db)`                           | `DROP TABLE IF EXISTS <table> CASCADE` for every entry in `AUTH_DROP_TABLES` plus `schema_version`. Safe on fresh DBs.                                                                                                  |
-| `create_describe_db(factories, truncate_tables)` | Returns `describe_db(name, fn)` that runs `fn(get_db)` once per factory, inside a `describe` block with shared `beforeAll(create)` + `beforeEach(TRUNCATE)` + `afterAll(close)`. Skipped factories use `describe.skip`. |
-| `log_db_factory_status(factories)`               | Console summary of enabled / skipped factories.                                                                                                                                                                         |
+| Helper                                           | Role                                                                                                                                                                                                                                                                                                 |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `IS_CI`                                          | `process.env.CI === 'true'` — CI detection.                                                                                                                                                                                                                                                          |
+| `DbFactory` interface                            | `{name, create, close, skip, skip_reason?}`.                                                                                                                                                                                                                                                         |
+| `reset_pglite(db)`                               | `DROP SCHEMA public CASCADE` + recreate. Reuses a live PGlite instance.                                                                                                                                                                                                                              |
+| `create_pglite_factory(init_schema)`             | In-memory; no external deps; `skip: false`. See WASM caching below.                                                                                                                                                                                                                                  |
+| `create_pg_factory(init_schema, test_url?)`      | PostgreSQL; `skip: true` when `test_url` is missing; drops `schema_version` before `init_schema` so migrations re-evaluate against actual tables (prevents stale tracker rows from skipping migrations when DDL changes between test sessions); pool is reused + cleaned up across `create()` calls. |
+| `AUTH_TRUNCATE_TABLES`                           | `['invite', 'api_token', 'auth_session', 'permit', 'permit_offer', 'actor', 'account']` in FK-safe order. Excludes `audit_log` — unit DB tests don't need to truncate it.                                                                                                                            |
+| `AUTH_INTEGRATION_TRUNCATE_TABLES`               | `AUTH_TRUNCATE_TABLES + ['audit_log']` — for integration suites that exercise the audit path.                                                                                                                                                                                                        |
+| `AUTH_DROP_TABLES`                               | Full set from `AUTH_MIGRATIONS` in drop order; call `drop_auth_schema(db)` at the top of `init_schema` on persistent pg databases that may hold stale DDL from previous fuz_app versions.                                                                                                            |
+| `drop_auth_schema(db)`                           | `DROP TABLE IF EXISTS <table> CASCADE` for every entry in `AUTH_DROP_TABLES` plus `schema_version`. Safe on fresh DBs.                                                                                                                                                                               |
+| `create_describe_db(factories, truncate_tables)` | Returns `describe_db(name, fn)` that runs `fn(get_db)` once per factory, inside a `describe` block with shared `beforeAll(create)` + `beforeEach(TRUNCATE)` + `afterAll(close)`. Skipped factories use `describe.skip`.                                                                              |
+| `log_db_factory_status(factories)`               | Console summary of enabled / skipped factories.                                                                                                                                                                                                                                                      |
 
 **PGlite WASM caching.** `create_pglite_factory` shares a single PGlite
 instance in a module-level ref (`module_db`) across all factories in the

package/dist/testing/db.d.ts

@@ -41,7 +41,7 @@ export declare const create_pglite_factory: (init_schema: (db: Db) => Promise<vo
  *
  * Skipped when `test_url` is not provided.
  * Drops `schema_version` before running `init_schema`, forcing migrations
- * to re-evaluate against the actual tables. Prevents stale version entries
+ * to re-evaluate against the actual tables. Prevents stale tracker rows
  * from skipping migrations when DDL changes between test sessions.
  *
  * For full clean-slate behavior (recommended), call `drop_auth_schema(db)`

package/dist/testing/db.js

@@ -82,7 +82,7 @@ export const create_pglite_factory = (init_schema) => ({
  *
  * Skipped when `test_url` is not provided.
  * Drops `schema_version` before running `init_schema`, forcing migrations
- * to re-evaluate against the actual tables. Prevents stale version entries
+ * to re-evaluate against the actual tables. Prevents stale tracker rows
  * from skipping migrations when DDL changes between test sessions.
  *
  * For full clean-slate behavior (recommended), call `drop_auth_schema(db)`
@@ -122,7 +122,7 @@ export const create_pg_factory = (init_schema, test_url) => {
             const { db } = create_pg_db(pool);
             try {
                 // Drop schema_version so migrations re-evaluate against the actual
-                // tables. Prevents stale version entries from skipping migrations
+                // tables. Prevents stale tracker rows from skipping migrations
                 // when DDL changes between test sessions. Migrations use
                 // IF NOT EXISTS guards, so re-running is safe.
                 await db.query('DROP TABLE IF EXISTS schema_version');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.41.1",
+  "version": "0.42.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",