@nanobpm/nano-workforce 0.106.0 → 0.106.2

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,17 @@
+## [0.106.2](https://github.com/nanobpm/nano-workforce/compare/v0.106.1...v0.106.2) (2026-08-20)
+
+
+### Bug Fixes
+
+* **velocity:** bucket burn-up by local timezone, not UTC ([#361](https://github.com/nanobpm/nano-workforce/issues/361)) ([#362](https://github.com/nanobpm/nano-workforce/issues/362)) ([84d842a](https://github.com/nanobpm/nano-workforce/commit/84d842ad443fba8a0c399bdd5f4fca466da4a21c))
+
+## [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/mergesPerDay.test.ts

@@ -12,6 +12,13 @@ import { assert, assertEquals } from "#test-assert";
 import type { DataLayer } from "@nanobpm/urban";
 import { deriveMergesPerDay, type MergeAuditRow, pollMergesPerDay } from "./mergesPerDay.ts";
 
+// The bucketing is now LOCAL-calendar-day (issue #361: use the viewer's timezone, not UTC). The
+// derivation buckets in an explicit IANA `timeZone` argument (via `Intl.DateTimeFormat`), so these
+// tests pass the zone directly rather than mutating the process-global `process.env.TZ` — which
+// `node --test` runs concurrently across files, so an in-process `TZ` flip could leak into and
+// reorder unrelated date-handling tests. The UTC-based assertions pass `"UTC"`; the
+// timezone-specific ones pass the zone they exercise.
+
 // A tiny in-memory record gateway (all/find/insert/update/delete), mirroring the fake-app style used
 // across the app tests (see app/delivery.test.ts), enough to exercise the `pollMergesPerDay`
 // projection.
@@ -62,7 +69,7 @@ test("counts DISTINCT merged PRs per calendar day", () => {
     merged("o/r#1", "2026-01-01T09:00:00Z"),
     merged("o/r#2", "2026-01-01T18:30:00Z"),
     merged("o/r#3", "2026-01-02T10:00:00Z"),
-  ]);
+  ], "UTC");
   assertEquals(days.map((d) => [d.day, d.merged]), [
     ["2026-01-01", 2],
     ["2026-01-02", 1],
@@ -74,7 +81,7 @@ test("dedupes duplicate merged rows for the same PR on the same day (COUNT DISTI
     merged("o/r#1", "2026-01-01T09:00:00Z"),
     merged("o/r#1", "2026-01-01T09:00:05Z"), // retry / already-merged short-circuit
     merged("o/r#1", "2026-01-01T23:59:00Z"),
-  ]);
+  ], "UTC");
   assertEquals(days.length, 1);
   assertEquals(days[0].merged, 1);
 });
@@ -84,7 +91,7 @@ test("the same PR merged on two different days counts once per day", () => {
   const days = deriveMergesPerDay([
     merged("o/r#1", "2026-01-01T09:00:00Z"),
     merged("o/r#1", "2026-01-02T09:00:00Z"),
-  ]);
+  ], "UTC");
   assertEquals(days.map((d) => [d.day, d.merged]), [
     ["2026-01-01", 1],
     ["2026-01-02", 1],
@@ -96,7 +103,7 @@ test("ignores queued and blocked attempts", () => {
     merged("o/r#1", "2026-01-01T09:00:00Z"),
     { pr_key: "o/r#2", outcome: "queued", at: "2026-01-01T09:10:00Z" },
     { pr_key: "o/r#3", outcome: "blocked", at: "2026-01-01T09:20:00Z" },
-  ]);
+  ], "UTC");
   assertEquals(days.length, 1);
   assertEquals(days[0].merged, 1);
 });
@@ -107,7 +114,7 @@ test("orders days ascending and carries a running burn-up cumulative", () => {
     merged("o/r#1", "2026-01-01T10:00:00Z"),
     merged("o/r#2", "2026-01-01T11:00:00Z"),
     merged("o/r#4", "2026-01-02T10:00:00Z"),
-  ]);
+  ], "UTC");
   assertEquals(days.map((d) => d.day), ["2026-01-01", "2026-01-02", "2026-01-03"]);
   assertEquals(days.map((d) => d.merged), [2, 1, 1]);
   assertEquals(days.map((d) => d.cumulative), [2, 3, 4]);
