Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
35.0 KB
Raw Blame
/**
 * BrainEngine parity — links family (edges, derived-link replacement, graph
 * traversal, relational fan-out, backlink/adjacency signals, page-id signal
 * reads, orphans).
 *
 * Authoring gate (docs/TESTING.md#authoring-gate):
 *  - Contract: every link write, link read, traversal and page-id signal read
 *    returns 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 edge dedup, removal counts, link
 *    provenance, traversal order/cycle handling, source isolation, backlink
 *    counts or orphan detection — the graph layer search ranking, `gbrain
 *    graph-query` and `gbrain orphans` read from.
 *  - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips
 *    entirely without Postgres and its graph cases hand-roll each engine; the
 *    per-engine unit tests never compare two engines on one scenario.
 *  - Seam: none. Real engines, typed methods only (no executeRaw: D18).
 *    Page ids come from putPage's returned Page and are mapped back to slugs
 *    before anything is returned (sequences are not reset on Postgres).
 */
import { describe, expect } from 'bun:test';
import type { BrainEngine, LinkBatchInput } from '../../src/core/engine.ts';
import type { Link, PageInput, PageType } from '../../src/core/types.ts';
import { linkFamily } from '../../src/core/search/relational-chain.ts';
import { createSource, parityArms, pick, sorted } from './harness.ts';
import { testBackends } from '../helpers/test-backends.ts';

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

const LINK_KEYS = ['from_slug', 'from_source_id', 'to_slug', 'to_source_id', 'link_type', 'context', 'link_source', 'origin_slug', 'origin_source_id', 'origin_field'] as const;

const linkView = (l: Link) => pick(l, LINK_KEYS);
const linkViews = (rows: Link[]) => rows.map(linkView);
const linkKey = (l: { from_slug: string; to_slug: string; link_type: string; link_source?: string | null }) =>
  `${l.from_slug}>${l.to_slug}:${l.link_type}:${l.link_source ?? ''}`;
const sortedLinks = (rows: Link[]) => sorted(linkViews(rows), (l) => `${linkKey(l)}|${l.origin_slug ?? ''}`);

function page(title: string, extra: Partial<PageInput> = {}): PageInput {
  return { type: 'note', title, compiled_truth: `${title} body`, timeline: '', ...extra };
}

async function seedPages(engine: BrainEngine, slugs: string[], type: PageType = 'note', opts?: { sourceId?: string }) {
  const ids = new Map<string, number>();
  for (const slug of slugs) ids.set(slug, (await engine.putPage(slug, page(slug, { type }), opts)).id);
  return ids;
}

/** Map a page-id keyed Map back to slug keys, sorted. */
function bySlug<V>(ids: Map<string, number>, m: Map<number, V>): Array<[string, V]> {
  const slugOf = new Map([...ids].map(([slug, id]) => [id, slug]));
  return sorted([...m].map(([id, v]) => [slugOf.get(id) ?? `<unknown ${id}>`, v] as [string, V]), ([s]) => s);
}

/** Seed: a -> b -> a (cycle), b -> c -> d chain. */
async function seedChain(engine: BrainEngine) {
  await seedPages(engine, ['tg/a', 'tg/b', 'tg/c', 'tg/d']);
  await engine.addLink('tg/a', 'tg/b', 'fwd-ctx', 'cycle-fwd', 'manual');
  await engine.addLink('tg/b', 'tg/a', 'back-ctx', 'cycle-back', 'manual');
  await engine.addLink('tg/b', 'tg/c', 'step-ctx', 'step', 'manual');
  await engine.addLink('tg/c', 'tg/d', 'deep-ctx', 'deep', 'manual');
}

