Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.3 KB
Raw Blame
/**
 * v0.32.2 — extract-from-fence pure-mapper tests.
 *
 * Covers the ParsedFact → FenceExtractedFact mapping including:
 *   - All-fields happy path
 *   - The strikethrough date-derivation contract (forgotten / superseded
 *     / inactive-unrecognized branches)
 *   - v0.46 (#3014) supersession transport: struck rows carry expired_at
 *     + the `superseded by #N` row reference; resolveSupersededByRow's
 *     self / dangling / chain edge cases
 *   - source default when fence row has no `source` cell
 *   - row_num and source_markdown_slug threading
 *   - ISO date parsing tolerance + UTC determinism
 */

import { describe, test, expect } from 'bun:test';

import {
  extractFactsFromFenceText,
  FENCE_SOURCE_DEFAULT,
} from '../src/core/facts/extract-from-fence.ts';
import {
  resolveSupersededByRow,
  isInt4RowRef,
  PG_INT4_MAX,
  type SupersedeTarget,
} from '../src/core/facts/supersede-resolve.ts';
import type { ParsedFact } from '../src/core/facts-fence.ts';

const baseFact = (overrides: Partial<ParsedFact> = {}): ParsedFact => ({
  rowNum: 1,
  claim: 'Founded Acme in 2017',
  kind: 'fact',
  confidence: 1.0,
  visibility: 'world',
  notability: 'high',
  validFrom: '2017-01-01',
  source: 'linkedin',
  active: true,
  ...overrides,
});

// Deterministic "today" for date-derivation tests.
const FROZEN_TODAY = new Date(Date.UTC(2026, 4, 11));  // 2026-05-11

