Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* PGLite forward-reference bootstrap tests.
*
* Validates the contract of `PGLiteEngine#applyForwardReferenceBootstrap`:
* given a brain that lacks the schema-blob's forward-referenced state, the
* bootstrap adds enough state for PGLITE_SCHEMA_SQL to replay safely.
*
* The bootstrap covers the wedge incidents from issues
* #239/#266/#357/#366/#374/#375/#378/#396 — every gbrain release that added
* a column-with-index in the schema blob without a corresponding bootstrap
* triggered the same wedge family.
*
* Honest limitation: test 4 simulates a v20 brain by dropping known forward
* state from a fresh-LATEST instance. This is the same down-mutation pattern
* codex flagged as "weak simulation" — it can't simulate every possible
* historical state. Acceptable here because the bootstrap's contract is
* narrow ("given a brain that lacks the specific forward-references,
* initSchema produces a brain at LATEST"), and that contract is exactly
* what this test exercises.
*/
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { LATEST_VERSION } from '../src/core/migrate.ts';
import { readFactsEmbeddingDim } from '../src/core/embedding-dim-check.ts';
// Tier 3 opt-out: this file tests the cold init / bootstrap path explicitly.
// If GBRAIN_PGLITE_SNAPSHOT is set (ci:local sets it for unit shards), every
// PGlite would boot post-initSchema and these assertions ("0 tables on fresh
// install", "bootstrap converts pre-v0.18 brain to LATEST") would fail
// trivially. Unset for this file's tests and restore it afterwards: a CI
// shard runs hundreds of files in ONE bun process (scripts/test-shard.sh),
// so a module-scope delete would cold-boot every later engine in the shard
// (~3 s each, +350 s per shard; check:test-env-opt-ins pins this shape).
let savedSnapshot: string | undefined;
beforeAll(() => {
savedSnapshot = process.env.GBRAIN_PGLITE_SNAPSHOT;
delete process.env.GBRAIN_PGLITE_SNAPSHOT;
});
afterAll(() => {
if (savedSnapshot === undefined) delete process.env.GBRAIN_PGLITE_SNAPSHOT;
else process.env.GBRAIN_PGLITE_SNAPSHOT = savedSnapshot;
});
describe('PGLiteEngine#applyForwardReferenceBootstrap', () => {
test('fact embedding identity bootstrap repairs old and partial schemas without inventing provenance', async () => {
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const { dims } = await readFactsEmbeddingDim(engine);
const fact = await engine.insertFact({ fact: 'Synthetic bootstrap claim', source: 'synthetic', embedding: new Float32Array(dims!).fill(0.1) }, { source_id: 'default' });
const original = await engine.executeRaw('SELECT id,fact,embedding::text,embedded_at FROM facts WHERE id=$1', [fact.id]);
expect(original[0].embedding).not.toBeNull();
for (const missing of [['embedding_model', 'embedded_text_hash'], ['embedding_model'], ['embedded_text_hash']]) {
await engine.executeRaw("UPDATE facts SET embedding_model='synthetic:original',embedded_text_hash='synthetic-preserved-hash' WHERE id=$1", [fact.id]);
for (const column of missing) await engine.executeRaw(`ALTER TABLE facts DROP COLUMN ${column}`);
await engine.setConfig('version', '165');
await (engine as any).applyForwardReferenceBootstrap();
await (engine as any).applyForwardReferenceBootstrap();
expect(await engine.getConfig('version')).toBe('165');
expect(await engine.executeRaw(`SELECT column_name,data_type,is_nullable,column_default FROM information_schema.columns
WHERE table_schema='public' AND table_name='facts' AND column_name IN ('embedding_model','embedded_text_hash') ORDER BY column_name`)).toEqual([
{ column_name: 'embedded_text_hash', data_type: 'text', is_nullable: 'YES', column_default: null },
{ column_name: 'embedding_model', data_type: 'text', is_nullable: 'YES', column_default: null },
]);
const identity = [{
embedding_model: missing.includes('embedding_model') ? null : 'synthetic:original',
embedded_text_hash: missing.includes('embedded_text_hash') ? null : 'synthetic-preserved-hash',
}];
expect(await engine.executeRaw('SELECT embedding_model,embedded_text_hash FROM facts WHERE id=$1', [fact.id])).toEqual(identity);
for (const column of missing) await engine.executeRaw(`ALTER TABLE facts DROP COLUMN ${column}`);
await engine.initSchema();
await engine.initSchema();
expect(await engine.getConfig('version')).toBe(String(LATEST_VERSION));
expect(await engine.executeRaw('SELECT embedding_model,embedded_text_hash FROM facts WHERE id=$1', [fact.id])).toEqual(identity);
expect(await engine.executeRaw('SELECT id,fact,embedding::text,embedded_at FROM facts WHERE id=$1', [fact.id])).toEqual(original);
}
} finally {
await engine.disconnect();
}
}, 60_000);
test('queue bootstrap preserves legacy jobs without authorizing them and repairs either missing column', async () => {
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const db = (engine as any).db;
await db.exec(`
DROP TRIGGER IF EXISTS minion_queue_protocol ON minion_jobs;
ALTER TABLE minion_jobs DROP COLUMN submission_authority;
ALTER TABLE minion_jobs DROP COLUMN claim_generation;
INSERT INTO minion_jobs (name, status, data, attempts_made, attempts_started, delay_until)
VALUES ('sync', 'delayed', '{"sourceId":"default"}', 1, 2, '2026-09-01T00:00:00Z'),
('lint', 'completed', '{}', 0, 1, NULL);
`);
const original = await engine.executeRaw(`
SELECT id, name, status, data, attempts_made, attempts_started, delay_until FROM minion_jobs ORDER BY id
`);
await (engine as any).applyForwardReferenceBootstrap();
await (engine as any).applyForwardReferenceBootstrap();
const columns = await engine.executeRaw<{ column_name: string; is_nullable: string; column_default: string | null }>(`
SELECT column_name, is_nullable, column_default FROM information_schema.columns
WHERE table_name = 'minion_jobs' AND column_name IN ('submission_authority', 'claim_generation')
ORDER BY column_name
`);
expect(columns).toEqual([
{ column_name: 'claim_generation', is_nullable: 'NO', column_default: '0' },
{ column_name: 'submission_authority', is_nullable: 'YES', column_default: null },
]);
expect(await engine.executeRaw(`
SELECT id, name, status, data, attempts_made, attempts_started, delay_until FROM minion_jobs ORDER BY id
`)).toEqual(original);
expect(await engine.executeRaw(`
SELECT submission_authority, claim_generation::int FROM minion_jobs ORDER BY id
`)).toEqual([{ submission_authority: null, claim_generation: 0 }, { submission_authority: null, claim_generation: 0 }]);
// Partial upgrades must repair either field without overwriting the other.
await db.exec(`ALTER TABLE minion_jobs DROP COLUMN submission_authority;
UPDATE minion_jobs SET claim_generation = 7 WHERE name = 'lint';`);
await (engine as any).applyForwardReferenceBootstrap();
expect(await engine.executeRaw(`SELECT submission_authority, claim_generation::int FROM minion_jobs WHERE name = 'lint'`))
.toEqual([{ submission_authority: null, claim_generation: 7 }]);
await db.exec(`ALTER TABLE minion_jobs DROP COLUMN claim_generation;
UPDATE minion_jobs SET submission_authority = '{"version":1,"kind":"application"}' WHERE name = 'lint';`);
await (engine as any).applyForwardReferenceBootstrap();
expect(await engine.executeRaw(`SELECT submission_authority, claim_generation::int FROM minion_jobs WHERE name = 'lint'`))
.toEqual([{ submission_authority: { version: 1, kind: 'application' }, claim_generation: 0 }]);
} finally {
await engine.disconnect();
}
}, 30000);
test('no-op on fresh install (no pages or links table)', async () => {
const engine = new PGLiteEngine();
await engine.connect({});
try {
// Don't call initSchema — verify bootstrap alone does nothing on empty DB
await (engine as any).applyForwardReferenceBootstrap();
const { rows } = await (engine as any).db.query(`
SELECT COUNT(*)::int AS c FROM information_schema.tables
WHERE table_schema = 'public'
`);
expect(rows[0].c).toBe(0);
} finally {
await engine.disconnect();
}
}, 30000);
test('idempotent: calling twice produces same result', async () => {
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const db = (engine as any).db;
// Mutate to pre-v0.18 shape: drop source_id and the sources FK target
await db.exec(`
ALTER TABLE pages DROP CONSTRAINT IF EXISTS pages_source_slug_key;
ALTER TABLE pages ADD CONSTRAINT pages_slug_key UNIQUE (slug);
DROP INDEX IF EXISTS idx_pages_source_id;
-- The v230 trust generation trigger's WHEN reads pages.source_id, slug and
-- deleted_at; a pre-v0.18 brain predates it (v230 recreates it).
DROP TRIGGER IF EXISTS trust_generation_update ON pages;
-- The v283 folder-rule stamp trigger fires on UPDATE OF source_id; a
-- pre-v0.18 brain predates it too (v283 recreates it).
DROP TRIGGER IF EXISTS pages_access_stamp_folder_rules ON pages;
ALTER TABLE pages DROP COLUMN IF EXISTS source_id;
DROP TABLE IF EXISTS sources CASCADE;
`);
// First call: applies bootstrap
await (engine as any).applyForwardReferenceBootstrap();
// Second call: must not error, must not duplicate state
await (engine as any).applyForwardReferenceBootstrap();
const { rows: cols } = await db.query(`
SELECT column_name FROM information_schema.columns
WHERE table_name = 'pages' AND column_name = 'source_id'
`);
expect(cols).toHaveLength(1);
const { rows: src } = await db.query(`SELECT COUNT(*)::int AS c FROM sources`);
expect(src[0].c).toBe(1); // 'default' seed not duplicated
} finally {
await engine.disconnect();
}
}, 30000);
test('no-op on modern brain (source_id and links provenance already present)', async () => {
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const db = (engine as any).db;
const before = await db.query(`SELECT COUNT(*)::int AS c FROM sources`);
await (engine as any).applyForwardReferenceBootstrap();
const after = await db.query(`SELECT COUNT(*)::int AS c FROM sources`);
// Bootstrap probe should detect the brain is modern and skip the seed insert
expect(after.rows[0].c).toBe(before.rows[0].c);
} finally {
await engine.disconnect();
}
}, 30000);
test('full path: pre-v0.18 brain reaches LATEST_VERSION via initSchema', async () => {
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const db = (engine as any).db;
// Mutate to pre-v0.18 shape: strip the forward-referenced state.
// Match the shape from #399's regression fixture; constraints first
// (so dropping columns succeeds).
await db.exec(`
ALTER TABLE pages DROP CONSTRAINT IF EXISTS pages_source_slug_key;
ALTER TABLE pages ADD CONSTRAINT pages_slug_key UNIQUE (slug);
DROP INDEX IF EXISTS idx_pages_source_id;
-- The v230 trust generation trigger's WHEN reads pages.source_id, slug and
-- deleted_at; a pre-v0.18 brain predates it (v230 recreates it).
DROP TRIGGER IF EXISTS trust_generation_update ON pages;
-- The v283 folder-rule stamp trigger fires on UPDATE OF source_id; a
-- pre-v0.18 brain predates it too (v283 recreates it).
DROP TRIGGER IF EXISTS pages_access_stamp_folder_rules ON pages;
ALTER TABLE pages DROP COLUMN IF EXISTS source_id;
DROP TABLE IF EXISTS sources CASCADE;
ALTER TABLE links DROP CONSTRAINT IF EXISTS links_resolution_type_check;
ALTER TABLE links DROP COLUMN IF EXISTS resolution_type;
`);
await engine.setConfig('version', '20');
// Path under test: bootstrap → SCHEMA_SQL → runMigrations
await engine.initSchema();
expect(await engine.getConfig('version')).toBe(String(LATEST_VERSION));
const { rows: srcCol } = await db.query(`
SELECT column_name FROM information_schema.columns
WHERE table_name = 'pages' AND column_name = 'source_id'
`);
expect(srcCol).toHaveLength(1);
const { rows: defaultSrc } = await db.query(`SELECT id FROM sources WHERE id = 'default'`);
expect(defaultSrc).toHaveLength(1);
} finally {
await engine.disconnect();
}
}, 30000);
test('fresh install regression: initSchema on empty DB produces LATEST', async () => {
// The bootstrap's table-existence probe must not mis-classify "no table"
// as "pre-v0.18 brain." Without the table-existence guard, the bootstrap
// would call runMigrations against an empty DB and crash on
// `relation "config" does not exist`. Regression test for that path.
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
expect(await engine.getConfig('version')).toBe(String(LATEST_VERSION));
const db = (engine as any).db;
const pages = await db.query(`SELECT 1 FROM pages LIMIT 0`);
const sources = await db.query(`SELECT 1 FROM sources LIMIT 0`);
const config = await db.query(`SELECT 1 FROM config LIMIT 0`);
expect(pages).toBeDefined();
expect(sources).toBeDefined();
expect(config).toBeDefined();
} finally {
await engine.disconnect();
}
}, 30000);
test('pre-v0.13 links shape: bootstrap adds link_source + origin_page_id', async () => {
// Issues #266 / #357 — pre-v0.13 brains had `links` without
// `link_source` / `origin_page_id`. Schema blob's
// `CREATE INDEX idx_links_source` would crash before v11 ran.
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const db = (engine as any).db;
await db.exec(`
DROP INDEX IF EXISTS idx_links_source;
DROP INDEX IF EXISTS idx_links_origin;
ALTER TABLE links DROP CONSTRAINT IF EXISTS links_from_to_type_source_origin_unique;
ALTER TABLE links DROP COLUMN IF EXISTS link_source;
ALTER TABLE links DROP COLUMN IF EXISTS origin_page_id;
`);
await (engine as any).applyForwardReferenceBootstrap();
const { rows: lsCol } = await db.query(`
SELECT column_name FROM information_schema.columns
WHERE table_name = 'links' AND column_name = 'link_source'
`);
expect(lsCol).toHaveLength(1);
const { rows: opCol } = await db.query(`
SELECT column_name FROM information_schema.columns
WHERE table_name = 'links' AND column_name = 'origin_page_id'
`);
expect(opCol).toHaveLength(1);
} finally {
await engine.disconnect();
}
}, 30000);
test('pre-v121 timeline shape reaches LATEST through full initSchema', async () => {
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const db = (engine as any).db;
await db.exec(`
DROP INDEX IF EXISTS idx_timeline_event_dedup;
DROP INDEX IF EXISTS idx_timeline_event_page;
ALTER TABLE timeline_entries DROP CONSTRAINT IF EXISTS timeline_entries_event_page_id_fkey;
ALTER TABLE timeline_entries DROP COLUMN IF EXISTS event_page_id;
`);
await engine.setConfig('version', '119');
await engine.initSchema();
await engine.initSchema();
expect(await engine.getConfig('version')).toBe(String(LATEST_VERSION));
const { rows } = await db.query(`
SELECT column_name FROM information_schema.columns
WHERE table_name = 'timeline_entries' AND column_name = 'event_page_id'
`);
expect(rows).toHaveLength(1);
} finally {
await engine.disconnect();
}
}, 30000);
test('pre-v121 partial bootstrap resumes without skipping migration work', async () => {
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const db = (engine as any).db;
await db.exec(`
DROP INDEX IF EXISTS idx_timeline_event_dedup;
DROP INDEX IF EXISTS idx_timeline_event_page;
ALTER TABLE timeline_entries DROP CONSTRAINT IF EXISTS timeline_entries_event_page_id_fkey;
`);
await engine.setConfig('version', '119');
// Simulates interruption after bootstrap added the column but before
// schema-blob replay and migration v121 completed the FK/index work.
await engine.initSchema();
expect(await engine.getConfig('version')).toBe(String(LATEST_VERSION));
const { rows } = await db.query(`
SELECT to_regclass('idx_timeline_event_page') AS lookup_idx,
to_regclass('idx_timeline_event_dedup') AS dedup_idx
`);
expect(rows[0]?.lookup_idx).not.toBeNull();
expect(rows[0]?.dedup_idx).not.toBeNull();
} finally {
await engine.disconnect();
}
}, 30000);
test('wedged-brain recovery: a brain that already FAILED the v0.42.56 upgrade converges on retry', async () => {
// The loudest #2626-class cohort: operators who upgraded, wedged, and are
// retrying with a fixed binary. Simulates the failed attempt (the blob's
// CREATE INDEX crashing on the missing column) and asserts the retry
// converges to the FULL final shape (column + FK + both partial indexes)
// with no residue — the failed attempt must not advance the version ledger.
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const db = (engine as any).db;
// Rewind to the pre-v121 shape: schema AND the version counter.
await db.exec(`
DROP INDEX IF EXISTS idx_timeline_event_page;
DROP INDEX IF EXISTS idx_timeline_event_dedup;
ALTER TABLE timeline_entries DROP CONSTRAINT IF EXISTS timeline_entries_event_page_id_fkey;
ALTER TABLE timeline_entries DROP COLUMN IF EXISTS event_page_id;
`);
await engine.setConfig('version', '120');
// The failed old-binary attempt: without the bootstrap probe, the blob's
// CREATE INDEX was the first statement to touch the missing column.
let wedgeError: Error | null = null;
try {
await db.exec(
`CREATE INDEX IF NOT EXISTS idx_timeline_event_page
ON timeline_entries(event_page_id) WHERE event_page_id IS NOT NULL`,
);
} catch (e) {
wedgeError = e as Error;
}
expect(wedgeError?.message ?? '').toContain('event_page_id');
// The failed attempt must not have advanced the ledger.
expect(parseInt((await engine.getConfig('version')) || '1', 10)).toBe(120);
// Retry with the fixed binary: full initSchema converges to LATEST with
// the complete final shape.
await engine.initSchema();
expect(await engine.getConfig('version')).toBe(String(LATEST_VERSION));
const { rows: col } = await db.query(`
SELECT column_name FROM information_schema.columns
WHERE table_name = 'timeline_entries' AND column_name = 'event_page_id'
`);
expect(col).toHaveLength(1);
const { rows: fk } = await db.query(`
SELECT conname FROM pg_constraint
WHERE conname = 'timeline_entries_event_page_id_fkey'
`);
expect(fk).toHaveLength(1);
const { rows: idx } = await db.query(`
SELECT indexname FROM pg_indexes
WHERE tablename = 'timeline_entries'
AND indexname IN ('idx_timeline_event_page', 'idx_timeline_event_dedup')
`);
expect(idx).toHaveLength(2);
} finally {
await engine.disconnect();
}
}, 30000);
test('compounded pre-v34 brain (v0.20 + v0.26.3 + v0.27 + v39-v41 gaps) walks forward to LATEST', async () => {
const engine = new PGLiteEngine();
await engine.connect({});
try {
await engine.initSchema();
const dropped: Array<[string, string]> = [
['content_chunks', 'parent_symbol_path'], ['content_chunks', 'doc_comment'],
['content_chunks', 'symbol_name_qualified'], ['content_chunks', 'search_vector'],
['mcp_request_log', 'agent_name'], ['mcp_request_log', 'params'], ['mcp_request_log', 'error_message'],
['subagent_messages', 'provider_id'],
['content_chunks', 'embedding_image'], ['content_chunks', 'modality'],
['pages', 'emotional_weight'], ['pages', 'effective_date'], ['pages', 'effective_date_source'],
['pages', 'import_filename'], ['pages', 'salience_touched_at'],
];
await (engine as any).db.exec(`
DROP INDEX IF EXISTS idx_chunks_search_vector;
DROP INDEX IF EXISTS idx_chunks_symbol_qualified;
DROP TRIGGER IF EXISTS chunk_search_vector_trigger ON content_chunks;
DROP FUNCTION IF EXISTS update_chunk_search_vector;
DROP INDEX IF EXISTS idx_mcp_log_agent_time;
DROP INDEX IF EXISTS idx_subagent_messages_provider;
DROP INDEX IF EXISTS idx_chunks_embedding_image;
${dropped.map(([table, column]) => `ALTER TABLE ${table} DROP COLUMN IF EXISTS ${column} CASCADE;`).join('\n ')}
UPDATE config SET value = '13' WHERE key = 'version';
`);
await engine.initSchema();
expect(await engine.getConfig('version')).toBe(String(LATEST_VERSION));
const present = await engine.executeRaw<{ table_name: string; column_name: string }>(
`SELECT table_name, column_name FROM information_schema.columns WHERE table_schema = 'public'`,
);
const have = new Set(present.map(r => `${r.table_name}.${r.column_name}`));
expect(dropped.map(([table, column]) => `${table}.${column}`).filter(c => !have.has(c))).toEqual([]);
} finally {
await engine.disconnect();
}
}, 30000);
});