Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
40.8 KB
Raw Blame
/**
 * BrainEngine parity — takes family (+ contradiction probe cache and dream
 * verdict cache, which hang off the same tables' lifecycle).
 *
 * Authoring gate (docs/TESTING.md#authoring-gate):
 *  - Contract: every takes method (batch write, list/search, embeddings and
 *    their staleness, update/supersede/resolve, scorecard and calibration,
 *    synthesis evidence), the contradiction-probe run/cache methods and the
 *    dream-verdict cache return the same observable result on every engine
 *    arm (PGLite always; Postgres with DATABASE_URL; a Rust arm later through
 *    test/engine-parity/harness.ts).
 *  - Regression: an engine that drifts on take ordering and filters, on which
 *    holder rows an allow-list hides, on resolve/supersede immutability, on
 *    scorecard/Brier/calibration math, or on cache hit/miss semantics: the
 *    numbers `gbrain takes` and the dream cycle report.
 *  - Why existing coverage misses it: the takes and cache tests each run one
 *    engine; test/e2e/takes-postgres.test.ts needs Postgres and never diffs it
 *    against PGLite on one scenario.
 *  - Seam: none. Real engines, typed methods only (no executeRaw: D18).
 */
import { describe, expect } from 'bun:test';
import type { BrainEngine, Take, TakeBatchInput, TakeHit } from '../../src/core/engine.ts';
import { basisEmbedding, createSource, parityArms, pick, sorted } from './harness.ts';
import { testBackends } from '../helpers/test-backends.ts';

const { parityTest } = parityArms(testBackends());

const TAKE_KEYS = [
  'page_slug', 'row_num', 'claim', 'kind', 'holder', 'weight', 'since_date', 'until_date', 'source',
  'superseded_by', 'active', 'resolved_quality', 'resolved_outcome', 'resolved_value', 'resolved_unit',
  'resolved_source', 'resolved_by',
] as const;

const tv = (t: Take) => ({ ...pick(t, TAKE_KEYS), resolved: t.resolved_at !== null });
const claims = (rows: Array<{ claim: string }>) => rows.map((r) => r.claim);
const round = (n: number | null | undefined, places = 4) => (n == null ? n : Number(n.toFixed(places)));

/** Run `fn` and return the error's GBrainError `problem` code, or null when it did not throw. */
async function errorCode(fn: () => Promise<unknown>): Promise<string | null> {
  try {
    await fn();
    return null;
  } catch (e) {
    return (e as { problem?: string }).problem ?? `non-gbrain:${(e as Error).constructor.name}`;
  }
}

async function page(engine: BrainEngine, slug: string, opts?: { sourceId?: string }) {
  const type = slug.startsWith('people/') ? 'person' : slug.startsWith('companies/') ? 'company' : 'note';
  return engine.putPage(slug, { type, title: slug, compiled_truth: `Page ${slug}.`, timeline: '' }, opts);
}

const take = (page_id: number, row_num: number, claim: string, extra: Partial<TakeBatchInput> = {}): TakeBatchInput => ({
  page_id, row_num, claim, kind: 'take', holder: 'garry', ...extra,
});

/** Map take ids to their claim text: ids are sequence-dependent and never compared across arms. */
// listTakes defaults to active rows only (`active ?? true`), so list both halves
async function allTakes(engine: BrainEngine, pageId: number) {
  return [...(await engine.listTakes({ page_id: pageId, active: true })), ...(await engine.listTakes({ page_id: pageId, active: false }))];
}

async function takeIds(engine: BrainEngine, pageId: number): Promise<Map<string, number>> {
  const rows = await allTakes(engine, pageId);
  return new Map(rows.map((r) => [r.claim, r.id]));
}