describe('extractFactsFromFenceText — happy path mapping', () => {
  test('maps all NewFact fields from a canonical row', () => {
    const out = extractFactsFromFenceText(
      [baseFact()],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out).toHaveLength(1);
    expect(out[0]).toMatchObject({
      fact: 'Founded Acme in 2017',
      kind: 'fact',
      entity_slug: 'people/alice',
      visibility: 'world',
      notability: 'high',
      source: 'linkedin',
      confidence: 1.0,
      row_num: 1,
      source_markdown_slug: 'people/alice',
    });
    expect(out[0].valid_from).toBeInstanceOf(Date);
    expect(out[0].valid_from!.getUTCFullYear()).toBe(2017);
    expect(out[0].valid_until).toBeNull();
  });

  test('source_id is supplied via the sourceId arg, not the fence', () => {
    const out = extractFactsFromFenceText(
      [baseFact()],
      'people/alice',
      'work-source',
      { nowOverride: FROZEN_TODAY },
    );
    // FenceExtractedFact does NOT carry source_id on the row itself; the
    // engine sets it from opts at insert time. The slug binding lives in
    // source_markdown_slug and entity_slug instead.
    expect(out[0].source_markdown_slug).toBe('people/alice');
    expect(out[0].entity_slug).toBe('people/alice');
  });

  test('preserves row_num exactly from the fence', () => {
    const out = extractFactsFromFenceText(
      [baseFact({ rowNum: 7 }), baseFact({ rowNum: 12 })],
      'people/bob',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out.map(r => r.row_num)).toEqual([7, 12]);
  });

  test('context maps through (including undefined → null contract)', () => {
    const out = extractFactsFromFenceText(
      [baseFact({ context: 'Founder bio' }), baseFact({ rowNum: 2, context: undefined })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].context).toBe('Founder bio');
    expect(out[1].context).toBeNull();
  });

  test('all six FactKind values pass through', () => {
    const kinds = ['event', 'preference', 'commitment', 'belief', 'fact', 'idea'] as const;
    const facts = kinds.map((k, i) => baseFact({ rowNum: i + 1, kind: k }));
    const out = extractFactsFromFenceText(facts, 'people/alice', 'default', { nowOverride: FROZEN_TODAY });
    expect(out.map(r => r.kind)).toEqual([...kinds]);
  });

  test('both visibility values pass through', () => {
    const out = extractFactsFromFenceText(
      [baseFact({ visibility: 'private' }), baseFact({ rowNum: 2, visibility: 'world' })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out.map(r => r.visibility)).toEqual(['private', 'world']);
  });
});

describe('extractFactsFromFenceText — date derivation contract', () => {
  test('explicit validUntil is honored as-is', () => {
    const out = extractFactsFromFenceText(
      [baseFact({ validUntil: '2026-12-31' })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_until).toBeInstanceOf(Date);
    expect(out[0].valid_until!.getUTCFullYear()).toBe(2026);
    expect(out[0].valid_until!.getUTCMonth()).toBe(11); // December
  });

  test('active row with no validUntil → valid_until = null', () => {
    const out = extractFactsFromFenceText(
      [baseFact()],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_until).toBeNull();
  });

  test('forgotten row → valid_until = today (UTC midnight) + expired_at set, no supersession', () => {
    const out = extractFactsFromFenceText(
      [baseFact({
        active: false,
        forgotten: true,
        context: 'forgotten: user asked to remove',
      })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_until).toEqual(FROZEN_TODAY);
    // v0.46 (#3014) — a struck row stamps expired_at so it exits active
    // views; a forgotten row is not a supersession, so no row reference.
    expect(out[0].expired_at).toEqual(FROZEN_TODAY);
    expect(out[0].superseded_by_row).toBeUndefined();
  });

  test('forgotten row with explicit validUntil → explicit value wins', () => {
    // Sanity check: if a hand-edit set validUntil AND added "forgotten:"
    // in context, honor the explicit date. The strikethrough-derivation
    // is a fallback, not a forced override.
    const out = extractFactsFromFenceText(
      [baseFact({
        active: false,
        forgotten: true,
        validUntil: '2024-06-01',
        context: 'forgotten: ancient history',
      })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_until!.getUTCFullYear()).toBe(2024);
    expect(out[0].valid_until).not.toEqual(FROZEN_TODAY);
  });

  test('supersededBy row without explicit validUntil → valid_until null, expired_at today, superseded_by_row carried', () => {
    // v0.46 (#3014): pre-fix the mapper dropped supersededBy and left
    // valid_until null "for the consolidator". The mapper now owns the
    // transport: it carries the row reference and stamps expired_at so the
    // struck row exits active views. valid_until stays null (no explicit
    // date, and the superseding row's valid_from isn't visible here).
    const out = extractFactsFromFenceText(
      [baseFact({
        active: false,
        supersededBy: 4,
        context: 'superseded by #4',
      })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_until).toBeNull();
    expect(out[0].expired_at).toEqual(FROZEN_TODAY);
    expect(out[0].superseded_by_row).toBe(4);
  });

  test('supersededBy row with explicit validUntil → explicit value wins for both valid_until and expired_at', () => {
    const out = extractFactsFromFenceText(
      [baseFact({
        active: false,
        supersededBy: 4,
        validUntil: '2026-06-01',
        context: 'superseded by #4',
      })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_until!.getUTCFullYear()).toBe(2026);
    // expired_at derives from valid_until when present (valid_until ?? today).
    expect(out[0].expired_at!.getUTCFullYear()).toBe(2026);
    expect(out[0].expired_at!.getUTCMonth()).toBe(5); // June
    expect(out[0].superseded_by_row).toBe(4);
  });

  test('inactive-unrecognized row (strikethrough but no forgotten/superseded flag) → today', () => {
    // The parser preserved the row's strikethrough intent without
    // recognizing why. The mapper treats unrecognized-inactive like
    // forgotten for DB-derivation safety. Honors the user's strikethrough.
    const out = extractFactsFromFenceText(
      [baseFact({
        active: false,
        context: 'I just don\'t believe this anymore',
        // No forgotten, no supersededBy
      })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_until).toEqual(FROZEN_TODAY);
    // v0.46 (#3014) — unrecognized-inactive still exits active views via
    // expired_at, but is not a supersession.
    expect(out[0].expired_at).toEqual(FROZEN_TODAY);
    expect(out[0].superseded_by_row).toBeUndefined();
  });

  test('active row → expired_at null, no supersession reference', () => {
    const out = extractFactsFromFenceText(
      [baseFact()],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].expired_at).toBeNull();
    expect(out[0].superseded_by_row).toBeUndefined();
  });
});

describe('resolveSupersededByRow — reference resolution (#3014)', () => {
  const live: SupersedeTarget = { id: 42, struck: false };

  test('valid reference → resolves to the target fact id, no warning', () => {
    const r = resolveSupersededByRow(1, 2, live, 'deals/acme');
    expect(r.superseded_by).toBe(42);
    expect(r.warning).toBeNull();
  });

  test('self-reference → NULL + warning', () => {
    const r = resolveSupersededByRow(3, 3, { id: 99, struck: false }, 'deals/acme');
    expect(r.superseded_by).toBeNull();
    expect(r.warning).toContain('references itself');
  });

  test('dangling reference (target absent from fence) → NULL + warning', () => {
    const r = resolveSupersededByRow(1, 9, undefined, 'deals/acme');
    expect(r.superseded_by).toBeNull();
    expect(r.warning).toContain('absent from the fence');
  });

  test('struck target (chain or forgotten) → NULL + warning', () => {
    const r = resolveSupersededByRow(1, 2, { id: 7, struck: true }, 'deals/acme');
    expect(r.superseded_by).toBeNull();
    // The warning names the target as struck/inactive, not specifically a
    // chain — a forgotten target is struck too but isn't a supersession chain.
    expect(r.warning).toContain('struck');
  });
});

describe('resolveSupersededByRow — supersession chains (B-13)', () => {
  test('a struck target that is itself superseded resolves', () => {
    const r = resolveSupersededByRow(1, 2, { id: 7, struck: true }, 'deals/acme', new Map([[2, 3]]));
    expect(r).toEqual({ superseded_by: 7, warning: null });
  });

  test('a chain that cycles back to the row is rejected', () => {
    const r = resolveSupersededByRow(1, 2, { id: 7, struck: true }, 'deals/acme', new Map([[1, 2], [2, 1]]));
    expect(r.superseded_by).toBeNull();
    expect(r.warning).toContain('cycle');
  });
});

describe('isInt4RowRef — supersession-target overflow guard (#3014)', () => {
  test('accepts a normal positive row reference', () => {
    expect(isInt4RowRef(1)).toBe(true);
    expect(isInt4RowRef(42)).toBe(true);
  });

  test('accepts the int4 maximum, rejects one past it', () => {
    expect(isInt4RowRef(PG_INT4_MAX)).toBe(true);
    expect(isInt4RowRef(PG_INT4_MAX + 1)).toBe(false);
  });

  test('rejects an 11-digit reference (the reported overflow shape)', () => {
    // The parser accepts any finite #N; this one would overflow int4 in the
    // resolution SELECT and abort the cycle if it reached the DB.
    expect(isInt4RowRef(99999999999)).toBe(false);
  });

  test('rejects zero, negatives, and non-integers', () => {
    expect(isInt4RowRef(0)).toBe(false);
    expect(isInt4RowRef(-5)).toBe(false);
    expect(isInt4RowRef(1.5)).toBe(false);
    expect(isInt4RowRef(Number.NaN)).toBe(false);
    expect(isInt4RowRef(Number.POSITIVE_INFINITY)).toBe(false);
  });
});

describe('extractFactsFromFenceText — source defaulting', () => {
  test('uses fence source when present', () => {
    const out = extractFactsFromFenceText(
      [baseFact({ source: 'OH 2026-04-29' })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].source).toBe('OH 2026-04-29');
  });

  test('falls back to FENCE_SOURCE_DEFAULT when fence has no source', () => {
    const out = extractFactsFromFenceText(
      [baseFact({ source: undefined })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].source).toBe(FENCE_SOURCE_DEFAULT);
    expect(FENCE_SOURCE_DEFAULT).toBe('fence:reconcile');
  });
});

describe('extractFactsFromFenceText — date parse tolerance', () => {
  test('YYYY-MM-DD shape parses', () => {
    const out = extractFactsFromFenceText(
      [baseFact({ validFrom: '2017-01-01' })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_from).toBeInstanceOf(Date);
    expect(out[0].valid_from!.getUTCFullYear()).toBe(2017);
  });

  test('empty validFrom → undefined (engine layer defaults to now())', () => {
    const out = extractFactsFromFenceText(
      [baseFact({ validFrom: undefined })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_from).toBeUndefined();
  });

  test('completely invalid validFrom string → undefined (lenient)', () => {
    const out = extractFactsFromFenceText(
      [baseFact({ validFrom: 'not a date at all' })],
      'people/alice',
      'default',
      { nowOverride: FROZEN_TODAY },
    );
    expect(out[0].valid_from).toBeUndefined();
  });
});

describe('extractFactsFromFenceText — bulk + edge cases', () => {
  test('empty input array → empty output array', () => {
    const out = extractFactsFromFenceText([], 'people/alice', 'default');
    expect(out).toEqual([]);
  });

  test('30-row fence maps without dropping rows', () => {
    const facts = Array.from({ length: 30 }, (_, i) =>
      baseFact({ rowNum: i + 1, claim: `claim ${i + 1}` }));
    const out = extractFactsFromFenceText(facts, 'people/alice', 'default', { nowOverride: FROZEN_TODAY });
    expect(out).toHaveLength(30);
    expect(out.map(r => r.row_num)).toEqual(facts.map(f => f.rowNum));
  });

  test('every output row carries source_markdown_slug equal to the input slug', () => {
    const facts = [baseFact({ rowNum: 1 }), baseFact({ rowNum: 2 }), baseFact({ rowNum: 3 })];
    const out = extractFactsFromFenceText(facts, 'companies/acme', 'default', { nowOverride: FROZEN_TODAY });
    out.forEach(r => expect(r.source_markdown_slug).toBe('companies/acme'));
  });
});