Skip to content

Commit a7e2a2e

Browse files
dmealingclaude
andcommitted
fix(verify): --replay prescribed a remedy that cannot work
`meta verify --replay` earned its keep immediately on two estates — it turned a paragraph of tribal knowledge into an exit code. Then it printed: Applied migrations are immutable, so fix this with a NEW migration that creates the missing object — not by editing a committed up.sql. That fix does not work, in any case. Migrations apply in timestamp order, so anything authored now sorts AFTER the file that failed and the object is still missing when it runs. Two estates hit it from opposite directions: - a chain whose FIRST migration needs a schema an out-of-band script creates (the third migration emits CREATE SCHEMA IF NOT EXISTS; the first predates it). Nothing in the chain could have created it. - a project where ANOTHER TOOL owns schema creation — drizzle-kit builds the tables, `.metaobjects/migrations/` holds later incremental patches. Following the printed remedy literally means hand-authoring every CREATE TABLE into the MetaObjects chain: duplicating a schema this project does not own, which is the opposite of what the agent context teaches two paragraphs into its own Principles. One message, assuming MetaObjects is the only schema authority and offering no third possibility. The remedy now names the fixes that exist: don't wire --replay when another tool owns creation; correct the migration in place if no database has applied it yet; or re-baseline from a live database. Immutability is stated as the CONDITION it is — a checksum guard on databases that already ran the file — rather than a blanket ban, because a migration nothing has applied is edited in place every day. The head of the chain gets the extra sentence that is only true there. Choosing correctly needs the POSITION, so `applyPending` now throws `MigrationApplyError` carrying the migration name, its index among the pending set and the pending count. The driver reports what the database refused and nothing about who asked, so `migrate apply-pending` gets the file name too. Gates: the error's identity and position in `migrate-ts`, and every claim in the message in `cli` — including that it never again prescribes a new migration. Both proved by breaking them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTcEKXTQMYt84fAjuw5A2M
1 parent 79f2c02 commit a7e2a2e

6 files changed

Lines changed: 214 additions & 10 deletions

File tree

