Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
40.5 KB
Raw Blame
/**
 * MEMORY_VERBS v1 conformance — the frozen-contract pin (Cathedral 1).
 *
 * In-process through dispatchToolCall (the exact layer both MCP transports
 * share), against in-memory PGLite. Covers:
 *   - recall legacy SUPERSET regression (G1B: legacy fields byte-equal,
 *     additions allowed — protocol_version everywhere, no carve-out)
 *   - server-side budget packing math (incl. budget < first item)
 *   - query-arm keyword degradation (never an error without embeddings)
 *   - remember contract: provenance_required, ttl forms (P30D trap), enum
 *     kinds, world default + the remote remember→recall round-trip [F2],
 *     private facts hidden from remote readers
 *   - entity: card shape vs RESPONSE_SCHEMAS, three resolution arms,
 *     miss→suggestions, ZERO-LLM guard (chat transport rigged to throw)
 *   - synthesize: [EXPENSIVE prefix, annotations, clean `unavailable` with
 *     suggestion when no LLM is configured [c10]
 *   - forget: idempotency (expired:false), not_found with suggestion
 *   - error-path envelopes [B6]: every error fixture's envelope carries
 *     protocol_version: 1 + a non-empty suggestion (entity missing name,
 *     context_pack malformed since, synthesize keyless unavailable — the
 *     runner's expectErrorCode branch checks code + suggestion only, so the
 *     protocol_version pin lives here), and a keyless --synthesize runner
 *     pass exercises the synthesize error arm end-to-end
 *   - writeSingleFact supersession rule [X1] + degraded dedup (embed seam)
 *   - negative conformance self-test [F3]: the runner FAILS a lying server
 *   - fixture mirror drift guard (cases.json === embedded module)
 */

import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'bun:test';
import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { operationsByName } from '../src/core/operations.ts';
import type { OperationContext } from '../src/core/operations.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { buildToolDefs } from '../src/mcp/tool-defs.ts';
import { RESPONSE_SCHEMAS, ERROR_SCHEMA, VERB_NAMES } from '../src/core/verbs.ts';
import {
  runConformance,
  validateAgainstSchema,
  type ConformanceClient,
} from '../src/core/verbs/conformance.ts';
import { CONFORMANCE_CASES } from '../src/core/verbs/conformance-fixtures.ts';
import { writeSingleFact } from '../src/core/facts/write-single.ts';
import {
  configureGateway,
  resetGateway,
  __setChatTransportForTests,
  __setEmbedTransportForTests,
} from '../src/core/ai/gateway.ts';
import { __setUsageLogPathForTests } from '../src/core/verbs/usage-log.ts';
import { emptyHome, withEnv } from './helpers/with-env.ts';
import { LEGACY_EMBEDDING_CONFIG } from './helpers/legacy-embedding-config.ts';

let engine: PGLiteEngine;
let home: string;

beforeAll(async () => {
  configureGateway({ ...LEGACY_EMBEDDING_CONFIG, env: {} });
  // Sidecar writes go to a temp file via the test seam — no global env mutation.
  home = mkdtempSync(join(tmpdir(), 'gbrain-verbs-test-'));
  __setUsageLogPathForTests(join(home, 'usage.jsonl'));
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
}, 60_000);

afterAll(async () => {
  await engine.disconnect();
  __setUsageLogPathForTests(null);
  // The deterministic-embedder tests configureGateway() with a FAKE OpenAI
  // key on the MODULE-GLOBAL gateway. Without a reset, every later file in
  // this shard process inherits "embeddings configured" and (with the test
  // transport also cleared) fires a REAL API call with the fake key — the
  // shard-8 turn-context 401 flake. Reset config AND both transports so the
  // file leaves the process exactly as it found it.
  resetGateway();
  __setChatTransportForTests(null);
  __setEmbedTransportForTests(null);
  try { rmSync(home, { recursive: true, force: true }); } catch { /* best-effort */ }
}, 60_000);

beforeEach(async () => {
  await resetPgliteState(engine);
  // This suite's default contract is keyless. A previous file (or one of the
  // deterministic-embedder cases below) must not leave fake credentials active
  // after the transport seam is cleared. Individual cases opt in explicitly.
  configureGateway({ ...LEGACY_EMBEDDING_CONFIG, env: {} });
  __setChatTransportForTests(null);
  __setEmbedTransportForTests(null);
});

function localCtx(sourceId = 'default'): OperationContext {
  return {
    engine,
    config: {},
    logger: { info: () => {}, warn: () => {}, error: () => {} },
    dryRun: false,
    remote: false,
    sourceId,
  } as unknown as OperationContext;
}

/** Remote-shaped call through the shared dispatcher (what both transports do). */
async function callRemote(name: string, params: Record<string, unknown>) {
  const res = await dispatchToolCall(engine, name, params, {
    remote: true,
    takesHoldersAllowList: ['world'],
    sourceId: 'default',
  });
  return { isError: res.isError === true, body: JSON.parse(res.content[0].text) };
}

async function seedPage(
  slug: string,
  title: string,
  type: string,
  body = 'Synthetic test content.',
) {
  const put = operationsByName['put_page'];
  await put.handler(localCtx(), {
    slug,
    content: `---\ntitle: ${title}\ntype: ${type}\n---\n\n# ${title}\n\n${body}\n`,
  });
}