describe('engine parity: links', () => {
  parityTest(
    'addLink then getLinks/getBacklinks round-trip with provenance; duplicates are idempotent',
    { methods: ['addLink', 'getLinks', 'getBacklinks', 'putPage'] },
    async (engine) => {
      await seedPages(engine, ['people/alice', 'companies/acme', 'notes/memo']);
      await engine.addLink('people/alice', 'companies/acme', 'Alice works at Acme', 'works_at', 'manual');
      await engine.addLink('people/alice', 'companies/acme', 'Alice works at Acme', 'works_at', 'manual');
      await engine.addLink('people/alice', 'companies/acme', 'invested', 'invested_in', 'manual');
      // Defaults: link_type '' and link_source 'markdown'.
      await engine.addLink('notes/memo', 'people/alice', 'memo mentions alice');
      await engine.addLink('companies/acme', 'people/alice', 'fm', 'key_people', 'frontmatter', 'companies/acme', 'key_people');

      const out = sortedLinks(await engine.getLinks('people/alice'));
      const back = sortedLinks(await engine.getBacklinks('people/alice'));
      expect(out.map(linkKey)).toEqual(['people/alice>companies/acme:invested_in:manual', 'people/alice>companies/acme:works_at:manual']);
      expect(back.map((l) => l.from_slug)).toEqual(['companies/acme', 'notes/memo']);
      const fm = back.find((l) => l.link_source === 'frontmatter');
      expect(fm).toMatchObject({ origin_slug: 'companies/acme', origin_field: 'key_people' });
      const memo = back.find((l) => l.from_slug === 'notes/memo');
      expect(memo?.link_source).toBe('markdown');
      expect(await engine.getLinks('companies/nobody')).toEqual([]);
      return { out, back, none: await engine.getBacklinks('notes/memo') };
    },
  );

  parityTest(
    'addLinksBatch inserts new edges, dedups conflicts and drops edges to missing pages',
    { methods: ['addLinksBatch', 'getLinks', 'putPage'] },
    async (engine) => {
      await seedPages(engine, ['b/one', 'b/two', 'b/three']);
      const batch: LinkBatchInput[] = [
        { from_slug: 'b/one', to_slug: 'b/two', link_type: 'cites', context: 'c1', link_source: 'manual' },
        { from_slug: 'b/one', to_slug: 'b/three', link_type: 'cites', context: 'c2', link_source: 'manual' },
        { from_slug: 'b/one', to_slug: 'b/missing', link_type: 'cites', link_source: 'manual' },
        { from_slug: 'b/two', to_slug: 'b/three' },
      ];
      const first = await engine.addLinksBatch(batch);
      const replay = await engine.addLinksBatch(batch);
      const empty = await engine.addLinksBatch([]);
      expect(first).toBe(3);
      expect(replay).toBe(0);
      expect(empty).toBe(0);
      const one = sortedLinks(await engine.getLinks('b/one'));
      const two = sortedLinks(await engine.getLinks('b/two'));
      return { first, replay, empty, one, two };
    },
  );

  parityTest(
    'removeLink honors link type and provenance and returns the deleted row count',
    { methods: ['removeLink', 'addLink', 'getLinks', 'putPage'] },
    async (engine) => {
      await seedPages(engine, ['r/from', 'r/to']);
      const seed = async () => {
        await engine.addLink('r/from', 'r/to', 'x', 'cites', 'manual');
        await engine.addLink('r/from', 'r/to', 'y', 'cites', 'markdown');
        await engine.addLink('r/from', 'r/to', 'z', 'mentions', 'manual');
      };
      await seed();
      const typo = await engine.removeLink('r/from', 'r/typo');
      const wrongType = await engine.removeLink('r/from', 'r/to', 'nope');
      const wrongSource = await engine.removeLink('r/from', 'r/to', 'cites', 'frontmatter');
      expect(typo).toBe(0);
      expect(wrongType).toBe(0);
      expect(wrongSource).toBe(0);
      const typed = await engine.removeLink('r/from', 'r/to', 'cites', 'manual');
      expect(typed).toBe(1);
      const afterTyped = sortedLinks(await engine.getLinks('r/from')).map(linkKey);
      const allTypes = await engine.removeLink('r/from', 'r/to');
      expect(allTypes).toBe(2);
      const afterAll = await engine.getLinks('r/from');
      expect(afterAll).toEqual([]);
      const again = await engine.removeLink('r/from', 'r/to');
      await seed();
      const bySource = await engine.removeLink('r/from', 'r/to', undefined, 'manual');
      const left = sortedLinks(await engine.getLinks('r/from')).map(linkKey);
      return { typo, wrongType, wrongSource, typed, afterTyped, allTypes, again, bySource, left };
    },
  );

  parityTest(
    'removeLinksByPagesAndSource deletes only the named provenance for the named pages',
    { methods: ['removeLinksByPagesAndSource', 'addLink', 'getLinks', 'putPage'] },
    async (engine) => {
      await seedPages(engine, ['m/a', 'm/b', 'm/c']);
      await engine.addLink('m/a', 'm/b', '', 'mentions', 'mentions');
      await engine.addLink('m/a', 'm/c', '', 'mentions', 'mentions');
      await engine.addLink('m/a', 'm/c', '', 'cites', 'manual');
      await engine.addLink('m/b', 'm/c', '', 'mentions', 'mentions');
      const none = await engine.removeLinksByPagesAndSource([], { linkSource: 'mentions' });
      const wrongSource = await engine.removeLinksByPagesAndSource([{ slug: 'm/a', source_id: 'nope' }], { linkSource: 'mentions' });
      expect(none).toBe(0);
      expect(wrongSource).toBe(0);
      // A keep list only protects typed_ner rows; mentions rows are removed regardless.
      const removed = await engine.removeLinksByPagesAndSource(
        [{ slug: 'm/a', source_id: 'default' }],
        { linkSource: 'mentions', keepTypedNerPairs: [{ from_slug: 'm/a', from_source_id: 'default', to_slug: 'm/b', to_source_id: 'default' }] },
      );
      expect(removed).toBe(2);
      return {
        none, wrongSource, removed,
        a: sortedLinks(await engine.getLinks('m/a')).map(linkKey),
        b: sortedLinks(await engine.getLinks('m/b')).map(linkKey),
      };
    },
  );

  parityTest(
    'listLinkSources counts edges per provenance, count DESC then name ASC',
    { methods: ['listLinkSources', 'addLink', 'putPage'] },
    async (engine) => {
      await seedPages(engine, ['ls/a', 'ls/b', 'ls/c']);
      await engine.addLink('ls/a', 'ls/b', '', 'cites', 'citation-graph');
      await engine.addLink('ls/a', 'ls/c', '', 'cites', 'citation-graph');
      await engine.addLink('ls/b', 'ls/c', '', 'rel', 'manual');
      await engine.addLink('ls/c', 'ls/a', '', 'rel', 'markdown');
      const scoped = await engine.listLinkSources({ sourceId: 'default' });
      const federated = await engine.listLinkSources({ sourceIds: ['default'] });
      const other = await engine.listLinkSources({ sourceId: 'no-such-source' });
      expect(scoped.map((r) => r.link_source)).toEqual(['citation-graph', 'manual', 'markdown']);
      expect(other).toEqual([]);
      return { scoped, federated, other };
    },
  );

  parityTest(
    'findByTitleFuzzy returns the best title match above the threshold, honoring prefix and source',
    { methods: ['findByTitleFuzzy', 'putPage'] },
    async (engine) => {
      await engine.putPage('people/alice-example', page('Alice Example', { type: 'person' }));
      await engine.putPage('people/alicia-example', page('Alicia Exampel', { type: 'person' }));
      await engine.putPage('companies/acme-example', page('Acme Example', { type: 'company' }));
      const exact = await engine.findByTitleFuzzy('Alice Example');
      const typo = await engine.findByTitleFuzzy('Alice Exmple', 'people');
      const wrongPrefix = await engine.findByTitleFuzzy('Alice Example', 'companies', 0.9);
      const none = await engine.findByTitleFuzzy('Totally Unrelated Zebra');
      const scoped = await engine.findByTitleFuzzy('Acme Example', 'companies', 0.55, 'default');
      const otherSource = await engine.findByTitleFuzzy('Acme Example', undefined, 0.55, 'no-such-source');
      expect(exact?.slug).toBe('people/alice-example');
      expect(exact?.similarity).toBeGreaterThan(0.9);
      expect(none).toBeNull();
      expect(otherSource).toBeNull();
      return {
        exact: exact && { slug: exact.slug, similarity: Math.round(exact.similarity * 1000) / 1000 },
        typo: typo?.slug,
        wrongPrefix: wrongPrefix?.slug ?? null,
        none,
        scoped: scoped?.slug,
        otherSource,
      };
    },
  );

  parityTest(
    'replaceDerivedLinks swaps one origin\'s derived edges and leaves manual edges alone',
    { methods: ['replaceDerivedLinks', 'readPageSnapshot', 'addLink', 'getLinks', 'putPage'] },
    async (engine) => {
      await seedPages(engine, ['d/origin', 'd/one', 'd/two', 'd/three']);
      await engine.addLink('d/origin', 'd/three', 'manual keep', 'cites', 'manual');
      const origin = async () => {
        const snap = await engine.readPageSnapshot('d/origin', { sourceId: 'default' });
        expect(snap).not.toBeNull();
        return { slug: 'd/origin', sourceId: 'default', expectedRevision: snap!.revision, sourceIncarnation: snap!.sourceIncarnation };
      };
      const first = await engine.replaceDerivedLinks(await origin(), [
        { from_slug: 'd/origin', to_slug: 'd/one', link_type: 'cites', context: 'one', link_source: 'markdown' },
        { from_slug: 'd/origin', to_slug: 'd/two', link_type: 'cites', context: 'two', link_source: 'markdown' },
        { from_slug: 'd/origin', to_slug: 'd/two', link_type: 'cites', context: 'dup', link_source: 'markdown' },
      ]);
      const afterFirst = sortedLinks(await engine.getLinks('d/origin')).map(linkKey);
      const second = await engine.replaceDerivedLinks(await origin(), [
        { from_slug: 'd/origin', to_slug: 'd/one', link_type: 'cites', context: 'one', link_source: 'markdown' },
      ]);
      const afterSecond = sortedLinks(await engine.getLinks('d/origin')).map(linkKey);
      const cleared = await engine.replaceDerivedLinks(await origin(), []);
      const afterClear = sortedLinks(await engine.getLinks('d/origin')).map(linkKey);
      expect(first).toEqual({ created: 2, removed: 0 });
      expect(afterClear).toEqual(['d/origin>d/three:cites:manual']);
      return { first, afterFirst, second, afterSecond, cleared, afterClear };
    },
  );

  parityTest(
    'replaceDerivedLinksBatch replaces many origins in one call',
    { methods: ['replaceDerivedLinksBatch', 'readPageSnapshot', 'getLinks', 'putPage'] },
    async (engine) => {
      await seedPages(engine, ['e/a', 'e/b', 'e/t1', 'e/t2']);
      const origin = async (slug: string) => {
        const snap = await engine.readPageSnapshot(slug, { sourceId: 'default' });
        return { slug, sourceId: 'default', expectedRevision: snap!.revision, sourceIncarnation: snap!.sourceIncarnation };
      };
      const items = [
        { origin: await origin('e/a'), links: [{ from_slug: 'e/a', to_slug: 'e/t1', link_type: 'cites', link_source: 'markdown' }] },
        { origin: await origin('e/b'), links: [
          { from_slug: 'e/b', to_slug: 'e/t1', link_type: 'cites', link_source: 'markdown' },
          { from_slug: 'e/b', to_slug: 'e/t2', link_type: 'cites', link_source: 'markdown' },
        ] },
      ];
      const results = await engine.replaceDerivedLinksBatch(items);
      const empty = await engine.replaceDerivedLinksBatch([]);
      expect(results).toEqual([{ created: 1, removed: 0 }, { created: 2, removed: 0 }]);
      const rerun = await engine.replaceDerivedLinksBatch([{ origin: await origin('e/b'), links: [] }]);
      return {
        results, empty, rerun,
        a: sortedLinks(await engine.getLinks('e/a')).map(linkKey),
        b: sortedLinks(await engine.getLinks('e/b')).map(linkKey),
      };
    },
  );

  parityTest(
    'getLinks/getBacklinks hide soft-deleted endpoints and respect source scope',
    { methods: ['getLinks', 'getBacklinks', 'addLink', 'softDeletePage', 'restorePage', 'putPage'] },
    async (engine, backend) => {
      await createSource(engine, backend, 'alt');
      await seedPages(engine, ['s/from', 's/to']);
      await seedPages(engine, ['s/alt-doc'], 'note', { sourceId: 'alt' });
      await engine.addLink('s/from', 's/to', 'ctx', 'wikilink');
      await engine.addLink('s/from', 's/alt-doc', 'cross', 'cites', 'manual', undefined, undefined, { fromSourceId: 'default', toSourceId: 'alt' });
      const unscoped = sortedLinks(await engine.getLinks('s/from')).map(linkKey);
      const scalar = sortedLinks(await engine.getLinks('s/from', { sourceId: 'default' })).map(linkKey);
      // A federated grant constrains BOTH endpoints: the alt target must not leak.
      const grant = sortedLinks(await engine.getLinks('s/from', { sourceIds: ['default'] })).map(linkKey);
      const altBack = linkViews(await engine.getBacklinks('s/alt-doc', { sourceId: 'alt' }));
      const grantBack = await engine.getBacklinks('s/alt-doc', { sourceIds: ['alt'] });
      expect(grant).toEqual(['s/from>s/to:wikilink:markdown']);
      expect(grantBack).toEqual([]);
      await engine.softDeletePage('s/from');
      const hiddenOut = await engine.getLinks('s/from');
      const hiddenBack = await engine.getBacklinks('s/to');
      expect(hiddenOut).toEqual([]);
      expect(hiddenBack).toEqual([]);
      await engine.restorePage('s/from');
      const restoredBack = (await engine.getBacklinks('s/to')).map(linkKey);
      return { unscoped, scalar, grant, altBack, grantBack, hiddenOut, hiddenBack, restoredBack };
    },
  );
});