‎server/typescript/packages/cli/src/commands/verify.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import {
1818
import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
1919
import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
2020
import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
21+
import { replayRemedy } from "../lib/replay-remedy.js";
2122
import { FileProvider } from "../lib/file-provider.js";
2223
import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
2324
import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
@@ -461,11 +462,7 @@ export async function verifyCommand(
461462
applied = await applyPending(engine.db, dir, { dryRun: false, dialect });
462463
} catch (err) {
463464
log.error(`meta verify --replay: ${(err as Error).message}`);
464-
log.error(
465-
`meta verify --replay: the committed chain does not apply to an empty database. ` +
466-
`Applied migrations are immutable, so fix this with a NEW migration that creates the ` +
467-
`missing object — not by editing a committed up.sql.`,
468-
);
465+
for (const line of replayRemedy(err)) log.error(`meta verify --replay: ${line}`);
469466
return 1;
470467
}
471468

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
import { MigrationApplyError } from "@metaobjectsdev/migrate-ts";
2+
3+
/**
4+
* What to tell someone whose committed chain will not apply to an empty database.
5+
*
6+
* The message this replaces prescribed ONE fix — *"fix this with a NEW migration that
7+
* creates the missing object"* — and it cannot work, in any case. Migrations apply in
8+
* timestamp order, so anything authored now sorts AFTER the migration that failed; the
9+
* object is still missing when that file runs. Two estates found it from opposite
10+
* directions and it is the same defect both times:
11+
*
12+
* - a chain whose FIRST migration needs a schema an out-of-band script creates (the third
13+
* migration emits `CREATE SCHEMA IF NOT EXISTS`, the first predates it). A new migration
14+
* sorts last, after the one that needs the schema.
15+
* - a project where **another tool owns schema creation** — drizzle-kit's chain builds the
16+
* tables, `.metaobjects/migrations/` holds later incremental patches. Following the
17+
* printed remedy literally means hand-authoring every `CREATE TABLE` into the MetaObjects
18+
* chain, i.e. duplicating a schema this project does not own, which is the opposite of
19+
* what the agent context teaches two paragraphs into its own Principles.
20+
*
21+
* The old message assumed MetaObjects is the only schema authority and offered no third
22+
* possibility. These name the fixes that exist, and the head-of-chain case gets the extra
23+
* sentence that is only true there: nothing in this chain could have created what the
24+
* first migration needs, so the base schema comes from outside it.
25+
*
26+
* "Applied migrations are immutable" is kept, because it is true and it is the reason the
27+
* obvious fix is not offered first — but it is stated as the CONDITION it actually is
28+
* (a checksum guard on databases that already ran the file), not as a blanket ban, because
29+
* a migration no database has applied yet is edited in place every day.
30+
*/
31+
export function replayRemedy(err: unknown): string[] {
32+
const applyErr = err instanceof MigrationApplyError ? err : undefined;
33+
const head = applyErr !== undefined && applyErr.index === 0;
34+
const which =
35+
applyErr === undefined
36+
? "the committed chain does not apply to an empty database."
37+
: `'${applyErr.migration}' (migration ${applyErr.index + 1} of ${applyErr.pendingCount}) ` +
38+
`does not apply to an empty database.`;
39+
40+
const out = [which];
41+
if (head) {
42+
out.push(
43+
"It is the FIRST migration in the chain, so nothing here could have created what it " +
44+
"needs — this chain has never built a database from empty, and its base schema comes " +
45+
"from outside it.",
46+
);
47+
}
48+
out.push(
49+
"A NEW migration cannot fix this: migrations apply in timestamp order, so anything you " +
50+
"author now sorts after the file that failed.",
51+
);
52+
out.push(
53+
"The fixes that do work: if another tool or an out-of-band script owns schema creation " +
54+
"for this project, --replay asserts a property this chain does not have — don't wire " +
55+
"it. Otherwise correct the migration in place if no database has applied it yet " +
56+
"(the ledger's checksum guard is what stops you once one has), or re-baseline from a " +
57+
"live database with `meta migrate baseline --from-db`.",
58+
);
59+
return out;
60+
}
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
// F58 + F71 — `verify --replay`'s remedy line prescribed something that cannot work.
2+
//
3+
// The old line was unconditional: "fix this with a NEW migration that creates the missing
4+
// object". Migrations apply in timestamp order, so a new one sorts AFTER the file that
5+
// failed and the object is still missing when it runs — the advice is wrong in every case,
6+
// and worse when another tool owns schema creation, where following it literally means
7+
// duplicating a schema this project does not own.
8+
//
9+
// These assert the CLAIMS in the message, because a remedy that names a fix which cannot
10+
// apply is the whole defect. The failure is silent by construction: nothing about a
11+
// wrong-but-confident sentence turns an exit code red.
12+
13+
import { describe, test, expect } from "bun:test";
14+
import { MigrationApplyError } from "@metaobjectsdev/migrate-ts";
15+
import { replayRemedy } from "../src/lib/replay-remedy.js";
16+
17+
const text = (err: unknown): string => replayRemedy(err).join(" ");
18+
19+
describe("replayRemedy", () => {
20+
test("never prescribes a new migration — the fix that cannot work", () => {
21+
for (const err of [
22+
new MigrationApplyError("20260521012518-init", 0, 3, new Error("no such table: purchases")),
23+
new MigrationApplyError("20260812090000-add-fk", 2, 3, new Error("no such table: purchases")),
24+
new Error("no such table: purchases"),
25+
]) {
26+
const msg = text(err);
27+
expect(msg).not.toMatch(/fix this with a NEW migration/i);
28+
expect(msg).toContain("A NEW migration cannot fix this");
29+
}
30+
});
31+
32+
test("names the failing migration and its position in the chain", () => {
33+
const msg = text(new MigrationApplyError("20260812090000-add-fk", 2, 5, new Error("boom")));
34+
expect(msg).toContain("'20260812090000-add-fk'");
35+
expect(msg).toContain("migration 3 of 5");
36+
});
37+
38+
test("F71 — the head of the chain gets the sentence that is only true there", () => {
39+
const msg = text(new MigrationApplyError("20260521012518-init", 0, 3, new Error("boom")));
40+
expect(msg).toContain("FIRST migration in the chain");
41+
expect(msg).toContain("base schema comes from outside it");
42+
});
43+
44+
test("a later migration does NOT get the head-of-chain sentence", () => {
45+
const msg = text(new MigrationApplyError("20260812090000-add-fk", 2, 3, new Error("boom")));
46+
expect(msg).not.toContain("FIRST migration in the chain");
47+
});
48+
49+
test("F58 — offers the possibility that another tool owns schema creation", () => {
50+
// The estate that produced this has drizzle-kit building the tables and
51+
// `.metaobjects/migrations/` holding later patches. The old message had no third
52+
// option: it assumed MetaObjects is the only schema authority.
53+
const msg = text(new MigrationApplyError("20260521012518-init", 0, 3, new Error("boom")));
54+
expect(msg).toMatch(/another tool or an out-of-band script owns schema creation/i);
55+
expect(msg).toContain("don't wire");
56+
});
57+
58+
test("immutability is stated as the condition it is, not a blanket ban", () => {
59+
// A migration no database has applied yet is edited in place every day; the checksum
60+
// guard is what stops you once one has. The old line forbade the edit outright.
61+
const msg = text(new MigrationApplyError("20260521012518-init", 0, 1, new Error("boom")));
62+
expect(msg).toContain("if no database has applied it yet");
63+
expect(msg).toContain("baseline --from-db");
64+
});
65+
66+
test("degrades to the un-positioned form for an error that is not a MigrationApplyError", () => {
67+
// applyPending can fail before it reaches any file (the checksum tamper guard, a
68+
// ledger failure). The remedy must still be right, just less specific.
69+
const msg = text(new Error("ledger unavailable"));
70+
expect(msg).toContain("the committed chain does not apply to an empty database");
71+
expect(msg).not.toContain("FIRST migration in the chain");
72+
});
73+
});

‎server/typescript/packages/migrate-ts/src/apply/apply.ts‎

Lines changed: 37 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,29 @@ export interface ApplyPendingResult {
4545
applied: string[];
4646
}
4747

48+
/**
49+
* A committed migration's SQL failed. Carries WHICH one, because the driver's error says
50+
* only what the database refused ("no such table: purchases") and never which file asked.
51+
*
52+
* The position matters to callers, not just the name: `--replay` prescribes a different
53+
* remedy at the HEAD of the chain, where nothing earlier in this chain could have created
54+
* what the migration needs, so the base schema must come from outside it.
55+
*/
56+
export class MigrationApplyError extends Error {
57+
constructor(
58+
/** `<timestamp>-<slug>` directory name of the migration that failed. */
59+
readonly migration: string,
60+
/** 0-based position among the PENDING migrations this run attempted. */
61+
readonly index: number,
62+
/** How many migrations were pending when the run started. */
63+
readonly pendingCount: number,
64+
override readonly cause: unknown,
65+
) {
66+
super(`migration '${migration}' failed to apply: ${(cause as Error)?.message ?? String(cause)}`);
67+
this.name = "MigrationApplyError";
68+
}
69+
}
70+
4871
interface DiscoveredMigration {
4972
/** `<timestamp>-<slug>` directory name — stable id + sort key. */
5073
name: string;
@@ -106,14 +129,24 @@ export async function applyPending(
106129
}
107130

108131
const applied: string[] = [];
109-
for (const m of pending) {
132+
for (const [i, m] of pending.entries()) {
110133
const text = await readFile(m.upPath, "utf8");
111134
const checksum = checksumOf(text);
112135
// Run the file's SQL + the ledger insert in ONE transaction. A failure
113136
// rolls the whole file back (unrecorded) and propagates — stopping the run.
114-
await runSqlFileWithLedgerMutation(db, text, (trx) =>
115-
recordApplied(trx, m.name, checksum, dialect, ledger),
116-
);
137+
//
138+
// Wrapped so the failure names the FILE. The driver reports what the database
139+
// refused and nothing about who asked, which left every caller — `apply-pending`
140+
// and `verify --replay` alike — printing "no such table: purchases" over a
141+
// directory of migrations, and `--replay` guessing at a remedy it could not
142+
// have chosen correctly without knowing the position.
143+
try {
144+
await runSqlFileWithLedgerMutation(db, text, (trx) =>
145+
recordApplied(trx, m.name, checksum, dialect, ledger),
146+
);
147+
} catch (err) {
148+
throw new MigrationApplyError(m.name, i, pending.length, err);
149+
}
117150
applied.push(m.name);
118151
}
119152

‎server/typescript/packages/migrate-ts/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ export {
104104
} from "./apply/ledger.js";
105105
export {
106106
applyPending,
107+
MigrationApplyError,
107108
rollbackTo,
108109
type ApplyPendingOptions,
109110
type ApplyPendingResult,

‎server/typescript/packages/migrate-ts/test/unit/apply.test.ts‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
44
import { join } from "node:path";
55
import { Kysely, sql } from "kysely";
66
import { LibsqlDialect } from "@libsql/kysely-libsql";
7-
import { applyPending } from "../../src/apply/apply.js";
7+
import { applyPending, MigrationApplyError } from "../../src/apply/apply.js";
88
import { ensureLedger, appliedNames } from "../../src/apply/ledger.js";
99

1010
function writeMig(root: string, name: string, up: string): void {
@@ -38,6 +38,46 @@ describe("applyPending — ordered, transactional, ledger-tracked", () => {
3838
rmSync(tmp, { recursive: true, force: true });
3939
});
4040

41+
// F58/F71 — the failure has to name WHICH file, and where it sits in the chain.
42+
//
43+
// The driver reports what the database refused ("no such table: x") and nothing about
44+
// who asked, so every caller printed that over a directory of migrations. `verify
45+
// --replay` then guessed at a remedy, and the guess was wrong: it prescribed a NEW
46+
// migration, which sorts AFTER the file that failed and cannot create what that file
47+
// needs. Choosing correctly requires the POSITION, which is why it rides on the error
48+
// rather than being re-derived by each caller.
49+
test("a failing migration throws MigrationApplyError naming the file and its position", async () => {
50+
writeMig(migDir, "20260101000000-a", "CREATE TABLE a (id INTEGER PRIMARY KEY);");
51+
writeMig(migDir, "20260102000000-b", "INSERT INTO nonexistent VALUES (1);");
52+
writeMig(migDir, "20260103000000-c", "CREATE TABLE c (id INTEGER PRIMARY KEY);");
53+
await ensureLedger(db);
54+
55+
const err = await applyPending(db, migDir, { dryRun: false }).catch((e: unknown) => e);
56+
expect(err).toBeInstanceOf(MigrationApplyError);
57+
const applyErr = err as MigrationApplyError;
58+
expect(applyErr.migration).toBe("20260102000000-b");
59+
expect(applyErr.index).toBe(1);
60+
expect(applyErr.pendingCount).toBe(3);
61+
// The driver's own text survives — the message adds the file, it does not replace
62+
// what the database said.
63+
expect(applyErr.message).toContain("20260102000000-b");
64+
expect(applyErr.message).toMatch(/nonexistent/);
65+
// The run stopped there: 'a' applied, 'c' never ran.
66+
expect(await tableExists(db, "a")).toBe(true);
67+
expect(await tableExists(db, "c")).toBe(false);
68+
});
69+
70+
test("index is 0 when the FIRST migration in the chain fails — the case with its own remedy", async () => {
71+
writeMig(migDir, "20260101000000-a", "INSERT INTO nonexistent VALUES (1);");
72+
writeMig(migDir, "20260102000000-b", "CREATE TABLE b (id INTEGER PRIMARY KEY);");
73+
await ensureLedger(db);
74+
75+
const err = (await applyPending(db, migDir, { dryRun: false })
76+
.catch((e: unknown) => e)) as MigrationApplyError;
77+
expect(err.index).toBe(0);
78+
expect(err.migration).toBe("20260101000000-a");
79+
});
80+
4181
test("runs only pending files, in order, and records them", async () => {
4282
writeMig(migDir, "20260101000000-a", "CREATE TABLE a (id INTEGER PRIMARY KEY);");
4383
writeMig(migDir, "20260102000000-b", "CREATE TABLE b (id INTEGER PRIMARY KEY);");

0 commit comments

Comments
 (0)