@bygghammar/cms-platform 0.91.1 → 0.92.1

package/src/backup/restore-core.ts

@@ -9,11 +9,12 @@ import { unzipSync, strFromU8 } from "fflate";
 
 import {
   ARCHIVE_FORMAT_VERSION,
+  CLEAR_ORDER,
   DATASET_GROUPS,
   IMPORT_ORDER,
   LINEAGE_KEYS,
-  SCHEMA_VERSION,
   groupById,
+  readSchemaVersion,
   type ArchiveManifest,
   type ImportMode,
   type TableSpec,
@@ -51,14 +52,23 @@ export function readArchive(bytes: Uint8Array): ReadArchiveResult {
       `Archive format ${manifest.format} cannot be restored — this tool reads format ${ARCHIVE_FORMAT_VERSION}.`,
     );
   }
-  if (manifest.schemaVersion !== SCHEMA_VERSION) {
-    throw new Error(
-      `Archive schema version ${manifest.schemaVersion} does not match this tool (${SCHEMA_VERSION}).`,
-    );
+  const reading = readSchemaVersion(manifest.schemaVersion);
+  if (!reading.supported) {
+    throw new Error(`This archive cannot be restored — ${reading.reason}.`);
   }
   return { manifest, entries };
 }
 
+/**
+ * True when the archive predates the review tables and therefore says nothing
+ * about which pages were reviewed. Restoring one leaves content whose
+ * classification is unknown until something scans it.
+ */
+export function needsReconciliation(manifest: ArchiveManifest): boolean {
+  const reading = readSchemaVersion(manifest.schemaVersion);
+  return reading.supported && !reading.carriesReviewHistory;
+}
+
 export function tableRows(entries: ArchiveEntries, table: string): Record<string, unknown>[] {
   const raw = entries[`data/${table}.json`];
   if (!raw) return [];
@@ -234,6 +244,24 @@ export function columnsOf(rows: Record<string, unknown>[]): string[] {
   return cols;
 }
 
+/**
+ * The columns a restore is allowed to name in an INSERT: everything the
+ * archive carries for the table, minus the ones the database computes for
+ * itself.
+ *
+ * PostgreSQL rejects an INSERT that names a GENERATED column outright, so
+ * carrying `inputs_digest` through from the archive would turn a perfectly
+ * valid backup into a failed restore — and gain nothing, because the value is
+ * recomputed from the same `inputs` and cannot come out different. Dropping it
+ * here is the reason a digest can be trusted at all: there is no code path,
+ * restore included, by which a stored digest and the inputs it claims to
+ * cover can disagree.
+ */
+export function writableColumns(rows: Record<string, unknown>[], spec: TableSpec): string[] {
+  const generated = new Set(spec.generated ?? []);
+  return columnsOf(rows).filter((c) => !generated.has(c));
+}
+
 function encode(value: unknown): unknown {
   if (value instanceof Date) return value.toISOString();
   if (value !== null && typeof value === "object") return JSON.stringify(toJsonSafe(value));
@@ -286,7 +314,8 @@ export function buildInsert(
   insertOnly: boolean,
 ): Statement {
   if (!rows.length) throw new Error("buildInsert called with no rows");
-  const cols = columnsOf(rows);
+  const cols = writableColumns(rows, spec);
+  if (!cols.length) throw new Error(`buildInsert called with no writable columns for ${table}`);
   const quoted = cols.map(quoteIdent);
   const values: unknown[] = [];
   const tuples = rows.map((row) => {
@@ -346,10 +375,85 @@ export function buildDeferredUpdates(planned: PlannedTable): Statement[] {
   return out;
 }
 
-/** Statement used by Replace mode. Insert-only tables are never cleared. */
-export function buildClear(planned: PlannedTable): Statement | null {
-  if (planned.insertOnly) return null;
-  return { text: `DELETE FROM public.${quoteIdent(planned.table)}`, values: [] };
+/* ----------------------------------------------------------- clear phase */
+
+/**
+ * One step of the Replace-mode clear phase.
+ *
+ * Two kinds, because emptying a table is not always a DELETE. `pages` points
+ * forward at `page_versions` through `current_version_id`; no ordering of
+ * DELETEs can satisfy that, because whichever table goes first is still being
+ * referenced by the other. So the pointer is released first, and only then
+ * does the reverse-order deletion have a path.
+ *
+ * A step is deliberately not a `Statement`. The two callers speak different
+ * dialects — the standalone tool sends SQL to PostgreSQL, the backoffice
+ * import goes through supabase-js and has no SQL channel at all — so what they
+ * share is the *plan*: which tables, in which order, and what to do to each.
+ * Each renders it in its own terms. Sharing rendered SQL would have meant
+ * sharing nothing, because only one of them can execute it.
+ */
+export type ClearStep =
+  | { kind: "release"; table: string; columns: string[] }
+  | { kind: "delete"; table: string };
+
+/**
+ * The ordered clear phase for a Replace restore of `groups`.
+ *
+ * Three properties matter, and none of them holds in the code this replaces:
+ *
+ * 1. It runs once, before the first insert — not interleaved with the inserts,
+ *    where a later table's DELETE would remove rows an earlier one just wrote.
+ * 2. It follows CLEAR_ORDER, the exact reverse of IMPORT_ORDER. Forward order
+ *    is not merely slower to fail: `cms_publication_review_items.page_id` is
+ *    ON DELETE RESTRICT, so deleting `pages` first raises instead of quietly
+ *    cascading history away. Keeping RESTRICT and getting the order right is
+ *    what turns an ordering mistake into a loud failure.
+ * 3. It covers every selected table whether or not the archive carries rows
+ *    for it. "Replace" means the target ends up holding what the archive holds;
+ *    a table the archive is silent about must end up empty, and the old code —
+ *    which cleared inside the per-table loop, after `if (!rows.length)
+ *    continue;` — left exactly those tables untouched.
+ *
+ * Insert-only tables are absent from the plan entirely. They are named in
+ * CLEAR_ORDER, because a dependency ordering with holes in it is not a
+ * dependency ordering, but the append-only review history is never deleted:
+ * see `replaceRefusals` for what happens when a caller asks for that anyway.
+ */
+export function buildClearPlan(groups: string[]): ClearStep[] {
+  const selected = new Map<string, { spec: TableSpec; insertOnly: boolean }>();
+  for (const id of groups) {
+    const group = groupById(id);
+    if (!group) continue;
+    for (const spec of group.tables) {
+      selected.set(spec.table, { spec, insertOnly: Boolean(group.insertOnly) });
+    }
+  }
+
+  const releases: ClearStep[] = [];
+  const deletes: ClearStep[] = [];
+  for (const table of CLEAR_ORDER) {
+    const entry = selected.get(table);
+    if (!entry || entry.insertOnly) continue;
+    const deferred = entry.spec.deferred ?? [];
+    if (deferred.length) releases.push({ kind: "release", table, columns: [...deferred] });
+    deletes.push({ kind: "delete", table });
+  }
+  // Every pointer is released before any row is deleted. Ordering the releases
+  // among themselves would be busywork: releasing one cannot make another fail.
+  return [...releases, ...deletes];
+}
+
+/** One clear step as SQL, for the caller that has a SQL channel. */
+export function buildClear(step: ClearStep): Statement {
+  if (step.kind === "release") {
+    const assignments = step.columns.map((c) => `${quoteIdent(c)} = NULL`).join(", ");
+    return {
+      text: `UPDATE public.${quoteIdent(step.table)} SET ${assignments}`,
+      values: [],
+    };
+  }
+  return { text: `DELETE FROM public.${quoteIdent(step.table)}`, values: [] };
 }
 
 /* ------------------------------------------------------------ auth users */
@@ -415,6 +519,242 @@ export function stageMedia(entries: ArchiveEntries): {
   return { files, quarantined, bytes };
 }
 
+/* ------------------------------------------------------- review history */
+
+/**
+ * The parts of the local review history a restore has to consult before it
+ * writes anything. Deliberately narrow: three tables, and from each only the
+ * columns a conflict can turn on. A caller supplies these by reading the local
+ * database; everything below is pure, so the comparison itself is testable
+ * without one.
+ */
+export type LocalReviewState = {
+  runs: { id: string; input_fingerprint: string | null }[];
+  items: { id: string; run_id: string; page_id: string; classification: string | null }[];
+  decisions: { item_id: string; decision: string | null }[];
+};
+
+export const EMPTY_REVIEW_STATE: LocalReviewState = Object.freeze({
+  runs: [],
+  items: [],
+  decisions: [],
+});
+
+export type ReviewConflict = {
+  /** Which table the disagreement is in. */
+  table: string;
+  /** How the archived row and the local row were matched to each other. */
+  key: string;
+  /** What this database currently says. */
+  local: string;
+  /** What the archive says instead. */
+  archived: string;
+};
+
+/**
+ * Places where the archive's review history and this database's review history
+ * describe the same thing differently.
+ *
+ * Only genuine disagreements are listed. A row that exists in both and says
+ * the same thing is not a conflict — it is the ordinary case for an archive
+ * taken from this database — and a row that exists in only one of them is not
+ * a conflict either, because insert-only restore adds it without touching
+ * anything. What is left is the case the append-only triggers cannot resolve
+ * on their own: two records claiming the same identity with different content.
+ *
+ * Note what this refuses to do about it. It reports; it does not pick a
+ * winner. A restore that quietly kept the local decision would silently
+ * discard imported history, and one that kept the archived decision would
+ * overwrite a choice somebody actually made — which is precisely what the
+ * decisions table's UNIQUE (item_id) and its append-only trigger exist to
+ * prevent. So the restore stops, before the first write, and a person decides.
+ */
+export function reviewConflicts(
+  entries: ArchiveEntries,
+  local: LocalReviewState,
+): ReviewConflict[] {
+  const out: ReviewConflict[] = [];
+
+  const localRuns = new Map(local.runs.map((r) => [String(r.id), r]));
+  for (const row of tableRows(entries, "cms_publication_review_runs")) {
+    const id = String(row["id"] ?? "");
+    const mine = localRuns.get(id);
+    if (!mine) continue;
+    const archived = row["input_fingerprint"] == null ? null : String(row["input_fingerprint"]);
+    if (archived === (mine.input_fingerprint ?? null)) continue;
+    out.push({
+      table: "cms_publication_review_runs",
+      key: `id="${id}"`,
+      local: `fingerprint ${mine.input_fingerprint ?? "(none)"}`,
+      archived: `fingerprint ${archived ?? "(none)"}`,
+    });
+  }
+
+  const localItemsByRunPage = new Map(
+    local.items.map((i) => [`${i.run_id}\u0000${i.page_id}`, i]),
+  );
+  for (const row of tableRows(entries, "cms_publication_review_items")) {
+    const runId = String(row["run_id"] ?? "");
+    const pageId = String(row["page_id"] ?? "");
+    const mine = localItemsByRunPage.get(`${runId}\u0000${pageId}`);
+    if (!mine) continue;
+    const archived = row["classification"] == null ? null : String(row["classification"]);
+    if (archived === (mine.classification ?? null)) continue;
+    out.push({
+      table: "cms_publication_review_items",
+      key: `run_id="${runId}" page_id="${pageId}"`,
+      local: `classified ${mine.classification ?? "(none)"}`,
+      archived: `classified ${archived ?? "(none)"}`,
+    });
+  }
+
+  const localDecisions = new Map(local.decisions.map((d) => [String(d.item_id), d]));
+  for (const row of tableRows(entries, "cms_publication_review_decisions")) {
+    const itemId = String(row["item_id"] ?? "");
+    const mine = localDecisions.get(itemId);
+    if (!mine) continue;
+    const archived = row["decision"] == null ? null : String(row["decision"]);
+    if (archived === (mine.decision ?? null)) continue;
+    out.push({
+      table: "cms_publication_review_decisions",
+      key: `item_id="${itemId}"`,
+      local: `decided ${mine.decision ?? "(none)"}`,
+      archived: `decided ${archived ?? "(none)"}`,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * A conflict list as one message an operator can act on.
+ *
+ * Every conflict is named, not just counted, and capped so a badly matched
+ * pair of databases produces a readable refusal rather than a wall of text.
+ */
+export function describeReviewConflicts(conflicts: ReviewConflict[]): string {
+  const shown = conflicts.slice(0, 10);
+  const lines = shown.map(
+    (c) => `  ${c.table} ${c.key}: this site says ${c.local}, the archive says ${c.archived}`,
+  );
+  const more = conflicts.length - shown.length;
+  return [
+    `This restore was stopped before it wrote anything: ${conflicts.length} piece(s) of ` +
+      `publication review history disagree between this site and the archive.`,
+    ...lines,
+    ...(more > 0 ? [`  …and ${more} more.`] : []),
+    "Review history is append-only — neither record can be overwritten by the other — " +
+      "so somebody has to decide which is right. Restore without the " +
+      "\"Publication review history\" dataset to leave this site's own history alone.",
+  ].join("\n");
+}
+
+/** True when this database holds any publication review history at all. */
+export function hasReviewHistory(local: LocalReviewState): boolean {
+  return local.runs.length > 0 || local.items.length > 0 || local.decisions.length > 0;
+}
+
+/**
+ * Requests this restore will not carry out, stated before it starts rather
+ * than discovered halfway through.
+ *
+ * There is exactly one today, and it is worth being explicit about why it is a
+ * refusal and not a repair. Replace mode empties the content tables; every
+ * page in a v3 database has a review item pointing at it with ON DELETE
+ * RESTRICT; the review tables themselves refuse DELETE unconditionally, by
+ * trigger. So Replace over content, in a database that has been reviewed,
+ * cannot succeed — the only ways to make it succeed are to weaken a trigger
+ * whose entire purpose is that it cannot be weakened from inside the
+ * application, or to cascade away the evidence for what the pages were. Merge
+ * does what the caller almost certainly wants and is not destructive.
+ *
+ * Returning the reason as text, rather than throwing here, keeps this usable
+ * from the analysis path: an operator sees the refusal alongside the rest of
+ * the report, before choosing anything.
+ */
+export function replaceRefusals(opts: PlanOptions, localHasReviewHistory: boolean): string[] {
+  if (opts.mode !== "replace") return [];
+  if (!opts.groups.includes("content")) return [];
+  if (!localHasReviewHistory) return [];
+  return [
+    "Replace cannot be used for Content & pages on this site: it would have to delete " +
+      "pages that the publication review history refers to, and that history is append-only " +
+      "by design — the database refuses to delete it, and this tool will not ask it twice. " +
+      "Restore with Merge instead, which adds and updates content without removing the " +
+      "review record of what was published before.",
+  ];
+}
+
+/* --------------------------------------------------------------- actors */
+
+/** An actor column that could not be pointed at a local account. */
+export type UnlinkedActor = { table: string; column: string; email: string };
+
+/**
+ * Point each actor column at the local account with that address, and drop the
+ * pointer where there is no such account.
+ *
+ * The email travels regardless — it is NOT NULL in the schema and it is the
+ * part that stays readable after an account is deleted — so nothing about who
+ * did what is lost here. What is dropped is only the join back to a row in
+ * `app_users` that this database does not have.
+ *
+ * Resolved before the insert rather than deferred and written back afterwards,
+ * which is the ordinary pattern elsewhere in this file. It has to be: the
+ * review tables carry BEFORE UPDATE triggers that raise unconditionally, so
+ * the second write of a deferred pair would not fail cleanly — it would fail
+ * after the row was already in, leaving a restore that reported success on a
+ * table whose actor pointers had all been rejected.
+ */
+export function resolveActors(
+  table: string,
+  spec: TableSpec,
+  rows: Record<string, unknown>[],
+  usersByEmail: Map<string, string>,
+): { rows: Record<string, unknown>[]; unlinked: UnlinkedActor[] } {
+  const actors = spec.actors ?? [];
+  if (!actors.length) return { rows, unlinked: [] };
+
+  const unlinkedSeen = new Set<string>();
+  const unlinked: UnlinkedActor[] = [];
+  const out = rows.map((row) => {
+    const next = { ...row };
+    for (const actor of actors) {
+      if (!(actor.column in next) && !(actor.email in next)) continue;
+      const raw = next[actor.email];
+      const email = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+      const localId = email ? usersByEmail.get(email) : undefined;
+      if (localId) {
+        next[actor.column] = localId;
+        continue;
+      }
+      next[actor.column] = null;
+      if (!email) continue;
+      const seen = `${table}.${actor.column}\u0000${email}`;
+      if (unlinkedSeen.has(seen)) continue;
+      unlinkedSeen.add(seen);
+      unlinked.push({ table, column: actor.column, email });
+    }
+    return next;
+  });
+
+  return { rows: out, unlinked };
+}
+
+/** Address → id for every local account, keyed the way `resolveActors` looks up. */
+export function indexUsersByEmail(
+  users: { id: string; email: string | null }[],
+): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const u of users) {
+    if (!u.email) continue;
+    const key = u.email.trim().toLowerCase();
+    if (!key || out.has(key)) continue;
+    out.set(key, String(u.id));
+  }
+  return out;
+}
+
 /* ------------------------------------------------------------- analysis */
 
 export type AnalysisReport = {
@@ -423,9 +763,32 @@ export type AnalysisReport = {
   media: { files: number; bytes: number; quarantined: string[] };
   authUsers: number;
   problems: string[];
+  /**
+   * Archived review history that disagrees with this database's own. Non-empty
+   * means the restore does not start. Separate from `problems` because these
+   * are not defects in the archive — both records are internally valid, and
+   * that is the difficulty.
+   */
+  reviewConflicts: ReviewConflict[];
+  /** Things this restore will not do, and why. Non-empty means it does not start. */
+  refusals: string[];
+  /** True when the archive predates review history, so a fresh scan is owed. */
+  reconciliationNeeded: boolean;
 };
 
-export function analyzeArchive(bytes: Uint8Array, opts: PlanOptions): AnalysisReport {
+/**
+ * Analyse an archive against this database's review history.
+ *
+ * `local` is the only impure input, and it is passed in rather than read here
+ * so the comparison stays testable without a database. Callers that have no
+ * local state to offer — the standalone tool inspecting a file, a test — use
+ * `analyzeArchive`, which supplies an empty one.
+ */
+export function analyzeArchiveCore(
+  bytes: Uint8Array,
+  opts: PlanOptions,
+  local: LocalReviewState,
+): AnalysisReport {
   const { manifest, entries } = readArchive(bytes);
   const plan = planRestore(entries, manifest, opts);
   const problems: string[] = [];
@@ -461,5 +824,13 @@ export function analyzeArchive(bytes: Uint8Array, opts: PlanOptions): AnalysisRe
     media: { files: media.files.length, bytes: media.bytes, quarantined: media.quarantined },
     authUsers,
     problems,
+    reviewConflicts: reviewConflicts(entries, local),
+    refusals: replaceRefusals(opts, hasReviewHistory(local)),
+    reconciliationNeeded: needsReconciliation(manifest) && opts.groups.includes("content"),
   };
 }
+
+/** Analysis of an archive on its own, with nothing to compare it against. */
+export function analyzeArchive(bytes: Uint8Array, opts: PlanOptions): AnalysisReport {
+  return analyzeArchiveCore(bytes, opts, EMPTY_REVIEW_STATE);
+}

package/src/platform/contract.ts

@@ -8,6 +8,53 @@
  * Bump `PLATFORM_CONTRACT_VERSION` whenever a shared screen starts requiring
  * schema or adapter capabilities an older site would not have.
  *
+ * ## v3 — five facts, five records
+ *
+ * v2 settled what is public. v3 settles who may say a release is live, and it
+ * does that by refusing to let one sentence stand for five separate facts.
+ * "The deployment succeeded" used to mean, all at once: the migration ran, the
+ * schema therefore offers a capability, somebody looked at the existing
+ * publication rows and understood what the new reader does differently to
+ * them, those decisions were applied, and the routes were activated. Each of
+ * those fails on its own, and collapsing them is what turns a green deploy
+ * into a site serving last month's homepage under a fresh version number.
+ *
+ * So each has its own record, and the later ones refuse to be written while an
+ * earlier one is missing:
+ *
+ *   1. *migration applied* — the canonical file ran. `SCHEMA_MIGRATIONS` and
+ *      `missingMigrations` already answered this and still do.
+ *   2. *schema capability* — `cms_schema_capabilities` says which contract
+ *      version the schema itself offers, written by the migration that makes
+ *      it true, so it cannot drift from the schema it describes.
+ *   3. *publication scan* — a review run records what the v3 reader would do
+ *      differently to every page that already has publication rows, item by
+ *      item, with the evidence it judged on.
+ *   4. *decisions applied* — a decision is recorded against one immutable
+ *      item, and applying it writes a new publication row rather than editing
+ *      the row that was reviewed.
+ *   5. *route activation, readiness, traffic* — three more, in that order.
+ *
+ * One canonical migration is new in v3:
+ *
+ *   - `20260905120000_…sql` — the installation identity, the capability
+ *     record, the canonical digest functions mirrored from `./digest`, the
+ *     review model, the route claims, and the readiness and activation
+ *     records.
+ *
+ * Nothing in it publishes, unpublishes or edits a page. Applying it to a live
+ * database changes what the site can be *asked*, not what it currently serves,
+ * which is what makes the ordered rollout below safe to start.
+ *
+ * Release order, and it is not optional:
+ *
+ *   1. Apply every missing canonical migration.
+ *   2. Scan, review and apply the publication decisions. The scan is a read;
+ *      applying is the first step that changes what visitors see, and it is
+ *      per-item and recorded.
+ *   3. Deploy this package, and the site pinned to contract v3 with it.
+ *   4. Activate the routes, declare the database ready, then release traffic.
+ *
  * ## v2 — publication rows decide what is public
  *
  * Saving a page version, publishing, unpublishing, scheduling a countdown
@@ -56,73 +103,48 @@
  * `INSERT`, and two repair `UPDATE`s scoped to pages already in the trash.
  */
 
-export const PLATFORM_CONTRACT_VERSION = 2 as const;
+import { MIGRATION_NAMES, migrationSlice } from "./migration-manifest";
+
+export const PLATFORM_CONTRACT_VERSION = 3 as const;
 
 /**
  * Canonical migration filenames, oldest first. Files live in the published
  * package at `@bygghammar/cms-platform/migrations/<name>`.
+ *
+ * Derived from the generated catalog rather than typed out beside it. Two
+ * modules used to carry the same sixty names — this one for the deploy-time
+ * assertion, `server/schema-drift` for the backoffice version screen — and the
+ * test that compared them could only report that they had already drifted
+ * apart. Now there is one list, written from the directory itself.
+ */
+export const SCHEMA_MIGRATIONS: readonly string[] = MIGRATION_NAMES;
+
+/**
+ * `migrationDigest` answers "is the file I have the file you published?", and
+ * `migrationSlice` names a part of the catalog without copying it. Both are
+ * defined in the generated module — it has no imports, so tooling that loads
+ * TypeScript sources directly can read it — and re-exported here, which is the
+ * subpath (`@bygghammar/cms-platform/platform/contract`) a site already uses.
+ */
+export { migrationDigest, migrationSlice } from "./migration-manifest";
+
+/**
+ * The pair that installs contract v2's transactional publication functions.
+ * `pages-core` names them when an RPC comes back "function does not exist",
+ * which is what a database that has not run them answers with.
  */
-export const SCHEMA_MIGRATIONS: readonly string[] = [
-  "20260728113741_f9744b19-078b-46e5-b00f-31c84aaf71ab.sql",
-  "20260728113757_4156a886-21fb-4a1f-9c12-acb7bb145102.sql",
-  "20260728113823_6e0237e1-99e3-4e1a-8a68-804b7bcdbbb8.sql",
-  "20260728115305_506d92b4-129f-4d2b-961f-cf76e592677e.sql",
-  "20260728115320_717d4447-f433-4a1d-89d2-fc8f028d4ac6.sql",
-  "20260728115347_c77f5a56-19db-4117-bb60-9ad692b817ab.sql",
-  "20260728132052_b692dcfe-a944-4a19-afd0-187f7600feb8.sql",
-  "20260728183318_05b05a47-ba05-4a66-ab8f-69f2688fea84.sql",
-  "20260728193035_84b68d27-c3f3-4516-a3a9-15fc6f476163.sql",
-  "20260728193707_8438ee2d-d589-4048-86e2-464fd209af80.sql",
-  "20260729055312_08862d7e-0279-4d4f-8709-a59b9f068c55.sql",
-  "20260729055348_418b7e36-4877-4304-831f-290ca73e56f3.sql",
-  "20260729055358_20b467e2-4efd-42c1-bd34-773ed6b77fc5.sql",
-  "20260729061039_306859eb-a38c-44ef-af1a-6c02a8fd84db.sql",
-  "20260730065600_54c25861-3355-4600-a72f-3d67b457ecb1.sql",
-  "20260730071745_d4904314-15ff-4c58-ac66-85e7371e04b5.sql",
-  "20260730071914_48163aa3-830e-4dcc-bdd4-c35be282ab87.sql",
-  "20260730085949_bcfc3270-ea80-4617-86a3-2555ed34a280.sql",
-  "20260730095256_c977c30e-b285-4041-8804-c0bd72b6d9b3.sql",
-  "20260730100057_e341b887-eb0e-4a74-850e-0ee5ffb70d7a.sql",
-  "20260730103703_d5c4e1b7-1e2c-4dd0-be4e-185c159ade69.sql",
-  "20260730105635_3557b7da-919e-48db-8c92-8221d68d3cf9.sql",
-  "20260730120308_12ff8cfb-43f9-4070-abde-61531ad3b75f.sql",
-  "20260730125024_1baf8926-12a2-48f4-8edc-7309941309e9.sql",
-  "20260730173510_feb974d1-510e-4f52-9e20-5fd0582d8952.sql",
-  "20260730175409_9f60743f-f5e1-418c-a700-c91fb3704db8.sql",
-  "20260730181224_1c52ff16-c7a2-4ef1-a0a8-e493c2c9106f.sql",
-  "20260730183129_933adb75-f985-4d82-ad5d-213b69fd42e5.sql",
-  "20260730183918_7bc7a827-2100-49f1-bc6e-24509249350b.sql",
-  "20260730202628_7ceade5e-644c-4bc2-91b8-594133329f31.sql",
-  "20260730211056_57f42049-00b4-473b-a2cd-65a13570b8d2.sql",
-  "20260730214340_98af2e55-9031-4c11-9659-c47a37a8d6b7.sql",
-  "20260731091630_8a6f28ce-5833-4901-ab17-27648cef32ec.sql",
-  "20260731094716_4c68a1df-83ed-4ba8-8019-fa2fe2b9681e.sql",
-  "20260731191655_fef97c3c-1397-47b4-8b56-afb020298e97.sql",
-  "20260731192212_95772a2f-19a1-4013-b463-2eb161e96737.sql",
-  "20260731192815_c490653e-1232-4ad9-a150-3c83d2b90f5e.sql",
-  "20260731193135_7966e740-5e86-4b14-8e1d-5119069666ba.sql",
-  "20260731193245_599790d0-ca5e-4b5d-a3e7-d69b2a79e1a3.sql",
-  "20260731212959_a748cb0d-4dc7-45dc-be90-f6bacbfab26c.sql",
-  "20260801003057_1195f4c1-fb54-42dc-9718-638a25e6a82e.sql",
-  "20260801003300_fc591960-cb41-41cf-837d-2eef23b29ca9.sql",
-  "20260802151445_a56b0023-eaf7-41e2-a7fb-d4beddfc587c.sql",
-  "20260802202621_d661af8a-8513-4b54-b375-f963ae824c8f.sql",
-  "20260802202702_c30cd837-744c-4641-85f1-edd3a7ebbcb6.sql",
-  "20260802202720_4418d18d-c851-42dc-9345-78fc330128ae.sql",
-  "20260803132514_78ba1f53-c85b-4457-96b1-7d49c5c8b494.sql",
-  "20260803181201_28c8aa09-baa8-431c-8338-90b1af9c8172.sql",
-  "20260803201518_6e8a6028-b70f-4a7d-8bc9-95c86304e7ae.sql",
-  "20260803201535_32a9a213-cb92-4035-b8cd-8211ca34af68.sql",
-  "20260811103505_29df753d-14fa-4a05-8fea-f4207785fba3.sql",
-  "20260811130318_7cb95e95-9baa-40af-8f3f-de1d4e09cec4.sql",
-  "20260818040722_1bdf1b8f-7fb0-4ae8-8ecf-73f1fadff3c2.sql",
-  "20260818040808_69a5e832-57e8-4aa7-aff8-7fd7777faa7c.sql",
-  "20260818040839_e6523163-bbf5-4a39-9233-91759059569a.sql",
-  "20260902090000_dc072b25-8467-46ae-aef3-0ccdf40aa7eb.sql",
-  "20260904090000_c54603f8-a155-40f8-a86c-54434aa5c0ae.sql",
+export const CONTRACT_V2_MIGRATIONS = migrationSlice("contract v2", [
   "20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql",
   "20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql",
-];
+]);
+
+/**
+ * The single file contract v3 adds: the installation identity, the capability
+ * record, the review model, the route claims and the readiness records.
+ */
+export const CONTRACT_V3_MIGRATIONS = migrationSlice("contract v3", [
+  "20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql",
+]);
 
 export function missingMigrations(applied: readonly string[]): string[] {
   const set = new Set(applied);