async function seedEntityPage(slug: string, title: string, body = 'A synthetic test entity.') {
  await seedPage(slug, title, 'person', body);
}

describe('recall — G1B superset + budget packing', () => {
  it('legacy-param recall keeps every legacy field shape and adds only the v1 fields', async () => {
    const r1 = await callRemote('remember', {
      fact: 'superset regression fact',
      provenance: 'conformance test',
      entity: 'people/superset-test',
    });
    expect(r1.isError).toBe(false);

    const { isError, body } = await callRemote('recall', { entity: 'people/superset-test' });
    expect(isError).toBe(false);
    // Legacy envelope fields, unchanged shapes.
    expect(typeof body.total).toBe('number');
    expect(Array.isArray(body.facts)).toBe(true);
    const f = body.facts[0];
    const LEGACY_FACT_KEYS = [
      'id', 'fact', 'kind', 'entity_slug', 'visibility', 'notability', 'valid_from',
      'valid_until', 'expired_at', 'superseded_by', 'consolidated_at',
      'consolidated_into', 'source', 'source_session', 'confidence', 'created_at',
    ];
    for (const k of LEGACY_FACT_KEYS) expect(k in f).toBe(true);
    expect(typeof f.id).toBe('number'); // legacy numeric id is FROZEN
    // v1 additions (G1B superset — on EVERY response, no carve-out).
    expect(body.protocol_version).toBe(1);
    expect(f.fact_id).toBe(String(f.id));
    expect(f.provenance).toBe(f.source);
    // No query/budget params → no search/budget fields.
    expect('results' in body).toBe(false);
    expect('budget_tokens' in body).toBe(false);
  });

  it('budget packing reports consistent meta and drops everything under a 1-token budget', async () => {
    for (let i = 0; i < 3; i++) {
      await callRemote('remember', {
        fact: `budget fact number ${i} with some padding text to cost tokens`,
        provenance: 'conformance test',
        entity: 'people/budget-test',
      });
    }
    const big = await callRemote('recall', { entity: 'people/budget-test', budget_tokens: 10000 });
    expect(big.body.budget_tokens).toBe(10000);
    expect(big.body.budget_used).toBeGreaterThan(0);
    expect(big.body.budget_used).toBeLessThanOrEqual(10000);
    expect(big.body.dropped_count).toBe(0);
    expect(big.body.total).toBe(3);

    const tiny = await callRemote('recall', { entity: 'people/budget-test', budget_tokens: 1 });
    expect(tiny.body.total).toBe(0);
    expect(tiny.body.dropped_count).toBeGreaterThanOrEqual(3);
  });

  it('query arm degrades to keyword-only without an embedding provider — never an error', async () => {
    await seedEntityPage('people/query-arm-test', 'Query Arm Marker Qzx');
    const { isError, body } = await callRemote('recall', { query: 'Query Arm Marker Qzx' });
    expect(isError).toBe(false);
    expect(Array.isArray(body.results)).toBe(true);
    expect(body.search_degraded).toBe('keyword_only_no_embedding_provider');
    const violations = validateAgainstSchema(body, RESPONSE_SCHEMAS.recall);
    expect(violations).toEqual([]);
  });
});