@@ -122,7 +129,7 @@ test("bar scales against the busiest day: full for the max, non-empty for a lone
     merged("o/r#4", "2026-01-01T04:00:00Z"),
     // day B: 1 merge → short but visible bar
     merged("o/r#5", "2026-01-02T01:00:00Z"),
-  ]);
+  ], "UTC");
   const [a, b] = days;
   assert(a.bar.length > b.bar.length, "the busier day must draw a longer bar");
   assert(b.bar.length >= 1, "a day with any merge must draw at least one glyph");
@@ -133,6 +140,83 @@ test("empty audit yields no days", () => {
   assertEquals(deriveMergesPerDay([]), []);
 });
 
+test("buckets by the viewer's LOCAL calendar day, not UTC (issue #361)", () => {
+  // 02:00Z on Jan 1 is still Dec 31 in a west-of-UTC zone (America/New_York, UTC-5).
+  {
+    const days = deriveMergesPerDay([merged("o/r#1", "2026-01-01T02:00:00Z")], "America/New_York");
+    assertEquals(
+      days.map((d) => d.day),
+      ["2025-12-31"],
+    );
+  }
+  // 23:00Z on Jan 1 is already Jan 2 in an east-of-UTC zone (Pacific/Kiritimati, UTC+14).
+  {
+    const days = deriveMergesPerDay([merged("o/r#1", "2026-01-01T23:00:00Z")], "Pacific/Kiritimati");
+    assertEquals(
+      days.map((d) => d.day),
+      ["2026-01-02"],
+    );
+  }
+});
+
+test("two merges either side of local midnight land on the same local day (issue #361)", () => {
+  // In UTC these are two different UTC days; in America/New_York (UTC-5) both are Jan 1 evening,
+  // so a local-time bucketing counts them together on 2026-01-01.
+  {
+    const days = deriveMergesPerDay(
+      [
+        merged("o/r#1", "2026-01-01T18:00:00Z"), // 13:00 local, Jan 1
+        merged("o/r#2", "2026-01-02T04:00:00Z"), // 23:00 local, Jan 1
+      ],
+      "America/New_York",
+    );
+    assertEquals(
+      days.map((d) => [d.day, d.merged]),
+      [["2026-01-01", 2]],
+    );
+  }
+});
+
+test("non-ISO / malformed `at` still groups deterministically without throwing", () => {
+  const days = deriveMergesPerDay([
+    { pr_key: "o/r#1", outcome: "merged", at: "not-a-timestamp" },
+    { pr_key: "o/r#2", outcome: "merged", at: "not-a-timestamp" },
+  ], "UTC");
+  assertEquals(days.length, 1);
+  assertEquals(days[0].day, "not-a-timestamp");
+  assertEquals(days[0].merged, 2);
+});
+
+test("ambiguous partially-formed `at` (date-only / offset-less) buckets on the trimmed string, not a runtime-dependent day", () => {
+  // `new Date("2026-01-01")` parses as UTC midnight while `new Date("2026-01-01T12:00:00")` parses in
+  // the host's local zone — bucketing either would be runtime/timezone-dependent, the exact drift this
+  // read model exists to avoid. Neither carries an explicit `Z`/offset, so both must fall back to the
+  // trimmed string and group deterministically regardless of the viewer's `timeZone`.
+  const rows: MergeAuditRow[] = [
+    { pr_key: "o/r#1", outcome: "merged", at: "2026-01-01" },
+    { pr_key: "o/r#2", outcome: "merged", at: "2026-01-01T12:00:00" },
+  ];
+  for (const zone of ["UTC", "America/New_York", "Pacific/Kiritimati"]) {
+    const days = deriveMergesPerDay(rows, zone);
+    assertEquals(days.map((d) => [d.day, d.merged]), [
+      ["2026-01-01", 1],
+      ["2026-01-01T12:00:00", 1],
+    ]);
+  }
+});
+
+test("an invalid IANA timeZone falls back to the host zone instead of throwing (issue #361)", () => {
+  // A bogus zone would make `Intl.DateTimeFormat` throw a `RangeError`; bucketing must stay
+  // deterministic and not wedge `deriveMergesPerDay`/`pollMergesPerDay`.
+  const days = deriveMergesPerDay(
+    [merged("o/r#1", "2026-01-01T12:00:00Z")],
+    "Not/AZone",
+  );
+  assertEquals(days.length, 1);
+  assertEquals(days[0].merged, 1);
+  assert(/^\d{4}-\d{2}-\d{2}$/.test(days[0].day));
+});
+
 test("pollMergesPerDay projects the aggregate onto merges_per_day", async () => {
   const { data, stores } = memData();
   stores.merges = [
@@ -141,7 +225,7 @@ test("pollMergesPerDay projects the aggregate onto merges_per_day", async () =>
     { id: 3, pr_key: "o/r#2", outcome: "merged", at: "2026-01-02T09:00:00Z" },
     { id: 4, pr_key: "o/r#3", outcome: "queued", at: "2026-01-02T09:10:00Z" }, // ignored
   ];
-  await pollMergesPerDay(data);
+  await pollMergesPerDay(data, "UTC");
   const rows = (stores.merges_per_day ?? []).slice().sort((x, y) => x.day.localeCompare(y.day));
   assertEquals(rows.map((r) => [r.day, r.merged, r.cumulative]), [
     ["2026-01-01", 1, 1],
@@ -153,10 +237,10 @@ test("pollMergesPerDay projects the aggregate onto merges_per_day", async () =>
 test("pollMergesPerDay is idempotent — a steady-state re-run writes nothing", async () => {
   const { data, stores, writes } = memData();
   stores.merges = [{ id: 1, pr_key: "o/r#1", outcome: "merged", at: "2026-01-01T09:00:00Z" }];
-  await pollMergesPerDay(data);
+  await pollMergesPerDay(data, "UTC");
   const afterFirst = writes();
   assert(afterFirst > 0, "the first pass must project at least one row");
-  await pollMergesPerDay(data);
+  await pollMergesPerDay(data, "UTC");
   assertEquals(writes(), afterFirst, "a steady-state re-run must not write");
 });
 
@@ -166,7 +250,7 @@ test("pollMergesPerDay prunes a day that no longer derives from the audit", asyn
     { day: "2025-12-31", merged: 3, cumulative: 3, bar: "███", updated_at: "old" },
   ];
   stores.merges = [{ id: 1, pr_key: "o/r#1", outcome: "merged", at: "2026-01-01T09:00:00Z" }];
-  await pollMergesPerDay(data);
+  await pollMergesPerDay(data, "UTC");
   const days = (stores.merges_per_day ?? []).map((r: any) => r.day);
   assert(!days.includes("2025-12-31"), "a stale day must be pruned");
   assert(days.includes("2026-01-01"), "the derived day must be present");

package/app/mergesPerDay.ts

@@ -7,10 +7,12 @@
 // set is not exhaustive), `at` = ISO timestamp. Only `outcome = 'merged'` rows feed this aggregate,
 // so merged-per-day is
 // fully DERIVABLE from that audit trail with NO new write-path bookkeeping (AGENTS.md: "Derivation
-// over duplication"). The canonical aggregate is the one in the issue:
+// over duplication"). The `at` audit value is UTC, but the day is bucketed in the viewer's LOCAL
+// timezone (issue #361) so an operator sees merges on the calendar day they happened locally, not
+// shifted across a UTC midnight. The canonical aggregate is the one in the issue, in local time:
 //
-//   SELECT date(at) AS day, COUNT(DISTINCT pr_key) AS merged
-//   FROM merges WHERE outcome = 'merged' GROUP BY date(at);
+//   SELECT date(at, 'localtime') AS day, COUNT(DISTINCT pr_key) AS merged
+//   FROM merges WHERE outcome = 'merged' GROUP BY date(at, 'localtime');
 //
 // Two halves, mirroring the `deriveDelivery`/`pollDelivery` and `deriveLineage`/`pollLineage`
 // convention:
@@ -37,7 +39,7 @@ export interface MergeAuditRow {
 
 /** One projected calendar day of merge throughput. */
 export interface MergeDay {
-  /** Calendar day, ISO `YYYY-MM-DD` (SQLite `date(at)`). */
+  /** Local calendar day, ISO `YYYY-MM-DD` (SQLite `date(at, 'localtime')` — issue #361). */
   day: string;
   /** Distinct PRs merged that day (`COUNT(DISTINCT pr_key)`). */
   merged: number;
@@ -51,12 +53,72 @@ export interface MergeDay {
 const BAR_WIDTH = 30;
 const BAR_FULL = "█";
 
-/** The calendar day of an ISO timestamp — the JS twin of SQLite `date(at)`. A well-formed `merges.at`
- *  is an ISO string, so the first 10 chars are `YYYY-MM-DD`; fall back to the whole trimmed value for
- *  any non-ISO shape so a malformed row still groups deterministically rather than throwing. */
-function dayOf(at: string): string {
+/** The **local** calendar day of an ISO timestamp — the viewer's-timezone twin of SQLite
+ *  `date(at, 'localtime')` (issue #361). The `merges.at` audit value is a UTC ISO string, but the
+ *  Velocity page is read by an operator in their own timezone, so bucketing on the UTC date split a
+ *  single local day across two rows (a late-evening merge west of UTC, or an early-morning one east
+ *  of it, landed on the wrong day). We derive the day in the target `timeZone` via
+ *  `Intl.DateTimeFormat` — an explicit, side-effect-free zone rather than one mutated through the
+ *  process-global `process.env.TZ`. When `timeZone` is omitted the formatter uses the host's
+ *  resolved zone (so a remote deployment can still pin the operator's zone via `TZ`, and a
+ *  co-located console — the default `npm start` on `localhost` — is already the browser's zone). An
+ *  invalid/unknown IANA `timeZone` falls back to the host-resolved zone (rather than throwing a
+ *  `RangeError` that would wedge `deriveMergesPerDay`/`pollMergesPerDay`), so bucketing stays
+ *  deterministic. Any value that is not an UNAMBIGUOUS ISO instant — one carrying an explicit
+ *  timezone designator (`Z` or a `±HH:MM`/`±HHMM` offset) — falls back to the whole trimmed string so
+ *  it still groups deterministically. This deliberately excludes partially-formed values a bare
+ *  `new Date(s)` would still parse but *ambiguously*: a date-only `"2026-01-01"` is read as UTC
+ *  midnight while an offset-less `"2026-01-01T12:00:00"` is read in the host's local zone — so
+ *  bucketing them would be runtime/timezone-dependent, the very drift this read model exists to avoid.
+ *  Production `merges.at` values are always `new Date().toISOString()` (UTC, `Z`-suffixed), so only a
+ *  malformed audit row ever takes the fallback. */
+const dayFormatters = new Map<string, Intl.DateTimeFormat>();
+
+/** An unambiguous ISO-8601 instant: a full `YYYY-MM-DDTHH:MM[:SS[.sss]]` carrying an explicit zone
+ *  designator (`Z`, or a `±HH:MM`/`±HHMM` offset). Only these parse to a timezone-independent instant;
+ *  anything else (date-only, offset-less datetime, free text) buckets ambiguously, so `dayOf` treats
+ *  it as a non-instant and groups on the trimmed string instead. */
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+/** A cached `en-CA` day formatter for `timeZone`, falling back to the host-resolved zone when the
+ *  zone is invalid/unknown (an invalid IANA string makes `Intl.DateTimeFormat` throw a `RangeError`).
+ *  Keyed so an invalid zone is only probed once. */
+function dayFormatter(timeZone?: string): Intl.DateTimeFormat {
+  const key = timeZone ?? "";
+  const cached = dayFormatters.get(key);
+  if (cached) return cached;
+  const opts: Intl.DateTimeFormatOptions = {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  };
+  let fmt: Intl.DateTimeFormat;
+  try {
+    fmt = new Intl.DateTimeFormat("en-CA", { ...opts, timeZone });
+  } catch {
+    fmt = new Intl.DateTimeFormat("en-CA", opts);
+  }
+  dayFormatters.set(key, fmt);
+  return fmt;
+}
+
+function dayOf(at: string, timeZone?: string): string {
   const s = String(at).trim();
-  return /^\d{4}-\d{2}-\d{2}/.test(s) ? s.slice(0, 10) : s;
+  // Only bucket unambiguous ISO instants (explicit `Z`/offset). A partially-formed value a bare
+  // `new Date(s)` would still parse — a date-only or offset-less datetime — buckets differently per
+  // runtime/timezone, so group it deterministically on the trimmed string instead.
+  if (!ISO_INSTANT.test(s)) return s;
+  const d = new Date(s);
+  if (Number.isNaN(d.getTime())) return s;
+  const parts = dayFormatter(timeZone).formatToParts(d);
+  const field = (type: string) => parts.find((p) => p.type === type)?.value ?? "";
+  const year = field("year");
+  const month = field("month");
+  const day = field("day");
+  // Guard against a formatter that somehow omits a field — never emit a `"--"`-shaped key; fall back
+  // to the trimmed string so the row still groups deterministically.
+  if (!year || !month || !day) return s;
+  return `${year}-${month}-${day}`;
 }
 
 /** Render a proportional bar: `merged` glyphs scaled against the busiest day's `max`, min one glyph
@@ -69,17 +131,20 @@ function barFor(merged: number, max: number): string {
 
 /** PURE aggregate: merge audit rows → one ordered `MergeDay` per calendar day (ascending).
  *
- * Only `outcome === "merged"` rows count; `queued`/`blocked` attempts are ignored. Within a day a
- * `pr_key` is counted once (`COUNT(DISTINCT pr_key)`), so duplicate `merged` audit rows — an
- * `already-merged` short-circuit or a retry — do not double-count. `cumulative` is the running total
- * across days (burn-up); `bar` is scaled against the busiest day so the chart is comparable. */
-export function deriveMergesPerDay(rows: readonly MergeAuditRow[]): MergeDay[] {
+ * Days are bucketed in `timeZone` (an IANA zone, e.g. `America/New_York`); omit it to use the host's
+ * resolved zone — the production default, matching SQLite `date(at, 'localtime')` for the operator's
+ * console (issue #361). Only `outcome === "merged"` rows count; `queued`/`blocked` attempts are
+ * ignored. Within a day a `pr_key` is counted once (`COUNT(DISTINCT pr_key)`), so duplicate `merged`
+ * audit rows — an `already-merged` short-circuit or a retry — do not double-count. `cumulative` is
+ * the running total across days (burn-up); `bar` is scaled against the busiest day so the chart is
+ * comparable. */
+export function deriveMergesPerDay(rows: readonly MergeAuditRow[], timeZone?: string): MergeDay[] {
   // day -> set of distinct merged pr_keys that day.
   const prKeysByDay = new Map<string, Set<string>>();
   for (const r of rows) {
     if (r.outcome !== "merged") continue;
     if (r.pr_key == null || r.at == null) continue;
-    const day = dayOf(r.at);
+    const day = dayOf(r.at, timeZone);
     let set = prKeysByDay.get(day);
     if (!set) {
       set = new Set<string>();
@@ -114,13 +179,14 @@ const mergesAudit = (data: DataLayer) => data.table<MergeAuditRow>("merges", "id
  * it onto the `merges_per_day` read table the Velocity page reads. Additive/derived only — never
  * touches `merges`. Upserts a day only when its projection actually changes (so a steady-state pass is
  * a no-op) and prunes any stale day row that no longer derives (defensive — days are append-only in
- * practice, but a purge/rewrite of the audit must not leave a phantom). */
-export async function pollMergesPerDay(data: DataLayer): Promise<void> {
+ * practice, but a purge/rewrite of the audit must not leave a phantom). Buckets in `timeZone` (an
+ * IANA zone) when given; the production caller omits it to use the host's resolved zone. */
+export async function pollMergesPerDay(data: DataLayer, timeZone?: string): Promise<void> {
   try {
     // Only `outcome === "merged"` rows contribute to the aggregate, so filter at the read rather than
     // scanning queued/blocked rows as the audit grows (deriveMergesPerDay ignores non-merged rows too).
     const audit = await mergesAudit(data).find({ outcome: "merged" });
-    const want = deriveMergesPerDay(audit);
+    const want = deriveMergesPerDay(audit, timeZone);
     const wantByDay = new Map(want.map((d) => [d.day, d]));
 
     const existing = await mergesPerDay(data).all();

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.2",
   "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;
+}