describe('engine parity: takes', () => {
  parityTest(
    'addTakesBatch inserts rows, is idempotent per (page, row_num), updates changed rows in place, clamps weight',
    { methods: ['putPage', 'addTakesBatch', 'listTakes'] },
    async (engine) => {
      const alice = await page(engine, 'people/alice-example');
      expect(await engine.addTakesBatch([])).toBe(0);
      const first = await engine.addTakesBatch([
        take(alice.id, 1, 'Alice will ship in Q3', { kind: 'bet', weight: 0.7, since_date: '2026-01-10', source: 'meeting' }),
        take(alice.id, 2, 'Alice prefers async work', { kind: 'take', weight: 0.4, holder: 'alice' }),
        take(alice.id, 3, 'Alice is in Austin', { kind: 'fact', weight: 1 }),
        take(alice.id, 4, 'Over-confident', { weight: 7 }),
        take(alice.id, 5, 'Under-confident', { weight: -3 }),
        take(alice.id, 6, 'Default weight'),
        take(alice.id, 7, 'Already inactive', { active: false, superseded_by: 6 }),
      ]);
      const initial = (await allTakes(engine, alice.id)).map(tv);
      // identical re-add counts every row and changes nothing
      const same = await engine.addTakesBatch([take(alice.id, 1, 'Alice will ship in Q3', { kind: 'bet', weight: 0.7, since_date: '2026-01-10', source: 'meeting' })]);
      // a changed claim/weight updates in place; still one row at that coordinate
      const changed = await engine.addTakesBatch([take(alice.id, 1, 'Alice will ship in Q4', { kind: 'bet', weight: 0.55, since_date: '2026-01-10', source: 'meeting' })]);
      const after = (await allTakes(engine, alice.id)).map(tv);
      expect([first, same, changed]).toEqual([7, 1, 1]);
      expect(initial.find((t) => t.row_num === 4)?.weight).toBe(1);
      expect(initial.find((t) => t.row_num === 5)?.weight).toBe(0);
      expect(initial.find((t) => t.row_num === 6)?.weight).toBe(0.5);
      expect(after.filter((t) => t.row_num === 1)).toHaveLength(1);
      expect(after.find((t) => t.row_num === 1)).toMatchObject({ claim: 'Alice will ship in Q4', weight: 0.55 });
      return { first, same, changed, initial: sorted(initial, (t) => String(t.row_num).padStart(3, '0')), after: sorted(after, (t) => String(t.row_num).padStart(3, '0')) };
    },
  );

  parityTest(
    'listTakes filters by page, holder, kind, active, resolved and holder allow-list',
    { methods: ['putPage', 'addTakesBatch', 'listTakes', 'resolveTake'] },
    async (engine) => {
      const alice = await page(engine, 'people/alice-example');
      const acme = await page(engine, 'companies/acme-example');
      await engine.addTakesBatch([
        take(alice.id, 1, 'a1 bet', { kind: 'bet', holder: 'garry', weight: 0.9 }),
        take(alice.id, 2, 'a2 take', { kind: 'take', holder: 'alice', weight: 0.3 }),
        take(alice.id, 3, 'a3 inactive', { kind: 'take', holder: 'garry', active: false }),
      ]);
      await engine.addTakesBatch([
        take(acme.id, 1, 'c1 fact', { kind: 'fact', holder: 'world', weight: 1 }),
        take(acme.id, 2, 'c2 bet', { kind: 'bet', holder: 'garry', weight: 0.6 }),
      ]);
      await engine.resolveTake(acme.id, 2, { quality: 'correct', resolvedBy: 'garry' });
      const q = async (opts?: Parameters<BrainEngine['listTakes']>[0]) => sorted(claims(await engine.listTakes(opts)));
      const out = {
        defaultActive: await q(),
        inactive: await q({ active: false }),
        activeUndefinedIsActive: await q({ active: undefined }),
        byPageId: await q({ page_id: alice.id }),
        byPageSlug: await q({ page_slug: 'companies/acme-example' }),
        byHolder: await q({ holder: 'garry' }),
        byKind: await q({ kind: 'bet' }),
        resolved: await q({ resolved: true }),
        unresolved: await q({ resolved: false }),
        allowGarry: await q({ takesHoldersAllowList: ['garry'] }),
        allowNobody: await q({ takesHoldersAllowList: [] }),
        allowWorldAlice: await q({ takesHoldersAllowList: ['world', 'alice'] }),
        missingSlug: await q({ page_slug: 'people/nobody' }),
      };
      expect(out.defaultActive).toEqual(['a1 bet', 'a2 take', 'c1 fact', 'c2 bet']);
      expect(out.inactive).toEqual(['a3 inactive']);
      expect(out.resolved).toEqual(['c2 bet']);
      expect(out.allowNobody).toEqual([]);
      return out;
    },
  );

  parityTest(
    'listTakes orders newest-first by default and by weight or since_date on request; pages with limit/offset',
    { methods: ['putPage', 'addTakesBatch', 'listTakes'] },
    async (engine) => {
      const p = await page(engine, 'notes/standup');
      await engine.addTakesBatch([
        take(p.id, 1, 't-low', { weight: 0.2, since_date: '2026-03-01' }),
        take(p.id, 2, 't-high', { weight: 0.9, since_date: '2025-12-31' }),
        take(p.id, 3, 't-mid', { weight: 0.5, since_date: '2026-06-15' }),
        take(p.id, 4, 't-undated', { weight: 0.5 }),
        take(p.id, 5, 't-month', { weight: 0.1, since_date: '2026-02' }),
      ]);
      const q = async (opts?: Parameters<BrainEngine['listTakes']>[0]) => claims(await engine.listTakes(opts));
      const byDefault = await q();
      const byWeight = await q({ sortBy: 'weight' });
      const sinceNewest = await q({ sortBy: 'since_date' });
      const sinceOldest = await q({ sortBy: 'since_date', oldestFirst: true });
      const onOrBefore = sorted(await q({ sinceOnOrBefore: '2026-03-01' }));
      const paged = await q({ sortBy: 'since_date', limit: 2, offset: 1 });
      expect(byWeight[0]).toBe('t-high');
      expect(byWeight[4]).toBe('t-month');
      expect(sinceNewest).toEqual(['t-mid', 't-low', 't-month', 't-high', 't-undated']);
      expect(sinceOldest).toEqual(['t-high', 't-month', 't-low', 't-mid', 't-undated']);
      expect(onOrBefore).toEqual(['t-high', 't-low', 't-month']);
      expect(paged).toEqual(['t-low', 't-month']);
      return { byDefault, byWeight, sinceNewest, sinceOldest, onOrBefore, paged };
    },
  );

  parityTest(
    'listTakes scopes to a source through the take page',
    { methods: ['putPage', 'addTakesBatch', 'listTakes'] },
    async (engine, backend) => {
      await createSource(engine, backend, 'notes-src');
      const main = await page(engine, 'people/alice-example');
      const side = await page(engine, 'people/alice-example', { sourceId: 'notes-src' });
      await engine.addTakesBatch([take(main.id, 1, 'main source take')]);
      await engine.addTakesBatch([take(side.id, 1, 'side source take')]);
      const q = async (opts?: Parameters<BrainEngine['listTakes']>[0]) => sorted(claims(await engine.listTakes(opts)));
      const all = await q();
      const onlyMain = await q({ sourceId: 'default' });
      const onlySide = await q({ sourceId: 'notes-src' });
      const arrayWins = await q({ sourceId: 'default', sourceIds: ['notes-src'] });
      expect(all).toEqual(['main source take', 'side source take']);
      expect(onlyMain).toEqual(['main source take']);
      expect(onlySide).toEqual(['side source take']);
      expect(arrayWins).toEqual(['side source take']);
      return { all, onlyMain, onlySide, arrayWins };
    },
  );

  parityTest(
    'updateTake changes weight/since_date/source only, clamps weight, and rejects a missing row',
    { methods: ['putPage', 'addTakesBatch', 'updateTake', 'listTakes'] },
    async (engine) => {
      const p = await page(engine, 'people/alice-example');
      await engine.addTakesBatch([take(p.id, 1, 'Alice likes tea', { weight: 0.4, since_date: '2026-01-01', source: 'chat', holder: 'alice', kind: 'take' })]);
      const read = async () => tv((await engine.listTakes({ page_id: p.id }))[0]);
      await engine.updateTake(p.id, 1, { weight: 0.8 });
      const afterWeight = await read();
      await engine.updateTake(p.id, 1, { since_date: '2026-02-02', source: 'email' });
      const afterDateSource = await read();
      await engine.updateTake(p.id, 1, { weight: 9 });
      const afterClamp = await read();
      await engine.updateTake(p.id, 1, {});
      const afterNoop = await read();
      const missing = await errorCode(() => engine.updateTake(p.id, 99, { weight: 0.1 }));
      expect(afterWeight).toMatchObject({ weight: 0.8, since_date: '2026-01-01', source: 'chat', claim: 'Alice likes tea', holder: 'alice', kind: 'take' });
      expect(afterDateSource).toMatchObject({ weight: 0.8, since_date: '2026-02-02', source: 'email' });
      expect(afterClamp.weight).toBe(1);
      expect(afterNoop).toEqual(afterClamp);
      expect(missing).toBe('TAKE_ROW_NOT_FOUND');
      return { afterWeight, afterDateSource, afterClamp, afterNoop, missing };
    },
  );

  parityTest(
    'supersedeTake appends the new row, deactivates the old one, and refuses missing or resolved rows',
    { methods: ['putPage', 'addTakesBatch', 'supersedeTake', 'resolveTake', 'listTakes', 'listActiveTakesForPages'] },
    async (engine) => {
      const p = await page(engine, 'people/alice-example');
      await engine.addTakesBatch([
        take(p.id, 1, 'Alice will raise a seed', { kind: 'bet', weight: 0.6 }),
        take(p.id, 2, 'Alice likes tea'),
        take(p.id, 4, 'Row four exists already'),
      ]);
      const res = await engine.supersedeTake(p.id, 1, { claim: 'Alice will raise a Series A', kind: 'bet', holder: 'garry', weight: 0.8, since_date: '2026-05-01', source: 'update' });
      // next row_num is max+1, so it lands after the gap
      expect(res).toEqual({ oldRow: 1, newRow: 5 });
      const all = (await allTakes(engine, p.id)).map(tv);
      const active = claims(await engine.listTakes({ page_id: p.id }));
      const activeMap = await engine.listActiveTakesForPages([p.id]);
      expect(all.find((t) => t.row_num === 1)).toMatchObject({ active: false, superseded_by: 5 });
      expect(all.find((t) => t.row_num === 5)).toMatchObject({ active: true, claim: 'Alice will raise a Series A', weight: 0.8, superseded_by: null });
      expect(sorted(active)).toEqual(['Alice likes tea', 'Alice will raise a Series A', 'Row four exists already']);
      expect(claims(activeMap.get(p.id)!)).toEqual(['Alice likes tea', 'Row four exists already', 'Alice will raise a Series A']);

      await engine.resolveTake(p.id, 2, { quality: 'incorrect', resolvedBy: 'garry' });
      const resolvedErr = await errorCode(() => engine.supersedeTake(p.id, 2, { claim: 'x', kind: 'take', holder: 'garry' }));
      const missingErr = await errorCode(() => engine.supersedeTake(p.id, 77, { claim: 'x', kind: 'take', holder: 'garry' }));
      expect(resolvedErr).toBe('TAKE_RESOLVED_IMMUTABLE');
      expect(missingErr).toBe('TAKE_ROW_NOT_FOUND');
      return { res, all: sorted(all, (t) => String(t.row_num).padStart(3, '0')), resolvedErr, missingErr };
    },
  );

  parityTest(
    'resolveTake derives quality/outcome, stores resolution metadata, and is immutable',
    { methods: ['putPage', 'addTakesBatch', 'resolveTake', 'listTakes'] },
    async (engine) => {
      const p = await page(engine, 'companies/acme-example');
      await engine.addTakesBatch(
        [1, 2, 3, 4, 5, 6].map((n) => take(p.id, n, `bet ${n}`, { kind: 'bet', weight: 0.5 })),
      );
      await engine.resolveTake(p.id, 1, { quality: 'correct', value: 1200000, unit: 'usd', source: 'press release', resolvedBy: 'garry' });
      await engine.resolveTake(p.id, 2, { quality: 'incorrect', resolvedBy: 'garry' });
      await engine.resolveTake(p.id, 3, { quality: 'partial', resolvedBy: 'people/alice-example' });
      await engine.resolveTake(p.id, 4, { quality: 'unresolvable', resolvedBy: 'garry' });
      await engine.resolveTake(p.id, 5, { outcome: true, resolvedBy: 'garry' });
      await engine.resolveTake(p.id, 6, { outcome: false, resolvedBy: 'garry' });
      const rows = (await engine.listTakes({ page_id: p.id })).map(tv);
      const again = await errorCode(() => engine.resolveTake(p.id, 1, { quality: 'incorrect', resolvedBy: 'garry' }));
      const missing = await errorCode(() => engine.resolveTake(p.id, 42, { quality: 'correct', resolvedBy: 'garry' }));
      const noVerdict = await errorCode(() => engine.resolveTake(p.id, 1, { resolvedBy: 'garry' }));
      expect(again).toBe('TAKE_ALREADY_RESOLVED');
      expect(missing).toBe('TAKE_ROW_NOT_FOUND');
      const byRow = Object.fromEntries(rows.map((r) => [r.row_num, r]));
      expect(byRow[1]).toMatchObject({ resolved_quality: 'correct', resolved_outcome: true, resolved_value: 1200000, resolved_unit: 'usd', resolved_source: 'press release', resolved_by: 'garry', resolved: true });
      expect(byRow[2]).toMatchObject({ resolved_quality: 'incorrect', resolved_outcome: false });
      expect(byRow[3]).toMatchObject({ resolved_quality: 'partial', resolved_outcome: null, resolved_by: 'people/alice-example' });
      expect(byRow[4]).toMatchObject({ resolved_quality: 'unresolvable', resolved_outcome: null });
      expect(byRow[5]).toMatchObject({ resolved_quality: 'correct', resolved_outcome: true });
      expect(byRow[6]).toMatchObject({ resolved_quality: 'incorrect', resolved_outcome: false });
      return { rows: sorted(rows, (t) => String(t.row_num).padStart(3, '0')), again, missing, noVerdict };
    },
  );

  parityTest(
    'getScorecard counts bets, accuracy, Brier and partial/unresolvable rates, scoped by holder, domain, dates, allow-list and source',
    { methods: ['putPage', 'addTakesBatch', 'resolveTake', 'getScorecard'] },
    async (engine, backend) => {
      await createSource(engine, backend, 'side');
      const acme = await page(engine, 'companies/acme-example');
      const alice = await page(engine, 'people/alice-example');
      const side = await page(engine, 'companies/side-example', { sourceId: 'side' });
      await engine.addTakesBatch([
        take(acme.id, 1, 'acme b1', { kind: 'bet', holder: 'garry', weight: 0.9, since_date: '2026-01-10' }),
        take(acme.id, 2, 'acme b2', { kind: 'bet', holder: 'garry', weight: 0.7, since_date: '2026-02-10' }),
        take(acme.id, 3, 'acme b3', { kind: 'bet', holder: 'garry', weight: 0.2, since_date: '2026-03-10' }),
        take(acme.id, 4, 'acme b4', { kind: 'bet', holder: 'garry', weight: 0.5, since_date: '2026-04-10' }),
        take(acme.id, 5, 'acme b5', { kind: 'bet', holder: 'garry', weight: 0.5, since_date: '2026-05-10' }),
        take(acme.id, 6, 'acme take (not a bet)', { kind: 'take', holder: 'garry', weight: 0.5 }),
      ]);
      await engine.addTakesBatch([
        take(alice.id, 1, 'alice b1', { kind: 'bet', holder: 'alice', weight: 0.6, since_date: '2026-02-20' }),
        take(alice.id, 2, 'alice b2', { kind: 'bet', holder: 'alice', weight: 0.4, since_date: '2026-06-01' }),
      ]);
      await engine.addTakesBatch([take(side.id, 1, 'side b1', { kind: 'bet', holder: 'garry', weight: 0.8, since_date: '2026-02-01' })]);
      await engine.resolveTake(acme.id, 1, { quality: 'correct', resolvedBy: 'garry' });
      await engine.resolveTake(acme.id, 2, { quality: 'incorrect', resolvedBy: 'garry' });
      await engine.resolveTake(acme.id, 3, { quality: 'correct', resolvedBy: 'garry' });
      await engine.resolveTake(acme.id, 4, { quality: 'partial', resolvedBy: 'garry' });
      await engine.resolveTake(acme.id, 5, { quality: 'unresolvable', resolvedBy: 'garry' });
      await engine.resolveTake(alice.id, 1, { quality: 'correct', resolvedBy: 'garry' });
      await engine.resolveTake(side.id, 1, { quality: 'incorrect', resolvedBy: 'garry' });
      const card = async (opts: Parameters<BrainEngine['getScorecard']>[0], allow?: string[]) => {
        const c = await engine.getScorecard(opts, allow);
        return { ...c, accuracy: round(c.accuracy), brier: round(c.brier), partial_rate: round(c.partial_rate), unresolvable_rate: round(c.unresolvable_rate) };
      };
      const all = await card({}, undefined);
      const holderGarry = await card({ holder: 'garry' }, undefined);
      const holderAlice = await card({ holder: 'alice' }, undefined);
      const domain = await card({ domainPrefix: 'companies/' }, undefined);
      const since = await card({ since: '2026-03-01' }, undefined);
      const until = await card({ until: '2026-02-28' }, undefined);
      const allowAlice = await card({}, ['alice']);
      const allowNobody = await card({}, []);
      const mainSource = await card({ sourceId: 'default' }, undefined);
      const sideSource = await card({ sourceId: 'side' }, undefined);
      const bothSources = await card({ sourceIds: ['default', 'side'] }, undefined);
      const emptyBrainHolder = await card({ holder: 'nobody' }, undefined);
      // 8 bets total (5 acme + 2 alice + 1 side); acme resolved 1+2+3+4 (partial) ; correct 3 incl. alice
      expect(all).toMatchObject({ total_bets: 8, resolved: 6, correct: 3, incorrect: 2, partial: 1, unresolvable_count: 1 });
      expect(all.accuracy).toBe(round(3 / 5));
      expect(allowNobody).toMatchObject({ total_bets: 0, resolved: 0, accuracy: null, brier: null });
      expect(emptyBrainHolder).toMatchObject({ total_bets: 0, accuracy: null, brier: null });
      return { all, holderGarry, holderAlice, domain, since, until, allowAlice, allowNobody, mainSource, sideSource, bothSources, emptyBrainHolder };
    },
  );

  parityTest(
    'getCalibrationCurve bins resolved correct/incorrect bets by weight and honors holder, bucket size and allow-list',
    { methods: ['putPage', 'addTakesBatch', 'resolveTake', 'getCalibrationCurve'] },
    async (engine) => {
      const p = await page(engine, 'companies/acme-example');
      const weights: Array<[number, 'correct' | 'incorrect' | 'partial', string]> = [
        [0.9, 'correct', 'garry'], [0.95, 'correct', 'garry'], [0.9, 'incorrect', 'garry'],
        [0.7, 'correct', 'garry'], [0.7, 'incorrect', 'alice'], [0.3, 'incorrect', 'garry'],
        [0.35, 'correct', 'alice'], [0.5, 'partial', 'garry'], [1, 'correct', 'garry'], [0, 'incorrect', 'garry'],
      ];
      await engine.addTakesBatch(weights.map(([w, , holder], i) => take(p.id, i + 1, `cal ${i + 1}`, { kind: 'bet', weight: w, holder })));
      await engine.addTakesBatch([take(p.id, 50, 'unresolved bet', { kind: 'bet', weight: 0.6 })]);
      for (const [i, [, quality]] of weights.entries()) await engine.resolveTake(p.id, i + 1, { quality, resolvedBy: 'garry' });
      const norm = (rows: Awaited<ReturnType<BrainEngine['getCalibrationCurve']>>) =>
        rows.map((r) => ({ lo: round(r.bucket_lo), hi: round(r.bucket_hi), n: r.n, observed: round(r.observed), predicted: round(r.predicted) }));
      const dflt = norm(await engine.getCalibrationCurve({}, undefined));
      const coarse = norm(await engine.getCalibrationCurve({ bucketSize: 0.5 }, undefined));
      const garry = norm(await engine.getCalibrationCurve({ holder: 'garry' }, undefined));
      const allow = norm(await engine.getCalibrationCurve({}, ['alice']));
      const none = norm(await engine.getCalibrationCurve({}, []));
      const badSize = norm(await engine.getCalibrationCurve({ bucketSize: 5 }, undefined));
      expect(dflt.reduce((a, b) => a + b.n, 0)).toBe(9); // partial and unresolved excluded
      expect(dflt.find((b) => b.lo === 0.9)).toMatchObject({ hi: 1, n: 4 }); // 0.9,0.95,0.9 and 1 (final bucket is inclusive of 1.0)
      expect(none).toEqual([]);
      expect(badSize).toEqual(dflt);
      return { dflt, coarse, garry, allow, none, badSize };
    },
  );

  parityTest(
    'addSynthesisEvidence inserts provenance rows once per (synthesis, take page, take row)',
    { methods: ['putPage', 'addTakesBatch', 'addSynthesisEvidence'] },
    async (engine) => {
      const synthesis = await page(engine, 'notes/think-2026-07');
      const source = await page(engine, 'people/alice-example');
      await engine.addTakesBatch([take(source.id, 1, 'cited one'), take(source.id, 2, 'cited two'), take(source.id, 3, 'cited three')]);
      expect(await engine.addSynthesisEvidence([])).toBe(0);
      const first = await engine.addSynthesisEvidence([
        { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 1, citation_index: 1 },
        { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 2, citation_index: 2 },
      ]);
      const repeat = await engine.addSynthesisEvidence([
        { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 1, citation_index: 9 },
      ]);
      const mixed = await engine.addSynthesisEvidence([
        { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 2, citation_index: 5 },
        { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 3, citation_index: 3 },
      ]);
      expect([first, repeat, mixed]).toEqual([2, 0, 1]);
      return { first, repeat, mixed };
    },
  );

  parityTest(
    'listActiveTakesForPages groups active takes per page in row order, filters by allow-list, and keys empty pages',
    { methods: ['putPage', 'addTakesBatch', 'listActiveTakesForPages'] },
    async (engine) => {
      const a = await page(engine, 'people/alice-example');
      const b = await page(engine, 'people/bob-example');
      const empty = await page(engine, 'people/empty-example');
      await engine.addTakesBatch([
        take(a.id, 2, 'a second', { holder: 'alice' }),
        take(a.id, 1, 'a first', { holder: 'garry' }),
        take(a.id, 3, 'a inactive', { active: false }),
        take(b.id, 1, 'b only', { holder: 'garry' }),
      ]);
      const slugOf = new Map([[a.id, 'alice'], [b.id, 'bob'], [empty.id, 'empty'], [123456789, 'missing']]);
      const shape = (m: Map<number, Take[]>) => sorted([...m.entries()].map(([id, ts]) => `${slugOf.get(id)}=${claims(ts).join('|')}`));
      const all = shape(await engine.listActiveTakesForPages([a.id, b.id, empty.id, 123456789]));
      const garryOnly = shape(await engine.listActiveTakesForPages([a.id, b.id], { takesHoldersAllowList: ['garry'] }));
      const nobody = shape(await engine.listActiveTakesForPages([a.id], { takesHoldersAllowList: [] }));
      const none = (await engine.listActiveTakesForPages([])).size;
      expect(all).toEqual(['alice=a first|a second', 'bob=b only', 'empty=', 'missing=']);
      expect(none).toBe(0);
      return { all, garryOnly, nobody, none };
    },
  );

  parityTest(
    'searchTakes ranks active takes by trigram similarity and applies holder allow-list, source and limit',
    { methods: ['putPage', 'addTakesBatch', 'searchTakes'] },
    async (engine, backend) => {
      await createSource(engine, backend, 'side');
      const a = await page(engine, 'people/alice-example');
      const s = await page(engine, 'people/side-example', { sourceId: 'side' });
      await engine.addTakesBatch([
        take(a.id, 1, 'Alice loves rust programming', { holder: 'garry', weight: 0.5 }),
        take(a.id, 2, 'Bob writes rust daily', { holder: 'alice', weight: 0.9 }),
        take(a.id, 3, 'Gardening is relaxing', { holder: 'garry' }),
        take(a.id, 4, 'Retired rust opinion', { holder: 'garry', active: false }),
      ]);
      await engine.addTakesBatch([take(s.id, 1, 'Side project in rust', { holder: 'garry', weight: 0.1 })]);
      const norm = (hits: TakeHit[]) => hits.map((h) => ({ slug: h.page_slug, row: h.row_num, claim: h.claim, holder: h.holder, weight: h.weight, score: round(h.score) }));
      const rust = norm(await engine.searchTakes('rust'));
      const limited = norm(await engine.searchTakes('rust', { limit: 1 }));
      const allow = norm(await engine.searchTakes('rust', { takesHoldersAllowList: ['alice'] }));
      const noOne = norm(await engine.searchTakes('rust', { takesHoldersAllowList: [] }));
      const side = norm(await engine.searchTakes('rust', { sourceId: 'side' }));
      const miss = norm(await engine.searchTakes('zzzzqqqq'));
      expect(rust.map((h) => h.claim)).not.toContain('Retired rust opinion');
      expect(rust.map((h) => h.claim)).not.toContain('Gardening is relaxing');
      expect(rust).toHaveLength(3);
      expect(allow.map((h) => h.claim)).toEqual(['Bob writes rust daily']);
      expect(noOne).toEqual([]);
      expect(side.map((h) => h.claim)).toEqual(['Side project in rust']);
      expect(miss).toEqual([]);
      return { rust, limited, allow, noOne, side, miss };
    },
  );

  parityTest(
    'take embeddings: write, read back, vector search, and staleness accounting',
    {
      methods: [
        'putPage', 'addTakesBatch', 'listTakes', 'updateTakeEmbeddings', 'getTakeEmbeddings', 'searchTakesVector',
        'countStaleTakes', 'listStaleTakes',
      ],
    },
    async (engine, backend) => {
      await createSource(engine, backend, 'side');
      const a = await page(engine, 'people/alice-example');
      const s = await page(engine, 'people/side-example', { sourceId: 'side' });
      await engine.addTakesBatch([
        take(a.id, 1, 'axis zero take', { holder: 'garry', weight: 0.5 }),
        take(a.id, 2, 'axis one take', { holder: 'alice', weight: 0.5 }),
        take(a.id, 3, 'never embedded take'),
        take(a.id, 4, 'inactive take', { active: false }),
      ]);
      await engine.addTakesBatch([take(s.id, 1, 'side axis zero take')]);
      const ids = await takeIds(engine, a.id);
      const sideIds = await takeIds(engine, s.id);
      const nameOf = new Map<number, string>([...ids, ...sideIds].map(([claim, id]) => [id, claim]));
      const staleClaims = async (opts?: Parameters<BrainEngine['listStaleTakes']>[0]) => (await engine.listStaleTakes(opts)).map((r) => r.claim);

      const beforeAll = await engine.countStaleTakes();
      expect(beforeAll).toBe(4); // active takes only: 3 on alice + 1 on side
      expect(await engine.updateTakeEmbeddings([])).toBe(0);

      // the takes.embedding column is the configured embedding width (1536 on a default brain)
      // The side take leans a little toward axis 2, so no two takes tie on cosine score: vector
      // search orders by distance alone (the shape its HNSW index serves), and an exact tie may come
      // back in either order. Its largest component stays on axis 0.
      const sideVector = basisEmbedding(0);
      sideVector[2] = 0.3;
      const written = await engine.updateTakeEmbeddings([
        { take_id: ids.get('axis zero take')!, embedding: basisEmbedding(0), claim: 'axis zero take', model: 'embed-m1' },
        { take_id: ids.get('axis one take')!, embedding: basisEmbedding(1), claim: 'axis one take', model: 'embed-m1' },
        { take_id: sideIds.get('side axis zero take')!, embedding: sideVector, claim: 'side axis zero take', model: 'embed-m1' },
        // claim drifted while the vector was in flight: discarded
        { take_id: ids.get('never embedded take')!, embedding: basisEmbedding(2), claim: 'an older claim text', model: 'embed-m1' },
        // inactive rows are ignored
        { take_id: ids.get('inactive take')!, embedding: basisEmbedding(3), claim: 'inactive take', model: 'embed-m1' },
      ]);
      expect(written).toBe(3);

      const stored = await engine.getTakeEmbeddings([...ids.values(), ...sideIds.values(), 987654321]);
      const storedView = sorted([...stored.entries()].map(([id, v]) => `${nameOf.get(id)}:${v.length}:${v.indexOf(1)}`));
      expect(storedView).toEqual(['axis one take:1536:1', 'axis zero take:1536:0', 'side axis zero take:1536:0']);
      expect((await engine.getTakeEmbeddings([])).size).toBe(0);

      const stale = {
        count: await engine.countStaleTakes(),
        claims: await staleClaims(),
        otherModel: await engine.countStaleTakes({ model: 'embed-m2' }),
        sameModel: await engine.countStaleTakes({ model: 'embed-m1' }),
        wrongDims: await engine.countStaleTakes({ dims: 768 }),
        rightDims: await engine.countStaleTakes({ dims: 1536 }),
        sideOnly: await staleClaims({ sourceId: 'side' }),
        defaultOnly: await staleClaims({ sourceId: 'default' }),
      };
      expect(stale.claims).toEqual(['never embedded take']);
      expect(stale.otherModel).toBe(4);
      expect(stale.sameModel).toBe(1);
      expect(stale.wrongDims).toBe(4);
      expect(stale.rightDims).toBe(1);
      expect(stale.sideOnly).toEqual([]);

      // vector search: cosine against the stored vectors, active + embedded rows only
      // scores against the query: axis zero 0.995, side 0.953, axis one 0.0995 (strictly ordered)
      const hit = (hits: TakeHit[]) => hits.map((h) => ({ claim: h.claim, score: round(h.score) }));
      const nearZero = new Float32Array(1536);
      nearZero[0] = 1;
      nearZero[1] = 0.1;
      const nearest = hit(await engine.searchTakesVector(nearZero));
      const nearestOne = hit(await engine.searchTakesVector(nearZero, { limit: 1 }));
      const allow = hit(await engine.searchTakesVector(nearZero, { takesHoldersAllowList: ['alice'] }));
      const sideScoped = hit(await engine.searchTakesVector(nearZero, { sourceId: 'side' }));
      const noOne = hit(await engine.searchTakesVector(nearZero, { takesHoldersAllowList: [] }));
      expect(nearest.map((h) => h.claim)).toEqual(['axis zero take', 'side axis zero take', 'axis one take']);
      expect(nearestOne.map((h) => h.claim)).toEqual(['axis zero take']);
      expect(allow.map((h) => h.claim)).toEqual(['axis one take']);
      expect(sideScoped.map((h) => h.claim)).toEqual(['side axis zero take']);
      expect(noOne).toEqual([]);

      // editing a claim through the batch upsert clears its vector (stale again); an unchanged claim keeps it
      await engine.addTakesBatch([
        take(a.id, 1, 'axis zero take, reworded', { holder: 'garry', weight: 0.5 }),
        take(a.id, 2, 'axis one take', { holder: 'alice', weight: 0.5 }),
      ]);
      const afterEdit = {
        stale: sorted(await staleClaims()),
        embeddings: sorted([...(await engine.getTakeEmbeddings([...ids.values()])).keys()].map((id) => nameOf.get(id)!)),
      };
      expect(afterEdit.stale).toEqual(['axis zero take, reworded', 'never embedded take']);
      expect(afterEdit.embeddings).toEqual(['axis one take']);

      const dupErr = await errorCode(() => engine.updateTakeEmbeddings([
        { take_id: ids.get('axis one take')!, embedding: basisEmbedding(1), claim: 'axis one take', model: 'embed-m1' },
        { take_id: ids.get('axis one take')!, embedding: basisEmbedding(1), claim: 'axis one take', model: 'embed-m1' },
      ]));
      expect(dupErr).not.toBeNull();
      return { beforeAll, written, storedView, stale, nearest, nearestOne, allow, sideScoped, noOne, afterEdit, rejectsDuplicateIds: dupErr !== null };
    },
  );
});