describe('remember — contract behavior', () => {
  it("kind enum is frozen at the 5 protocol kinds — 'idea' is extractor/DB-only", () => {
    // docs/protocol/MEMORY_VERBS_v1.md:39-41 — the remember verb's kind enum
    // is a frozen protocol surface. The extractor/DB taxonomy gained 'idea'
    // (engine.ts FactKind, migration v145); the protocol enum MUST NOT.
    const kindEnum = operationsByName['remember'].params?.kind?.enum ?? [];
    expect(kindEnum).toEqual(['event', 'preference', 'commitment', 'belief', 'fact']);
    expect(kindEnum).not.toContain('idea');
  });

  it("recall's RESPONSE kind enum admits 'idea' — the reader must not be told a lie", () => {
    // The INPUT freeze above is the protocol contract (a caller cannot WRITE
    // an idea through the verb). The response side describes what the system
    // actually RETURNS: the extractor and the facts table carry 'idea', so a
    // stored idea fact flows back through recall. A response schema omitting
    // it would declare a contract the system itself violates. Widening a
    // response enum is strictly permissive for consumers.
    const { RESPONSE_SCHEMAS } = require('../src/core/verbs.ts') as {
      RESPONSE_SCHEMAS: Record<string, Record<string, unknown>>;
    };
    const facts = ((RESPONSE_SCHEMAS.recall as Record<string, Record<string, Record<string, unknown>>>)
      .properties?.facts) as Record<string, Record<string, Record<string, Record<string, unknown>>>>;
    const kindEnum = facts?.items?.properties?.kind?.enum as string[] | undefined;
    expect(kindEnum).toEqual(['event', 'preference', 'commitment', 'belief', 'fact', 'idea']);
    // ...while the remember INPUT enum stays frozen at five (asserted above).
  });

  it('rejects empty provenance with provenance_required + a populated suggestion', async () => {
    const { isError, body } = await callRemote('remember', { fact: 'x', provenance: '   ' });
    expect(isError).toBe(true);
    expect(body.error).toBe('provenance_required');
    expect(typeof body.suggestion).toBe('string');
    expect(body.suggestion.length).toBeGreaterThan(0);
    expect(body.protocol_version).toBe(1);
  });

  it('an argument-less remember (a tool call cut off at the output limit) stays invalid_params and says so', async () => {
    const { isError, body } = await callRemote('remember', {});
    expect(isError).toBe(true);
    expect(body.error).toBe('invalid_params');
    expect(body.suggestion).toContain('output-token limit');
    expect(body.suggestion).toContain('items');
  });

  it('rejects ISO-8601 duration ttl (P30D) with a self-correcting suggestion', async () => {
    const { isError, body } = await callRemote('remember', {
      fact: 'ttl trap', provenance: 'test', ttl: 'P30D',
    });
    expect(isError).toBe(true);
    expect(body.error).toBe('invalid_params');
    expect(body.suggestion).toContain('30d');
  });

  it('treats a null-like entity STRING ("null") as absent — never entity_slug=\'null\' (#4755)', async () => {
    // LLM callers emit the literal token "null" for subjectless statements;
    // it means what omitting the param means.
    const { isError, body } = await callRemote('remember', {
      fact: 'a gap statement with no subject', provenance: 'test', entity: 'null',
    });
    expect(isError).toBe(false);
    expect(body.status).toBe('inserted');
    expect(body.entity_slug).toBe(null);
  });

  it('accepts duration ttl and returns a future ISO valid_until; echoes null entity_slug', async () => {
    const { isError, body } = await callRemote('remember', {
      fact: 'expiring fact with ttl', provenance: 'test', ttl: '30d',
    });
    expect(isError).toBe(false);
    expect(typeof body.id).toBe('string');
    expect(body.status).toBe('inserted');
    expect(body.entity_slug).toBe(null); // omitted optional inputs echo as null
    expect(Date.parse(body.valid_until)).toBeGreaterThan(Date.now());
    const violations = validateAgainstSchema(body, RESPONSE_SCHEMAS.remember);
    expect(violations).toEqual([]);
  });

  it('remote remember→recall round-trip holds (world default [F2]); private facts stay hidden', async () => {
    await callRemote('remember', {
      fact: 'world-visible round-trip fact', provenance: 'test', entity: 'people/roundtrip-test',
    });
    await callRemote('remember', {
      fact: 'PRIVATE-SENTINEL fact', provenance: 'test', entity: 'people/roundtrip-test',
      visibility: 'private',
    });
    const { body } = await callRemote('recall', { entity: 'people/roundtrip-test' });
    const texts = body.facts.map((f: { fact: string }) => f.fact).join('|');
    expect(texts).toContain('world-visible round-trip fact');
    expect(texts).not.toContain('PRIVATE-SENTINEL');
  });
});

