@nanobpm/nano-workforce 0.106.0 → 0.106.1

package/.github/workflows/ci.yml

@@ -16,6 +16,11 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          # Full history + tags: the migration immutability gate (check:migrations) diffs against the
+          # merge-base with origin/main, and the upgrade smoke test materialises the previous release
+          # tag's migration set — both need history a shallow clone doesn't have (issue #357).
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

package/AGENTS.md

@@ -273,6 +273,36 @@ Migrations live in `db/migrations/*.sql` and are **auto-applied on boot** from
   prefix while `main` keeps advancing, so the branch-local "next" number collides
   on merge. Two files must never share a prefix; `npm run check:migrations`
   (a CI gate) enforces this and fails the build on any new duplicate.
+- **A merged migration is IMMUTABLE — never rename, delete, or edit it.** The
+  runtime keys the `_urban_migrations` ledger by *filename*, so a renamed file is
+  a *new* migration to the runner: it re-runs its DDL against an already-migrated
+  DB and aborts boot (`duplicate column …`); a deleted file desyncs the ledger
+  from the schema; an edited file silently no-ops on every existing install (the
+  name is already recorded) while diverging fresh ones. To change a merged
+  migration's effect, add a NEW migration. `npm run check:migrations` also gates
+  this — it diffs `db/migrations/` against the merge-base with `origin/main` and
+  fails on any rename/delete/edit — and the upgrade smoke test
+  (`app/migration-upgrade-smoke.test.ts`) materialises the previous release's
+  migration set and upgrades it to the current set, catching non-idempotent DDL a
+  fresh-DB CI never exercises (issue #357). Both need history: CI checks out with
+  `fetch-depth: 0`.
+
+### Healing an install wedged by a renamed migration
+
+If a live node fails to boot with `migration "NNN_…sql" failed and was rolled
+back … duplicate column` because a migration was renamed *before* the immutability
+gate existed (e.g. `043_user_tasks_subject_title.sql` → `046_…`, issue #357),
+reconcile its ledger — this makes **no schema change**, only aliases the old
+ledger row to the new filename, and is safe to re-run:
+
+```bash
+npm run heal:migrations -- /path/to/the/app.sqlite   # then restart the node
+```
+
+The known renames live in `RENAMED_MIGRATIONS` (`app/migrationHeal.ts`), the
+single source of truth the heal script and its tests share. This list only heals
+the pre-gate past — the immutability gate above prevents any new entry from ever
+being needed.
 
 ## Runtime & CI gates
 
@@ -286,7 +316,7 @@ npm run typecheck                                     # tsc --noEmit (Node)
 npm run check                                         # urban check (manifest validation)
 npm run layout:check                                  # BPMN diagram freshness (no drift)
 npm run check:prompts                                 # agent-prompt linkedResource resolution
-npm run check:migrations                              # migration prefixes (no collisions)
+npm run check:migrations                              # migration prefixes + immutability (no rename/delete/edit of a merged migration)
 npm run check:contracts                               # contract registry (no synonyms / undeclared env keys)
 npm test                                              # unit tests (node --test)
 ```

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.106.1](https://github.com/nanobpm/nano-workforce/compare/v0.106.0...v0.106.1) (2026-08-20)
+
+
+### Bug Fixes
+
+* **migrations:** gate migration immutability + add upgrade smoke test ([#357](https://github.com/nanobpm/nano-workforce/issues/357)) ([#359](https://github.com/nanobpm/nano-workforce/issues/359)) ([7f7c6a6](https://github.com/nanobpm/nano-workforce/commit/7f7c6a6c59dac33602441c729dca897b3b23fabc)), closes [#311](https://github.com/nanobpm/nano-workforce/issues/311) [#316](https://github.com/nanobpm/nano-workforce/issues/316) [#351](https://github.com/nanobpm/nano-workforce/issues/351) [#355](https://github.com/nanobpm/nano-workforce/issues/355)
+
 # [0.106.0](https://github.com/nanobpm/nano-workforce/compare/v0.105.0...v0.106.0) (2026-08-20)
 
 

package/app/migration-upgrade-smoke.test.ts

@@ -0,0 +1,55 @@
+// Upgrade smoke test (issue #357) — CI only ever migrates a FRESH database, so it never exercises the
+// one state where the forward-only contract actually breaks: a *pre-existing* install upgrading to
+// the current set. This materialises the migration set at the previous release tag, applies the
+// current set on top the way the runtime does (ledger keyed by filename, skip-applied / apply-new),
+// and asserts the upgrade completes cleanly.
+//
+// It covers the whole failure class on a real release boundary — a renamed/deleted migration
+// re-running, non-idempotent DDL, or an ordering assumption — rather than any single instance. When
+// the tag is unavailable (a shallow clone without tags) it skips with a diagnostic; CI checks out
+// full history + tags (`fetch-depth: 0`), so the real upgrade path is always exercised there.
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  applyMigrationSet,
+  previousReleaseTag,
+  readMigrationSetFromDisk,
+  readMigrationSetFromGit,
+} from "#test-migrations";
+
+test("upgrading a DB from the previous release's migrations to the current set applies cleanly", (t) => {
+  const tag = previousReleaseTag();
+  if (tag === null) {
+    t.skip("no previous release tag reachable (shallow clone without tags) — CI runs this with fetch-depth: 0");
+    return;
+  }
+  const baseline = readMigrationSetFromGit(tag);
+  if (baseline === null) {
+    t.skip(`migration set at ${tag} unavailable — CI runs this with fetch-depth: 0`);
+    return;
+  }
+
+  const db = new DatabaseSync(":memory:");
+  // Stand up the DB exactly as the previous release left it...
+  applyMigrationSet(db, baseline);
+  const ledgerBefore = new Set(
+    (db.prepare("SELECT name FROM _urban_migrations").all() as { name: string }[]).map((r) => r.name),
+  );
+
+  // ...then upgrade in place to the current set. A rename/delete/non-idempotent migration throws here.
+  const current = readMigrationSetFromDisk();
+  applyMigrationSet(db, current);
+
+  // Every current migration is now recorded, and nothing the baseline applied went missing.
+  const ledgerAfter = new Set(
+    (db.prepare("SELECT name FROM _urban_migrations").all() as { name: string }[]).map((r) => r.name),
+  );
+  for (const file of current) {
+    assert(ledgerAfter.has(file.name), `current migration ${file.name} is recorded as applied after upgrade`);
+  }
+  for (const name of ledgerBefore) {
+    assert(ledgerAfter.has(name), `baseline migration ${name} remains in the ledger after upgrade`);
+  }
+  assertEquals(ledgerAfter.size, current.length, "the upgraded ledger holds exactly the current set");
+});

package/app/migrationHeal.test.ts

@@ -0,0 +1,75 @@
+// Regression guard for issue #357 — a migration renamed after it merged (`043_user_tasks_subject_
+// title.sql` -> `046_…` in #316) re-runs against an already-migrated DB and aborts boot with
+// "duplicate column name: subject_title", because the ledger is keyed by filename.
+//
+// This reproduces that exact break on the CURRENT migration set (RED), then proves
+// `healMigrationLedger` reconciles the ledger so the upgrade completes cleanly (GREEN) — the recovery
+// path for installs that migrated under the old name before the rename landed.
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { healMigrationLedger, RENAMED_MIGRATIONS } from "../app/migrationHeal.ts";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+import { applyMigrationSet, readMigrationSetFromDisk } from "#test-migrations";
+
+const NEW_NAME = "046_user_tasks_subject_title.sql";
+const OLD_NAME = "043_user_tasks_subject_title.sql";
+
+// A DB migrated fully with the CURRENT set, then rewound to model an install that applied the
+// renamed migration under its OLD filename: the schema change is present, but the ledger records the
+// old name — exactly the state a boot between #311 and #316 left behind.
+function dbAppliedUnderOldName(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  applyMigrationSet(db, readMigrationSetFromDisk());
+  db.prepare("UPDATE _urban_migrations SET name=? WHERE name=?").run(OLD_NAME, NEW_NAME);
+  return db;
+}
+
+const applied = (db: DatabaseSync, name: string): boolean =>
+  (db.prepare("SELECT 1 AS one FROM _urban_migrations WHERE name=?").get(name) as
+    | { one: number }
+    | undefined) !== undefined;
+
+test("RENAMED_MIGRATIONS pins the 043->046 user_tasks_subject_title rename", () => {
+  assertEquals(RENAMED_MIGRATIONS.get(NEW_NAME), OLD_NAME);
+});
+
+test("#357 repro: re-applying the current set to a DB migrated under the old name aborts on duplicate column", () => {
+  const db = dbAppliedUnderOldName();
+  // The renamed migration is unapplied under its NEW name, so the runtime re-runs its
+  // `ALTER TABLE user_tasks ADD COLUMN subject_title` against a table that already has the column.
+  const err = assertThrows(() => applyMigrationSet(db, readMigrationSetFromDisk()));
+  assert(
+    /duplicate column name: subject_title/.test(err.message),
+    `expected a duplicate-column abort, got: ${err.message}`,
+  );
+});
+
+test("heal reconciles the ledger so the upgrade completes cleanly", () => {
+  const db = dbAppliedUnderOldName();
+
+  const healed = healMigrationLedger(db);
+  assertEquals(healed, [NEW_NAME], "the new filename was aliased into the ledger");
+  assert(applied(db, NEW_NAME), "046 is now recorded as applied");
+  assert(applied(db, OLD_NAME), "the historical 043 ledger row is left intact");
+
+  // With the ledger reconciled, the renamed migration is skipped and the boot-time upgrade is clean.
+  const newly = applyMigrationSet(db, readMigrationSetFromDisk());
+  assertEquals(newly, [], "no migration re-runs after the heal");
+});
+
+test("heal is idempotent and a no-op on a healthy DB", () => {
+  // A DB that applied the migration under its CURRENT name needs no healing.
+  const clean = new DatabaseSync(":memory:");
+  applyMigrationSet(clean, readMigrationSetFromDisk());
+  assertEquals(healMigrationLedger(clean), [], "clean install: nothing to heal");
+
+  // Healing twice changes nothing the second time.
+  const broken = dbAppliedUnderOldName();
+  assertEquals(healMigrationLedger(broken), [NEW_NAME]);
+  assertEquals(healMigrationLedger(broken), [], "second heal is a no-op");
+});
+
+test("heal is a no-op on a fresh DB with no migration ledger", () => {
+  const fresh = new DatabaseSync(":memory:");
+  assertEquals(healMigrationLedger(fresh), [], "no ledger table => nothing to heal");
+});

package/app/migrationHeal.ts

@@ -0,0 +1,74 @@
+// migrationHeal — recover installs broken by a migration that was RENAMED after it had already
+// merged and applied (issue #357).
+//
+// The runtime (`@nanobpm/urban` applyMigrations) keys the `_urban_migrations` ledger by FILENAME, so
+// a renamed migration is a *different* migration to the runner: it re-runs its DDL against a schema
+// that already has the change, and a bare `ALTER TABLE ... ADD COLUMN` then aborts boot with
+// "duplicate column". The direct hazard is now blocked forward by the immutability gate
+// (`scripts/check-migrations.ts`), but installs that migrated under the OLD name *before* the rename
+// landed are already stuck and need their ledger reconciled.
+//
+// The fix is a ledger-alias, NOT a schema change and NOT an edit to the renamed migration (editing a
+// merged migration is itself forbidden by the immutability gate, and would silently no-op on every
+// already-migrated DB anyway): if the old filename is recorded as applied, the new filename names the
+// exact same forward-only change, so it is safe — and correct — to record the new filename as applied
+// too. `healMigrationLedger` does that, guarded so it only ever fires on the broken state.
+//
+// `RENAMED_MIGRATIONS` is the single source of truth for known historical renames. It exists ONLY to
+// heal the pre-gate past — the immutability gate prevents any new entry from ever being needed.
+import type { DatabaseSync } from "node:sqlite";
+
+const MIGRATIONS_TABLE = "_urban_migrations";
+
+// new filename -> old filename, for merged migrations that were renamed before the immutability gate
+// existed. Each entry names the SAME forward-only change under two prefixes, so aliasing the ledger
+// from the old name to the new is lossless.
+//
+// - `046_user_tasks_subject_title.sql` was merged as `043_user_tasks_subject_title.sql` (#311) and
+//   renumbered to 046 (#316) to break a prefix collision with `043_pr_epic_phase.sql`. Any DB that
+//   booted between those two PRs applied it as 043 and now re-runs it as 046 → "duplicate column
+//   name: subject_title" (issue #357).
+export const RENAMED_MIGRATIONS: ReadonlyMap<string, string> = new Map([
+  ["046_user_tasks_subject_title.sql", "043_user_tasks_subject_title.sql"],
+]);
+
+/** Does the `_urban_migrations` ledger table exist? A fresh/never-migrated DB has nothing to heal. */
+function ledgerExists(db: DatabaseSync): boolean {
+  return (
+    db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+      .get(MIGRATIONS_TABLE) !== undefined
+  );
+}
+
+function isApplied(db: DatabaseSync, name: string): boolean {
+  return db.prepare(`SELECT 1 AS one FROM ${MIGRATIONS_TABLE} WHERE name=?`).get(name) !== undefined;
+}
+
+/**
+ * Reconcile the migration ledger for known historical renames, in place. For every rename where the
+ * OLD filename is recorded as applied but the NEW one is not, record the new filename as applied
+ * (aliasing the ledger) so the runtime stops re-running the renamed migration.
+ *
+ * Idempotent and safe on every state:
+ *  - old applied, new missing  -> alias inserted (the broken install; the only case that acts)
+ *  - both applied              -> no-op (overlay-drift install carrying both files)
+ *  - only new applied          -> no-op (clean install that never saw the old name)
+ *  - neither applied / no ledger-> no-op (fresh DB)
+ *
+ * @returns the new filenames that were aliased in (empty when nothing needed healing).
+ */
+export function healMigrationLedger(db: DatabaseSync, now: () => Date = () => new Date()): string[] {
+  if (!ledgerExists(db)) return [];
+  const healed: string[] = [];
+  for (const [newName, oldName] of RENAMED_MIGRATIONS) {
+    if (isApplied(db, oldName) && !isApplied(db, newName)) {
+      db.prepare(`INSERT OR IGNORE INTO ${MIGRATIONS_TABLE} (name, applied_at) VALUES (?, ?)`).run(
+        newName,
+        now().toISOString(),
+      );
+      healed.push(newName);
+    }
+  }
+  return healed;
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.106.0",
+  "version": "0.106.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
   "imports": {
-    "#test-assert": "./test/assert.ts"
+    "#test-assert": "./test/assert.ts",
+    "#test-migrations": "./test/migrations.ts"
   },
   "engines": {
     "node": ">=22.6"
@@ -37,6 +38,7 @@
     "pretypecheck": "urban gen",
     "check:prompts": "node --experimental-strip-types scripts/check-agent-prompts.ts",
     "check:migrations": "node --experimental-strip-types scripts/check-migrations.ts",
+    "heal:migrations": "node --experimental-strip-types scripts/heal-migration-ledger.ts",
     "check:contracts": "node --experimental-strip-types scripts/check-contracts.ts",
     "reconcile:contracts": "node --experimental-strip-types scripts/reconcile-contracts.ts",
     "gen": "urban gen",

package/scripts/check-migrations.test.ts

@@ -0,0 +1,58 @@
+// Red/green coverage for the migration immutability gate (scripts/check-migrations.ts, issue #357).
+//
+// The runtime keys the migration ledger by FILENAME, so once a migration merges it must never be
+// renamed (re-runs against a migrated DB and aborts boot), deleted (desyncs ledger from schema), or
+// edited (silently no-ops on migrated installs). The gate diffs db/migrations against the merge-base
+// with origin/main; here we drive its diff classifier directly with representative
+// `git diff --find-renames --name-status` output so each violation shape is pinned.
+import test from "node:test";
+import { immutabilityErrorsFromDiff } from "./check-migrations.ts";
+import { assert, assertEquals } from "#test-assert";
+
+test("a rename of a merged migration is a violation", () => {
+  const errors = immutabilityErrorsFromDiff(
+    "R100\tdb/migrations/043_user_tasks_subject_title.sql\tdb/migrations/046_user_tasks_subject_title.sql",
+  );
+  assertEquals(errors.length, 1);
+  assert(/RENAMED/.test(errors[0]));
+  assert(/043_user_tasks_subject_title.sql -> 046_user_tasks_subject_title.sql/.test(errors[0]));
+});
+
+test("a delete of a merged migration is a violation", () => {
+  const errors = immutabilityErrorsFromDiff("D\tdb/migrations/046_user_tasks_subject_title.sql");
+  assertEquals(errors.length, 1);
+  assert(/DELETED/.test(errors[0]));
+});
+
+test("an edit of a merged migration is a violation", () => {
+  const errors = immutabilityErrorsFromDiff("M\tdb/migrations/046_user_tasks_subject_title.sql");
+  assertEquals(errors.length, 1);
+  assert(/EDITED/.test(errors[0]));
+});
+
+test("adding a new migration is allowed", () => {
+  assertEquals(
+    immutabilityErrorsFromDiff("A\tdb/migrations/061_brand_new.sql"),
+    [],
+    "an addition is not a violation",
+  );
+});
+
+test("a clean diff (no migration changes) yields no violations", () => {
+  assertEquals(immutabilityErrorsFromDiff(""), []);
+});
+
+test("mixed changes report every violation but ignore the addition", () => {
+  const errors = immutabilityErrorsFromDiff(
+    [
+      "A\tdb/migrations/061_new.sql",
+      "M\tdb/migrations/010_old.sql",
+      "D\tdb/migrations/011_gone.sql",
+      "R096\tdb/migrations/012_a.sql\tdb/migrations/013_a.sql",
+    ].join("\n"),
+  );
+  assertEquals(errors.length, 3, "the three mutations are flagged, the addition is not");
+  assert(errors.some((e) => /EDITED/.test(e)));
+  assert(errors.some((e) => /DELETED/.test(e)));
+  assert(errors.some((e) => /RENAMED/.test(e)));
+});

package/scripts/check-migrations.ts

@@ -13,11 +13,23 @@
 // The rule: no two migration files may share a numeric prefix. The pre-existing historical
 // duplicates are forward-only and already applied, so they cannot be renamed — they are
 // grandfathered in GRANDFATHERED_DUPES. Any NEW duplicate prefix fails the build.
+//
+// A second, independent invariant lives here too (issue #357): once a migration has merged to
+// `main` it is IMMUTABLE — never renamed, deleted, or edited. The runtime keys the migration ledger
+// by FILENAME, so renaming a merged migration makes the runner re-apply it against an already-
+// migrated DB and abort boot ("duplicate column"); editing one silently no-ops on every existing
+// install (the ledger already has that name) while diverging fresh installs. `checkImmutability`
+// diffs `db/migrations/` against the merge-base with `origin/main` and fails on any rename, delete,
+// or content change to a file that existed there. It compares against the merge-base (the branch's
+// fork point), NOT `origin/main`'s tip, so a branch that is merely behind main isn't wrongly flagged
+// for migrations added to main after it forked.
+import { execFileSync } from "node:child_process";
 import { readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const MIGRATIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "db", "migrations");
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const MIGRATIONS_DIR = join(REPO_ROOT, "db", "migrations");
 
 // Historical collisions that predate this gate. Forward-only + already applied ⇒ cannot be
 // renumbered. New duplicates are NOT allowed here — fix them before merge.
@@ -32,10 +44,112 @@ const MIGRATIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "db",
 // cannot be renumbered (a rename re-runs `CREATE TABLE`/`ALTER TABLE DROP COLUMN` on migrated DBs and
 // fails). They create three disjoint schema objects, so their relative apply order is irrelevant.
 // Grandfather 049; any NEW duplicate prefix still fails the build.
-const GRANDFATHERED_DUPES: ReadonlySet<string> = new Set(["004", "005", "006", "007", "049"]);
+//
+// 052 is the same story across two PRs: #351 landed `052_worker_durable_resume` and #355 landed
+// `052_plan_conformance`, each the branch-local "next" prefix, colliding silently only once both were
+// on main. Both are already applied forward-only, and — reinforced now by the immutability check
+// below — renumbering a merged migration is itself forbidden (the rename would re-run it and abort
+// boot, issue #357). The two create disjoint tables (`worker_durable_resume`, `plan_conformance`), so
+// apply order is irrelevant. Grandfather 052; any NEW duplicate prefix still fails the build.
+const GRANDFATHERED_DUPES: ReadonlySet<string> = new Set(["004", "005", "006", "007", "049", "052"]);
 
 const PREFIX = /^(\d{3})_[^/]*\.sql$/;
 
+function git(args: string[]): string {
+  return execFileSync("git", args, { cwd: REPO_ROOT, encoding: "utf8" });
+}
+
+/** The commit to treat as "already merged" — the branch's fork point from `origin/main` (fall back to
+ *  local `main`). `null` when no baseline is resolvable (e.g. a shallow clone with no `main`), in
+ *  which case the immutability check is skipped with a warning; CI checks out full history. Override
+ *  with `MIGRATION_BASELINE_REF` (used by the gate's own tests). */
+function resolveBaseline(): string | null {
+  const override = process.env.MIGRATION_BASELINE_REF;
+  const upstreams = override ? [override] : ["origin/main", "main"];
+  for (const ref of upstreams) {
+    try {
+      // An explicit override is used as-is; a branch name is resolved to its merge-base with HEAD so a
+      // branch that is merely behind main isn't blamed for migrations main gained after it forked.
+      if (override) {
+        git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+        return ref;
+      }
+      return git(["merge-base", ref, "HEAD"]).trim();
+    } catch {
+      // try the next candidate
+    }
+  }
+  return null;
+}
+
+/** Classify a `git diff --find-renames --name-status <baseline> -- db/migrations` listing into
+ *  immutability violations. Renames (`R`), deletes (`D`), and content edits (`M`) of a merged
+ *  migration are violations; additions (`A`) are allowed. Exported for unit coverage. */
+export function immutabilityErrorsFromDiff(statusOutput: string): string[] {
+  const errors: string[] = [];
+  const name = (p: string): string => p.slice(p.lastIndexOf("/") + 1);
+  for (const line of statusOutput.split("\n")) {
+    if (line.trim() === "") continue;
+    const [status, ...paths] = line.split("\t");
+    if (status.startsWith("R")) {
+      errors.push(
+        `  ${name(paths[0])} -> ${name(paths[1])}: a merged migration was RENAMED. The ledger keys ` +
+          `by filename, so the renamed file re-runs on every existing install and aborts boot. Keep ` +
+          `the original filename; add a NEW migration for further change.`,
+      );
+    } else if (status.startsWith("D")) {
+      errors.push(
+        `  ${name(paths[0])}: a merged migration was DELETED. Forward-only migrations are immutable — ` +
+          `removing one desyncs the ledger from the schema. Leave it in place.`,
+      );
+    } else if (status.startsWith("M")) {
+      errors.push(
+        `  ${name(paths[0])}: a merged migration was EDITED. The ledger already records it, so the ` +
+          `edit silently no-ops on every migrated install while diverging fresh ones. Add a NEW ` +
+          `migration instead of changing a merged one.`,
+      );
+    }
+  }
+  return errors;
+}
+
+/** Fail on any rename, delete, or content change to a migration already present at the baseline — a
+ *  merged migration is immutable (issue #357). Additions are fine. Returns whether the immutability
+ *  gate actually ran (false when it was skipped because no baseline/diff was available), so the
+ *  caller's success message doesn't claim a guarantee the gate never checked. */
+function checkImmutability(errors: string[]): boolean {
+  const baseline = resolveBaseline();
+  if (baseline === null) {
+    console.warn(
+      "check-migrations: WARN — no origin/main baseline resolvable; skipping the immutability check " +
+        "(CI runs it with full history via fetch-depth: 0).",
+    );
+    return false;
+  }
+
+  let statusOutput: string;
+  try {
+    // Diff the baseline tree against the WORKING TREE (staged + unstaged), detecting renames, scoped
+    // to db/migrations. `--find-renames` surfaces a rename as one `R` row instead of a delete+add.
+    statusOutput = git([
+      "diff",
+      "--find-renames",
+      "--name-status",
+      baseline,
+      "--",
+      "db/migrations",
+    ]);
+  } catch {
+    console.warn(
+      `check-migrations: WARN — could not diff migrations against ${baseline}; skipping the immutability check.`,
+    );
+    return false;
+  }
+
+  errors.push(...immutabilityErrorsFromDiff(statusOutput));
+  return true;
+}
+
 function main(): void {
   const files = readdirSync(MIGRATIONS_DIR)
     .filter((f) => f.endsWith(".sql"))
@@ -68,12 +182,20 @@ function main(): void {
     }
   }
 
+  const immutabilityChecked = checkImmutability(errors);
+
   if (errors.length > 0) {
-    console.error(`check-migrations: db/migrations has colliding prefixes:\n${errors.join("\n")}`);
+    console.error(`check-migrations: db/migrations failed its merge-safety checks:\n${errors.join("\n")}`);
     process.exit(1);
   }
 
-  console.log(`check-migrations: OK (${files.length} migrations, no colliding prefixes).`);
+  const immutabilityClause = immutabilityChecked
+    ? "none renamed/deleted/edited"
+    : "immutability check skipped (no baseline)";
+  console.log(
+    `check-migrations: OK (${files.length} migrations, no colliding prefixes, ${immutabilityClause}).`,
+  );
 }
 
-main();
+if (import.meta.main) main();
+

package/scripts/heal-migration-ledger.ts

@@ -0,0 +1,49 @@
+// heal-migration-ledger — one-shot recovery for an install wedged by issue #357 (a migration that
+// was renamed after it merged, so the runtime re-runs it and boot aborts on "duplicate column").
+//
+// Usage:
+//   node --experimental-strip-types scripts/heal-migration-ledger.ts <path-to-sqlite.db>
+//
+// It reconciles the `_urban_migrations` ledger for every known historical rename
+// (`RENAMED_MIGRATIONS`): where the OLD filename is recorded as applied but the NEW one is not, it
+// records the new filename as applied. This is a pure ledger-alias — it makes NO schema change — and
+// is safe to run repeatedly and on a healthy DB (it only acts on the broken state). After running it,
+// restart the node; the renamed migration is skipped and boot completes.
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { healMigrationLedger } from "../app/migrationHeal.ts";
+
+function main(): void {
+  const dbPath = process.argv[2];
+  if (!dbPath) {
+    console.error(
+      "usage: node --experimental-strip-types scripts/heal-migration-ledger.ts <path-to-sqlite.db>",
+    );
+    process.exit(2);
+  }
+
+  // `DatabaseSync` silently CREATES an empty DB when the path doesn't exist, so a typo'd path would
+  // "heal" a brand-new empty file and misleadingly report "nothing to heal". Fail loudly instead.
+  if (!existsSync(dbPath)) {
+    console.error(
+      `heal-migration-ledger: ${dbPath} — no such file. Pass the path to the existing install's SQLite DB.`,
+    );
+    process.exit(2);
+  }
+
+  const db = new DatabaseSync(dbPath);
+  try {
+    const healed = healMigrationLedger(db);
+    if (healed.length === 0) {
+      console.log(`heal-migration-ledger: ${dbPath} — nothing to heal (ledger already consistent).`);
+    } else {
+      console.log(
+        `heal-migration-ledger: ${dbPath} — aliased ${healed.length} migration(s) as applied: ${healed.join(", ")}. Restart the node to complete boot.`,
+      );
+    }
+  } finally {
+    db.close();
+  }
+}
+
+if (import.meta.main) main();

package/test/migrations.ts

@@ -0,0 +1,121 @@
+// Test helpers for exercising the forward-only SQLite migration set the way the runtime does.
+//
+// `applyMigrationSet` mirrors `@nanobpm/urban`'s `applyMigrations` (ledger keyed by FILENAME, each
+// migration wrapped in its own transaction, skip-applied / apply-new) against a `node:sqlite`
+// `DatabaseSync`, so upgrade tests reproduce the exact boot-time behaviour — including the
+// "duplicate column" abort a renamed migration causes — without booting the whole app.
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { DatabaseSync } from "node:sqlite";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const MIGRATIONS_DIR = join(REPO_ROOT, "db", "migrations");
+const MIGRATIONS_TABLE = "_urban_migrations";
+
+export interface MigrationFile {
+  name: string;
+  sql: string;
+}
+
+function byName(files: MigrationFile[]): MigrationFile[] {
+  // Match the runtime's plain lexical `.sort()` on filename (apply order).
+  return [...files].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/**
+ * Apply `files` to `db` exactly as the runtime does: create the ledger, skip any filename already
+ * recorded, and for each remaining file run its SQL + record the filename atomically in one
+ * transaction. Throws the same rolled-back error the runtime raises when a migration's SQL fails.
+ * @returns the filenames newly applied.
+ */
+export function applyMigrationSet(
+  db: DatabaseSync,
+  files: MigrationFile[],
+  now: () => Date = () => new Date(),
+): string[] {
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)`,
+  );
+  const applied = new Set(
+    (db.prepare(`SELECT name FROM ${MIGRATIONS_TABLE}`).all() as { name: string }[]).map(
+      (r) => r.name,
+    ),
+  );
+  const newlyApplied: string[] = [];
+  for (const file of byName(files)) {
+    if (applied.has(file.name)) continue;
+    db.exec("BEGIN");
+    try {
+      db.exec(file.sql);
+      db.prepare(`INSERT INTO ${MIGRATIONS_TABLE} (name, applied_at) VALUES (?, ?)`).run(
+        file.name,
+        now().toISOString(),
+      );
+      db.exec("COMMIT");
+    } catch (err) {
+      db.exec("ROLLBACK");
+      throw new Error(
+        `migration "${file.name}" failed and was rolled back (no partial schema change, not recorded as applied): ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err },
+      );
+    }
+    newlyApplied.push(file.name);
+  }
+  return newlyApplied;
+}
+
+/** The current worktree's migration set, read from `db/migrations/`. */
+export function readMigrationSetFromDisk(): MigrationFile[] {
+  return readdirSync(MIGRATIONS_DIR)
+    .filter((f) => f.endsWith(".sql"))
+    .map((name) => ({ name, sql: readFileSync(join(MIGRATIONS_DIR, name), "utf8") }));
+}
+
+function git(args: string[]): string {
+  return execFileSync("git", args, { cwd: REPO_ROOT, encoding: "utf8" });
+}
+
+/**
+ * The migration set as it existed at a git ref (tag/branch/sha), read straight from the object
+ * store so it works from any worktree. Returns `null` if the ref (or git) is unavailable — e.g. a
+ * shallow clone without tags — so callers can skip rather than fail spuriously (CI fetches full
+ * history + tags, so it exercises the real path).
+ */
+export function readMigrationSetFromGit(ref: string): MigrationFile[] | null {
+  let listing: string;
+  try {
+    listing = git(["ls-tree", "-r", "--name-only", ref, "--", "db/migrations"]);
+  } catch {
+    return null;
+  }
+  const paths = listing
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.endsWith(".sql"));
+  if (paths.length === 0) return null;
+  const files: MigrationFile[] = [];
+  for (const path of paths) {
+    const name = path.slice(path.lastIndexOf("/") + 1);
+    files.push({ name, sql: git(["show", `${ref}:${path}`]) });
+  }
+  return files;
+}
+
+/**
+ * The most recent release tag (`vN.N.N`) reachable from HEAD's parent — i.e. the release we would be
+ * upgrading a live install FROM. Falls back to the tag on HEAD itself, then `null` if none is
+ * reachable (shallow clone without tags).
+ */
+export function previousReleaseTag(): string | null {
+  for (const from of ["HEAD^", "HEAD"]) {
+    try {
+      const ref = git(["describe", "--tags", "--abbrev=0", "--match", "v*", from]).trim();
+      if (ref) return ref;
+    } catch {
+      // try the next base
+    }
+  }
+  return null;
+}