Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
27.8 KB
Raw Blame
/**
 * Per-domain write-then-throw rollback cases for the engine-sql executor
 * (refactor wave 1, EO1 / T-G1). Each W1-core domain commit adds its case.
 *
 * A case seeds state outside the transaction THROUGH THE SAME DOMAIN on the
 * root engine (so a long-lived engine's executor has been used before the
 * transaction starts), performs one migrated domain write through the
 * TRANSACTION CLONE (so the write resolves the clone's
 * `engineSql`), and reads the observed value back. The runner asserts:
 *   - inside the transaction the write is visible to the clone,
 *   - on Postgres a concurrent pool read during the transaction does not see it,
 *   - after the body throws, the value equals the seeded value.
 * A regression that caches the executor on the engine (bound to the pool at
 * connect time) makes the write commit outside the transaction and fails.
 */
import { expect, test } from 'bun:test';
import { ROW_BATCH_MAX_ROWS } from '../../src/core/batch-rows.ts';
import type { BrainEngine } from '../../src/core/engine.ts';
import { invalidateStaleSignatureEmbeddingsGuarded } from '../../src/core/embedding-invalidation.ts';
import { reconcileContextualEmbeddingInputs } from '../../src/core/page-state/contextual-proof.ts';
import { installPageProjection, readProjectionSnapshot } from '../../src/core/page-state/projections.ts';
import { installFixtureChunks } from './page-projection.ts';
import { chunk, flipInput, hexOf, manifestRow, pageMeta, publishSegmentedPage, segmentText, sha256, stageGeneration, stagingInput } from './page-body-fixtures.ts';
import type { SegmentDerivationInput, SegmentDerivationKind, SegmentDerivationState } from '../../src/core/page-body/derivations.ts';

export interface RollbackCase {
  domain: string;
  seed(engine: BrainEngine): Promise<void>;
  write(tx: BrainEngine): Promise<void>;
  observe(engine: BrainEngine): Promise<unknown>;
}

const SLUG = 'notes/engine-sql-rollback-alice-example';
const LINK_TARGET = 'notes/engine-sql-rollback-target-alice-example';

async function seedPage(engine: BrainEngine): Promise<void> {
  await engine.putPage(SLUG, { type: 'note', title: 'Rollback probe', compiled_truth: 'body' });
}