describe('engine parity: graph traversal', () => {
  const nodeShape = (nodes: Awaited<ReturnType<BrainEngine['traverseGraph']>>) =>
    sorted(nodes.map((n) => `${n.source_id}:${n.slug}@${n.depth}[${n.links.map((l) => `${l.to_slug}:${l.link_type}`).sort().join(',')}]`));
  // Not sorted: ORDER BY depth, from_slug, to_slug is part of the traversePaths contract.
  const edgeShape = (paths: Awaited<ReturnType<BrainEngine['traversePaths']>>) =>
    paths.map((p) => `${p.from_slug}>${p.to_slug}:${p.link_type}@${p.depth}`);

  parityTest(
    'traverseGraph returns identical nodes for depth 1..3 and survives a cycle',
    { methods: ['traverseGraph'] },
    async (engine) => {
      await seedChain(engine);
      const byDepth: Record<number, string[]> = {};
      for (const depth of [1, 2, 3]) byDepth[depth] = nodeShape(await engine.traverseGraph('tg/a', depth));
      const deep = nodeShape(await engine.traverseGraph('tg/a', 10));
      const missing = await engine.traverseGraph('tg/nope', 3);
      expect(deep.map((n) => n.split('@')[0])).toEqual(['default:tg/a', 'default:tg/b', 'default:tg/c', 'default:tg/d']);
      expect(missing).toEqual([]);
      return { byDepth, deep, missing };
    },
  );

  parityTest(
    'traverseGraph source scope keeps cross-source nodes out of a scoped walk',
    { methods: ['traverseGraph', 'addLink', 'putPage'] },
    async (engine, backend) => {
      await createSource(engine, backend, 'tg-alt');
      await seedChain(engine);
      await seedPages(engine, ['tg/x'], 'note', { sourceId: 'tg-alt' });
      await engine.addLink('tg/b', 'tg/x', 'x-ctx', 'xsrc', 'manual', undefined, undefined, { fromSourceId: 'default', toSourceId: 'tg-alt' });
      const unscoped = nodeShape(await engine.traverseGraph('tg/a', 3));
      const scalar = nodeShape(await engine.traverseGraph('tg/a', 3, { sourceId: 'default' }));
      const federated = nodeShape(await engine.traverseGraph('tg/a', 3, { sourceIds: ['default'] }));
      const both = nodeShape(await engine.traverseGraph('tg/a', 3, { sourceIds: ['default', 'tg-alt'] }));
      expect(unscoped.some((n) => n.includes('tg-alt:tg/x'))).toBe(true);
      expect(scalar.some((n) => n.includes('tg/x'))).toBe(false);
      expect(federated).toEqual(scalar);
      return { unscoped, scalar, federated, both };
    },
  );

  parityTest(
    'traversePaths returns ordered edges across depth and direction, with link type filter',
    { methods: ['traversePaths'] },
    async (engine) => {
      await seedChain(engine);
      const out: Record<string, string[]> = {};
      for (const depth of [1, 2, 3]) {
        for (const direction of ['in', 'out', 'both'] as const) {
          out[`${direction}@${depth}`] = edgeShape(await engine.traversePaths('tg/b', { depth, direction }));
        }
      }
      const typed = edgeShape(await engine.traversePaths('tg/a', { depth: 5, direction: 'out', linkType: 'cycle-fwd' }));
      const typedMiss = await engine.traversePaths('tg/a', { depth: 5, direction: 'out', linkType: 'no-such-type' });
      const context = (await engine.traversePaths('tg/c', { depth: 1, direction: 'out' })).map((p) => pick(p, ['from_slug', 'to_slug', 'link_type', 'context', 'depth', 'from_source_id', 'to_source_id']));
      expect(out['out@1']).toEqual(['tg/b>tg/a:cycle-back@1', 'tg/b>tg/c:step@1']);
      expect(typed).toEqual(['tg/a>tg/b:cycle-fwd@1']);
      expect(typedMiss).toEqual([]);
      return { out, typed, typedMiss, context };
    },
  );

  parityTest(
    'traversePaths source scope: scalar and federated grants stop at the source boundary',
    { methods: ['traversePaths', 'addLink', 'putPage'] },
    async (engine, backend) => {
      await createSource(engine, backend, 'tg-alt');
      await seedChain(engine);
      await seedPages(engine, ['tg/x'], 'note', { sourceId: 'tg-alt' });
      await engine.addLink('tg/b', 'tg/x', 'x-ctx', 'xsrc', 'manual', undefined, undefined, { fromSourceId: 'default', toSourceId: 'tg-alt' });
      const unscoped = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'out' }));
      const scalar = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'out', sourceId: 'default' }));
      const federated = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'out', sourceIds: ['default'] }));
      expect(unscoped.some((e) => e.includes('tg/x'))).toBe(true);
      expect(scalar.some((e) => e.includes('tg/x'))).toBe(false);
      return { unscoped, scalar, federated };
    },
  );

  parityTest(
    'traversePathsDetailed reports the paths and an untruncated walk',
    { methods: ['traversePathsDetailed'] },
    async (engine) => {
      await seedChain(engine);
      const shallow = await engine.traversePathsDetailed('tg/a', { depth: 1, direction: 'both' });
      const deep = await engine.traversePathsDetailed('tg/a', { depth: 4, direction: 'out' });
      const scoped = await engine.traversePathsDetailed('tg/a', { depth: 4, direction: 'out', sourceIds: ['default'], linkType: 'step' });
      expect(shallow.truncated).toBe(false);
      expect(deep.truncated).toBe(false);
      return { shallow: edgeShape(shallow.paths), deep: edgeShape(deep.paths), scoped: edgeShape(scoped.paths), truncated: [shallow.truncated, deep.truncated, scoped.truncated] };
    },
  );

  parityTest(
    'traversal hides soft-deleted pages and recovers them after restore',
    { methods: ['traverseGraph', 'traversePaths', 'softDeletePage', 'restorePage'] },
    async (engine) => {
      await seedChain(engine);
      await engine.softDeletePage('tg/b');
      const graph = nodeShape(await engine.traverseGraph('tg/a', 3));
      const paths = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'both' }));
      const fromDeleted = await engine.traversePaths('tg/b', { depth: 3, direction: 'out' });
      expect(paths).toEqual([]);
      expect(fromDeleted).toEqual([]);
      await engine.restorePage('tg/b');
      const restored = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'out' }));
      expect(restored.length).toBeGreaterThan(0);
      return { graph, paths, fromDeleted, restored };
    },
  );
});