describe('entity — card, arms, zero LLM', () => {
  it('prefers an entity page when a newer conversation has the same exact title', async () => {
    await seedEntityPage('people/jordan-example', 'Jordan Example');
    await seedPage(
      'conversations/jordan-example-session',
      'Jordan Example',
      'conversation',
      'A newer conversation transcript with the same title.',
    );
    await engine.executeRaw(
      `UPDATE pages
          SET updated_at = CASE slug
            WHEN 'people/jordan-example' THEN '2026-01-01T00:00:00Z'::timestamptz
            ELSE '2026-02-01T00:00:00Z'::timestamptz
          END
        WHERE source_id = 'default'
          AND slug IN ('people/jordan-example', 'conversations/jordan-example-session')`,
    );

    const { isError, body } = await callRemote('entity', { name: 'Jordan Example' });
    expect(isError).toBe(false);
    expect(body.card.entity.slug).toBe('people/jordan-example');
    expect(body.suggestions).toContainEqual(expect.objectContaining({
      slug: 'conversations/jordan-example-session',
    }));
  });

  it('keeps an explicit namespaced slug above an entity-shaped exact-title collision', async () => {
    await seedPage('notes/exact-target', 'Operational Runbook', 'note');
    await seedEntityPage('people/slug-shaped-title', 'notes/exact-target');
    await engine.executeRaw(
      `UPDATE pages
          SET updated_at = CASE slug
            WHEN 'notes/exact-target' THEN '2026-01-01T00:00:00Z'::timestamptz
            ELSE '2026-02-01T00:00:00Z'::timestamptz
          END
        WHERE source_id = 'default'
          AND slug IN ('notes/exact-target', 'people/slug-shaped-title')`,
    );

    const { body } = await callRemote('entity', { name: 'notes/exact-target' });
    expect(body.card.entity.slug).toBe('notes/exact-target');
  });

  it('keeps an explicit alias above entity-type preference', async () => {
    await seedEntityPage('people/alias-title-collision', 'Jordan Alias');
    await seedPage('notes/alias-target', 'Archived Context', 'note');
    await engine.setPageAliases('notes/alias-target', 'default', ['jordan alias']);

    const { body } = await callRemote('entity', { name: 'Jordan Alias' });
    expect(body.card.entity.slug).toBe('notes/alias-target');
  });

  it('retains a non-entity exact-title page as the fallback when no entity page exists', async () => {
    await seedPage('notes/release-checklist', 'Release Checklist', 'note');

    const { body } = await callRemote('entity', { name: 'Release Checklist' });
    expect(body.found).toBe(true);
    expect(body.card.entity.slug).toBe('notes/release-checklist');
  });

  it('resolves an exact namespaced slug to a schema-valid card with the chat gateway rigged to throw', async () => {
    __setChatTransportForTests(() => {
      throw new Error('entity must NEVER call the chat LLM');
    });
    await seedEntityPage('people/card-test', 'Card Test Person', 'Runs engineering at a-company.');
    const { isError, body } = await callRemote('entity', { name: 'people/card-test' });
    expect(isError).toBe(false);
    expect(body.found).toBe(true);
    expect(typeof body.latency_ms).toBe('number');
    expect(body.card.entity.slug).toBe('people/card-test');
    expect(body.card.summary.length).toBeGreaterThan(0);
    const violations = validateAgainstSchema(body, RESPONSE_SCHEMAS.entity);
    expect(violations).toEqual([]);
  });

  it('resolves by exact title and by slug suffix (arms 2)', async () => {
    await seedEntityPage('people/arm-test-alice', 'Arm Test Alice');
    const byTitle = await callRemote('entity', { name: 'Arm Test Alice' });
    expect(byTitle.body.found).toBe(true);
    const bySuffix = await callRemote('entity', { name: 'arm-test-alice' });
    expect(bySuffix.body.found).toBe(true);
  });

  it('miss returns found:false + suggestions, never an error', async () => {
    await seedEntityPage('people/suggestion-source', 'Suggestion Source Person');
    const { isError, body } = await callRemote('entity', { name: 'zzz-definitely-absent-entity' });
    expect(isError).toBe(false);
    expect(body.found).toBe(false);
    expect(Array.isArray(body.suggestions)).toBe(true);
    const violations = validateAgainstSchema(body, RESPONSE_SCHEMAS.entity);
    expect(violations).toEqual([]);
  });

  it('[ship P1.2] entity card backlinks are source-isolated on BOTH sides (no foreign from_slug leak)', async () => {
    // Same slug exists in two sources; a foreign-source page links to the
    // default-source entity. The card must NOT surface the foreign edge/count.
    await seedEntityPage('people/iso-target', 'Iso Target');
    // Register the foreign tenant source (FK target) + a foreign page that
    // links INTO the default-source entity.
    await engine.executeRaw(
      `INSERT INTO sources (id, name, config) VALUES ('other', 'other-tenant', '{}'::jsonb)
       ON CONFLICT (id) DO NOTHING`,
      [],
    );
    await engine.executeRaw(
      `INSERT INTO pages (slug, type, title, compiled_truth, frontmatter, source_id, created_at, updated_at)
       VALUES ('people/foreign-linker', 'person', 'Foreign Linker', '# Foreign', '{}', 'other', NOW(), NOW())`,
      [],
    );
    await engine.executeRaw(
      `INSERT INTO links (from_page_id, to_page_id, link_type, link_source)
       SELECT f.id, t.id, 'works_at', 'markdown'
         FROM pages f, pages t
        WHERE f.slug = 'people/foreign-linker' AND f.source_id = 'other'
          AND t.slug = 'people/iso-target' AND t.source_id = 'default'`,
      [],
    );
    const { body } = await callRemote('entity', { name: 'people/iso-target' });
    expect(body.found).toBe(true);
    // The foreign cross-source backlink must not appear in edges OR the count.
    const edgeSlugs = (body.card.edges as Array<{ slug: string }>).map(e => e.slug);
    expect(edgeSlugs).not.toContain('people/foreign-linker');
    expect(body.card.backlink_count).toBe(0);
  });

  it('[B6] missing required name is invalid_params with protocol_version 1 + a populated suggestion', async () => {
    const { isError, body } = await callRemote('entity', {});
    expect(isError).toBe(true);
    expect(body.error).toBe('invalid_params');
    expect(body.protocol_version).toBe(1);
    expect(typeof body.suggestion).toBe('string');
    expect(body.suggestion.trim().length).toBeGreaterThan(0);
    expect(validateAgainstSchema(body, ERROR_SCHEMA)).toEqual([]);
  });

  it('remote card never carries private commitment facts (fence test)', async () => {
    await seedEntityPage('people/fence-test', 'Fence Test Person');
    await callRemote('remember', {
      fact: 'PRIVATE-SENTINEL commitment text', provenance: 'test',
      entity: 'people/fence-test', kind: 'commitment', visibility: 'private',
    });
    const { body } = await callRemote('entity', { name: 'people/fence-test' });
    expect(body.found).toBe(true);
    expect(JSON.stringify(body.card.open_threads)).not.toContain('PRIVATE-SENTINEL');
  });

  it('active_fact_count is exact beyond the fetch cap, source-scoped, and visibility-scoped', async () => {
    // Pre-fix, active_fact_count was facts.length under a 100-row fetch cap,
    // so entities with more facts silently reported 100.
    await seedEntityPage('people/count-truth-test', 'Count Truth Test Person');
    await engine.executeRaw(
      `INSERT INTO facts
         (source_id, entity_slug, fact, kind, visibility, notability, valid_from, source, confidence, created_at)
       SELECT 'default', 'people/count-truth-test', 'world fact ' || gs::text,
              'fact', 'world', 'medium', NOW(), 'conformance-seed', 1.0, NOW()
         FROM generate_series(1, 125) gs`,
      [],
    );
    await engine.insertFact(
      {
        fact: 'PRIVATE-COUNT-SENTINEL fact',
        kind: 'fact',
        entity_slug: 'people/count-truth-test',
        visibility: 'private',
        source: 'conformance-seed',
      },
      { source_id: 'default' },
    );
    // A same-slug fact in a foreign source must never inflate the count.
    await engine.executeRaw(
      `INSERT INTO sources (id, name, config) VALUES ('other', 'other-tenant', '{}'::jsonb)
       ON CONFLICT (id) DO NOTHING`,
      [],
    );
    await engine.insertFact(
      {
        fact: 'FOREIGN-SOURCE-SENTINEL fact',
        kind: 'fact',
        entity_slug: 'people/count-truth-test',
        visibility: 'world',
        source: 'conformance-seed',
      },
      { source_id: 'other' },
    );

    // Remote: world-only — the 125 seeded world facts, exactly.
    const remote = await callRemote('entity', { name: 'people/count-truth-test' });
    expect(remote.body.card.active_fact_count).toBe(125);

    // Local: private rows count too (126); foreign source never does.
    const local = await operationsByName.entity.handler(localCtx(), { name: 'people/count-truth-test' });
    expect((local as { card: { active_fact_count: number } }).card.active_fact_count).toBe(126);
  });

  it('timeline dates honor the string|null card contract in-process (PGLite returns Date objects)', async () => {
    // The frozen RESPONSE_SCHEMAS type last_timeline_date and thread dates as
    // string|null, but PGLite returns a Date object for the DATE column. The
    // JSON wire hides this (Date.toJSON), so pin the IN-PROCESS card that
    // local consumers (loops, CLI rendering) read directly.
    await seedEntityPage('people/date-contract-test', 'Date Contract Test Person');
    await engine.addTimelineEntry(
      'people/date-contract-test',
      {
        date: new Date().toISOString().slice(0, 10),
        source: 'conformance-seed',
        summary: 'Recent event inside the open-thread window',
      },
      { sourceId: 'default' },
    );

    const res = await operationsByName.entity.handler(localCtx(), { name: 'people/date-contract-test' }) as {
      card: {
        last_touched: { last_timeline_date: unknown };
        open_threads: Array<{ kind: string; date: unknown }>;
      };
    };
    expect(typeof res.card.last_touched.last_timeline_date).toBe('string');
    const recent = res.card.open_threads.find(t => t.kind === 'recent_event');
    expect(recent).toBeDefined();
    for (const t of res.card.open_threads) {
      expect(t.date === null || typeof t.date === 'string').toBe(true);
    }
  });
});