export const ROLLBACK_CASES: RollbackCase[] = [
  {
    domain: 'salience',
    async seed(engine) {
      await seedPage(engine);
      await engine.setEmotionalWeightBatch([{ slug: SLUG, source_id: 'default', weight: 0.25 }]);
    },
    async write(tx) {
      const changed = await tx.setEmotionalWeightBatch([{ slug: SLUG, source_id: 'default', weight: 0.75 }]);
      expect(changed).toBe(1);
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ w: number }>(
        `SELECT emotional_weight::float8 AS w FROM pages WHERE slug = $1 AND source_id = 'default'`, [SLUG]);
      return Number(rows[0]?.w ?? 0);
    },
  },
  {
    domain: 'facts',
    async seed(engine) {
      await engine.insertFact(
        { fact: 'seeded rollback fact', source: 'test:rollback', entity_slug: 'people/alice-example' },
        { source_id: 'default' },
      );
    },
    async write(tx) {
      const res = await tx.insertFact(
        { fact: 'rolled-back fact', source: 'test:rollback', entity_slug: 'people/alice-example' },
        { source_id: 'default' },
      );
      expect(res.status).toBe('inserted');
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ n: number }>(
        `SELECT count(*)::int AS n FROM facts WHERE source_id = 'default' AND fact = 'rolled-back fact'`);
      return Number(rows[0]?.n ?? 0);
    },
  },
  {
    domain: 'takes',
    async seed(engine) {
      await seedPage(engine);
      await engine.addTakesBatch([{ page_id: await pageId(engine), row_num: 1, claim: 'rollback claim', kind: 'take', holder: 'alice-example', weight: 0.25 }]);
    },
    async write(tx) {
      const n = await tx.addTakesBatch([{ page_id: await pageId(tx), row_num: 1, claim: 'rollback claim', kind: 'take', holder: 'alice-example', weight: 0.75 }]);
      expect(n).toBe(1);
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ w: number }>(
        `SELECT t.weight::float8 AS w FROM takes t JOIN pages p ON p.id = t.page_id WHERE p.slug = $1 AND t.row_num = 1`, [SLUG]);
      return Number(rows[0]?.w ?? 0);
    },
  },
  {
    domain: 'code-edges',
    async seed(engine) {
      await seedPage(engine);
      await engine.addCodeEdges([{ from_chunk_id: await rollbackChunk(engine), to_chunk_id: null, from_symbol_qualified: 'run', to_symbol_qualified: 'seeded-target', edge_type: 'calls' }]);
    },
    async write(tx) {
      const n = await tx.addCodeEdges([{ from_chunk_id: await rollbackChunk(tx), to_chunk_id: null, from_symbol_qualified: 'run', to_symbol_qualified: 'rolled-back-target', edge_type: 'calls' }]);
      expect(n).toBe(1);
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ n: number }>(
        `SELECT count(*)::int AS n FROM code_edges_symbol WHERE to_symbol_qualified = 'rolled-back-target'`);
      return Number(rows[0]?.n ?? 0);
    },
  },
  {
    domain: 'sources',
    async seed(engine) {
      expect(await engine.updateSourceConfig('default', { engine_sql_rollback_probe: 'seeded' })).toBe(true);
    },
    async write(tx) {
      expect(await tx.updateSourceConfig('default', { engine_sql_rollback_probe: 'rolled-back' })).toBe(true);
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ v: string | null }>(
        `SELECT config->>'engine_sql_rollback_probe' AS v FROM sources WHERE id = 'default'`);
      return rows[0]?.v ?? null;
    },
  },
  {
    domain: 'files',
    async seed(engine) {
      await engine.upsertFile({ filename: 'rollback.png', storage_path: 'attachments/engine-sql-rollback.png', content_hash: 'seeded' });
    },
    async write(tx) {
      const res = await tx.upsertFile({ filename: 'rollback.png', storage_path: 'attachments/engine-sql-rollback.png', content_hash: 'rolled-back' });
      expect(res.created).toBe(false);
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ h: string }>(
        `SELECT content_hash AS h FROM files WHERE storage_path = 'attachments/engine-sql-rollback.png'`);
      return rows[0]?.h ?? null;
    },
  },
  {
    domain: 'chunks (upsertChunks)',
    async seed(engine) {
      await seedPage(engine);
      await engine.upsertChunks(SLUG, [{ chunk_index: 0, chunk_text: 'seeded chunk', chunk_source: 'compiled_truth' }]);
    },
    async write(tx) {
      await tx.upsertChunks(SLUG, [{ chunk_index: 0, chunk_text: 'rolled-back chunk', chunk_source: 'compiled_truth' }]);
    },
    observe: chunkTexts,
  },
  {
    // A3: a replacement larger than one row batch commits as several INSERTs
    // after one prune; all of them leave with the transaction.
    domain: 'chunks (upsertChunks, several row batches)',
    async seed(engine) {
      await seedPage(engine);
      await engine.upsertChunks(SLUG, [{ chunk_index: 0, chunk_text: 'seeded chunk', chunk_source: 'compiled_truth' }]);
    },
    async write(tx) {
      await tx.upsertChunks(SLUG, Array.from({ length: ROW_BATCH_MAX_ROWS * 2 + 1 }, (_, i) => ({
        chunk_index: i, chunk_text: `rolled-back chunk ${i}`, chunk_source: 'compiled_truth' as const })));
    },
    observe: chunkTexts,
  },
  {
    domain: 'chunks (deleteChunks)',
    async seed(engine) {
      await seedPage(engine);
      await engine.upsertChunks(SLUG, [{ chunk_index: 0, chunk_text: 'seeded chunk', chunk_source: 'compiled_truth' }]);
    },
    async write(tx) {
      await tx.deleteChunks(SLUG);
    },
    observe: chunkTexts,
  },
  {
    domain: 'chunks (setPageEmbeddingSignature)',
    async seed(engine) {
      await seedPage(engine);
      await engine.setPageEmbeddingSignature(SLUG, { signature: 'seeded:3' });
    },
    async write(tx) {
      await tx.setPageEmbeddingSignature(SLUG, { signature: 'rolled-back:3' });
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ s: string | null }>(
        `SELECT embedding_signature AS s FROM pages WHERE slug = $1 AND source_id = 'default'`, [SLUG]);
      return rows[0]?.s ?? null;
    },
  },
  // Every site that leaves a chunk without its vector stamps
  // embedding_pending_since (doctor ages the embedding backlog from it).
  // Seeded embedded, so the stamp is NULL before the write.
  {
    domain: 'chunks (upsertChunks insert without a vector stamps embedding_pending_since)',
    async seed(engine) {
      await seedPage(engine);
      await engine.deleteChunks(SLUG);
    },
    async write(tx) {
      await tx.upsertChunks(SLUG, [{ chunk_index: 0, chunk_text: 'pending chunk', chunk_source: 'compiled_truth' }]);
      expect(await vectorState(tx)).toEqual({ missing: true, pending: true });
    },
    observe: pendingStamp,
  },
  {
    domain: 'chunks (upsertChunks text change NULLs the vector and stamps embedding_pending_since)',
    seed: (engine) => seedEmbeddedChunk(engine),
    async write(tx) {
      await tx.upsertChunks(SLUG, [{ chunk_index: 0, chunk_text: 'edited chunk', chunk_source: 'compiled_truth' }]);
      expect(await vectorState(tx)).toEqual({ missing: true, pending: true });
    },
    observe: pendingStamp,
  },
  {
    domain: 'chunks (invalidateStaleSignatureEmbeddings stamps embedding_pending_since)',
    seed: (engine) => seedEmbeddedChunk(engine),
    async write(tx) {
      expect(await tx.invalidateStaleSignatureEmbeddings({ signature: await swapSignature(tx), includeNullSignature: true })).toBe(1);
      expect(await vectorState(tx)).toEqual({ missing: true, pending: true });
    },
    observe: pendingStamp,
  },
  {
    domain: 'chunks (invalidateContentDriftEmbeddings stamps embedding_pending_since)',
    async seed(engine) {
      await seedEmbeddedChunk(engine);
      await engine.executeRaw(`UPDATE content_chunks SET chunk_text = 'drifted chunk'
        WHERE page_id = (SELECT id FROM pages WHERE slug = $1 AND source_id = 'default')`, [SLUG]);
    },
    async write(tx) {
      expect(await tx.invalidateContentDriftEmbeddings()).toBe(1);
      expect(await vectorState(tx)).toEqual({ missing: true, pending: true });
    },
    observe: pendingStamp,
  },
  {
    domain: 'embedding-invalidation (guarded model-swap invalidation stamps embedding_pending_since)',
    seed: (engine) => seedEmbeddedChunk(engine),
    async write(tx) {
      expect(await invalidateStaleSignatureEmbeddingsGuarded(tx, { signature: await swapSignature(tx), includeNullSignature: true })).toBe(1);
      expect(await vectorState(tx)).toEqual({ missing: true, pending: true });
    },
    observe: pendingStamp,
  },
  {
    domain: 'pages (contextual mode back to none stamps embedding_pending_since)',
    async seed(engine) {
      await seedEmbeddedChunk(engine);
      await engine.executeRaw(`UPDATE pages SET contextual_retrieval_mode = 'title' WHERE slug = $1 AND source_id = 'default'`, [SLUG]);
    },
    async write(tx) {
      await tx.updatePageContextualRetrievalState(SLUG, 'default', 'none', null);
      expect(await vectorState(tx)).toEqual({ missing: true, pending: true });
    },
    observe: pendingStamp,
  },
  {
    domain: 'contextual proof (a vector from a retired model input stamps embedding_pending_since)',
    seed: (engine) => seedEmbeddedChunk(engine, RETIRED_MODEL),
    async write(tx) {
      const snapshot = await tx.readPageSnapshot(SLUG, { sourceId: 'default' });
      expect(await reconcileContextualEmbeddingInputs(tx, snapshot!, 'none', null)).toBe(1);
      expect(await vectorState(tx)).toEqual({ missing: true, pending: true });
    },
    observe: pendingStamp,
  },
  {
    domain: 'projections (a re-seal that drops a retired vector stamps embedding_pending_since)',
    seed: (engine) => seedEmbeddedChunk(engine, RETIRED_MODEL),
    async write(tx) {
      const snapshot = await readProjectionSnapshot(tx, SLUG, 'default', { allowUnsealed: true });
      await installPageProjection(tx, snapshot!, [{ chunk_index: 0, chunk_text: EMBEDDED_TEXT, chunk_source: 'compiled_truth' }],
        { seal: true, preserveEmbeddings: true });
      expect(await vectorState(tx)).toEqual({ missing: true, pending: true });
    },
    observe: pendingStamp,
  },
  {
    domain: 'pages',
    async seed(engine) {
      await seedPage(engine);
    },
    async write(tx) {
      const page = await tx.putPage(SLUG, { type: 'note', title: 'Rollback probe', compiled_truth: 'rolled-back body' });
      expect(page.compiled_truth).toBe('rolled-back body');
      expect(await tx.softDeletePage(SLUG, { sourceId: 'default' })).toEqual({ slug: SLUG });
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ body: string; deleted: boolean }>(
        `SELECT compiled_truth AS body, deleted_at IS NOT NULL AS deleted FROM pages WHERE slug = $1 AND source_id = 'default'`, [SLUG]);
      return rows[0] ? { body: rows[0].body, deleted: rows[0].deleted } : null;
    },
  },
  {
    domain: 'pages (stale reserved frontmatter keys, #6454)',
    async seed(engine) {
      await seedPage(engine);
      await engine.executeRaw(`UPDATE pages SET frontmatter = frontmatter || '{"type":"legacy","title":"Stored Title"}'::jsonb WHERE slug = $1 AND source_id = 'default'`, [SLUG]);
    },
    async write(tx) {
      const [row] = await tx.listStaleFrontmatterKeyPages({ sourceId: 'default', afterId: 0, limit: 10 });
      expect(row).toMatchObject({ slug: SLUG, keys: ['title', 'type'] });
      expect(await tx.countStaleFrontmatterKeyPages({ sourceIds: ['default'] })).toEqual([{ source_id: 'default', n: 1 }]);
      expect(await tx.stripStaleFrontmatterKeys({ sourceId: 'default', ids: [row.id] })).toBe(1);
      expect(await tx.countStaleFrontmatterKeyPages({ sourceIds: ['default'] })).toEqual([]);
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ stale: boolean }>(
        `SELECT frontmatter ?| ARRAY['type','title','tags','slug'] AS stale FROM pages WHERE slug = $1 AND source_id = 'default'`, [SLUG]);
      return rows[0]?.stale ?? null;
    },
  },
  {
    domain: 'pages (attendance marker)',
    async seed(engine) {
      await seedPage(engine);
    },
    async write(tx) {
      const snapshot = await tx.readPageSnapshot(SLUG, { sourceId: 'default' });
      expect(await tx.markPagesAttendanceBlocked([{ slug: SLUG, source_id: 'default', revision: snapshot!.revision }])).toBe(1);
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ blocked: boolean }>(
        `SELECT links_attendance_blocked_revision IS NOT NULL AS blocked FROM pages WHERE slug = $1 AND source_id = 'default'`, [SLUG]);
      return rows[0]?.blocked ?? null;
    },
  },
  {
    domain: 'tags',
    async seed(engine) {
      await seedPage(engine);
      await engine.addTag(SLUG, 'seeded-tag');
    },
    async write(tx) {
      await tx.addTag(SLUG, 'rolled-back-tag');
    },
    async observe(engine) {
      return engine.getTags(SLUG, { sourceId: 'default' });
    },
  },
  {
    domain: 'links',
    async seed(engine) {
      await seedPage(engine);
      await engine.putPage(LINK_TARGET, { type: 'note', title: 'Rollback link target', compiled_truth: 'target' });
      await engine.addLink(SLUG, LINK_TARGET, 'seeded context', 'mentions', 'manual');
    },
    async write(tx) {
      await tx.addLink(SLUG, LINK_TARGET, 'rolled-back context', 'mentions', 'manual');
    },
    async observe(engine) {
      return (await engine.getLinks(SLUG, { sourceId: 'default' }))
        .filter((l) => l.to_slug === LINK_TARGET).map((l) => `${l.link_type}:${l.context}`).sort();
    },
  },
  {
    domain: 'timeline',
    async seed(engine) {
      await seedPage(engine);
      await engine.addTimelineEntry(SLUG, { date: '2026-01-02', source: 'test:rollback', summary: 'seeded entry' });
    },
    async write(tx) {
      expect(await tx.addTimelineEntry(SLUG, { date: '2026-01-03', source: 'test:rollback', summary: 'rolled-back entry' })).toBe(true);
    },
    async observe(engine) {
      return (await engine.getTimeline(SLUG, { sourceId: 'default' })).map((e) => e.summary).sort();
    },
  },
  {
    domain: 'page-body (stageSegmentTexts)',
    async seed(engine) { await seedSegmentedPage(engine, SEGMENTED_SLUG); },
    async write(tx) { expect(await tx.stageSegmentTexts('default', [ROLLBACK_TEXT])).toEqual({ inserted: 1 }); },
    observe: engine => segmentTextExists(engine, ROLLBACK_TEXT),
  },
  {
    domain: 'page-body (stageManifestRows)',
    async seed(engine) {
      await seedSegmentedPage(engine, SEGMENTED_SLUG);
      await engine.stageSegmentTexts('default', [MANIFEST_TEXT]);
      await seedStaging(engine, MANIFEST_STAGING_ID);
    },
    async write(tx) {
      const [occurrenceId] = await tx.allocateBodyOccurrenceIds(1);
      await tx.stageManifestRows([manifestRow({ pageId: await segmentedPageId(tx, SEGMENTED_SLUG), occurrenceId: occurrenceId!, genFrom: 2, seq: 0,
        text: MANIFEST_TEXT, byteStart: 0, stagingId: MANIFEST_STAGING_ID })]);
    },
    async observe(engine) { return (await engine.readManifest(await segmentedPageId(engine, SEGMENTED_SLUG), { stagingId: MANIFEST_STAGING_ID })).length; },
  },
  {
    domain: 'page-body (stageSegmentChunks)',
    async seed(engine) { await seedSegmentedPage(engine, SEGMENTED_SLUG); },
    async write(tx) {
      const [occurrenceId] = await tx.allocateBodyOccurrenceIds(1);
      await tx.stageSegmentChunks(await segmentedPageId(tx, SEGMENTED_SLUG), 99, [chunk(occurrenceId!, 0, 'rolled-back staged chunk')]);
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM content_chunks WHERE page_id = $1 AND body_generation = 99',
        [await segmentedPageId(engine, SEGMENTED_SLUG)]);
      return Number(rows[0]?.n ?? 0);
    },
  },
  {
    domain: 'page-body (createSegmentedPageShell)',
    async seed() {},
    async write(tx) { await tx.createSegmentedPageShell(SHELL_SLUG, pageMeta(), { sourceId: 'default' }); },
    async observe(engine) {
      const rows = await engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM pages WHERE slug = $1 AND source_id = 'default'", [SHELL_SLUG]);
      return Number(rows[0]?.n ?? 0);
    },
  },
  {
    domain: 'page-body (flipBodyGeneration)',
    async seed(engine) {
      await seedSegmentedPage(engine, FLIP_SLUG);
      const pageId = await segmentedPageId(engine, FLIP_SLUG);
      if (await openStagingOf(engine, FLIP_SLUG)) return;
      await stageGeneration(engine, { pageId, slug: FLIP_SLUG, genFrom: 2, texts: [FLIP_TEXT] });
    },
    async write(tx) {
      const pageId = await segmentedPageId(tx, FLIP_SLUG);
      const live = await tx.readManifest(pageId);
      expect(await tx.flipBodyGeneration(flipInput(pageId, 1, (await openStagingOf(tx, FLIP_SLUG))!, [FLIP_TEXT],
        { closeOccurrences: live.map(r => r.occurrenceId) }))).toEqual({ retiredChunks: 0, retireDeferred: false });
    },
    async observe(engine) {
      const rows = await engine.executeRaw<{ g: number }>("SELECT body_generation::int AS g FROM pages WHERE slug = $1 AND source_id = 'default'", [FLIP_SLUG]);
      return Number(rows[0]?.g ?? -1);
    },
  },
  {
    domain: 'page-body (openBodyStaging)',
    async seed(engine) { await seedSegmentedPage(engine, SEGMENTED_SLUG); },
    async write(tx) { await tx.openBodyStaging(stagingInput({ id: OPENED_STAGING_ID, slug: SEGMENTED_SLUG })); },
    observe: engine => stagingState(engine, OPENED_STAGING_ID),
  },
  {
    domain: 'page-body (setBodyStagingState)',
    async seed(engine) { await seedStaging(engine, STATE_STAGING_ID); },
    async write(tx) { await tx.setBodyStagingState(STATE_STAGING_ID, 'aborted'); },
    observe: engine => stagingState(engine, STATE_STAGING_ID),
  },
  {
    domain: 'page-body (sweepSegments)',
    async seed(engine) {
      await seedSegmentedPage(engine, SEGMENTED_SLUG);
      await engine.stageSegmentTexts('default', [ORPHAN_TEXT]);
      await engine.executeRaw("UPDATE page_segment_texts SET created_at = now() - interval '2 hours' WHERE source_id = 'default' AND sha256 = decode($1, 'hex')",
        [hexOf(ORPHAN_TEXT.sha256)]);
    },
    async write(tx) {
      expect((await tx.sweepSegments({ sourceId: 'default' })).textsDeleted).toBeGreaterThanOrEqual(1);
    },
    observe: engine => segmentTextExists(engine, ORPHAN_TEXT),
  },
  {
    domain: 'page-body (upsertSegmentDerivations)',
    async seed(engine) {
      await seedSegmentedPage(engine, SEGMENTED_SLUG);
      await engine.upsertSegmentDerivations([derivationRow(await segmentedPageId(engine, SEGMENTED_SLUG), 'links', 1, 'partial')]);
    },
    async write(tx) { await tx.upsertSegmentDerivations([derivationRow(await segmentedPageId(tx, SEGMENTED_SLUG), 'links', 1, 'done')]); },
    async observe(engine) {
      return (await engine.readSegmentDerivations(await segmentedPageId(engine, SEGMENTED_SLUG), { kind: 'links' })).map(r => r.state);
    },
  },
  {
    domain: 'page-body (retireSegmentDerivations)',
    async seed(engine) {
      await seedSegmentedPage(engine, SEGMENTED_SLUG);
      const pageId = await segmentedPageId(engine, SEGMENTED_SLUG);
      await engine.upsertSegmentDerivations([derivationRow(pageId, 'mentions', 1, 'done'), derivationRow(pageId, 'mentions', 2, 'done')]);
    },
    async write(tx) { expect(await tx.retireSegmentDerivations(await segmentedPageId(tx, SEGMENTED_SLUG), [1], { kind: 'mentions' })).toBe(1); },
    async observe(engine) {
      return (await engine.readSegmentDerivations(await segmentedPageId(engine, SEGMENTED_SLUG), { kind: 'mentions' })).map(r => r.occurrenceId);
    },
  },
];