describe('engine parity: relational fan-out', () => {
  async function seedRelational(engine: BrainEngine) {
    const ids = new Map<string, number>();
    const pages: Array<[string, PageType]> = [
      ['companies/ep-widget', 'company'], ['companies/ep-other', 'company'],
      ['people/ep-inv-a', 'person'], ['people/ep-inv-b', 'person'], ['people/ep-emp-c', 'person'], ['people/ep-mentioner', 'person'],
    ];
    for (const [slug, type] of pages) ids.set(slug, (await engine.putPage(slug, page(slug, { type }))).id);
    await engine.addLink('people/ep-inv-a', 'companies/ep-widget', '', 'invested_in', 'manual');
    await engine.addLink('people/ep-inv-b', 'companies/ep-widget', '', 'invested_in', 'manual');
    await engine.addLink('people/ep-emp-c', 'companies/ep-widget', '', 'works_at', 'manual');
    await engine.addLink('people/ep-mentioner', 'companies/ep-widget', '', 'mentions', 'mentions');
    await engine.addLink('people/ep-inv-a', 'companies/ep-other', '', 'invested_in', 'manual');
    return ids;
  }
  // canonical_chunk_id is a serial id: compare its presence only.
  const shape = (rows: Awaited<ReturnType<BrainEngine['relationalFanout']>>) =>
    rows.map((r) => `${r.source_id}:${r.slug}:${r.hop}:${r.edge_count}:${r.via_link_types.join(',')}:${r.path.join('>')}:${r.canonical_chunk_id != null ? 'chunk' : 'nochunk'}`);

  parityTest(
    'relationalFanout walks typed edges, excludes mentions by default and orders deterministically',
    { methods: ['relationalFanout', 'upsertChunks'] },
    async (engine) => {
      await seedRelational(engine);
      await engine.upsertChunks('people/ep-inv-b', [{ chunk_index: 0, chunk_text: 'inv b chunk', chunk_source: 'compiled_truth', token_count: 3 }]);
      const typed = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in', linkTypes: ['invested_in'] }));
      const agnostic = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in' }));
      const withMentions = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in', includeMentions: true }));
      const connects = shape(await engine.relationalFanout(['companies/ep-widget', 'companies/ep-other'], { direction: 'both' }));
      const limited = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in', limit: 1 }));
      const scoped = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in', sourceIds: ['no-such-source'] }));
      expect(typed.map((r) => r.split(':')[1])).toEqual(['people/ep-inv-a', 'people/ep-inv-b']);
      expect(agnostic.some((r) => r.includes('ep-mentioner'))).toBe(false);
      expect(withMentions.some((r) => r.includes('ep-mentioner'))).toBe(true);
      expect(limited.length).toBe(1);
      expect(scoped).toEqual([]);
      return { typed, agnostic, withMentions, connects, limited, scoped };
    },
  );

  parityTest(
    'relationalChainHop orients and collapses edges from frontier page ids',
    { methods: ['relationalChainHop', 'addLink'] },
    async (engine) => {
      const ids = await seedRelational(engine);
      await engine.addLink('companies/ep-widget', 'people/ep-emp-c', 'founded by c', 'founded', 'markdown');
      const slugOf = new Map([...ids].map(([slug, id]) => [id, slug]));
      const edgeView = (edges: Awaited<ReturnType<BrainEngine['relationalChainHop']>>) => edges.map((e) => ({
        from: slugOf.get(e.from_page_id),
        to: e.to_slug,
        to_type: e.to_type,
        link_type: e.link_type,
        orientation: e.orientation,
        link_count: e.link_ids.length,
        stored_from: e.stored_from_slug,
        stored_to: e.stored_to_slug,
        context: e.context,
        from_degree: e.from_degree,
        neighbor_cap_hit: e.neighbor_cap_hit,
      }));
      const toObject = edgeView(await engine.relationalChainHop([ids.get('people/ep-inv-a')!], {
        linkTypes: linkFamily('invested_in'), toward: 'object', subjectTypes: ['company', 'person'],
        objectTypes: ['company', 'deal'], degreeLinkTypes: ['invested_in', 'founded'], neighborCap: 100,
      }));
      const toSubject = edgeView(await engine.relationalChainHop([ids.get('companies/ep-widget')!], {
        linkTypes: ['founded'], toward: 'subject', subjectTypes: ['person'], objectTypes: ['company'],
        degreeLinkTypes: ['founded'], neighborCap: 100,
      }));
      const capped = edgeView(await engine.relationalChainHop([ids.get('companies/ep-widget')!], {
        linkTypes: linkFamily('invested_in'), toward: 'subject', subjectTypes: ['person', 'company'],
        objectTypes: ['company', 'deal'], degreeLinkTypes: ['invested_in'], neighborCap: 1,
      }));
      const empty = await engine.relationalChainHop([], {
        linkTypes: ['founded'], toward: 'object', subjectTypes: ['person'], objectTypes: ['company'], degreeLinkTypes: ['founded'], neighborCap: 5,
      });
      expect(toObject.map((e) => e.to).sort()).toEqual(['companies/ep-other', 'companies/ep-widget']);
      expect(toSubject.map((e) => e.to)).toEqual(['people/ep-emp-c']);
      expect(empty).toEqual([]);
      return { toObject: sorted(toObject, (e) => e.to), toSubject, capped, empty };
    },
  );
});

