Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.2 KB
Raw Blame
/**
 * #1780 Gap 1 — code-graph readiness signal.
 *
 * Verifies the typed readiness contract that lets code-* callers tell
 * "graph not built / still indexing" apart from "genuinely no match" when
 * count === 0:
 *   - empty brain → not_built (both grains)
 *   - code chunks with no symbol metadata → symbol grain no_symbols (#3640)
 *   - code synced, edges not resolved → symbol grain ready, edge grain indexing
 *   - edges resolved → edge grain ready
 *   - count > 0 → ready short-circuit (no query)
 *   - source scoping (scoped miss → not_built; allSources → brain-wide)
 *   - DB error → unknown, fail-open (CRITICAL regression)
 */

import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { importCodeFile } from '../src/core/import-file.ts';
import { resolveCodeReadiness, readinessHint } from '../src/core/code-graph-readiness.ts';

let engine: PGLiteEngine;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
});

afterAll(async () => {
  await engine.disconnect();
});

beforeEach(async () => {
  // Clean slate per test: remove all chunks + pages so empty-brain cases hold.
  await engine.executeRaw('DELETE FROM content_chunks');
  await engine.executeRaw('DELETE FROM pages');
});

// Each function must exceed the chunker's small-sibling merge threshold
// (15% of the 300-token chunk target) so chunks keep their symbol_name.
// Tiny functions would merge into one symbol_type='merged' chunk with
// symbol_name NULL — which is exactly the #3640 no_symbols state, tested
// separately below.
const SAMPLE = `export function alpha(x: number): number {
  // Alpha computes the successor of beta applied to its input. The body is
  // deliberately padded with commentary so the emitted chunk stays above the
  // merge threshold and keeps its own symbol_name in content_chunks, which
  // the readiness probe (and code-def itself) match on.
  const intermediate = beta(x);
  const successor = intermediate + 1;
  return successor;
}

export function beta(y: number): number {
  // Beta doubles its input. Same padding rationale as alpha above: keep this
  // chunk large enough that mergeSmallSiblings passes it through verbatim
  // instead of rolling it into an anonymous merged chunk without a
  // symbol_name, so the 'ready' fixtures exercise symbol-bearing chunks.
  const doubled = y * 2;
  return doubled;
}
`;

describe('resolveCodeReadiness — empty brain', () => {
  test('symbol grain → not_built when no code exists', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0 });
    expect(r.status).toBe('not_built');
    expect(r.ready).toBe(false);
    expect(r.has_code).toBe(false);
  });

  test('edge grain → not_built when no code exists', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'edge', count: 0 });
    expect(r.status).toBe('not_built');
    expect(r.ready).toBe(false);
  });
});

describe('resolveCodeReadiness — code synced, edges unresolved', () => {
  beforeEach(async () => {
    // importCodeFile writes code chunks with edges_backfilled_at = NULL
    // (resolve phase hasn't run), exactly the "graph still building" state.
    await importCodeFile(engine, 'src/sample.ts', SAMPLE, { noEmbed: true });
  });

  test('symbol grain → ready (symbol metadata is at chunk time)', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0 });
    expect(r.status).toBe('ready');
    expect(r.ready).toBe(true);
    expect(r.has_code).toBe(true);
  });

  test('edge grain → indexing (edges pending resolution)', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'edge', count: 0 });
    expect(r.status).toBe('indexing');
    expect(r.ready).toBe(false);
    expect(r.pending_edges).toBe(true);
  });

  test('edge grain → ready once edges_backfilled_at is stamped fresh', async () => {
    // Mirror what the resolve_symbol_edges phase does: stamp every code chunk.
    await engine.executeRaw('UPDATE content_chunks SET edges_backfilled_at = NOW()');
    const r = await resolveCodeReadiness(engine, { kind: 'edge', count: 0 });
    expect(r.status).toBe('ready');
    expect(r.ready).toBe(true);
    expect(r.pending_edges).toBe(false);
  });

  test('count > 0 short-circuits to ready with no probe', async () => {
    // Even with pending edges, a non-empty result is trivially ready.
    const r = await resolveCodeReadiness(engine, { kind: 'edge', count: 3 });
    expect(r.status).toBe('ready');
    expect(r.ready).toBe(true);
  });
});

describe('resolveCodeReadiness — code chunks without symbol metadata (#3640)', () => {
  beforeEach(async () => {
    await importCodeFile(engine, 'src/sample.ts', SAMPLE, { noEmbed: true });
    // Simulate chunks written before symbol-aware chunking (or a chunker
    // fallback that skipped extraction): code chunks exist, no symbol_name.
    await engine.executeRaw('UPDATE content_chunks SET symbol_name = NULL');
  });

  test('symbol grain → no_symbols (not ready) when no chunk carries symbol_name', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0 });
    expect(r.status).toBe('no_symbols');
    expect(r.ready).toBe(false);
    expect(r.has_code).toBe(true);
  });

  test('no_symbols hint points at reindex-code', () => {
    const hint = readinessHint({ status: 'no_symbols', ready: false, has_code: true, pending_edges: false });
    expect(hint).toContain('reindex-code');
  });

  test('edge grain is unaffected (still indexing on pending edges)', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'edge', count: 0 });
    expect(r.status).toBe('indexing');
  });

  test('symbol grain scoped to a source with only symbol-less code → no_symbols', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0, sourceId: 'default' });
    expect(r.status).toBe('no_symbols');
  });
});