function derivationRow(pageId: number, kind: SegmentDerivationKind, occurrenceId: number, state: SegmentDerivationState): SegmentDerivationInput {
  return { pageId, kind, occurrenceId, version: 1, segmentSha256: sha256(`segment ${occurrenceId}`), contextHash: sha256(`context ${occurrenceId}`),
    state, output: { n: occurrenceId }, receipt: null };
}

const SEGMENTED_SLUG = 'notes/engine-sql-rollback-segmented-alice-example';
const FLIP_SLUG = 'notes/engine-sql-rollback-flip-alice-example';
const SHELL_SLUG = 'notes/engine-sql-rollback-shell-alice-example';
const ROLLBACK_TEXT = segmentText('# Rollback\nstaged text that never commits\n');
const MANIFEST_TEXT = segmentText('# Rollback\nmanifest probe text\n');
const FLIP_TEXT = segmentText('# Rollback\nflipped body\n');
const ORPHAN_TEXT = segmentText('# Rollback\nunreferenced aged text\n');
const MANIFEST_STAGING_ID = '6d1f1c2a-8b6e-4a59-9c39-2f0b6d4a0001';
const OPENED_STAGING_ID = '6d1f1c2a-8b6e-4a59-9c39-2f0b6d4a0002';
const STATE_STAGING_ID = '6d1f1c2a-8b6e-4a59-9c39-2f0b6d4a0003';

