Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
19.4 KB
Raw Blame
/**
 * Plan D9 — BrainEngine surface-coverage sweep (mechanical, shrink-only).
 *
 * Three layers, all runtime-enumerated (no TypeScript type machinery):
 *
 *  1. INTERFACE_METHODS is the checked-in literal list of every method on the
 *     `BrainEngine` interface (src/core/engine.ts). It is asserted BOTH ways
 *     against `Object.getOwnPropertyNames(PGLiteEngine.prototype)`: every
 *     listed method must exist on the prototype, and every non-private
 *     prototype member must be classified (interface method or pinned
 *     internal helper). A new engine method therefore forces a visible,
 *     reviewable edit to one of these lists.
 *
 *  2. The UNCALLED allowlist is SHRINK-ONLY. At runtime the test scans every
 *     other file under test/ for a reference to each interface method
 *     (`.name(`, `.name!(`, `.name?.(` call sites, or `name:` stub-property
 *     definitions — the same loose-but-mechanical match a coverage grep
 *     uses; a bare mention in a comment does not count). The set of
 *     methods with ZERO references outside this file must equal UNCALLED
 *     exactly:
 *       - a NEW method with no test anywhere fails ("never-called methods
 *         can't ship") until it either gets a real test or is explicitly
 *         allowlisted + smoked here;
 *       - when real coverage lands elsewhere for an UNCALLED entry, this
 *         test fails until the entry is REMOVED (shrink-only, mechanized).
 *
 *  3. Every UNCALLED entry is smoked ONCE below against a seeded PGLite
 *     engine with a real-shape assertion (not bare no-throw). The SMOKES
 *     map's keys are asserted equal to UNCALLED so an allowlisted method
 *     can't skip its smoke.
 *
 * Known softness (accepted): the corpus scan can false-positive on a
 * `name:` object key that isn't an engine stub. That errs toward "covered"
 * (a stale UNCALLED entry), which the shrink-only equality then flags.
 */
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';

const DIM = 1536;

/**
 * Every method declared on the BrainEngine interface (src/core/engine.ts),
 * in declaration order. `kind` (a readonly data property, not a prototype
 * method) is asserted separately on the instance in the smoke block.
 */