describe('engine parity: backlink and page signal reads', () => {
  parityTest(
    'getBacklinkCounts counts distinct linkers per page id, excluding mentions',
    { methods: ['getBacklinkCounts', 'addLink'] },
    async (engine) => {
      const ids = await seedPages(engine, ['bc/hub', 'bc/leaf', 'bc/one', 'bc/two', 'bc/three']);
      await engine.addLink('bc/one', 'bc/hub', '', 'cites', 'manual');
      await engine.addLink('bc/two', 'bc/hub', '', 'cites', 'manual');
      await engine.addLink('bc/two', 'bc/hub', '', 'related', 'manual');
      await engine.addLink('bc/three', 'bc/hub', '', 'mentions', 'mentions');
      await engine.addLink('bc/hub', 'bc/leaf', '', 'cites', 'manual');
      const counts = await engine.getBacklinkCounts([...ids.values()]);
      const scoped = await engine.getBacklinkCounts([ids.get('bc/hub')!, ids.get('bc/leaf')!], { sourceIds: ['default'] });
      const none = await engine.getBacklinkCounts([]);
      expect(counts.get(ids.get('bc/hub')!)).toBe(2);
      expect(none.size).toBe(0);
      return { counts: bySlug(ids, counts), scoped: bySlug(ids, scoped), none: none.size };
    },
  );

  parityTest(
    'getAdjacencyBoosts aggregates in-set linkers only',
    { methods: ['getAdjacencyBoosts', 'addLink'] },
    async (engine) => {
      const ids = await seedPages(engine, ['adj/a', 'adj/b', 'adj/c', 'adj/outside']);
      await engine.addLink('adj/a', 'adj/c', '', 'cites', 'manual');
      await engine.addLink('adj/b', 'adj/c', '', 'cites', 'manual');
      await engine.addLink('adj/outside', 'adj/c', '', 'cites', 'manual');
      await engine.addLink('adj/a', 'adj/b', '', 'mentions', 'mentions');
      const inSet = [ids.get('adj/a')!, ids.get('adj/b')!, ids.get('adj/c')!];
      const boosts = await engine.getAdjacencyBoosts(inSet);
      const scoped = await engine.getAdjacencyBoosts(inSet, { sourceIds: ['default'] });
      const empty = await engine.getAdjacencyBoosts([]);
      expect(boosts.get(ids.get('adj/c')!)?.hits).toBe(2);
      expect(empty.size).toBe(0);
      return { boosts: bySlug(ids, boosts), scoped: bySlug(ids, scoped), empty: empty.size };
    },
  );

  parityTest(
    'getContentFlagsByPageIds and getUnverifiedExtractionPageIds read frontmatter markers',
    { methods: ['getContentFlagsByPageIds', 'getUnverifiedExtractionPageIds', 'putPage'] },
    async (engine) => {
      const ids = new Map<string, number>();
      const put = async (slug: string, frontmatter: Record<string, unknown>) => {
        ids.set(slug, (await engine.putPage(slug, page(slug, { frontmatter }))).id);
      };
      await put('fm/flagged', { content_flag: { reason: 'markup_heavy', detail: '80% tags' } });
      await put('fm/stub', { provenance: 'auto-extracted', status: 'unverified' });
      await put('fm/verified', { provenance: 'auto-extracted', status: 'verified' });
      await put('fm/draft', { status: 'draft' });
      await put('fm/plain', {});
      const all = [...ids.values()];
      const flags = await engine.getContentFlagsByPageIds(all);
      const unverified = await engine.getUnverifiedExtractionPageIds(all);
      const emptyFlags = await engine.getContentFlagsByPageIds([]);
      const emptyUnverified = await engine.getUnverifiedExtractionPageIds([]);
      expect(flags.size).toBe(1);
      expect(emptyFlags.size).toBe(0);
      expect(emptyUnverified.size).toBe(0);
      return { flags: bySlug(ids, flags), unverified: bySlug(ids, unverified) };
    },
  );

  parityTest(
    'getPageTimestamps and getEffectiveDates return dates only for existing live pages',
    { methods: ['getPageTimestamps', 'getEffectiveDates', 'putPage', 'softDeletePage'] },
    async (engine) => {
      await engine.putPage('ts/dated', page('dated', { effective_date: new Date('2024-03-05T00:00:00Z'), effective_date_source: 'date' }));
      await engine.putPage('ts/undated', page('undated'));
      await engine.putPage('ts/gone', page('gone'));
      await engine.softDeletePage('ts/gone');
      const stamps = await engine.getPageTimestamps(['ts/dated', 'ts/undated', 'ts/missing']);
      const refs = ['ts/dated', 'ts/undated', 'ts/missing', 'ts/gone'].map((slug) => ({ slug, source_id: 'default' }));
      const dates = await engine.getEffectiveDates(refs);
      const wrongSource = await engine.getEffectiveDates([{ slug: 'ts/dated', source_id: 'no-such-source' }]);
      const none = await engine.getEffectiveDates([]);
      expect(dates.get('default::ts/dated')?.toISOString()).toBe('2024-03-05T00:00:00.000Z');
      expect(dates.has('default::ts/missing')).toBe(false);
      expect(wrongSource.size).toBe(0);
      expect(none.size).toBe(0);
      return {
        stampSlugs: sorted([...stamps.keys()]),
        stampsAreDates: [...stamps.values()].every((d) => d instanceof Date),
        dateKeys: sorted([...dates.keys()]),
        dated: dates.get('default::ts/dated')?.toISOString(),
        wrongSource: wrongSource.size,
      };
    },
  );

  parityTest(
    'getSalienceScores combines emotional weight and take count',
    { methods: ['getSalienceScores', 'setEmotionalWeightBatch', 'addTakesBatch', 'putPage'] },
    async (engine) => {
      const ids = await seedPages(engine, ['sal/plain', 'sal/weighted', 'sal/taken']);
      await engine.setEmotionalWeightBatch([{ slug: 'sal/weighted', source_id: 'default', weight: 0.4 }]);
      await engine.addTakesBatch([
        { page_id: ids.get('sal/taken')!, row_num: 1, claim: 'a take', kind: 'take', holder: 'garry' },
        { page_id: ids.get('sal/taken')!, row_num: 2, claim: 'another take', kind: 'take', holder: 'garry' },
      ]);
      const refs = ['sal/plain', 'sal/weighted', 'sal/taken', 'sal/missing'].map((slug) => ({ slug, source_id: 'default' }));
      const scores = await engine.getSalienceScores(refs);
      const none = await engine.getSalienceScores([]);
      const round = (n: number | undefined) => (n === undefined ? null : Math.round(n * 1e6) / 1e6);
      expect(none.size).toBe(0);
      return {
        keys: sorted([...scores.keys()]),
        plain: round(scores.get('default::sal/plain')),
        weighted: round(scores.get('default::sal/weighted')),
        taken: round(scores.get('default::sal/taken')),
        missing: round(scores.get('default::sal/missing')),
      };
    },
  );

  parityTest(
    'findOrphanPages: islanded default vs inbound mode, with source scope',
    { methods: ['findOrphanPages', 'addLink', 'putPage'] },
    async (engine, backend) => {
      await createSource(engine, backend, 'orphan-src');
      await seedPages(engine, ['people/op-island', 'people/op-target', 'people/op-linker'], 'person');
      await seedPages(engine, ['people/op-alt-island'], 'person', { sourceId: 'orphan-src' });
      await engine.addLink('people/op-linker', 'people/op-target', '', 'cites', 'manual');
      const view = async (opts?: Parameters<BrainEngine['findOrphanPages']>[0]) =>
        sorted((await engine.findOrphanPages(opts)).map((r) => `${r.source_id ?? 'default'}:${r.slug}`));
      const islanded = await view();
      const inbound = await view({ mode: 'inbound' });
      const scopedDefault = await view({ sourceId: 'default' });
      const scopedAlt = await view({ sourceId: 'orphan-src' });
      const federated = await view({ sourceIds: ['default', 'orphan-src'] });
      expect(islanded).toEqual(['default:people/op-island', 'orphan-src:people/op-alt-island']);
      expect(inbound).toEqual(['default:people/op-island', 'default:people/op-linker', 'orphan-src:people/op-alt-island']);
      return { islanded, inbound, scopedDefault, scopedAlt, federated };
    },
  );
});