describe('engine parity: contradiction probe runs and judge cache', () => {
  const runRow = (id: string, over: Record<string, unknown> = {}) => ({
    run_id: id, judge_model: 'judge-m1', prompt_version: 'v1', queries_evaluated: 20, queries_with_contradiction: 4,
    total_contradictions_flagged: 6, wilson_ci_lower: 0.08, wilson_ci_upper: 0.42, judge_errors_total: 1, cost_usd_total: 0.37,
    duration_ms: 1234, source_tier_breakdown: { curated: 3, bulk: 1 }, report_json: { notes: ['a', 'b'], nested: { ok: true } }, ...over,
  });
  type Run = ReturnType<typeof runRow>;

  parityTest(
    'writeContradictionsRun is idempotent on run_id; loadContradictionsTrend returns runs newest first with parsed JSON',
    { methods: ['writeContradictionsRun', 'loadContradictionsTrend'] },
    async (engine) => {
      // ran_at defaults to the database clock's now(), and loadContradictionsTrend keeps rows with
      // ran_at >= a cutoff taken from the JS clock. Wait until the JS clock is strictly past the
      // newest stored ran_at (millisecond ISO) before the next write or the days=0 read, so neither
      // newest-first order nor the empty window depends on how fast the calls ran.
      const waitPastNewestRun = async () => {
        const newest = Date.parse((await engine.loadContradictionsTrend(7))[0]!.ran_at);
        expect(Number.isFinite(newest)).toBe(true);
        while (Date.now() <= newest) await new Promise((r) => setTimeout(r, 1));
      };
      const wrote: boolean[] = [];
      wrote.push(await engine.writeContradictionsRun(runRow('run-a') as Run));
      await waitPastNewestRun();
      wrote.push(await engine.writeContradictionsRun(runRow('run-b', { queries_evaluated: 30, cost_usd_total: 1.5, report_json: {} }) as Run));
      await waitPastNewestRun();
      wrote.push(await engine.writeContradictionsRun(runRow('run-a', { queries_evaluated: 999 }) as Run)); // same run_id: no-op
      wrote.push(await engine.writeContradictionsRun(runRow('run-c', { judge_model: 'judge-m2', source_tier_breakdown: {} }) as Run));
      expect(wrote).toEqual([true, true, false, true]);
      const trend = await engine.loadContradictionsTrend(7);
      expect(trend.map((r) => r.run_id)).toEqual(['run-c', 'run-b', 'run-a']);
      expect(trend.find((r) => r.run_id === 'run-a')?.queries_evaluated).toBe(20); // not overwritten
      expect(typeof trend[0].ran_at).toBe('string');
      await waitPastNewestRun();
      const nothing = await engine.loadContradictionsTrend(0);
      expect(nothing).toEqual([]);
      return {
        wrote,
        trend: trend.map(({ ran_at: _ranAt, ...rest }) => rest),
        nothing,
      };
    },
  );

  const key = { chunk_a_hash: 'hash-a', chunk_b_hash: 'hash-b', model_id: 'judge-m1', prompt_version: 'v1', truncation_policy: 'head-2k' };

  parityTest(
    'judge cache: put/get by the full 5-part key, upsert refreshes the verdict, other keys miss',
    { methods: ['putContradictionCacheEntry', 'getContradictionCacheEntry', 'sweepContradictionCache'] },
    async (engine) => {
      const empty = await engine.getContradictionCacheEntry(key);
      await engine.putContradictionCacheEntry({ ...key, verdict: { contradicts: true, confidence: 0.9, axes: ['date', 'amount'] } });
      const hit = await engine.getContradictionCacheEntry(key);
      await engine.putContradictionCacheEntry({ ...key, verdict: { contradicts: false } });
      const updated = await engine.getContradictionCacheEntry(key);
      const misses = {
        otherA: await engine.getContradictionCacheEntry({ ...key, chunk_a_hash: 'hash-z' }),
        otherB: await engine.getContradictionCacheEntry({ ...key, chunk_b_hash: 'hash-z' }),
        otherModel: await engine.getContradictionCacheEntry({ ...key, model_id: 'judge-m2' }),
        otherPrompt: await engine.getContradictionCacheEntry({ ...key, prompt_version: 'v2' }),
        otherTruncation: await engine.getContradictionCacheEntry({ ...key, truncation_policy: 'tail-2k' }),
      };
      // a second key lives beside the first; a short ttl is floored to 60s, so it is still live
      await engine.putContradictionCacheEntry({ ...key, prompt_version: 'v2', verdict: { contradicts: true }, ttl_seconds: 1 });
      const shortTtl = await engine.getContradictionCacheEntry({ ...key, prompt_version: 'v2' });
      // nothing has expired, so a sweep removes nothing and the entries stay readable
      const swept = await engine.sweepContradictionCache();
      const stillThere = await engine.getContradictionCacheEntry(key);
      expect(empty).toBeNull();
      expect(hit).toEqual({ contradicts: true, confidence: 0.9, axes: ['date', 'amount'] });
      expect(updated).toEqual({ contradicts: false });
      expect(Object.values(misses).every((m) => m === null)).toBe(true);
      expect(shortTtl).toEqual({ contradicts: true });
      expect(swept).toBe(0);
      return { empty, hit, updated, misses, shortTtl, swept, stillThere };
    },
  );
});