async function segmentedPageId(engine: BrainEngine, slug: string): Promise<number> {
  const rows = await engine.executeRaw<{ id: number }>("SELECT id FROM pages WHERE slug = $1 AND source_id = 'default'", [slug]);
  return Number(rows[0]?.id ?? 0);
}

async function seedSegmentedPage(engine: BrainEngine, slug: string): Promise<void> {
  if (await segmentedPageId(engine, slug)) return;
  await publishSegmentedPage(engine, slug, [segmentText(`# ${slug}\nbase body\n`)]);
}

async function seedStaging(engine: BrainEngine, id: string): Promise<void> {
  await seedSegmentedPage(engine, SEGMENTED_SLUG);
  if (await stagingState(engine, id)) return;
  await engine.openBodyStaging(stagingInput({ id, slug: SEGMENTED_SLUG, pageId: await segmentedPageId(engine, SEGMENTED_SLUG) }));
}

async function stagingState(engine: BrainEngine, id: string): Promise<string | null> {
  const rows = await engine.executeRaw<{ state: string }>('SELECT state FROM page_body_stagings WHERE id = $1::uuid', [id]);
  return rows[0]?.state ?? null;
}

async function openStagingOf(engine: BrainEngine, slug: string): Promise<string | null> {
  const rows = await engine.executeRaw<{ id: string }>("SELECT id::text AS id FROM page_body_stagings WHERE slug = $1 AND state = 'open' ORDER BY created_at LIMIT 1", [slug]);
  return rows[0]?.id ?? null;
}

