Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.32.2 — fence-write module tests.
*
* Exercises the markdown-first write path: page lock + stub-create +
* atomic .tmp + parse-validate + engine.insertFacts batch + the
* legacy fallback for missing local_path. Real PGLite + a real
* filesystem under a per-test tempdir.
*
* The page-lock contention test (multi-process integration via
* Bun.spawn) lives in test/e2e/facts-lock-contention.test.ts (commit
* 10's invariant E2E capstone, since spawning child processes is an
* E2E concern). These unit/integration cases cover the in-process
* happy + recovery paths.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { writeFactsToFence, lookupSourceLocalPath } from '../src/core/facts/fence-write.ts';
import type { FenceInputFact } from '../src/core/facts/fence-write.ts';
import { forgetFactInFence } from '../src/core/facts/forget.ts';
import { readRecentStubGuardEvents } from '../src/core/facts/stub-guard-audit.ts';
import { writeSingleFact, isNullLikeEntity } from '../src/core/facts/write-single.ts';
import { _resetWriteThroughCacheForTest } from '../src/core/write-through.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { resetGateway } from '../src/core/ai/gateway.ts';
import { withEnv } from './helpers/with-env.ts';
let engine: PGLiteEngine;
let brainDir: string;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
});
afterAll(async () => {
await engine.disconnect();
});
beforeEach(async () => {
await engine.executeRaw('DELETE FROM fact_withdrawals');
// Fresh tempdir per test so the fence-write FS state is hermetic.
brainDir = mkdtempSync(join(tmpdir(), 'fence-write-test-'));
_resetWriteThroughCacheForTest();
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`DELETE FROM config WHERE key = 'sync.write_through'`);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query('DELETE FROM facts');
// Default source pointed at the fresh brainDir.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`UPDATE sources SET local_path = $1 WHERE id = 'default'`,
[brainDir],
);
});
const baseInput = (overrides: Partial<FenceInputFact> = {}): FenceInputFact => ({
fact: 'Founded Acme in 2017',
kind: 'fact',
notability: 'high',
source: 'mcp:put_page',
visibility: 'world',
confidence: 1.0,
validFrom: new Date(Date.UTC(2017, 0, 1)),
embedding: null,
sessionId: null,
...overrides,
});
function git(cwd: string, ...args: string[]): string {
return execFileSync('git', ['-C', cwd, ...args], {
stdio: ['ignore', 'pipe', 'pipe'],
encoding: 'utf-8',
}).trim();
}
function initGitRepo(repoPath: string): void {
git(repoPath, 'init');
git(repoPath, 'config', 'user.email', '[email protected]');
git(repoPath, 'config', 'user.name', 'T');
writeFileSync(join(repoPath, 'seed.md'), 'seed\n');
git(repoPath, 'add', 'seed.md');
git(repoPath, 'commit', '-m', 'init');
}
function installFakeDurabilityHook(repoPath: string): void {
const hooksDir = join(repoPath, '.git', 'hooks');
mkdirSync(hooksDir, { recursive: true });
const hookPath = join(hooksDir, 'post-commit');
writeFileSync(hookPath, [
'#!/usr/bin/env bash',
'# gbrain brain-durability post-commit hook (v0.42.44+)',
'exit 0',
'',
].join('\n'));
chmodSync(hookPath, 0o755);
}
describe('writeFactsToFence — happy path', () => {
test('stub-creates entity page when none exists, writes fence, stamps DB', async () => {
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/alice', resolutionSource: 'exact_page' },
[baseInput()],
);
expect(result.inserted).toBe(1);
expect(result.ids).toHaveLength(1);
expect(result.legacyFallback).toBeUndefined();
expect(result.fenceWriteFailed).toBeUndefined();
// Page was stub-created with min frontmatter.
const filePath = join(brainDir, 'people/alice.md');
expect(existsSync(filePath)).toBe(true);
const body = readFileSync(filePath, 'utf-8');
expect(body).toContain('type: person');
expect(body).toContain('slug: people/alice');
expect(body).toContain('## Facts');
expect(body).toContain('Founded Acme in 2017');
// DB row has v51 columns populated.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const dbRows = await (engine as any).db.query(
'SELECT row_num, source_markdown_slug, fact FROM facts WHERE id = $1',
[result.ids[0]],
);
expect(dbRows.rows[0]).toMatchObject({
row_num: 1,
source_markdown_slug: 'people/alice',
fact: 'Founded Acme in 2017',
});
});
// #4322 regression. stubEntityPage used to pick the type from a hardcoded
// people/companies/deals/topics ternary, so a stub under ANY other declared
// prefix silently became `concept`. `projects/` is in the gbrain-base prefix
// table (→ `project`) but was absent from that ternary, so it is the minimal
// case that fails on the old code and passes on the pack-aware one. No custom
// pack needed: with no pack configured the loader returns null and
// inferTypeFromPack falls back to GBRAIN_BASE_PATH_PREFIXES.
test('types a stub from the prefix table, not a hardcoded 4-entry list', async () => {
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'projects/apollo', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Apollo shipped in 2017' })],
);
expect(result.inserted).toBe(1);
const body = readFileSync(join(brainDir, 'projects/apollo.md'), 'utf-8');
expect(body).toContain('type: project');
expect(body).not.toContain('type: concept');
expect(body).toContain('slug: projects/apollo');
});
test('appends to existing entity page without overwriting body', async () => {
// Pre-create the entity page with custom content.
const filePath = join(brainDir, 'people/bob.md');
mkdirSync(join(brainDir, 'people'), { recursive: true });
writeFileSync(
filePath,
'---\ntype: person\ntitle: Bob\nslug: people/bob\n---\n\n# Bob\n\nMet at YC W22.\n',
'utf-8',
);
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/bob', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Founded Widgets Inc.' })],
);
expect(result.inserted).toBe(1);
const body = readFileSync(filePath, 'utf-8');
expect(body).toContain('Met at YC W22.'); // preserved
expect(body).toContain('# Bob'); // preserved
expect(body).toContain('## Facts'); // added
expect(body).toContain('Founded Widgets Inc.');
});
test('#4872 mirrors the rewritten file into pages.compiled_truth; the next sync re-chunks the new row', async () => {
const filePath = join(brainDir, 'people/bob.md');
mkdirSync(join(brainDir, 'people'), { recursive: true });
const file = '---\ntype: person\ntitle: Bob\nslug: people/bob\n---\n\n# Bob\n\nMet at YC W22.\n';
writeFileSync(filePath, file, 'utf-8');
expect((await importFromContent(engine, 'people/bob', file, { noEmbed: true, sourceId: 'default' })).status).toBe('imported');
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/bob', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Founded Widgets Inc.' })],
);
expect(result.inserted).toBe(1);
// The DB body get_page / the reconcile read must carry the row remember
// just reported stored — otherwise a get→put round-trip flattens it away.
const page = await engine.getPage('people/bob', { sourceId: 'default' });
expect(page!.compiled_truth).toContain('Founded Widgets Inc.');
expect(page!.compiled_truth).toContain('Met at YC W22.');
// The mirror is body-only (content_chunks untouched), so it must NOT
// claim the importer's hash: the next sync has to see the file as changed
// and re-chunk, or search never indexes the remembered row (wave review).
const imp = await importFromContent(engine, 'people/bob', readFileSync(filePath, 'utf-8'), { noEmbed: true, sourceId: 'default' });
expect(imp.status).toBe('imported');
const chunks = await engine.getChunks('people/bob', { sourceId: 'default', requireSafeChunks: true });
expect(chunks.map((c) => c.chunk_text).join('\n')).toContain('Founded Widgets Inc.');
});
test('multi-fact batch appends consecutive row_nums', async () => {
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/carol', resolutionSource: 'exact_page' },
[
baseInput({ fact: 'Claim 1' }),
baseInput({ fact: 'Claim 2' }),
baseInput({ fact: 'Claim 3' }),
],
);
expect(result.inserted).toBe(3);
expect(result.ids).toHaveLength(3);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
`SELECT row_num, fact FROM facts WHERE source_markdown_slug = 'people/carol' ORDER BY row_num`,
);
expect(rows.rows.map((r: { row_num: number; fact: string }) => r.row_num)).toEqual([1, 2, 3]);
expect(rows.rows.map((r: { fact: string }) => r.fact)).toEqual(['Claim 1', 'Claim 2', 'Claim 3']);
});
test('appending to a page that already has a facts fence continues row_num sequence', async () => {
// First write seeds the fence with rows 1 and 2.
await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/dan', resolutionSource: 'exact_page' },
[baseInput({ fact: 'First' }), baseInput({ fact: 'Second' })],
);
// Second write should pick up at row_num=3.
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/dan', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Third' })],
);
expect(result.inserted).toBe(1);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
`SELECT row_num, fact FROM facts WHERE source_markdown_slug = 'people/dan' ORDER BY row_num`,
);
expect(rows.rows[2]).toMatchObject({ row_num: 3, fact: 'Third' });
});
test('stub-creates nested directories (companies/x → mkdir companies)', async () => {
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'companies/acme', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Founded 2017' })],
);
expect(result.inserted).toBe(1);
expect(existsSync(join(brainDir, 'companies/acme.md'))).toBe(true);
const body = readFileSync(join(brainDir, 'companies/acme.md'), 'utf-8');
expect(body).toContain('type: company'); // type inferred from slug prefix
});
test('commits the fence file on a durability-hardened repo without sweeping unrelated dirt', async () => {
initGitRepo(brainDir);
installFakeDurabilityHook(brainDir);
writeFileSync(join(brainDir, 'seed.md'), 'dirty unrelated edit\n');
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/durable', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Durable fence fact' })],
);
expect(result.inserted).toBe(1);
expect(git(brainDir, 'log', '-1', '--format=%s')).toBe('gbrain: write-through people/durable');
expect(git(brainDir, 'log', '-1', '--name-only', '--format=')).toBe('people/durable.md');
expect(git(brainDir, 'status', '--porcelain', 'people/durable.md')).toBe('');
expect(git(brainDir, 'status', '--porcelain', 'seed.md')).not.toBe('');
}, 60_000);
});
describe('writeFactsToFence — withdrawn claims (write-path audit B-10)', () => {
test('never appends a withdrawn claim, or a punctuation variant of it, as an active Markdown row', async () => {
await engine.executeRaw(`INSERT INTO fact_withdrawals(source_id,visibility,subject,fact_hash)
VALUES ('default','world','people/alice',gbrain_fact_fingerprint('Founded Acme in 2017'))`);
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/alice', resolutionSource: 'exact_page' },
[baseInput(), baseInput({ fact: 'founded Acme, in 2017.' }), baseInput({ fact: 'Moved to Lisbon in 2020' })],
);
expect(result.withdrawnSkipped).toBe(2);
expect(result.inserted).toBe(1);
const body = readFileSync(join(brainDir, 'people/alice.md'), 'utf-8');
expect(body).not.toContain('Acme');
expect(body).toContain('Moved to Lisbon in 2020');
expect(await engine.executeRaw(`SELECT fact FROM facts WHERE entity_slug='people/alice' ORDER BY id`))
.toEqual([{ fact: 'Moved to Lisbon in 2020' }]);
});
test('a claim withdrawn for another entity is still written for this one', async () => {
await engine.executeRaw(`INSERT INTO fact_withdrawals(source_id,visibility,subject,fact_hash)
VALUES ('default','world','people/bob',gbrain_fact_fingerprint('Founded Acme in 2017'))`);
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/alice', resolutionSource: 'exact_page' },
[baseInput()],
);
expect(result).toMatchObject({ inserted: 1 });
expect(result.withdrawnSkipped).toBeUndefined();
});
test('an entirely withdrawn batch leaves the filesystem untouched', async () => {
await engine.executeRaw(`INSERT INTO fact_withdrawals(source_id,visibility,subject,fact_hash)
VALUES ('default','world','*',gbrain_fact_fingerprint('Founded Acme in 2017'))`);
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/carol', resolutionSource: 'exact_page' },
[baseInput()],
);
expect(result).toEqual({ inserted: 0, ids: [], withdrawnSkipped: 1 });
expect(existsSync(join(brainDir, 'people/carol.md'))).toBe(false);
});
});
describe('writeFactsToFence — legacy fallback', () => {
test('null localPath returns legacyFallback:true with no inserts', async () => {
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: null, slug: 'people/whoever', resolutionSource: 'exact_page' },
[baseInput()],
);
expect(result).toEqual({ inserted: 0, ids: [], legacyFallback: true });
// No DB inserts happened either.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query('SELECT COUNT(*) AS n FROM facts');
expect(Number(rows.rows[0].n)).toBe(0);
});
test('empty facts array returns inserted:0 without touching FS', async () => {
const slug = 'people/should-not-exist';
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug, resolutionSource: 'exact_page' },
[],
);
expect(result).toEqual({ inserted: 0, ids: [] });
// The page file should NOT have been stub-created since there was
// nothing to write.
expect(existsSync(join(brainDir, `${slug}.md`))).toBe(false);
});
});
describe('writeFactsToFence — atomic recovery', () => {
test('after a successful write, no .tmp file is left behind', async () => {
await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/erin', resolutionSource: 'exact_page' },
[baseInput()],
);
const tmpPath = join(brainDir, 'people/erin.md.tmp');
expect(existsSync(tmpPath)).toBe(false);
});
});
describe('writeFactsToFence — stub guard (v0.34.5)', () => {
test('refuses to stub-create an unprefixed entity page (bare slug), even with exact_page provenance', async () => {
// #4108: the guard is a UNION — the unprefixed-slug arm keeps blocking
// regardless of resolution provenance, it wasn't replaced by the
// provenance arm.
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'alice', resolutionSource: 'exact_page' },
[baseInput()],
);
// Result shape: no facts inserted, guard flag set, no ids.
expect(result.inserted).toBe(0);
expect(result.ids).toHaveLength(0);
expect(result.stubGuardBlocked).toBe(true);
// No phantom file at brain root.
expect(existsSync(join(brainDir, 'alice.md'))).toBe(false);
// No phantom .tmp either.
expect(existsSync(join(brainDir, 'alice.md.tmp'))).toBe(false);
});
test('prefixed slugs (people/, companies/, etc.) bypass the guard', async () => {
// Sanity: re-prove the happy path right next to the guard test so a
// future refactor that breaks the guard's slug.includes('/') check
// can't silently pass by only running the guard case. #4108: passes
// 'exact_page' — resolved-to-existing entities still fence.
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/zelda', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Founded Hyrule Labs in 2024' })],
);
expect(result.inserted).toBe(1);
expect(result.stubGuardBlocked).toBeUndefined();
expect(existsSync(join(brainDir, 'people/zelda.md'))).toBe(true);
});
test('empty facts array is a no-op (does NOT trigger the guard)', async () => {
// Empty input short-circuits BEFORE the guard runs — confirming the
// guard only fires when there's actual work the caller wants to do.
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'alice', resolutionSource: 'fallback_slugify' },
[],
);
expect(result.inserted).toBe(0);
expect(result.stubGuardBlocked).toBeUndefined();
expect(result.legacyFallback).toBeUndefined();
expect(existsSync(join(brainDir, 'alice.md'))).toBe(false);
});
});
describe('writeFactsToFence — v0.46 (#3014) supersession-warning seam', () => {
test('forwards an unresolvable `superseded by #N` warning to console.warn', async () => {
// The reachable shape through this path: `fact` and `context` are
// caller-controlled free text, and a claim that arrives already wrapped
// in `~~ ~~` re-parses as a struck row. A struck row with a
// "superseded by #N" context re-parses to supersededBy=N (an unstruck
// row never does, #9069). When #N names no row, insertFacts resolves it
// to NULL + a warning; this test pins that writeFactsToFence forwards
// that warning to console.warn (the no-swallowed-errors seam) rather
// than dropping it.
const captured: string[] = [];
const original = console.warn;
// eslint-disable-next-line no-console
console.warn = (msg?: unknown) => { captured.push(String(msg)); };
let result;
try {
result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/alice', resolutionSource: 'exact_page' },
[baseInput({ fact: '~~Points at a row that is not there~~', context: 'superseded by #99' })],
);
} finally {
// eslint-disable-next-line no-console
console.warn = original;
}
// The row still lands (the bad reference doesn't block the insert).
expect(result.inserted).toBe(1);
// The warning was logged with the category tag, not swallowed.
expect(captured.some(w => w.includes('[facts.supersession]') && w.includes('absent from the fence'))).toBe(true);
});
});
describe('writeFactsToFence — fallback-resolution stub guard (#4108)', () => {
test('prefixed slug with fallback_slugify provenance is blocked: no page, no DB rows', async () => {
const auditDir = mkdtempSync(join(tmpdir(), 'stub-guard-audit-4108-'));
try {
await withEnv({ GBRAIN_AUDIT_DIR: auditDir }, async () => {
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'companies/zeta-nonexistent', resolutionSource: 'fallback_slugify' },
[baseInput()],
);
expect(result.inserted).toBe(0);
expect(result.ids).toHaveLength(0);
expect(result.stubGuardBlocked).toBe(true);
// No canonical stub page materialized for the invented slug.
expect(existsSync(join(brainDir, 'companies/zeta-nonexistent.md'))).toBe(false);
expect(existsSync(join(brainDir, 'companies/zeta-nonexistent.md.tmp'))).toBe(false);
// No DB rows either — the CALLER routes to the legacy DB-only path.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query('SELECT COUNT(*) AS n FROM facts');
expect(Number(rows.rows[0].n)).toBe(0);
// The audit event carries the new reason so stub_guard_24h can count
// fallback blocks separately from unprefixed ones.
const events = readRecentStubGuardEvents({ sinceMs: 60_000 });
expect(events).toHaveLength(1);
expect(events[0]).toMatchObject({
slug: 'companies/zeta-nonexistent',
reason: 'fallback_resolution',
});
});
} finally {
rmSync(auditDir, { recursive: true, force: true });
}
});
test('null provenance is blocked too (fail-closed when the caller has no resolution step)', async () => {
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'companies/zeta-nullprov', resolutionSource: null },
[baseInput()],
);
expect(result.stubGuardBlocked).toBe(true);
expect(existsSync(join(brainDir, 'companies/zeta-nullprov.md'))).toBe(false);
});
test('fallback provenance still APPENDS when the page file already exists on disk (DB/file drift edge)', async () => {
// The guard lives on the stub-CREATE branch only: a file that exists on
// disk but hasn't reached the pages index yet keeps accepting appends.
const slug = 'companies/zeta-ondisk';
mkdirSync(join(brainDir, 'companies'), { recursive: true });
writeFileSync(
join(brainDir, `${slug}.md`),
`---\ntype: company\ntitle: Zeta Ondisk\nslug: ${slug}\n---\n\n# Zeta Ondisk\n`,
'utf-8',
);
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug, resolutionSource: 'fallback_slugify' },
[baseInput({ fact: 'Still accepts drift appends' })],
);
expect(result.inserted).toBe(1);
expect(result.stubGuardBlocked).toBeUndefined();
expect(readFileSync(join(brainDir, `${slug}.md`), 'utf-8')).toContain('Still accepts drift appends');
});
test('alias_exact provenance passes the guard (curated alias hits may stub-create)', async () => {
// #4108 blocklist shape: only fallback_slugify/null are blocked, so the
// v0.46.15 alias_exact member fences like exact_page/fuzzy_match.
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/star-example', resolutionSource: 'alias_exact' },
[baseInput()],
);
expect(result.inserted).toBe(1);
expect(result.stubGuardBlocked).toBeUndefined();
expect(existsSync(join(brainDir, 'people/star-example.md'))).toBe(true);
});
});
describe('lookupSourceLocalPath', () => {
test('returns the configured local_path for an existing source', async () => {
const got = await lookupSourceLocalPath(engine, 'default');
expect(got).toBe(brainDir);
});
test('returns null for unknown source_id', async () => {
const got = await lookupSourceLocalPath(engine, 'nonexistent');
expect(got).toBeNull();
});
test('returns null when local_path is NULL on the source row', async () => {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`UPDATE sources SET local_path = NULL WHERE id = 'default'`);
const got = await lookupSourceLocalPath(engine, 'default');
expect(got).toBeNull();
});
});
describe('writeFactsToFence — row_num survives a fence-less rewrite', () => {
// Regression: row_num uniqueness is enforced by idx_facts_fence_key on
// (source_id, source_markdown_slug, row_num), but the value was derived
// from the markdown fence alone, falling back to 1 when the file has no
// fence. Any write path that rewrites a page without preserving its facts
// fence (put_page write-through, sync, dream-cycle reverse-render) then
// makes the next absorb re-issue an already-taken row_num, and the whole
// batch dies on a duplicate-key error.
test('does not reuse a row_num after the fence is stripped from the file', async () => {
const slug = 'people/carol';
const filePath = join(brainDir, `${slug}.md`);
const first = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug, resolutionSource: 'exact_page' },
[baseInput({ fact: 'First fact' }), baseInput({ fact: 'Second fact' })],
);
expect(first.inserted).toBe(2);
// Simulate a non-fence-aware writer replacing the page body. The DB still
// holds row_num 1 and 2; the file now advertises none.
writeFileSync(
filePath,
'---\ntype: person\ntitle: Carol\nslug: people/carol\n---\n\n# Carol\n\nRegenerated without the fence.\n',
'utf-8',
);
expect(readFileSync(filePath, 'utf-8')).not.toContain('First fact');
// Pre-fix this threw: upsertFactRow restarted at 1, colliding with the
// existing rows on idx_facts_fence_key.
const second = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug, resolutionSource: 'exact_page' },
[baseInput({ fact: 'Third fact' })],
);
expect(second.inserted).toBe(1);
expect(second.fenceWriteFailed).toBeUndefined();
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
'SELECT row_num, fact FROM facts WHERE source_markdown_slug = $1 ORDER BY row_num',
[slug],
);
const rowNums = rows.rows.map((r: { row_num: number }) => r.row_num);
// Three distinct row_nums, and the new one clears the previous maximum.
expect(new Set(rowNums).size).toBe(3);
expect(Math.max(...rowNums)).toBeGreaterThan(2);
});
test('still writes when the facts table cannot be consulted', async () => {
// The DB seed is a hint, not a hard dependency: a lookup failure must
// degrade to the previous file-derived behaviour rather than making
// fence writes impossible (pre-v51 brains, transient DB errors).
const brokenEngine = Object.create(engine) as typeof engine;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// A transaction engine derived from brokenEngine keeps its own connection: delegate with `this`.
(brokenEngine as any).executeRaw = async function (this: typeof engine, sqlText: string, params: unknown[]) {
if (sqlText.includes('MAX(row_num)')) throw new Error('simulated lookup failure');
// eslint-disable-next-line @typescript-eslint/no-explicit-any
return (engine as any).executeRaw.call(this, sqlText, params);
};
const result = await writeFactsToFence(
brokenEngine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/dave', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Written despite the failed hint' })],
);
expect(result.inserted).toBe(1);
expect(result.fenceWriteFailed).toBeUndefined();
});
});
describe('writeFactsToFence — sync.write_through opt-out', () => {
test("flag 'false' suppresses the fence lane: no stub page, no fence file, legacyFallback contract", async () => {
await engine.setConfig('sync.write_through', 'false');
_resetWriteThroughCacheForTest();
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/alice-example', resolutionSource: 'exact_page' },
[baseInput()],
);
// Same contract as a missing local_path — the caller's DB-only path
// records the facts, so nothing is silently dropped.
expect(result).toEqual({ inserted: 0, ids: [], legacyFallback: true });
expect(existsSync(join(brainDir, 'people/alice-example.md'))).toBe(false);
expect(existsSync(join(brainDir, 'people'))).toBe(false);
// The fence lane wrote nothing to the DB either (the caller owns the
// DB-only insert).
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query('SELECT COUNT(*) AS n FROM facts');
expect(Number(rows.rows[0].n)).toBe(0);
});
test("off values parse case-insensitively ('OFF'), and no git commit fires on a hardened repo", async () => {
initGitRepo(brainDir);
installFakeDurabilityHook(brainDir);
await engine.setConfig('sync.write_through', 'OFF');
_resetWriteThroughCacheForTest();
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/db-only', resolutionSource: 'exact_page' },
[baseInput()],
);
expect(result).toEqual({ inserted: 0, ids: [], legacyFallback: true });
expect(existsSync(join(brainDir, 'people/db-only.md'))).toBe(false);
expect(git(brainDir, 'log', '-1', '--format=%s')).toBe('init');
}, 60_000);
test('writeSingleFact under the flag: the DB fact still lands, no file appears', async () => {
// No embedder configured → degraded dedup, no network (matches the
// conformance suite's no-provider assumption).
resetGateway();
await engine.setConfig('sync.write_through', 'false');
_resetWriteThroughCacheForTest();
const r = await writeSingleFact(engine, 'default', {
fact: 'prefers DB-only storage',
provenance: 'test',
entity: 'people/frank-example',
});
expect(r.status).toBe('inserted');
// #5504: people/frank-example has no page, so the resolver fell back to
// slugification and the row carries no entity (the backstop convention).
expect(r.entity_slug).toBeNull();
expect(existsSync(join(brainDir, 'people/frank-example.md'))).toBe(false);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
'SELECT entity_slug, source_markdown_slug FROM facts WHERE id = $1',
[r.id],
);
expect(rows.rows[0].entity_slug).toBeNull();
// No .md backs the row — the fence-tracking column stays null.
expect(rows.rows[0].source_markdown_slug).toBeNull();
});
});
describe('writeSingleFact — null-like entity tokens (#4755)', () => {
// LLM extractors emit the literal STRING "null" (or "None", "N/A", …) for
// subjectless statements. Pre-fix that token passed the non-empty check,
// failed resolution, fell back to itself as the slug, and the facts landed
// unreachable under entity_slug='null' (stub guard fired, no page rendered
// them, no entity lookup could reach them).
test('entity "null" is treated as absent: entity_slug null, no phantom slug', async () => {
resetGateway(); // no embedder → degraded dedup, no network
const r = await writeSingleFact(engine, 'default', {
fact: 'some statement with no subject',
provenance: 'test',
entity: 'null',
});
expect(r.status).toBe('inserted');
expect(r.entity_slug).toBeNull();
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
'SELECT entity_slug FROM facts WHERE id = $1',
[r.id],
);
expect(rows.rows[0].entity_slug).toBeNull();
// No phantom page/tmp for the token either.
expect(existsSync(join(brainDir, 'null.md'))).toBe(false);
expect(existsSync(join(brainDir, 'null.md.tmp'))).toBe(false);
});
test('entity "None" (any casing) is treated as absent too', async () => {
resetGateway();
const r = await writeSingleFact(engine, 'default', {
fact: 'another subjectless statement',
provenance: 'test',
entity: 'None',
});
expect(r.status).toBe('inserted');
expect(r.entity_slug).toBeNull();
});
test('isNullLikeEntity: null-like tokens in any casing; real names pass', () => {
for (const t of ['null', 'NULL', 'Null', 'undefined', 'none', 'N/A', 'n/a', 'nil', '-', '', ' ', ' null ']) {
expect(isNullLikeEntity(t)).toBe(true);
}
expect(isNullLikeEntity(null)).toBe(true);
expect(isNullLikeEntity(undefined)).toBe(true);
for (const t of ['people/alice-example', 'Nullsoft', 'Noneck Labs', 'a-founder']) {
expect(isNullLikeEntity(t)).toBe(false);
}
});
});
describe('writeFactsToFence — durability latch recovery', () => {
test('a failed commit does not latch durability off: the next write sweeps the self-dirt', async () => {
const home = mkdtempSync(join(tmpdir(), 'fence-latch-home-'));
try {
await withEnv({ GBRAIN_HOME: home }, async () => {
initGitRepo(brainDir);
installFakeDurabilityHook(brainDir);
// Sabotage the first commit the way real contention does: a live
// index.lock makes git add/commit fail through all retries.
const indexLock = join(brainDir, '.git', 'index.lock');
writeFileSync(indexLock, '');
const first = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/latch', resolutionSource: 'exact_page' },
[baseInput({ fact: 'First latch fact' })],
);
expect(first.inserted).toBe(1);
// Commit failed — the fence file is uncommitted self-dirt.
expect(git(brainDir, 'status', '--porcelain', 'people/latch.md')).not.toBe('');
rmSync(indexLock);
const second = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/latch', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Second latch fact' })],
);
expect(second.inserted).toBe(1);
// Pre-fix: the prewrite self-dirt recorded preexisting_dirty and
// skipped the commit on every subsequent write, forever. The
// path-limited commit sweeping the file's own dirt IS the recovery.
expect(git(brainDir, 'status', '--porcelain', 'people/latch.md')).toBe('');
expect(git(brainDir, 'log', '-1', '--format=%s')).toBe('gbrain: write-through people/latch');
const committed = git(brainDir, 'show', 'HEAD:people/latch.md');
expect(committed).toContain('First latch fact');
expect(committed).toContain('Second latch fact');
});
} finally {
rmSync(home, { recursive: true, force: true });
}
}, 60_000);
test("a concurrent waiter commits its write instead of skipping on the holder's in-flight dirt", async () => {
const home = mkdtempSync(join(tmpdir(), 'fence-race-home-'));
try {
await withEnv({ GBRAIN_HOME: home }, async () => {
initGitRepo(brainDir);
installFakeDurabilityHook(brainDir);
const filePath = join(brainDir, 'people/race.md');
// Gate writer A after its publishing transaction and before its git commit,
// so writer B arrives while A's content is renamed
// into place but not yet committed — the false preexisting_dirty
// shape from the out-of-lock prewrite snapshot.
let release: () => void = () => {};
const gate = new Promise<void>((r) => { release = r; });
let gated = false;
const gatedEngine = Object.create(engine) as typeof engine;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
// The transaction engine is derived from gatedEngine: delegate with `this`.
(gatedEngine as any).transaction = async function (this: typeof engine, fn: Parameters<typeof engine.transaction>[0]) {
const result = await engine.transaction.call(this, fn);
if (!gated && existsSync(filePath) && readFileSync(filePath, 'utf-8').includes('Writer A fact')) { gated = true; await gate; }
return result;
};
const a = writeFactsToFence(
gatedEngine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/race', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Writer A fact' })],
);
// Wait until A's rename landed (post-rename, pre-commit).
for (let i = 0; i < 400; i++) {
if (existsSync(filePath) && readFileSync(filePath, 'utf-8').includes('Writer A fact')) break;
await new Promise((r) => setTimeout(r, 10));
}
expect(readFileSync(filePath, 'utf-8')).toContain('Writer A fact');
const b = writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/race', resolutionSource: 'exact_page' },
[baseInput({ fact: 'Writer B fact' })],
);
// Give B a beat to start (pre-fix, its snapshot fired here, before
// the page lock), then let A finish.
await new Promise((r) => setTimeout(r, 100));
release();
const [ra, rb] = await Promise.all([a, b]);
expect(ra.inserted).toBe(1);
expect(rb.inserted).toBe(1);
// B's write is committed — pre-fix B skipped its commit on A's
// in-flight dirt and left the fence file dirty with a false audit.
expect(git(brainDir, 'status', '--porcelain', 'people/race.md')).toBe('');
expect(git(brainDir, 'show', 'HEAD:people/race.md')).toContain('Writer B fact');
const failLog = join(home, '.gbrain', 'facts.write_failures.jsonl');
if (existsSync(failLog)) {
expect(readFileSync(failLog, 'utf-8')).not.toContain('git_durability_preexisting_dirty');
}
});
} finally {
rmSync(home, { recursive: true, force: true });
}
}, 60_000);
});
describe('writeFactsToFence — path matches writePageThrough (#4204)', () => {
test('non-default source with its own local_path fences at the tree ROOT, not .sources/<id>/', async () => {
const projDir = mkdtempSync(join(tmpdir(), 'fence-write-proj-'));
try {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`INSERT INTO sources (id, name, local_path) VALUES ('proj', 'proj-test', $1)
ON CONFLICT (id) DO UPDATE SET local_path = EXCLUDED.local_path`,
[projDir],
);
const result = await writeFactsToFence(
engine,
{ sourceId: 'proj', localPath: projDir, slug: 'people/alice', resolutionSource: 'exact_page' },
[baseInput()],
);
expect(result.inserted).toBe(1);
// writePageThrough (#2018) writes a source that has its OWN local_path at
// that tree's root, never nested under `.sources/` — and sync's walker
// skips dot-directories, so a `.sources/` fence would be invisible to
// sync and its DB rows wiped by the next extract_facts reconcile.
expect(existsSync(join(projDir, 'people/alice.md'))).toBe(true);
expect(existsSync(join(projDir, '.sources/proj/people/alice.md'))).toBe(false);
} finally {
rmSync(projDir, { recursive: true, force: true });
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`DELETE FROM facts WHERE source_id = 'proj'`);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`DELETE FROM pages WHERE source_id = 'proj'`);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`DELETE FROM sources WHERE id = 'proj'`);
}
});
test("fence appends into the page's recorded source_path file, not a slug-derived twin", async () => {
try {
// A human-authored vault file whose on-disk name is not the slug.
const recordedRel = 'People/Alice Smith.md';
const recordedAbs = join(brainDir, recordedRel);
mkdirSync(join(brainDir, 'People'), { recursive: true });
writeFileSync(
recordedAbs,
'---\ntype: person\ntitle: Alice Smith\nslug: people/alice-smith\n---\n\n# Alice Smith\n',
'utf-8',
);
await engine.putPage('people/alice-smith', {
type: 'person',
title: 'Alice Smith',
compiled_truth: '# Alice Smith',
source_path: recordedRel,
}, { sourceId: 'default' });
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: brainDir, slug: 'people/alice-smith', resolutionSource: 'exact_page' },
[baseInput()],
);
expect(result.inserted).toBe(1);
// The fence must land in the file of record (same preference
// writePageThrough applies), or sync round-trips two divergent files.
expect(readFileSync(recordedAbs, 'utf-8')).toContain('Founded Acme in 2017');
expect(existsSync(join(brainDir, 'people/alice-smith.md'))).toBe(false);
// Round-trip: forget must find the fence in the SAME file the write
// targeted, or it degrades to a DB-only expire and leaves a live fence
// row for the next absorb to resurrect.
const forgot = await forgetFactInFence(engine, result.ids[0], { reason: 'test' });
expect(forgot.ok).toBe(true);
expect(forgot.path).toBe('fence');
expect(readFileSync(recordedAbs, 'utf-8')).toContain('~~');
} finally {
// The engine is shared across the file; drop the page row so its
// recorded source_path (relative to this test's dead tempdir) can't
// leak into later tests.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`DELETE FROM pages WHERE slug = 'people/alice-smith' AND source_id = 'default'`);
}
});
test('unusable source tree returns targetUnresolvable so callers route to DB-only, not drop', async () => {
// Point the source at a directory that no longer exists — the resolver
// must refuse (same repo_not_found refusal as writePageThrough) instead
// of blindly resurrecting the deleted tree with mkdir -p.
const goneDir = mkdtempSync(join(tmpdir(), 'fence-write-gone-'));
rmSync(goneDir, { recursive: true, force: true });
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`UPDATE sources SET local_path = $1 WHERE id = 'default'`, [goneDir]);
const result = await writeFactsToFence(
engine,
{ sourceId: 'default', localPath: goneDir, slug: 'people/erin', resolutionSource: 'exact_page' },
[baseInput()],
);
expect(result.inserted).toBe(0);
expect(result.targetUnresolvable).toBe(true);
expect(existsSync(goneDir)).toBe(false);
});
});
// Cleanup any leftover tempdirs after the whole suite.
afterAll(() => {
// No-op: each test cleaned up via the beforeEach; this is a safety net.
try {
if (brainDir) rmSync(brainDir, { recursive: true, force: true });
} catch {
/* best-effort */
}
});
describe('writeFactsToFence — DB-body mirror never persists an empty content_hash (wave review)', () => {
test('a page row with no content_hash gets a non-empty one from the mirror', async () => {
const target = { sourceId: 'default', localPath: brainDir, slug: 'people/hashless', resolutionSource: 'exact_page' as const };
await writeFactsToFence(engine, target, [baseInput()]);
// The fence writer only stub-creates the FILE; sync creates the row. Import
// it, then drop the hash to model a row that lost it.
const stub = readFileSync(join(brainDir, 'people/hashless.md'), 'utf-8');
await importFromContent(engine, 'people/hashless', stub, { noEmbed: true, sourceId: 'default' });
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`UPDATE pages SET content_hash = NULL WHERE slug = 'people/hashless'`);
const r = await writeFactsToFence(engine, target, [baseInput({ fact: 'Raised a seed round' })]);
expect(r.inserted).toBe(1);
const page = await engine.getPage('people/hashless', { sourceId: 'default' });
expect(page?.compiled_truth).toContain('Raised a seed round');
expect(typeof page?.content_hash).toBe('string');
expect(page!.content_hash!.length).toBeGreaterThan(0);
});
});