describe('resolveCodeReadiness — source scoping', () => {
  beforeEach(async () => {
    await importCodeFile(engine, 'src/sample.ts', SAMPLE, { noEmbed: true });
  });

  // #3707: pre-fix this reported `not_built` — indistinguishable from a
  // never-synced brain — and the hint misdirected to `gbrain sync`. Code
  // exists brain-wide (the beforeEach import), so a scoped miss is a
  // scope/grant problem, not an indexing one. #4352 remediation: the
  // brain-wide rerun is a trusted-local-only signal (remote: false).
  test('scoped to a source with no code while code exists brain-wide → out_of_scope (symbol)', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0, sourceId: 'no-such-source', remote: false });
    expect(r.status).toBe('out_of_scope');
    expect(r.ready).toBe(false);
    expect(r.has_code).toBe(false);
    expect(r.scoped_source_id).toBe('no-such-source');
  });

  test('scoped to a source with no code while code exists brain-wide → out_of_scope (edge)', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'edge', count: 0, sourceId: 'no-such-source', remote: false });
    expect(r.status).toBe('out_of_scope');
    expect(r.scoped_source_id).toBe('no-such-source');
  });

  test('scoped to the default source (where code lives) → ready (symbol)', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0, sourceId: 'default' });
    expect(r.status).toBe('ready');
  });

  test('allSources ignores a non-matching sourceId and goes brain-wide', async () => {
    const r = await resolveCodeReadiness(engine, {
      kind: 'symbol', count: 0, sourceId: 'no-such-source', allSources: true,
    });
    expect(r.status).toBe('ready');
  });
});

describe('resolveCodeReadiness — #3707 out_of_scope vs not_built', () => {
  test('scoped miss on a genuinely empty brain stays not_built (no code anywhere)', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0, sourceId: 'no-such-source', remote: false });
    expect(r.status).toBe('not_built');
    expect(r.scoped_source_id).toBeUndefined();
  });

  test('unscoped miss never reports out_of_scope', async () => {
    await importCodeFile(engine, 'src/sample.ts', SAMPLE, { noEmbed: true });
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0 });
    expect(r.status).toBe('ready'); // brain-wide probe sees the code
  });

  test('out_of_scope hint names the scope and does NOT recommend gbrain sync', () => {
    const hint = readinessHint({
      status: 'out_of_scope', ready: false, has_code: false,
      pending_edges: false, scoped_source_id: 'default',
    });
    expect(hint).toContain("source 'default'");
    expect(hint).toContain('scope/grant problem');
    expect(hint).toContain('federated_read');
    expect(hint).not.toMatch(/Run `gbrain sync`/);
  });
});

describe('resolveCodeReadiness — #4352 remediation: out_of_scope rerun is trusted-local only', () => {
  beforeEach(async () => {
    await importCodeFile(engine, 'src/sample.ts', SAMPLE, { noEmbed: true });
  });

  // The #3707 rerun probes code existence OUTSIDE the caller's resolved scope.
  // A scoped remote caller must not learn that code exists brain-wide.
  test('remote scoped miss stays not_built (no brain-wide existence disclosure)', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0, sourceId: 'no-such-source', remote: true });
    expect(r.status).toBe('not_built');
    expect(r.scoped_source_id).toBeUndefined();
  });

  test('unset trust is untrusted (fail-closed): scoped miss stays not_built', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'edge', count: 0, sourceId: 'no-such-source' });
    expect(r.status).toBe('not_built');
    expect(r.scoped_source_id).toBeUndefined();
  });

  test('trusted local (remote === false) keeps the #3707 out_of_scope signal', async () => {
    const r = await resolveCodeReadiness(engine, { kind: 'symbol', count: 0, sourceId: 'no-such-source', remote: false });
    expect(r.status).toBe('out_of_scope');
    expect(r.scoped_source_id).toBe('no-such-source');
  });
});

describe('resolveCodeReadiness — fail-open (CRITICAL regression)', () => {
  test('DB error → status unknown, ready false, never throws', async () => {
    const broken = {
      kind: 'pglite',
      executeRaw: async () => { throw new Error('boom'); },
    } as unknown as BrainEngine;
    const r = await resolveCodeReadiness(broken, { kind: 'edge', count: 0 });
    expect(r.status).toBe('unknown');
    expect(r.ready).toBe(false);
  });
});

describe('readinessHint', () => {
  test('not_built / indexing / unknown produce a hint; ready does not', () => {
    expect(readinessHint({ status: 'not_built', ready: false, has_code: false, pending_edges: false })).toContain('not built');
    expect(readinessHint({ status: 'indexing', ready: false, has_code: true, pending_edges: true })).toContain('still building');
    expect(readinessHint({ status: 'unknown', ready: false, has_code: false, pending_edges: false })).toContain('unavailable');
    expect(readinessHint({ status: 'ready', ready: true, has_code: true, pending_edges: false })).toBeNull();
  });
});