async function segmentTextExists(engine: BrainEngine, text: { sha256: Uint8Array }): Promise<boolean> {
  return (await engine.readSegmentTexts('default', [text.sha256])).has(hexOf(text.sha256));
}

async function chunkTexts(engine: BrainEngine): Promise<string[]> {
  const rows = await engine.executeRaw<{ t: string }>(
    `SELECT cc.chunk_text AS t FROM content_chunks cc JOIN pages p ON p.id = cc.page_id
      WHERE p.slug = $1 AND p.source_id = 'default' ORDER BY cc.chunk_index`, [SLUG]);
  return rows.map((r) => r.t);
}

const EMBEDDED_TEXT = 'embedded chunk';
const CURRENT_MODEL = 'openai:text-embedding-3-large';
const RETIRED_MODEL = 'rollback:retired-model';

/** SLUG with one sealed chunk embedded through the real upsert, no contextual mode, no signature. */
async function seedEmbeddedChunk(engine: BrainEngine, model = CURRENT_MODEL): Promise<void> {
  await seedPage(engine);
  await engine.executeRaw(`UPDATE pages SET contextual_retrieval_mode = NULL, embedding_signature = NULL
    WHERE slug = $1 AND source_id = 'default'`, [SLUG]);
  await installFixtureChunks(engine, SLUG, [{ chunk_index: 0, chunk_text: EMBEDDED_TEXT, chunk_source: 'compiled_truth', model }]);
  const vector = new Float32Array(await embeddingDims(engine));
  vector[0] = 1;
  await engine.upsertChunks(SLUG, [{ chunk_index: 0, chunk_text: EMBEDDED_TEXT, chunk_source: 'compiled_truth', embedding: vector, model }]);
  expect(await vectorState(engine)).toEqual({ missing: false, pending: false });
}