const INTERFACE_METHODS: readonly string[] = [
  // Lifecycle
  'connect', 'disconnect', 'reconnect', 'initSchema', 'transaction', 'transactionDirect', 'registerBeforeDisconnect', 'withReservedConnection',
  // Pages CRUD
  'getPage', 'readPageSnapshot', 'readPageSnapshotsBatch', 'lockPageKeys', 'putPage', 'findDuplicatePage', 'findDuplicatePages', 'deletePage', 'deletePages', 'resolveSlugsByPaths',
  'softDeletePage', 'softDeletePages', 'restorePage', 'purgeDeletedPages', 'listPages', 'findPages', 'countPagesBy', 'resolveSlugs', 'getAllSlugs',
  'listAllPageRefs', 'listAllSources', 'updateSourceConfig', 'listPrefixSampledPages', 'listCorpusSample',
  // Search
  'searchKeyword', 'countKeywordPages', 'searchKeywordPages', 'searchTitles', 'searchVector', 'getEmbeddingsByChunkIds',
  // Chunks
  'upsertChunks', 'sealChunks', 'getChunks', 'getChunkPage', 'getChunkWindows', 'countStaleChunks', 'sumStaleChunkChars', 'setPageEmbeddingSignature',
  'invalidateStaleSignatureEmbeddings', 'invalidateContentDriftEmbeddings', 'listStaleChunks',
  'countChunklessPagesWithContent', 'listChunklessPagesWithContent', 'readEmbeddingStateCounts', 'listEmbeddingStateRows', 'deleteChunks',
  // Extraction watermark
  'countStalePagesForExtraction', 'listStalePagesForExtraction', 'markPagesExtractedBatch', 'markPagesAttendanceBlocked',
  // #6454 stale reserved frontmatter keys
  'countStaleFrontmatterKeyPages', 'listStaleFrontmatterKeyPages', 'stripStaleFrontmatterKeys',
  // Links + graph
  'addLink', 'addLinksBatch', 'replaceDerivedLinks', 'replaceDerivedLinksBatch', 'removeLink', 'getLinks', 'getBacklinks', 'listLinkSources',
  'findByTitleFuzzy', 'traverseGraph', 'traversePaths', 'traversePathsDetailed', 'relationalFanout', 'relationalChainHop', 'getBacklinkCounts',
  'getAdjacencyBoosts', 'getContentFlagsByPageIds', 'getUnverifiedExtractionPageIds',
  'getPageTimestamps', 'getEffectiveDates', 'getSalienceScores', 'findOrphanPages',
  // Tags
  'addTag', 'removeTag', 'getTags',
  // Timeline + chronicle
  'addTimelineEntry', 'addTimelineEntriesBatch', 'getTimeline', 'getTimelineForDate', 'getSince',
  'getOnThisDay', 'getLastSeen', 'upsertEventProjection',
  // Ontology
  'mergeOntologyFact', 'getOntology', 'discoverOntologyDimensions', 'findOntologyConflicts',
  // Raw data + files
  'putRawData', 'getRawData', 'upsertFile', 'getFile', 'listFilesForPage',
  // Takes
  'addTakesBatch', 'listTakes', 'searchTakes', 'searchTakesVector', 'getTakeEmbeddings',
  'countStaleTakes', 'listStaleTakes', 'updateTake', 'supersedeTake', 'resolveTake',
  'getScorecard', 'getCalibrationCurve', 'addSynthesisEvidence',
  // Dream verdicts (sweepDreamVerdicts: wave-k #4069 TTL housekeeping,
  // covered by test/dream-verdict-cache-ttl.test.ts)
  'getDreamVerdict', 'putDreamVerdict', 'sweepDreamVerdicts',
  // Contradiction probe
  'listActiveTakesForPages', 'writeContradictionsRun', 'loadContradictionsTrend',
  'getContradictionCacheEntry', 'putContradictionCacheEntry', 'sweepContradictionCache',
  // Facts (hot memory)
  'insertFact', 'insertFacts', 'deleteFactsForPage', 'expireFact', 'listFactsByEntity',
  'listFactsSince', 'listFactsKeyset', 'listFactsBySession', 'listSupersessions', 'countUnconsolidatedFacts',
  'findCandidateDuplicates', 'consolidateFact', 'findTrajectory', 'getFactsHealth',
  // Versions
  'createVersion', 'getVersions', 'revertToVersion',
  // Stats + health + ingest log
  'getStats', 'getHealth', 'logIngest', 'getIngestLog',
  // Sync + aliases + narrow updates
  'updateSlug', 'rewriteLinks', 'resolveSlugWithAlias', 'resolveSlugWithAliasDetailed', 'resolveAliases', 'setPageAliases',
  'refreshPageBody', 'updatePageContextualRetrievalState', 'migrateFactsToCanonical',
  // Config + migration + raw SQL
  'getConfig', 'setConfig', 'unsetConfig', 'listConfigKeys', 'runMigration',
  'getChunksWithEmbeddings', 'executeRaw', 'executeRawDirect', 'keywordBoundedRead',
  // v0.46.28-34 master waves (classified at the test-gap-wave merge):
  // #3980 bulk config read, #3776 takes-embedding update, #3674 scoped
  // link removal.
  'getAllConfig', 'updateTakeEmbeddings', 'removeLinksByPagesAndSource',
  // Code edges
  'addCodeEdges', 'deleteCodeEdgesForChunks', 'getCallersOf', 'getCalleesOf', 'getEdgesByChunk',
  'searchKeywordChunks',
  // Eval capture
  'logEvalCandidate', 'listEvalCandidates', 'deleteEvalCandidatesBefore', 'logEvalCaptureFailure',
  'listEvalCaptureFailures',
  // Salience + anomaly + enrich
  'batchLoadEmotionalInputs', 'setEmotionalWeightBatch', 'getRecentSalience', 'listEnrichCandidates',
  'findAnomalies',
  // Wave B segmented page bodies (src/core/engine-sql/page-body.ts; covered by test/large-pages/ and test/engine-sql-page-body.test.ts)
  'allocateBodyOccurrenceIds', 'stageSegmentTexts', 'readSegmentTexts', 'stageManifestRows', 'readManifest', 'stageSegmentChunks',
  'createSegmentedPageShell', 'flipBodyGeneration', 'openBodyStaging', 'setBodyStagingState', 'sweepSegments',
  // Wave B PR 4 per-segment derivation rows (same SQL module; covered by test/engine-sql-segment-derivations.test.ts and its Postgres arm)
  'readSegmentDerivations', 'upsertSegmentDerivations', 'retireSegmentDerivations',
];