describe('synthesize — marked expensive + unavailable conversion [c10]', () => {
  it('description starts with [EXPENSIVE and the tool def carries annotations', () => {
    const op = operationsByName['synthesize'];
    expect(op.description.startsWith('[EXPENSIVE')).toBe(true);
    const def = buildToolDefs([op])[0];
    expect(def.annotations?.readOnlyHint).toBe(true);
    expect(def.annotations?.title).toContain('costly');
  });

  it('delegates to runThink and returns the frozen envelope with a priced cost block (chat seam — no real LLM)', async () => {
    // Fully hermetic regardless of the dev/CI machine's ambient credentials:
    // runThink builds its client via a real-key check (hasAnthropicKey reads
    // process.env), NOT the gateway chat seam — so we must BOTH provide a fake
    // key via withEnv (so the client builds) AND install the chat seam (so no
    // real API call fires). Without the env key, CI (credential-free) takes the
    // NO_ANTHROPIC_API_KEY path → the verb's `unavailable` conversion → isError.
    __setChatTransportForTests(async () => ({
      text: JSON.stringify({ answer: 'Synthesized test answer.', citations: [], gaps: ['none'] }),
      blocks: [],
      stopReason: 'end' as const,
      usage: { input_tokens: 1200, output_tokens: 80, cache_read_tokens: 0, cache_creation_tokens: 0 },
      model: 'anthropic:claude-haiku-4-5-20251001',
      providerId: 'anthropic',
    }));
    const { isError, body } = await withEnv({ ANTHROPIC_API_KEY: 'sk-test-hermetic' }, async () =>
      callRemote('synthesize', { question: 'what do we know?' }),
    );
    expect(isError).toBe(false);
    expect(body.answer).toBe('Synthesized test answer.');
    expect(body.protocol_version).toBe(1);
    expect(body.cost.input_tokens).toBe(1200);
    expect(body.cost.output_tokens).toBe(80);
    expect(Array.isArray(body.sources)).toBe(true);
    // v0.45.x additive compose-status fields ride EVERY success response
    // (schema-optional for pre-v0.45.x servers, always emitted by this one).
    expect(body.synthesis_status).toBe('ok');
    expect(typeof body.pages_gathered).toBe('number');
    expect(typeof body.takes_gathered).toBe('number');
    expect(Array.isArray(body.warnings)).toBe(true);
    const violations = validateAgainstSchema(body, RESPONSE_SCHEMAS.synthesize);
    expect(violations).toEqual([]);
  });

  it('[B6/c10] keyless synthesize is a clean unavailable error with protocol_version 1 + a populated suggestion', async () => {
    // Forced-keyless hermetically: clear the module-global gateway (a prior
    // configureGateway env snapshot would satisfy resolveAnthropicKey), drop
    // the env var, and point GBRAIN_HOME at an empty dir so a dev machine's
    // real ~/.gbrain/config.json key can't flip the assertion (see emptyHome).
    resetGateway();
    const { isError, body } = await withEnv(
      { ANTHROPIC_API_KEY: undefined, GBRAIN_HOME: emptyHome() },
      async () => callRemote('synthesize', { question: 'keyless error-path probe' }),
    );
    expect(isError).toBe(true);
    expect(body.error).toBe('unavailable');
    expect(body.protocol_version).toBe(1);
    expect(typeof body.suggestion).toBe('string');
    expect(body.suggestion.trim().length).toBeGreaterThan(0);
    expect(validateAgainstSchema(body, ERROR_SCHEMA)).toEqual([]);
  });
});

