Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Fail verify when a migration would take every page it touches out of search (#9192) (#9488)

Garry Tan90f9eb6be046
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 51bc58fade..7b83faaa27 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -435,7 +435,7 @@ to a sibling module. Every row also adds a behavior test of its own; the
| Change kind | Create or edit | Registry to touch | Regenerate | Smallest test |
|---|---|---|---|---|
| Storage method (a `BrainEngine` method) | The signature in `src/core/engine.ts`; the SQL once in `src/core/engine-sql/<domain>.ts`; a one-line delegation in `src/core/pglite-engine.ts` and `src/core/postgres-engine.ts` (copy a sibling read's shape, e.g. `getAllSlugs`) | `scripts/module-size-limits.tsv`: raise the `engine.ts`, `pglite-engine.ts` and `postgres-engine.ts` ceilings by the lines you added. A new SQL-bearing engine member fails `check:engine-sql-ratchet`; `scripts/engine-sql-baseline.tsv` rows only shrink | Nothing | `test/engine-sql-<domain>-<topic>.test.ts` on PGLite (seed with `engine.putPage(slug, { type, title, compiled_truth })`; the default source id is `'default'`); for a write, a case in `test/helpers/engine-sql-rollback-cases.ts`, run by `bun test test/engine-sql-transaction.test.ts` |
-| Schema migration | `bun run new:migration <snake_name>` writes `src/core/schema-migrations/v<NNN>-<name>.ts`; fresh-install DDL in `src/schema.sql` (or the TS fragment its region banner names); a forward-reference probe in `src/core/engine-sql/bootstrap.ts` only when the schema blob references a column older brains lack | `src/core/schema-migrations/registry.generated.ts` (generated) | `new:migration` already regenerates the registry; rerun `bun run build:schema-migrations` only after editing or renaming a migration file. `bun run build:schema` whenever `schema.sql` or a fragment changed. Every object a fresh install should have goes in `schema.sql` (or its fragment) as well as the migration; grep `src/schema.sql` first so you do not add a second index on the same columns | `bun test test/scripts/build-schema-migrations.test.ts test/migrate.test.ts`, then `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test test/migrations-golden.test.ts test/schema-catalog-golden.test.ts` and review the golden diff |
+| Schema migration | `bun run new:migration <snake_name>` writes `src/core/schema-migrations/v<NNN>-<name>.ts`; fresh-install DDL in `src/schema.sql` (or the TS fragment its region banner names); a forward-reference probe in `src/core/engine-sql/bootstrap.ts` only when the schema blob references a column older brains lack | `src/core/schema-migrations/registry.generated.ts` (generated) | `new:migration` already regenerates the registry; rerun `bun run build:schema-migrations` only after editing or renaming a migration file. `bun run build:schema` whenever `schema.sql` or a fragment changed. Every object a fresh install should have goes in `schema.sql` (or its fragment) as well as the migration; grep `src/schema.sql` first so you do not add a second index on the same columns. A migration that updates a page column the revision trigger watches, or writes `tags`, empties search for every page it touches until the rebuild (#9192): `bun run check:migration-projection` fails until `scripts/migration-projection-baseline.tsv` says how search keeps answering | `bun test test/scripts/build-schema-migrations.test.ts test/migrate.test.ts`, then `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test test/migrations-golden.test.ts test/schema-catalog-golden.test.ts` and review the golden diff |
| Doctor check | A `{ name, emits, run }` entry in the topic module under `src/commands/doctor/checks/` (a new topic gets a new file): `name` and `emits` are string literals, and `run` names a top-level `async function run<X>(ctx): Promise<Check[]>` in the same file that builds `const checks: Check[] = []` and calls `checks.push({ name: '<literal>', ... })` directly (the `emits` test walks that AST; helpers and returned array literals are invisible to it) | `DOCTOR_CHECK_REGISTRY` in `src/commands/doctor/registry.ts` (position = output order; `test/doctor-registry-golden.test.ts` pins `dangling_aliases` as the last check, so insert before `searchModeEntry`) and every emitted name in `src/core/doctor-categories.ts` | The doctor goldens, deliberately: `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test test/doctor-registry-golden.test.ts test/doctor-json-golden.test.ts` | `test/doctor-<name>.test.ts` on in-memory PGLite (copy `test/doctor-slug-collisions.test.ts`), plus `bun test test/doctor-registry.test.ts` |
| CLI-only command | The implementation in `src/commands/<name>.ts`; the dispatch module `src/cli/commands/<name>.ts`; a help line in `printHelp` (`src/cli.ts`, so raise its `module-size-limits.tsv` ceiling by one) | A record in `CLI_COMMANDS` (`src/cli/command-table.ts`): `phase: 'pre-connect'` when the command never touches the database, `'post-connect'` when its `run(engine, args, ctx)` needs an engine; `thinClient: 'none'` unless remote brains must refuse it (`'refuse'`, or `'route-then-refuse'` for subcommand routing); `selfHelp: true` when the command has flags or subcommands (its `run` then prints its own `--help`); optional `skipStartupHooks`; `load: () => import('<literal>')` | `bun run build:flag-registry`; the CLI goldens, deliberately: `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test test/cli-goldens.test.ts test/cli-dispatch-phase.test.ts test/cli-dispatch-thin-client.test.ts` | `test/<name>.test.ts` spawning `bun src/cli.ts <name>` and asserting output and exit code, plus `bun test test/cli-command-table.test.ts test/cli-flag-validation.test.ts` |
| HTTP route (`gbrain serve --http`) | The route inside `mount<Area>(app, ctx)` in `src/commands/serve-http-<area>.ts` (`/admin/api/*` goes in `serve-http-admin-api.ts`, `/mcp` in `serve-http-mcp.ts`, OAuth in `serve-http-oauth.ts`); a new area is a new module plus one mount call in `buildServeHttpApp` (`src/commands/serve-http.ts`). An `/admin` route takes `ctx.requireAdmin` before its handler | None for a route in an existing area; a new area adds its mount call in `buildServeHttpApp` (order matters) | The route goldens, deliberately: `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test test/serve-http-route-golden.test.ts test/serve-http-route-runtime-golden.test.ts` | A behavior test (`test/serve-http-<area>-<route>.test.ts`: mount the area on a bare `express()` app with a stub ctx; `mountAdminApi` reads `requireAdmin`, `sseClients` and `mcpResourceUrl` at mount time) plus `bun test test/serve-http-admin-route-guard.test.ts`, which finds the new route by itself |
diff --git a/changelog.d/capy-migration-projection-guard-9192.md b/changelog.d/capy-migration-projection-guard-9192.md
new file mode 100644
index 0000000000..90c1df99e6
--- /dev/null
+++ b/changelog.d/capy-migration-projection-guard-9192.md
@@ -0,0 +1,6 @@
+**`bun run verify` now fails when a schema migration would take every page it touches out of search until `gbrain projections drain` rebuilds them, unless the migration is listed with the reason search keeps answering (#9192).**
+
+### For contributors
+- `bun run check:migration-projection`, part of `bun run verify`, fails on a migration whose SQL, or whose handler's own source, updates a page column the page revision trigger watches (`UPDATE pages ... SET` or an `INSERT INTO pages ... DO UPDATE SET` upsert) or writes `tags`. The dollar-quoted body of a `CREATE FUNCTION` or `CREATE PROCEDURE` is skipped; a `DO` block is read.
+- A migration that has to do this goes in `scripts/migration-projection-baseline.tsv` with the reason search keeps answering, or why it cannot. v153 and v189 are listed. A listed migration that no longer matches fails as stale.
+- The guard cannot see a handler that changes pages through helpers or functions defined elsewhere, SQL assembled at run time, or writes made by a database function the migration calls. Review those by hand.
diff --git a/package.json b/package.json
index fd009b7736..97d88e49f9 100644
--- a/package.json
+++ b/package.json
@@ -178,6 +178,7 @@
"check:chunk-visibility": "bun scripts/check-chunk-visibility.ts",
"check:page-body-readers": "bun scripts/check-page-body-readers.ts",
"check:engine-sql-dynamic": "bun scripts/check-engine-sql-dynamic.ts",
+ "check:migration-projection": "bun scripts/check-migration-projection.ts",
"check:remote-privacy-reads": "bun scripts/check-remote-privacy-reads.ts",
"check:engine-sql-brands": "bun scripts/check-engine-sql-brands.ts",
"check:sync-run-state": "bun scripts/check-sync-run-state.ts",
diff --git a/scripts/check-migration-projection.ts b/scripts/check-migration-projection.ts
new file mode 100644
index 0000000000..52c3b02d1f
--- /dev/null
+++ b/scripts/check-migration-projection.ts
@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+/**
+ * Migration search-index guard (#9192).
+ *
+ * A schema migration that bulk-changes what the page revision trigger watches
+ * clears every touched page's text projection, so those pages leave keyword and
+ * vector search until 'gbrain projections drain' rebuilds them. On a large brain
+ * reached over the network that is hours of empty search (v153 did exactly this).
+ * This guard loads the migration registry and fails on a migration whose SQL, or
+ * whose handler's own source text, does either of:
+ *
+ * 1. 'UPDATE pages ... SET' or 'INSERT INTO pages ... DO UPDATE SET' assigning
+ * a watched column: source_id, slug, type, page_kind, title, compiled_truth,
+ * timeline, frontmatter, deleted_at, body_generation, knowledge_revision or
+ * text_projection_revision;
+ * 2. 'INSERT INTO tags', 'UPDATE tags' or 'DELETE FROM tags' (the tags trigger
+ * advances the page revision).
+ *
+ * The dollar-quoted body of a CREATE FUNCTION or CREATE PROCEDURE is skipped, since
+ * defining a trigger function changes no row; a DO block is read.
+ *
+ * Unless scripts/migration-projection-baseline.tsv lists it with the reason
+ * search keeps answering, or why it cannot. A listed migration that no longer
+ * matches (or no longer exists) fails as stale.
+ *
+ * What it cannot see: a handler that changes pages through engine helpers or
+ * functions defined elsewhere (only the handler's own source text is read), SQL
+ * assembled at run time from pieces, and writes through a database function the
+ * migration calls. Review those by hand.
+ *
+ * Seam: GBRAIN_GUARD_ROOT (fixture tree root).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.env.GBRAIN_GUARD_ROOT ?? join(import.meta.dir, '..');
+const REGISTRY = 'src/core/schema-migrations/registry.generated.ts';
+const BASELINE = 'scripts/migration-projection-baseline.tsv';
+const WATCHED = new Set(['source_id', 'slug', 'type', 'page_kind', 'title', 'compiled_truth', 'timeline', 'frontmatter',
+ 'deleted_at', 'body_generation', 'knowledge_revision', 'text_projection_revision']);
+
+type Migration = { version: number; name: string; sql?: string; sqlFor?: { postgres?: string; pglite?: string }; handler?: unknown };
+
+/** Drops line comments outside quotes and the dollar-quoted bodies of CREATE FUNCTION / PROCEDURE: defining a trigger function changes no row (a DO block still counts). */
+function stripComments(text: string): string {
+ let out = '';
+ let quote: string | null = null;
+ for (let i = 0; i < text.length; i++) {
+ const c = text[i]!;
+ if (quote) { if (c === quote) quote = null; out += c; continue; }
+ if (c === "'" || c === '"') { quote = c; out += c; continue; }
+ if (c === '-' && text[i + 1] === '-') { while (i < text.length && text[i] !== '\n') i++; out += ' \n'; continue; }
+ out += c;
+ }
+ return out.replace(/\bCREATE\s+(?:OR\s+REPLACE\s+)?(?:FUNCTION|PROCEDURE)\b[^;]*?(\$\w*\$)[\s\S]*?\1/gi, ' ');
+}
+
+/** The SET list after an 'UPDATE pages [alias] SET', cut at the first top-level WHERE, FROM, RETURNING or ';'. */
+function setList(text: string, from: number): string {
+ let depth = 0;
+ let quote: string | null = null;
+ for (let i = from; i < text.length; i++) {
+ const c = text[i]!;
+ if (quote) { if (c === quote) quote = null; continue; }
+ if (c === "'" || c === '"' || c === '\x60') { quote = c; continue; }
+ if (c === '(') depth++;
+ else if (c === ')') { if (depth === 0) return text.slice(from, i); depth--; }
+ else if (depth === 0 && (c === ';' || /^(WHERE|FROM|RETURNING)\b/i.test(text.slice(i, i + 9)) && /\W/.test(text[i - 1] ?? ' '))) return text.slice(from, i);
+ }
+ return text.slice(from);
+}
+
+/** Columns a SET list assigns: each top-level item's 'col =' or '(col, col) ='. */
+function assigned(list: string): string[] {
+ const items: string[] = [];
+ let depth = 0;
+ let quote: string | null = null;
+ let start = 0;
+ for (let i = 0; i < list.length; i++) {
+ const c = list[i]!;
+ if (quote) { if (c === quote) quote = null; continue; }
+ if (c === "'" || c === '"' || c === '\x60') { quote = c; continue; }
+ if (c === '(') depth++;
+ else if (c === ')') depth--;
+ else if (c === ',' && depth === 0) { items.push(list.slice(start, i)); start = i + 1; }
+ }
+ items.push(list.slice(start));
+ const cols: string[] = [];
+ for (const item of items) {
+ const m = /^\s*(\([^)]*\)|"?\w+"?)\s*(?:\[[^\]]*\]\s*|\.\s*"?\w+"?\s*)*=/.exec(item);
+ if (m) for (const col of m[1]!.replace(/[()"]/g, '').split(',')) cols.push(col.trim().toLowerCase());
+ }
+ return cols;
+}
+
+function findings(text: string): string[] {
+ const out: string[] = [];
+ const body = stripComments(text);
+ const pages = String.raw`(?:"?public"?\.)?(?:"pages"|pages\b)`;
+ const update = new RegExp(String.raw`\bUPDATE\s+(?:ONLY\s+)?${pages}(?:\s+(?:AS\s+)?(?!SET\b)\w+)?\s+SET\b|\bINSERT\s+INTO\s+${pages}[^;]*?\bDO\s+UPDATE\s+SET\b`, 'gi');
+ for (let m: RegExpExecArray | null; (m = update.exec(body));) {
+ const hit = assigned(setList(body, m.index + m[0].length)).filter(col => WATCHED.has(col));
+ if (hit.length) out.push('UPDATE pages SET ' + [...new Set(hit)].join(', '));
+ }
+ const tags = /\b(INSERT\s+INTO|DELETE\s+FROM|UPDATE)\s+(?:public\.)?tags\b/gi;
+ for (let m: RegExpExecArray | null; (m = tags.exec(body));) out.push(m[1]!.replace(/\s+/g, ' ').toUpperCase() + ' tags');
+ return [...new Set(out)];
+}
+
+const registryPath = join(ROOT, REGISTRY);
+if (!existsSync(registryPath)) {
+ console.log('GBRAIN_CHECK_SKIPPED: no migration registry at ' + REGISTRY);
+ process.exit(0);
+}
+const { MIGRATIONS } = await import(registryPath) as { MIGRATIONS: Migration[] };
+const baseline = new Map<number, { name: string; reason: string }>();
+const baselinePath = join(ROOT, BASELINE);
+if (existsSync(baselinePath)) {
+ for (const line of readFileSync(baselinePath, 'utf8').split('\n')) {
+ if (!line.trim() || line.startsWith('#')) continue;
+ const [version, name, reason] = line.split('\t');
+ if (!reason?.trim()) { console.error('check-migration-projection: ' + BASELINE + ' row without a reason: ' + line); process.exit(1); }
+ baseline.set(Number(version), { name: name!, reason });
+ }
+}
+
+const violations: string[] = [];
+const matched = new Set<number>();
+for (const m of MIGRATIONS) {
+ const texts = [m.sql ?? '', m.sqlFor?.postgres ?? '', m.sqlFor?.pglite ?? '', typeof m.handler === 'function' ? m.handler.toString() : ''];
+ const hits = [...new Set(texts.flatMap(findings))];
+ if (!hits.length) continue;
+ const row = baseline.get(m.version);
+ if (row && row.name === m.name) { matched.add(m.version); continue; }
+ violations.push('v' + m.version + ' ' + m.name + ': ' + hits.join('; '));
+}
+for (const [version, row] of baseline) {
+ if (!matched.has(version)) violations.push('stale baseline row v' + version + ' ' + row.name + ': that migration no longer changes what the page revision trigger watches (or is gone); delete the row');
+}
+if (violations.length) {
+ for (const v of violations) console.error(' ' + v);
+ console.error('check-migration-projection: ' + violations.length + ' violation(s)');
+ console.error('A migration that changes what the page revision trigger watches clears those pages\' text projection: they leave search until');
+ console.error('gbrain projections drain rebuilds them (#9192). Keep it out of the migration, limit it to pages that were not searchable,');
+ console.error('or add a row to ' + BASELINE + ' saying how search keeps answering (or why it cannot).');
+ process.exit(1);
+}
+console.log('check-migration-projection: ok (' + MIGRATIONS.length + ' migrations, ' + matched.size + ' baseline rows)');
diff --git a/scripts/guards-manifest.tsv b/scripts/guards-manifest.tsv
index 103efe0571..65ebf89247 100644
--- a/scripts/guards-manifest.tsv
+++ b/scripts/guards-manifest.tsv
@@ -75,6 +75,7 @@ check-engine-sql-ratchet.ts scanner yes goal (a) engine-sql ratchet (TS AST): SQ
check-core-world-reads.ts scanner yes GBRA-248 W1 embeddable-core ratchet (TS AST): per-file counts in src/core of loadConfig calls, process.env/Bun.env, fs imports, module-level mutable collections, spawn-wrapper/child_process imports, process-wide hooks and AsyncLocalStorage stores; rises and stale rows fail; baseline scripts/core-world-reads-baseline.tsv; --prune lowers stale rows only
check-page-body-readers.ts scanner yes Wave B segmented storage (spec 1.5 layer 4, TS AST): src units reading .compiled_truth/.timeline, SQL literals naming the body columns or p.* from pages, and whole-body calls (serializePageToMarkdown, putPage, ...) need a baseline row with an action code; stale/duplicate/malformed rows fail; boundedBodyPrefixSql allowed by name; baseline scripts/page-body-readers-baseline.tsv; --prune drops stale rows only
check-engine-sql-dynamic.ts scanner yes CQ3/EO17 dynamic SQL in src/core/engine-sql/** (TS AST; fragment.ts exempt as the renderer): trustedSql args and composed .query/.unsafe/.executeRaw/executeRawJsonb SQL splice only literals, as-const/allowlisted constants, VETTED_BUILDERS calls or Number.isFinite-checked numbers; no $<digit> in composed strings; no expanded IN lists
+check-migration-projection.ts scanner yes #9192: a schema migration whose SQL or handler source updates a page column the revision trigger watches, or writes tags, fails unless scripts/migration-projection-baseline.tsv lists it with a reason (stale rows fail); CREATE FUNCTION bodies skipped, DO blocks read; bad-tags/bad-tuple/bad-do/bad-stale variants
check-remote-privacy-reads.ts scanner yes GBRA-218 (TS AST): the remote-privacy relaxations (GBRAIN_REMOTE_PRIVATE_PAGES, search.remote_private_pages / REMOTE_PRIVATE_PAGES_KEY) are read only in src/core/search/private-visibility.ts, whose resolver keeps the member-access part mandatory; name lists in array literals and import specifiers are not reads
check-engine-sql-brands.ts scanner yes EO4/AR2 RLS read brands (TS AST + text): brand-key mentions outside engine-sql/brands.ts; casts onto ScopedRead/LegacyUnscopedRead or `as unknown as` executor types in src/; unscopedExecutor/LegacyUnscopedRead/scopedRead imports outside their allowlists, src/core/ops/** always denied
check-sync-run-state.ts scanner yes A17 (W4 sync): SyncRun mutable fields (non-readonly members of interface SyncRun) are never destructured or aliased into locals under src/commands/sync/; @checkpoint fields are assigned only in sync-run.ts (single owner); fixtures cover destructuring, aliasing, a parameter pattern in a nested dir, and an out-of-owner checkpoint write
diff --git a/scripts/migration-projection-baseline.tsv b/scripts/migration-projection-baseline.tsv
new file mode 100644
index 0000000000..6cfa0a544c
--- /dev/null
+++ b/scripts/migration-projection-baseline.tsv
@@ -0,0 +1,4 @@
+# Migrations allowed to change what the page revision trigger watches (scripts/check-migration-projection.ts, #9192).
+# Each row: version<TAB>name<TAB>how search keeps answering, or why it cannot. A row whose migration no longer matches fails as stale.
+153 verified_text_projection_activation Assigns a revision only to pages that have none, then marks every page whose pre-upgrade chunks hold nothing the rebuild would remove as served from that index, so search keeps answering; pages with a facts or takes fence, private-key text or a quarantine key, images and pages indexed before the safe-chunk fence wait for gbrain projections drain (#9192).
+189 pages_credential_projection_pending Withholds on purpose only pages whose body carries a private-key marker: their old chunks can hold key text the credential-safe projection removes, so they must leave search until rebuilt.
diff --git a/scripts/run-verify-parallel.sh b/scripts/run-verify-parallel.sh
index 90de6cb529..78d1f886aa 100755
--- a/scripts/run-verify-parallel.sh
+++ b/scripts/run-verify-parallel.sh
@@ -220,6 +220,8 @@ CHECKS=(
# CQ3 / EO17 (refactor wave 1): engine-sql splices only constant text, no
# composed $n, no expanded IN lists.
"check:engine-sql-dynamic"
+ # #9192: a migration that changes what the page revision trigger watches empties search until the rebuild.
+ "check:migration-projection"
# GBRA-218: the remote-privacy relaxations are read only in private-visibility.ts.
"check:remote-privacy-reads"
# EO4 (refactor wave 1): RLS read brands stay unforgeable; brand factories
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-atomic/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad-atomic/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..49c3df870e
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-atomic/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'atomic_then_do', sql: 'CREATE FUNCTION f() RETURNS int LANGUAGE sql BEGIN ATOMIC SELECT 1; END; DO $$ BEGIN UPDATE pages SET title = lower(title); END $$;' },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-comment-quote/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad-comment-quote/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..dc6f62c596
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-comment-quote/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'quoted_dashes', sql: "SELECT '--x'; UPDATE pages SET slug = lower(slug);" },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-do/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad-do/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..47dc19a042
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-do/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'do_block', sql: 'DO $$ BEGIN UPDATE pages SET frontmatter = frontmatter || \'{}\'::jsonb; END $$;' },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-quoted-table/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad-quoted-table/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..dc64236621
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-quoted-table/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'quoted_table', sql: 'UPDATE "pages" SET title = lower(title);' },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-stale/scripts/migration-projection-baseline.tsv b/test/fixtures/guards/check-migration-projection.ts/bad-stale/scripts/migration-projection-baseline.tsv
new file mode 100644
index 0000000000..35ff1ec4e6
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-stale/scripts/migration-projection-baseline.tsv
@@ -0,0 +1 @@
+1 add_column Fixture: stale row.
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-stale/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad-stale/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..6924813b87
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-stale/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'add_column', sql: 'ALTER TABLE pages ADD COLUMN IF NOT EXISTS extra TEXT;' },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-subscript/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad-subscript/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..c0c613b9ad
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-subscript/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'frontmatter_key', sql: `UPDATE pages SET frontmatter['k'] = '"v"';` },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-tags/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad-tags/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..2c83bc1e50
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-tags/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'retag', sql: '', handler: async (engine: { executeRaw(sql: string): Promise<unknown> }) => { await engine.executeRaw('INSERT INTO tags(page_id, tag) SELECT id, \'x\' FROM pages'); } },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-tuple/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad-tuple/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..4d72f21ec6
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-tuple/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'move_body', sql: '', sqlFor: { postgres: 'UPDATE ONLY pages AS p SET (compiled_truth, timeline) = (p.timeline, p.compiled_truth);', pglite: 'SELECT 1;' } },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad-upsert/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad-upsert/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..7e5550a6f5
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad-upsert/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'seed_titles', sql: "INSERT INTO pages (slug, title) VALUES ('x', 'X') ON CONFLICT (slug) DO UPDATE SET title = EXCLUDED.title;" },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/bad/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/bad/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..1ea180c51f
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/bad/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,4 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'lower_titles', sql: 'UPDATE pages SET title = lower(title), chunker_version = 0;' },
+];
diff --git a/test/fixtures/guards/check-migration-projection.ts/good/scripts/migration-projection-baseline.tsv b/test/fixtures/guards/check-migration-projection.ts/good/scripts/migration-projection-baseline.tsv
new file mode 100644
index 0000000000..d89f79b810
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/good/scripts/migration-projection-baseline.tsv
@@ -0,0 +1 @@
+4 listed_reset Fixture: one page only.
diff --git a/test/fixtures/guards/check-migration-projection.ts/good/src/core/schema-migrations/registry.generated.ts b/test/fixtures/guards/check-migration-projection.ts/good/src/core/schema-migrations/registry.generated.ts
new file mode 100644
index 0000000000..b589aeb068
--- /dev/null
+++ b/test/fixtures/guards/check-migration-projection.ts/good/src/core/schema-migrations/registry.generated.ts
@@ -0,0 +1,9 @@
+// Fixture registry for scripts/check-migration-projection.ts.
+export const MIGRATIONS = [
+ { version: 1, name: 'add_column', sql: 'ALTER TABLE pages ADD COLUMN IF NOT EXISTS extra TEXT;' },
+ { version: 2, name: 'chunker_reset', sql: 'UPDATE pages SET chunker_version = 0 WHERE chunker_version IS NULL;' },
+ { version: 3, name: 'trigger_function', sql: `CREATE OR REPLACE FUNCTION f() RETURNS trigger LANGUAGE plpgsql AS $fn$
+ BEGIN UPDATE pages SET knowledge_revision = gen_random_uuid() WHERE id = NEW.page_id; RETURN NULL; END $fn$;` },
+ { version: 4, name: 'listed_reset', sql: 'UPDATE pages p SET text_projection_revision = NULL WHERE p.slug = \'x\';' },
+ { version: 5, name: 'comment_only', sql: '-- UPDATE pages SET title = lower(title)\nSELECT 1;' },
+];