/**
 * Non-interface prototype members that are legitimate engine internals
 * (helpers/getters shared across the peeled engine modules). Names starting
 * with `_` are treated as private implicitly and need no entry here. Adding
 * a new PUBLIC helper requires a row here — a visible review event, same as
 * a new interface method.
 */
const ENGINE_INTERNAL_HELPERS: readonly string[] = [
  'db',
  'connectForRestore',
  'applyForwardReferenceBootstrap',
  'getBulkRetryOpts',
  'batchRetry',
  'activeEmbeddingColId',
  'codeEdgesDeps',
  // refactor wave 1 C9: per-call engine-sql executor getter (EO1).
  'engineSql',
  // Engine graduation: PGLite close/open that keeps the kernel lock across the custody window.
  'closeRetainingLock',
  'connectWithHeldLock',
  // #9227: whether this engine holds the datastore lock; the PGLite abandoned-claim release rests on it.
  'holdsDatastoreLock',
];

/**
 * SHRINK-ONLY allowlist: interface methods with zero references anywhere in
 * test/ outside this file (verified mechanically by the corpus-scan test
 * below). Each entry is smoked once in the SMOKES block. Do NOT add an
 * entry without a smoke; REMOVE an entry as soon as real coverage lands
 * elsewhere (the scan test forces both).
 *
 * Zero-production-caller flags (deletion candidates — maintainer decision,
 * per the coverage-plan D9 spec; smoked here regardless):
 *   - getPageTimestamps: @deprecated since v0.29.1 in favor of
 *     getEffectiveDates; ZERO src/ callers outside the two engines.
 *   - getTakeEmbeddings left the list at the master merge: wave-k's #3776
 *     semantic takes retrieval gave it real callers + coverage (the ratchet
 *     shrank, as designed — its smoke below stays as a shape pin).
 *   - listPrefixSampledPages, listCorpusSample and getPageTimestamps left the
 *     list in refactor wave 1 W0: the Postgres SQL-text goldens
 *     (test/helpers/postgres-engine-sql-cases.ts) call them. Their PGLite
 *     smokes stay below, unchanged, as ex-UNCALLED shape pins.
 *   - rewriteLinks left the list when the BrainEngine parity suite
 *     (test/engine-parity/sync-aliases.test.ts) began calling it on every
 *     engine arm. Its PGLite smoke stays below as an ex-UNCALLED shape pin.
 */
const UNCALLED: readonly string[] = [];

function methodNames(): string[] {
  return Object.getOwnPropertyNames(PGLiteEngine.prototype).filter((n) => n !== 'constructor');
}

describe('BrainEngine surface — mechanical enumeration (D9)', () => {
  test('every interface method exists as a function on the PGLite prototype', () => {
    const missing = INTERFACE_METHODS.filter((n) => {
      const d = Object.getOwnPropertyDescriptor(PGLiteEngine.prototype, n);
      return !d || typeof d.value !== 'function';
    });
    expect(missing).toEqual([]);
  });

  test('no unclassified public members on the prototype (new methods must be listed)', () => {
    const unclassified = methodNames().filter(
      (n) =>
        !n.startsWith('_') &&
        !INTERFACE_METHODS.includes(n) &&
        !ENGINE_INTERNAL_HELPERS.includes(n),
    );
    expect(unclassified).toEqual([]);
  });

  test('classification lists carry no stale rows', () => {
    const proto = new Set(methodNames());
    expect(ENGINE_INTERNAL_HELPERS.filter((n) => !proto.has(n))).toEqual([]);
    // UNCALLED must stay a subset of the interface.
    expect(UNCALLED.filter((n) => !INTERFACE_METHODS.includes(n))).toEqual([]);
    // No duplicates in the checked-in lists.
    expect(new Set(INTERFACE_METHODS).size).toBe(INTERFACE_METHODS.length);
    expect(new Set(UNCALLED).size).toBe(UNCALLED.length);
  });

  test('UNCALLED equals the set of methods with zero references in the rest of test/ (shrink-only)', () => {
    const testRoot = import.meta.dir; // <repo>/test
    const files: string[] = [];
    (function walk(dir: string) {
      for (const entry of readdirSync(dir, { withFileTypes: true })) {
        if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
        const p = join(dir, entry.name);
        if (entry.isDirectory()) walk(p);
        else if (/\.(ts|tsx|mjs|js)$/.test(entry.name) && p !== import.meta.path) files.push(p);
      }
    })(testRoot);
    // Fail closed if the walk ever breaks — an empty corpus would classify
    // EVERYTHING as uncovered (or, inverted, mask a regression).
    expect(files.length).toBeGreaterThan(500);

    let corpus = '';
    for (const f of files) corpus += readFileSync(f, 'utf8') + '\n';

    const referenced = (name: string): boolean =>
      // `.name(` / `.name!(` call sites, `.name?.(` optional-chain calls,
      // or `name:` stub-property definitions on engine test doubles.
      new RegExp(`[.]${name}\\s*!?\\s*\\(|[.]${name}\\?\\.\\(|\\b${name}\\s*:`).test(corpus);

    const unreferenced = INTERFACE_METHODS.filter((n) => !referenced(n));

    // Two-direction diff for actionable failure output:
    //  - newlyUncovered: add a real test, or allowlist + smoke it here.
    //  - nowCovered: coverage landed elsewhere — SHRINK the UNCALLED list.
    const newlyUncovered = unreferenced.filter((n) => !UNCALLED.includes(n));
    const nowCovered = UNCALLED.filter((n) => !unreferenced.includes(n));
    expect({ newlyUncovered, nowCovered }).toEqual({ newlyUncovered: [], nowCovered: [] });
  });
});