describe('context_pack — error-path envelope [B6]', () => {
  it('malformed since is invalid_params with protocol_version 1 + an ISO 8601 fix in the suggestion', async () => {
    const { isError, body } = await callRemote('context_pack', {
      entities: 'people/nobody-here',
      since: 'not-a-timestamp',
    });
    expect(isError).toBe(true);
    expect(body.error).toBe('invalid_params');
    expect(body.protocol_version).toBe(1);
    expect(body.suggestion).toContain('ISO 8601');
    expect(validateAgainstSchema(body, ERROR_SCHEMA)).toEqual([]);
  });
});

describe('forget — idempotency + not_found', () => {
  it('expires once, reports expired:false on re-forget, not_found on unknown id', async () => {
    const r = await callRemote('remember', {
      fact: 'fact to forget', provenance: 'test', entity: 'people/forget-test',
    });
    const id = r.body.id as string;

    const first = await callRemote('forget', { id, reason: 'test cleanup' });
    expect(first.isError).toBe(false);
    expect(first.body.expired).toBe(true);
    expect(first.body.reason).toBe('test cleanup');
    expect(validateAgainstSchema(first.body, RESPONSE_SCHEMAS.forget)).toEqual([]);

    const second = await callRemote('forget', { id });
    expect(second.isError).toBe(false);
    expect(second.body.expired).toBe(false);
    expect(second.body.reason).toBe(null); // omitted optional → null

    const missing = await callRemote('forget', { id: '999999999' });
    expect(missing.isError).toBe(true);
    expect(missing.body.error).toBe('not_found');
    expect(missing.body.suggestion.length).toBeGreaterThan(0);
  });

  it('[ship P1.1] a remote caller in source A cannot forget a fact in source B (returns not_found, not expired)', async () => {
    // Register the 'other' tenant source (FK target) then seed a fact in it.
    await engine.executeRaw(
      `INSERT INTO sources (id, name, config) VALUES ('other', 'other-tenant', '{}'::jsonb)
       ON CONFLICT (id) DO NOTHING`,
      [],
    );
    await engine.insertFact(
      { fact: 'cross-source secret fact', kind: 'fact', entity_slug: null, visibility: 'world', source: 'seed' },
      { source_id: 'other' },
    );
    const otherRows = await engine.executeRaw<{ id: number }>(
      `SELECT id FROM facts WHERE source_id = 'other' AND fact = 'cross-source secret fact' LIMIT 1`,
      [],
    );
    const foreignId = String(otherRows[0].id);

    // Remote caller scoped to 'default' tries to forget the 'other'-source id.
    const res = await dispatchToolCall(engine, 'forget', { id: foreignId }, {
      remote: true, takesHoldersAllowList: ['world'], sourceId: 'default',
    });
    const body = JSON.parse(res.content[0].text);
    expect(res.isError).toBe(true);
    expect(body.error).toBe('not_found'); // no cross-source existence leak

    // And the foreign fact is STILL active (not expired by the cross-source call).
    const stillActive = await engine.executeRaw<{ expired_at: Date | null }>(
      `SELECT expired_at FROM facts WHERE id = $1`,
      [otherRows[0].id],
    );
    expect(stillActive[0].expired_at).toBe(null);
  });

  it('[ship P1.1] a remote caller cannot forget a private fact (world-only)', async () => {
    const r = await callRemote('remember', {
      fact: 'private fact remote cannot forget', provenance: 'test',
      entity: 'people/private-forget-test', visibility: 'private',
    });
    // remote remember defaults world; force a private one locally instead.
    const localRes = await dispatchToolCall(engine, 'remember', {
      fact: 'truly private fact', provenance: 'test',
      entity: 'people/private-forget-test', visibility: 'private',
    }, { remote: false, sourceId: 'default' });
    const localId = JSON.parse(localRes.content[0].text).id as string;

    const res = await dispatchToolCall(engine, 'forget', { id: localId }, {
      remote: true, takesHoldersAllowList: ['world'], sourceId: 'default',
    });
    const body = JSON.parse(res.content[0].text);
    expect(res.isError).toBe(true);
    expect(body.error).toBe('not_found'); // remote can't reach a private fact
    void r;
  });
});