describe('engine parity: dream verdict cache', () => {
  const verdict = (over: Record<string, unknown> = {}) => ({
    worth_processing: true, reasons: ['mentions a decision', 'names a person'], score: 0.82, content_type: 'meeting',
    segments: [{ quote: 'we will ship in Q3', note: 'commitment' }, { quote: 'Alice owns it' }],
    entities: ['people/alice-example', 'companies/acme-example'], model: 'triage-m1', triage_version: 1, ...over,
  });
  type Verdict = ReturnType<typeof verdict>;

  parityTest(
    'putDreamVerdict/getDreamVerdict round-trip by (file, hash); a re-put replaces; sweep spares live rows',
    { methods: ['putDreamVerdict', 'getDreamVerdict', 'sweepDreamVerdicts'] },
    async (engine) => {
      const miss = await engine.getDreamVerdict('transcripts/a.md', 'h1');
      await engine.putDreamVerdict('transcripts/a.md', 'h1', verdict() as Verdict);
      const hit = await engine.getDreamVerdict('transcripts/a.md', 'h1');
      await engine.putDreamVerdict('transcripts/a.md', 'h1', verdict({ worth_processing: false, reasons: [], score: 0.1, content_type: null, segments: [], entities: [], model: 'triage-m2', triage_version: 2 }) as Verdict);
      const replaced = await engine.getDreamVerdict('transcripts/a.md', 'h1');
      // a backoff marker: no score, still stored
      await engine.putDreamVerdict('transcripts/b.md', 'h9', verdict({ score: null, worth_processing: false }) as Verdict);
      const backoff = await engine.getDreamVerdict('transcripts/b.md', 'h9');
      const otherHash = await engine.getDreamVerdict('transcripts/a.md', 'h2');
      const otherFile = await engine.getDreamVerdict('transcripts/c.md', 'h1');
      const swept = await engine.sweepDreamVerdicts();
      const afterSweep = await engine.getDreamVerdict('transcripts/a.md', 'h1');
      const strip = <T extends { judged_at: string } | null>(v: T) => (v ? { ...v, judged_at: typeof v.judged_at === 'string' && v.judged_at.length > 0 ? '<ts>' : v.judged_at } : v);
      expect(miss).toBeNull();
      expect(hit).toMatchObject({ worth_processing: true, reasons: ['mentions a decision', 'names a person'], score: 0.82, content_type: 'meeting', model: 'triage-m1', triage_version: 1 });
      expect(hit?.segments).toEqual([{ quote: 'we will ship in Q3', note: 'commitment' }, { quote: 'Alice owns it' }]);
      expect(replaced).toMatchObject({ worth_processing: false, reasons: [], score: 0.1, segments: [], entities: [], model: 'triage-m2', triage_version: 2 });
      expect(backoff?.score).toBeNull();
      expect(otherHash).toBeNull();
      expect(otherFile).toBeNull();
      expect(swept).toBe(0);
      expect(afterSweep).not.toBeNull();
      return { miss, hit: strip(hit), replaced: strip(replaced), backoff: strip(backoff), otherHash, otherFile, swept, afterSweep: strip(afterSweep) };
    },
  );
});