Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.7 KB
Raw Blame
/**
 * Conversation backfill save-time resolution against the shipped
 * alias_exact cascade (v0.46.15 / #3730).
 */
import {
  afterAll,
  beforeAll,
  beforeEach,
  describe,
  expect,
  spyOn,
  test,
} from 'bun:test';
import {
  extractConversationFactsFingerprint,
  PER_SEGMENT_SOURCE_PREFIX,
  runExtractConversationFactsCore,
  TERMINAL_AUDIT_SOURCE,
} from '../src/commands/extract-conversation-facts.ts';
import {
  BudgetExhausted,
  BudgetTracker,
} from '../src/core/budget/budget-tracker.ts';
import { runPhaseConversationFactsBackfill } from '../src/core/cycle/conversation-facts-backfill.ts';
import * as resolve from '../src/core/entities/resolve.ts';
import type { ExtractedFact } from '../src/core/facts/extract.ts';
import { loadOpCheckpoint } from '../src/core/op-checkpoint.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';

function message(name: string, date: string, time: string, body: string): string {
  return `**${name}** (${date} ${time}): ${body}`;
}

const ONE_SEGMENT_BODY = [
  message('Alpha Example', '2026-08-12', '10:00 AM', 'The role was accepted.'),
  message('Beta Example', '2026-08-12', '10:01 AM', 'Congratulations.'),
].join('\n');

const TWO_SEGMENT_BODY = [
  message('Alpha Example', '2026-08-12', '10:00 AM', 'First segment.'),
  message('Beta Example', '2026-08-12', '10:01 AM', 'Still first.'),
  message('Alpha Example', '2026-08-12', '11:00 AM', 'Second segment.'),
  message('Beta Example', '2026-08-12', '11:01 AM', 'Still second.'),
].join('\n');

const extractedFacts: ExtractedFact[] = [
  {
    fact: 'Brian accepted the role',
    kind: 'event',
    entity_slug: 'Brian',
    source: 'test',
    source_session: null,
    confidence: 1,
    notability: 'medium',
  },
  {
    fact: 'An unlisted person attended',
    kind: 'event',
    entity_slug: 'Unlisted Person',
    source: 'test',
    source_session: null,
    confidence: 1,
    notability: 'medium',
  },
  {
    fact: 'The weather was clear',
    kind: 'fact',
    entity_slug: null,
    source: 'test',
    source_session: null,
    confidence: 1,
    notability: 'low',
  },
];

let engine: PGLiteEngine;

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

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

beforeEach(async () => {
  await resetPgliteState(engine);
  await engine.setConfig('facts.extraction_enabled', 'true');
  await engine.setConfig('conversation_parser.llm_fallback_enabled', 'false');
  await engine.setConfig('cycle.conversation_facts_backfill.enabled', 'true');
  await seedConversation(ONE_SEGMENT_BODY);
});

async function seedConversation(body: string): Promise<void> {
  await engine.putPage('sessions/example', {
    type: 'conversation',
    title: 'Example conversation',
    compiled_truth: body,
    timeline: '',
    frontmatter: {},
  });
  await engine.putPage('people/brian-example', {
    type: 'person',
    title: 'Brian Example',
    compiled_truth: '# Brian Example',
    timeline: '',
    frontmatter: {},
  });
  await engine.setPageAliases('people/brian-example', 'default', ['brian']);
}

function extractorFor(...batches: ExtractedFact[][]) {
  let index = 0;
  return async (): Promise<ExtractedFact[]> =>
    (batches[index++] ?? []).map((row) => ({ ...row }));
}

async function checkpointEntries(): Promise<string[]> {
  return loadOpCheckpoint(engine, {
    op: 'extract-conversation-facts',
    fingerprint: extractConversationFactsFingerprint({ sourceId: 'default' }),
  });
}

async function dataEntities(): Promise<Array<string | null>> {
  const rows = await engine.executeRaw<{ entity_slug: string | null }>(
    `SELECT entity_slug
       FROM facts
      WHERE source = $1
        AND source_markdown_slug = 'sessions/example'
      ORDER BY row_num`,
    [PER_SEGMENT_SOURCE_PREFIX],
  );
  return rows.map((row) => row.entity_slug);
}