describe('writeSingleFact — supersession rule [X1] + degraded dedup', () => {
  function installDeterministicEmbedder() {
    // The schema's facts.embedding column is the init-time default dim (1536);
    // test vectors must match or pgvector's CheckExpectedDim rejects the row.
    const DIM = 1536;
    configureGateway({
      embedding_model: 'openai:text-embedding-3-small',
      embedding_dimensions: DIM,
      env: { OPENAI_API_KEY: 'sk-test-deterministic' },
    });
    // The seam replaces the AI SDK's embedMany({ model, values }) call.
    __setEmbedTransportForTests((async (opts: { values: string[] }) => ({
      embeddings: opts.values.map(t => {
        // Same vector for the SUPERSEDE-PAIR family (cosine 1.0 — above the
        // dedup threshold); a distinct deterministic vector otherwise.
        const v = new Array(DIM).fill(0);
        if (t.includes('SUPERSEDE-PAIR')) v[0] = 1;
        else for (let i = 0; i < 16; i++) v[i] = ((t.charCodeAt(i % t.length) % 13) + 1) / 13;
        return v;
      }),
    })) as never);
  }

  it('near-duplicate with changed text and same kind SUPERSEDES; identical text is a duplicate', async () => {
    installDeterministicEmbedder();
    // Calibrate the deterministic test embedder: an uncalibrated model never supersedes by cosine (supersession-threshold.ts).
    await engine.setConfig('facts.supersession_thresholds', JSON.stringify({ 'openai:text-embedding-3-small@1536': 0.95 }));
    // #5504: an entity the resolver can only slugify is stored with entity_slug NULL, and a NULL-entity fact dedups
    // by exact fingerprint only (candidate lookup is entity-keyed), so the supersession rule needs a live entity page.
    await seedEntityPage('people/supersede-test', 'Supersede Test');
    const a = await writeSingleFact(engine, 'default', {
      fact: 'SUPERSEDE-PAIR alice works at acme-example',
      provenance: 'test', entity: 'people/supersede-test', kind: 'fact',
    });
    expect(a.status).toBe('inserted');
    expect(a.degraded_dedup).toBe(false);

    const dup = await writeSingleFact(engine, 'default', {
      fact: 'SUPERSEDE-PAIR alice works at acme-example',
      provenance: 'test', entity: 'people/supersede-test', kind: 'fact',
    });
    expect(dup.status).toBe('duplicate');
    expect(dup.id).toBe(a.id);

    const updated = await writeSingleFact(engine, 'default', {
      fact: 'SUPERSEDE-PAIR alice LEFT acme-example, now at widget-co',
      provenance: 'test', entity: 'people/supersede-test', kind: 'fact',
    });
    expect(updated.status).toBe('superseded');
    expect(updated.id).not.toBe(a.id);

    const rows = await engine.executeRaw<{ id: number; superseded_by: number | null }>(
      `SELECT id, superseded_by FROM facts WHERE id = $1`, [a.id],
    );
    expect(rows[0].superseded_by).toBe(updated.id);
  });

  it('reports degraded_dedup when no embedding provider is configured', async () => {
    const r = await withNoEmbeddingProvider(() =>
      writeSingleFact(engine, 'default', {
        fact: 'a fact written with no embedding provider',
        provenance: 'test', entity: 'people/degraded-test',
      }),
    );
    expect(r.status).toBe('inserted');
    expect(r.degraded_dedup).toBe(true);
  });
});