async function embeddingDims(engine: BrainEngine): Promise<number> {
  const rows = await engine.executeRaw<{ dim: number }>(
    `SELECT atttypmod AS dim FROM pg_attribute WHERE attrelid = 'content_chunks'::regclass AND attname = 'embedding' AND attnum > 0`);
  return Number(rows[0].dim);
}

/** A signature for a model the seeded chunk was not embedded with. */
async function swapSignature(engine: BrainEngine): Promise<string> {
  return `rollback:swapped-model:${await embeddingDims(engine)}`;
}

async function vectorState(engine: BrainEngine): Promise<{ missing: boolean; pending: boolean } | null> {
  const rows = await engine.executeRaw<{ missing: boolean; pending: boolean }>(
    `SELECT cc.embedding IS NULL AS missing, cc.embedding_pending_since IS NOT NULL AS pending
       FROM content_chunks cc JOIN pages p ON p.id = cc.page_id
      WHERE p.slug = $1 AND p.source_id = 'default' AND cc.chunk_index = 0`, [SLUG]);
  return rows[0] ? { missing: rows[0].missing, pending: rows[0].pending } : null;
}

async function pendingStamp(engine: BrainEngine): Promise<boolean | null> {
  return (await vectorState(engine))?.pending ?? null;
}

async function rollbackChunk(engine: BrainEngine): Promise<number> {
  const existing = await engine.getChunks(SLUG);
  if (existing.length > 0) return existing[0]!.id;
  await installFixtureChunks(engine, SLUG, [{
    chunk_index: 0, chunk_text: 'body', chunk_source: 'compiled_truth',
    language: 'typescript', symbol_name: 'run', symbol_type: 'function', symbol_name_qualified: 'run',
  }]);
  return (await engine.getChunks(SLUG))[0]!.id;
}