// ============================================================
// Smokes: each UNCALLED method called once against a seeded engine,
// asserting a minimal real-shape invariant.
// ============================================================

let engine: PGLiteEngine;
let fundAPageId: number;
let fundATakeId: number;

function unitEmbedding(): Float32Array {
  const e = new Float32Array(DIM);
  e[0] = 1;
  return e;
}

// Ex-UNCALLED shape pins: methods that gained references elsewhere (the
// ratchet shrank, as designed); each keeps its original seeded-PGLite smoke.
const EX_UNCALLED_SHAPE_PINS: Record<string, () => Promise<void>> = {
  listPrefixSampledPages: async () => {
    // One row per two-segment prefix, ordered by prefix; inbound-link count
    // is the tiebreaker inside a prefix; representative_chunk_id resolves to
    // the lowest embedded chunk (null when the page has no embedded chunks).
    const rows = await engine.listPrefixSampledPages({ prefixes: ['wiki/vc', 'wiki/biology'] });
    expect(rows.map((r) => r.prefix)).toEqual(['wiki/biology', 'wiki/vc']);
    const bio = rows[0];
    expect(bio.slug).toBe('wiki/biology/cells');
    expect(bio.source_id).toBe('default');
    expect(bio.connection_count).toBe(0);
    expect(bio.representative_chunk_id).toBeNull();
    const vc = rows[1];
    // fund-b has 1 inbound link (from fund-a) → beats fund-a on the
    // connection_count tiebreak.
    expect(vc.slug).toBe('wiki/vc/fund-b');
    expect(vc.connection_count).toBe(1);
    expect(typeof vc.page_id).toBe('number');
    expect(vc.compiled_truth).toContain('fund b');
    expect(vc.representative_chunk_id).not.toBeNull();
    // Unknown prefix → no row; empty prefix list short-circuits to [].
    expect(await engine.listPrefixSampledPages({ prefixes: ['no/such'] })).toEqual([]);
    expect(await engine.listPrefixSampledPages({ prefixes: [] })).toEqual([]);
  },

  listCorpusSample: async () => {
    const a = await engine.listCorpusSample({ n: 2, seed: 0.42 });
    expect(a).toHaveLength(2);
    for (const row of a) {
      expect(typeof row.slug).toBe('string');
      expect(row.source_id).toBe('default');
      expect(row.page_id).toBeGreaterThan(0);
      expect(typeof row.connection_count).toBe('number');
    }
    // Deterministic under an explicit seed (the documented test contract).
    const b = await engine.listCorpusSample({ n: 2, seed: 0.42 });
    expect(b.map((r) => r.slug)).toEqual(a.map((r) => r.slug));
    // n <= 0 short-circuits without touching the DB.
    expect(await engine.listCorpusSample({ n: 0 })).toEqual([]);
  },

  getPageTimestamps: async () => {
    const ts = await engine.getPageTimestamps(['wiki/vc/fund-a', 'missing/none']);
    expect(ts.size).toBe(1);
    const when = ts.get('wiki/vc/fund-a');
    expect(when).toBeInstanceOf(Date);
    expect(Number.isNaN(when!.getTime())).toBe(false);
    expect(ts.has('missing/none')).toBe(false);
    // Empty input short-circuits to an empty map.
    expect((await engine.getPageTimestamps([])).size).toBe(0);
  },
  rewriteLinks: async () => {
    // Ex-UNCALLED: test/engine-parity/sync-aliases.test.ts calls it on every arm.
    // Documented no-op stub on PGLite: links key on integer page_id FKs, so
    // they are already correct after updateSlug. Pin the no-op contract —
    // resolves undefined and leaves the link table untouched.
    const before = await engine.getLinks('wiki/vc/fund-a');
    expect(before.length).toBe(1);
    const out = await engine.rewriteLinks('wiki/vc/fund-a', 'wiki/vc/renamed');
    expect(out).toBeUndefined();
    const after = await engine.getLinks('wiki/vc/fund-a');
    expect(after.map((l) => l.to_slug)).toEqual(before.map((l) => l.to_slug));
  },
};