describe('conformance runner — negative self-test [F3]', () => {
  function lyingClient(corrupt: (verb: string, body: Record<string, unknown>) => Record<string, unknown>): ConformanceClient {
    return {
      listTools: async () =>
        VERB_NAMES.map(name => ({
          name,
          description: name === 'synthesize' ? '[EXPENSIVE / SLOW] x' : `MEMORY VERB (v1): ${name}`,
        })),
      callTool: async (name, params) => {
        const res = await dispatchToolCall(engine, name, params, {
          remote: true, takesHoldersAllowList: ['world'], sourceId: 'default',
        });
        const body = JSON.parse(res.content[0].text);
        const mutated = res.isError ? body : corrupt(name, body);
        return { isError: res.isError, text: JSON.stringify(mutated) };
      },
    };
  }

  it('a certifier that cannot fail certifies nothing: missing fields, bad enums, wrong id types all flag', async () => {
    // Mutation 1: remember drops the required `status` field.
    const r1 = await withNoEmbeddingProvider(() =>
      runConformance(
        lyingClient((verb, body) => (verb === 'remember' ? (({ status: _s, ...rest }) => rest)(body as { status?: unknown } & Record<string, unknown>) : body)),
        { marker: 'neg1' },
      ),
    );
    expect(r1.ok).toBe(false);

    // Mutation 2: remember returns an out-of-enum status.
    const r2 = await withNoEmbeddingProvider(() =>
      runConformance(
        lyingClient((verb, body) => (verb === 'remember' ? { ...body, status: 'absorbed' } : body)),
        { marker: 'neg2' },
      ),
    );
    expect(r2.ok).toBe(false);

    // Mutation 3: recall re-types fact_id to a number (the opaque-string mandate [T4]).
    const r3 = await withNoEmbeddingProvider(() =>
      runConformance(
        lyingClient((verb, body) => {
          if (verb !== 'recall' || !Array.isArray((body as { facts?: unknown[] }).facts)) return body;
          return {
            ...body,
            facts: (body.facts as Array<Record<string, unknown>>).map(f => ({ ...f, fact_id: Number(f.fact_id) })),
          };
        }),
        { marker: 'neg3' },
      ),
    );
    expect(r3.ok).toBe(false);

    // Honest server passes (sanity: the failures above are the mutations' doing).
    const honest = await withNoEmbeddingProvider(() =>
      runConformance(lyingClient((_v, b) => b), { marker: 'pos1' }),
    );
    const failures = honest.results.filter(r => r.status === 'fail');
    expect(failures).toEqual([]);
  }, 20_000); // v0.45.7: two full runConformance passes now exercise 7 verbs;
  // the default 5s budget flakes under the parallel shard runner (red-team F6).

  it('[B6] keyless self-cert with --synthesize passes via the unavailable error arm (cases run, never skip)', async () => {
    // The synthesize fixtures are dual-mode (keyed servers answer, keyless
    // servers must return the clean `unavailable` envelope). This run is the
    // CI assertion of the ERROR arm: forced keyless (no gateway, no env key,
    // empty config home — the chat transport seam is cleared by beforeEach)
    // with the cost gate OPEN, both synthesize cases must EXECUTE and pass
    // through the runner's unavailable+suggestion+ERROR_SCHEMA checks.
    resetGateway();
    const honest: ConformanceClient = {
      listTools: async () =>
        VERB_NAMES.map(name => ({
          name,
          description: name === 'synthesize' ? '[EXPENSIVE / SLOW] x' : `MEMORY VERB (v1): ${name}`,
        })),
      callTool: async (name, params) => {
        const res = await dispatchToolCall(engine, name, params, {
          remote: true, takesHoldersAllowList: ['world'], sourceId: 'default',
        });
        return { isError: res.isError, text: res.content[0].text };
      },
    };
    const r = await withEnv({ ANTHROPIC_API_KEY: undefined, GBRAIN_HOME: emptyHome() }, async () =>
      runConformance(honest, { marker: `keyless-${Date.now().toString(36)}`, synthesize: true }),
    );
    expect(r.results.filter(x => x.status === 'fail')).toEqual([]);
    const synth = r.results.filter(x => x.verb === 'synthesize' && !x.name.startsWith('tools/list') && !x.name.startsWith('synthesize is marked'));
    expect(synth.length).toBeGreaterThanOrEqual(2);
    expect(synth.every(x => x.status === 'pass')).toBe(true);
  }, 20_000);
});

describe('fixture mirror + surface invariants', () => {
  it('test/fixtures/memory-verbs/cases.json matches the embedded fixture module (BrainBench seed drift guard)', () => {
    const onDisk = JSON.parse(readFileSync(join(import.meta.dir, 'fixtures/memory-verbs/cases.json'), 'utf-8'));
    expect(onDisk).toEqual(JSON.parse(JSON.stringify(CONFORMANCE_CASES)));
  });

  it('every VERB_NAMES entry (7 as of v0.45.7) carries verb: true and nothing else does', async () => {
    const { operations } = await import('../src/core/operations.ts');
    const verbs = operations.filter(o => o.verb === true).map(o => o.name).sort();
    expect(verbs).toEqual([...VERB_NAMES].sort());
    // An accidental verb addition/removal must be a LOUD, named failure —
    // the frozen set is 5 core + 2 additive (context_pack, delta).
    expect(VERB_NAMES.length).toBe(7);
  });

  it('a pre-v0.45.7 five-verb endpoint still certifies (additive verbs skip, never fail)', async () => {
    const CORE = ['recall', 'remember', 'entity', 'synthesize', 'forget'];
    const fiveVerbClient: ConformanceClient = {
      listTools: async () =>
        CORE.map((name) => ({
          name,
          description: name === 'synthesize' ? '[EXPENSIVE / SLOW] cost-gated' : `MEMORY VERB (v1): ${name}`,
        })),
      callTool: async (name, params) => {
        const res = await dispatchToolCall(engine, name, params, {
          remote: true,
          takesHoldersAllowList: ['world'],
          sourceId: 'default',
        });
        return { isError: res.isError, text: res.content[0].text };
      },
    };
    const r = await withNoEmbeddingProvider(() =>
      runConformance(fiveVerbClient, { marker: `five-${Date.now()}` }),
    );
    // The additive verbs must appear ONLY as skips — never executed, never failed.
    const additive = r.results.filter((x) => x.verb === 'context_pack' || x.verb === 'delta');
    expect(additive.length).toBeGreaterThan(0);
    expect(additive.every((x) => x.status === 'skip')).toBe(true);
    // And no list-level advertising failure for them either.
    const advertFails = r.results.filter(
      (x) => x.name.startsWith('tools/list advertises') && x.status === 'fail',
    );
    expect(advertFails).toEqual([]);
  });
});

function withNoEmbeddingProvider<T>(fn: () => T | Promise<T>): Promise<T> {
  return withEnv(
    {
      GBRAIN_HOME: emptyHome(),
      OPENAI_API_KEY: undefined,
      VOYAGE_API_KEY: undefined,
      GOOGLE_GENERATIVE_AI_API_KEY: undefined,
    },
    async () => {
      resetGateway();
      __setEmbedTransportForTests(null);
      try {
        return await fn();
      } finally {
        resetGateway();
        __setEmbedTransportForTests(null);
      }
    },
  );
}