async function pageId(engine: BrainEngine): Promise<number> {
  const rows = await engine.executeRaw<{ id: number }>(`SELECT id FROM pages WHERE slug = $1 AND source_id = 'default'`, [SLUG]);
  return Number(rows[0].id);
}

class Rollback extends Error {}

/** Register one test per case and transaction entry point. */
export function defineRollbackCases(opts: {
  getEngine: () => BrainEngine;
  entryPoints: ReadonlyArray<'transaction' | 'transactionDirect'>;
  concurrentPoolRead: boolean;
}): void {
  for (const c of ROLLBACK_CASES) {
    for (const entry of opts.entryPoints) {
      test(`${c.domain}: a write through engine.${entry}() that then throws is rolled back`, async () => {
        const engine = opts.getEngine();
        await c.seed(engine);
        const before = await c.observe(engine);
        const err = await engine[entry](async (tx) => {
          await c.write(tx);
          expect(await c.observe(tx)).not.toEqual(before);
          if (opts.concurrentPoolRead) expect(await c.observe(engine)).toEqual(before);
          throw new Rollback('rollback probe');
        }).then(() => null, (e: unknown) => e);
        expect(err).toBeInstanceOf(Rollback);
        expect(await c.observe(engine)).toEqual(before);
      }, 15_000);
    }
  }
}