const SMOKES: Record<string, () => Promise<void>> = {};

describe('uncovered-method smokes (seeded PGLite)', () => {
  beforeAll(async () => {
    configureGateway({
      embedding_model: 'openai:text-embedding-3-large',
      embedding_dimensions: DIM,
      env: { ...process.env },
    });
    engine = new PGLiteEngine();
    await engine.connect({}); // in-memory
    await engine.initSchema();

    const fundA = await engine.putPage('wiki/vc/fund-a', {
      type: 'note',
      title: 'Fund A',
      compiled_truth: 'about fund a.',
    });
    fundAPageId = fundA.id;
    await engine.putPage('wiki/vc/fund-b', { type: 'note', title: 'Fund B', compiled_truth: 'about fund b.' });
    await engine.putPage('wiki/biology/cells', { type: 'note', title: 'Cells', compiled_truth: 'about cells.' });
    // fund-b gets one inbound link → the prefix-sampling tiebreaker target.
    await engine.addLink('wiki/vc/fund-a', 'wiki/vc/fund-b');
    // One embedded chunk on fund-b → representative_chunk_id is non-null.
    await engine.upsertChunks('wiki/vc/fund-b', [
      {
        chunk_index: 0,
        chunk_text: 'about fund b.',
        chunk_source: 'compiled_truth',
        embedding: unitEmbedding(),
        token_count: 3,
      },
    ]);
    // One take with a hand-written embedding for getTakeEmbeddings.
    await engine.addTakesBatch([
      { page_id: fundAPageId, row_num: 1, claim: 'Fund A is focused', kind: 'take', holder: 'world', weight: 0.7 },
    ]);
    const [take] = await engine.listTakes({ page_id: fundAPageId });
    fundATakeId = take.id;
    const vecStr = '[' + Array.from(unitEmbedding()).join(',') + ']';
    await engine.executeRaw(`UPDATE takes SET embedding = $1::vector, embedded_at = now() WHERE id = $2`, [
      vecStr,
      fundATakeId,
    ]);
  }, 120_000);

  afterAll(async () => {
    await engine.disconnect();
    resetGateway(); // R5: restore the preload baseline for later files in this shard
  });

  test('kind discriminator (readonly instance property, not on the prototype)', () => {
    expect(engine.kind).toBe('pglite');
  });

  test('smoke map covers exactly the UNCALLED allowlist', () => {
    expect(Object.keys(SMOKES).sort()).toEqual([...UNCALLED].sort());
  });

  for (const name of Object.keys(SMOKES)) {
    test(`smoke: ${name}`, () => SMOKES[name]());
  }

  for (const name of Object.keys(EX_UNCALLED_SHAPE_PINS)) {
    test(`shape pin (ex-UNCALLED): ${name}`, () => EX_UNCALLED_SHAPE_PINS[name]());
  }

  // getTakeEmbeddings left UNCALLED at the master merge (#3776 gave it real
  // coverage elsewhere); its shape pin stays here, inside the seeded engine's
  // lifecycle, no longer tied to the UNCALLED map.
  test('getTakeEmbeddings shape pin (ex-UNCALLED): Float32Array rehydration + omissions', async () => {
    const embs = await engine.getTakeEmbeddings([fundATakeId, 999_999]);
    expect(embs.size).toBe(1);
    const vec = embs.get(fundATakeId);
    expect(vec).toBeInstanceOf(Float32Array);
    expect(vec!.length).toBe(DIM);
    expect(vec![0]).toBeCloseTo(1);
    expect((await engine.getTakeEmbeddings([])).size).toBe(0);
  });
});