async function terminalCount(): Promise<number> {
  const rows = await engine.executeRaw<{ count: string | number }>(
    `SELECT COUNT(*) AS count
       FROM facts
      WHERE source = $1
        AND source_markdown_slug = 'sessions/example'`,
    [TERMINAL_AUDIT_SOURCE],
  );
  return Number(rows[0]?.count ?? 0);
}

describe('conversation backfill entity resolution', () => {
  test('canonicalizes aliases via alias_exact, preserves null, and counts fallback slugification', async () => {
    const writeSpy = spyOn(process.stderr, 'write').mockImplementation(() => true);
    try {
      const result = await runExtractConversationFactsCore(engine, {
        sourceId: 'default',
        slug: 'sessions/example',
        types: ['conversation'],
        sleepMs: 0,
        extractor: extractorFor(extractedFacts),
      });

      // GBRA-574: the unresolved full name keeps its name key (facts.unbacked_entity_keys, on by default).
      expect(await dataEntities()).toEqual([
        'people/brian-example',
        'unlisted-person',
        null,
      ]);
      expect(result.fallback_slugify_count).toBe(1);
      expect(result.unbacked_keys).toBe(1);
      expect(result.resolution_errors).toBe(0);
      expect(result.facts_inserted).toBe(3);
      expect(await terminalCount()).toBe(1);

      const stderr = writeSpy.mock.calls.map((call) => String(call[0])).join('');
      expect(stderr).toContain(
        'entity_resolution_counts={"alias_exact":1,"fallback_slugify":1}',
      );
      expect(stderr).not.toContain('alias_match');
      expect(stderr).not.toContain('alias_redirect');
    } finally {
      writeSpy.mockRestore();
    }
  });

  test('a lowercase hyphenated display form still hits page_aliases', async () => {
    await engine.putPage('people/kendall-example', {
      type: 'person',
      title: 'Kendall Example',
      compiled_truth: '# Kendall Example',
      timeline: '',
      frontmatter: {},
    });
    await engine.setPageAliases('people/kendall-example', 'default', [
      'kendall',
      'kendall-example',
    ]);

    const result = await runExtractConversationFactsCore(engine, {
      sourceId: 'default',
      slug: 'sessions/example',
      types: ['conversation'],
      sleepMs: 0,
      extractor: extractorFor([
        {
          fact: 'Kendall joined the call',
          kind: 'event',
          entity_slug: 'kendall',
          source: 'test',
          source_session: null,
          confidence: 1,
          notability: 'medium',
        },
        {
          fact: 'Kendall Example spoke again',
          kind: 'event',
          entity_slug: 'kendall-example',
          source: 'test',
          source_session: null,
          confidence: 1,
          notability: 'medium',
        },
      ]),
    });

    expect(await dataEntities()).toEqual([
      'people/kendall-example',
      'people/kendall-example',
    ]);
    expect(result.fallback_slugify_count).toBe(0);
    expect(result.resolution_errors).toBe(0);
  });

  test('a deleted page alias falls through instead of stamping a dead target', async () => {
    await engine.putPage('people/ghost-example', {
      type: 'person',
      title: 'Ghost Example',
      compiled_truth: '# Ghost Example',
      timeline: '',
      frontmatter: {},
    });
    await engine.setPageAliases('people/ghost-example', 'default', ['spectre']);
    await engine.softDeletePage('people/ghost-example');

    const result = await runExtractConversationFactsCore(engine, {
      sourceId: 'default',
      slug: 'sessions/example',
      types: ['conversation'],
      sleepMs: 0,
      extractor: extractorFor([{
        fact: 'A ghost was mentioned',
        kind: 'event',
        entity_slug: 'Spectre',
        source: 'test',
        source_session: null,
        confidence: 1,
        notability: 'medium',
      }]),
    });

    expect(await dataEntities()).toEqual([null]);
    expect(result.fallback_slugify_count).toBe(1);
  });

  test('best-effort resolver failure keeps the fact unparented and later segments checkpoint', async () => {
    await seedConversation(TWO_SEGMENT_BODY);
    const original = resolve.resolveEntitySlugWithSource;
    const spy = spyOn(resolve, 'resolveEntitySlugWithSource').mockImplementation(
      async (eng, sourceId, raw) => {
        if (raw === 'Unlisted Person') {
          throw new Error('resolver unavailable for unlisted person');
        }
        return original(eng, sourceId, raw);
      },
    );
    const writeSpy = spyOn(process.stderr, 'write').mockImplementation(() => true);
    try {
      const result = await runExtractConversationFactsCore(engine, {
        sourceId: 'default',
        slug: 'sessions/example',
        types: ['conversation'],
        sleepMs: 0,
        extractor: extractorFor(
          [extractedFacts[0]],
          [extractedFacts[1], extractedFacts[0], extractedFacts[2]],
        ),
      });

      expect(await dataEntities()).toEqual([
        'people/brian-example',
        null,
        'people/brian-example',
        null,
      ]);
      expect(result.resolution_errors).toBe(1);
      expect(result.fallback_slugify_count).toBe(0);
      expect(result.segments_processed).toBe(2);
      expect(result.facts_inserted).toBe(4);
      expect(result.pages_processed).toBe(1);
      expect(await checkpointEntries()).toContain(
        'default|sessions/example|2026-08-12T11:01:00Z',
      );
      expect(await terminalCount()).toBe(1);

      const stderr = writeSpy.mock.calls.map((call) => String(call[0])).join('');
      expect(stderr).toContain('entity resolution failed for "Unlisted Person"');
      expect(stderr).toContain('preserving fact without an entity target');
    } finally {
      spy.mockRestore();
      writeSpy.mockRestore();
    }
  });

  test('BudgetExhausted from resolution halts without becoming a resolution error', async () => {
    const spy = spyOn(resolve, 'resolveEntitySlugWithSource').mockImplementation(
      async () => {
        throw new BudgetExhausted('resolver budget exhausted', {
          reason: 'cost',
          spent: 2,
          cap: 1,
        });
      },
    );
    try {
      const tracker = new BudgetTracker({ maxCostUsd: 1, label: 'track1-resolution' });
      const result = await runExtractConversationFactsCore(engine, {
        sourceId: 'default',
        slug: 'sessions/example',
        types: ['conversation'],
        sleepMs: 0,
        budgetTracker: tracker,
        extractor: extractorFor(extractedFacts),
      });

      expect(result.budget_exhausted).toBeTrue();
      expect(result.resolution_errors).toBe(0);
      expect(result.facts_inserted).toBe(0);
      expect(await dataEntities()).toEqual([]);
      expect(await terminalCount()).toBe(0);
      expect(await checkpointEntries()).toEqual([]);
    } finally {
      spy.mockRestore();
    }
  });

  test('failed data insert writes no terminal or telemetry and retries cleanly', async () => {
    const originalInsertFacts = engine.insertFacts;
    const writeSpy = spyOn(process.stderr, 'write').mockImplementation(() => true);
    try {
      engine.insertFacts = async function(this: PGLiteEngine, facts, opts) {
        if (facts.some((row) => row.source === PER_SEGMENT_SOURCE_PREFIX)) {
          throw new Error('constraint sentinel');
        }
        return originalInsertFacts.call(this, facts, opts);
      };
      await expect(runExtractConversationFactsCore(engine, {
        sourceId: 'default',
        slug: 'sessions/example',
        types: ['conversation'],
        sleepMs: 0,
        extractor: extractorFor(extractedFacts),
      })).rejects.toThrow('constraint sentinel');

      expect(await dataEntities()).toEqual([]);
      expect(await terminalCount()).toBe(0);
      expect(await checkpointEntries()).toEqual([]);
      const failedStderr = writeSpy.mock.calls.map((call) => String(call[0])).join('');
      expect(failedStderr).not.toContain('entity_resolution_counts=');
      engine.insertFacts = originalInsertFacts;

      const result = await runExtractConversationFactsCore(engine, {
        sourceId: 'default',
        slug: 'sessions/example',
        types: ['conversation'],
        sleepMs: 0,
        extractor: extractorFor(extractedFacts),
      });
      expect(result.facts_inserted).toBe(3);
      expect(result.fallback_slugify_count).toBe(1);
      expect(result.resolution_errors).toBe(0);
      expect(await terminalCount()).toBe(1);
      expect(await checkpointEntries()).toContain(
        'default|sessions/example|2026-08-12T10:01:00Z',
      );
    } finally {
      engine.insertFacts = originalInsertFacts;
      writeSpy.mockRestore();
    }
  });

  test('cycle propagates an abort instead of aggregating it as a source warning', async () => {
    const controller = new AbortController();
    controller.abort();
    await expect(runPhaseConversationFactsBackfill(engine, {
      signal: controller.signal,
      dryRun: true,
    })).rejects.toThrow('aborted');
  });
});