Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { afterAll, beforeAll, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { configDir } from '../src/core/config.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { parseMarkdown, serializePageToMarkdown } from '../src/core/markdown.ts';
import { acceptWriterTransfer, acquireWorktree, claimWorktree, getWorktreeBinding, prepareWriterTransfer } from '../src/core/persistence/ownership.ts';
import { registerLocalWriter, withVerifiedLocalRegistration, type LocalRegistration } from '../src/core/persistence/identity.ts';
import { runReconcileApply, runReconcileBackups, runReconcilePreview, assertReconcileOutputPath } from '../src/core/persistence/reconcile.ts';
import { fileClaimCandidatesQuery } from '../src/core/persistence/reconcile-state.ts';
import { prepareFileTarget } from '../src/core/persistence/page-prepare.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { admitWrite, claimNextWrite, compactWriteReceipts, getWriteRequest } from '../src/core/persistence/journal.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
import { submissionAuthority } from '../src/core/persistence/authority.ts';
import { retainReconcileBackup } from '../src/core/persistence/reconcile-backup.ts';
import { prepareReconcileMutation } from '../src/core/persistence/reconcile-prepare.ts';
import { publishMutation } from '../src/core/persistence/coordinator.ts';
import { localHostId } from '../src/core/persistence/identity.ts';
import { parseFactsFence, renderFactsTable, replaceOrInsertFactsFence, upsertFactRow } from '../src/core/facts-fence.ts';
import { sha256 } from '../src/core/persistence/digest.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { operationsByName } from '../src/core/operations.ts';
import { reconcileCanonical } from '../src/core/persistence/reconcile-merge.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { withEnv } from './helpers/with-env.ts';
import { dropOriginIndex } from './helpers/origin-index.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
const home = mkdtempSync(join(tmpdir(), 'gbrain-reconcile-'));
const engines: BrainEngine[] = [];
let closePostgres: (() => Promise<void>) | undefined;
beforeAll(async () => {
const engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); engines.push(engine);
if (process.env.DATABASE_URL) { const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL); engines.push(pg.engine); closePostgres = pg.close; }
// Several tests seed legacy shared origins, which only a brain whose pages_live_origin_key index is pending holds (#6948).
for (const engine of engines) await dropOriginIndex(engine);
}, 120_000);
afterAll(async () => {
await withEnv({ GBRAIN_HOME: home }, async () => {
for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
});
await closePostgres?.(); rmSync(home, { recursive: true, force: true });
});
async function fixture(engine: BrainEngine, enabled = false, body = 'A useful durable example observation.', slug = 'notes/example') {
await disposePersistenceConsumer(engine);
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
const id = `reconcile-${randomUUID().slice(0, 12)}`, root = join(home, id);
mkdirSync(join(root, 'notes'), { recursive: true });
await engine.executeRaw('INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,\'{}\')', [id, root]);
const content = `---\ntype: note\ntitle: Example\ncustom_database: kept\nprofile:\n role: example-role\n---\n${body}\n`;
await importFromContent(engine, slug, content, { sourceId: id, sourcePath: `${slug}.md`, noEmbed: true });
const snapshot = (await engine.readPageSnapshot(slug, { sourceId: id }))!;
const file = join(root, `${slug}.md`);
writeFileSync(file, serializePageToMarkdown({ ...snapshot.page, frontmatter: { profile: { location: 'example-place' }, custom_file: 'kept' } }, snapshot.tags));
const binding = await claimWorktree(engine, id, root);
await engine.executeRaw('UPDATE persistence_brain SET enabled=$1 WHERE singleton=1', [enabled]);
const registration = await registerLocalWriter(engine, 'cli');
return { id, root, slug, file, binding, registration, snapshot };
}
const local = <T>(engine: BrainEngine, registration: LocalRegistration, fn: () => Promise<T>) => withVerifiedLocalRegistration(engine, registration, fn);
const isolated = (fn: (engine: BrainEngine) => Promise<void>) => withEnv({ GBRAIN_HOME: home, OPENAI_API_KEY: undefined, ANTHROPIC_API_KEY: undefined }, async () => {
for (const engine of engines) await fn(engine);
});
async function preparedRepair(engine: BrainEngine, f: Awaited<ReturnType<typeof fixture>>) {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const authority = await submissionAuthority({ engine, remote: false } as OperationContext, 'put_page', f.id, preview.preconditions.source_incarnation, f.slug);
const requestId = randomUUID(), reference = await retainReconcileBackup(engine, preview, authority.principal, requestId);
const callerIntent = { kind: 'canonical_reconcile', preview };
await admitWrite(engine, { principal: authority.principal, operation: 'put_page', sourceId: f.id, sourceIncarnation: preview.preconditions.source_incarnation,
slug: f.slug, pageId: f.snapshot.page.id, worktreeId: f.binding.worktree_id, topologyGeneration: f.binding.topology_generation,
requestId, authority, callerIntent, intent: { ...callerIntent, backup_reference: reference } });
const row = (await claimNextWrite(engine, localHostId()))!;
expect(row.request_id).toBe(requestId);
const prepared = await prepareReconcileMutation(engine, row, { engine: engine.kind });
return { preview, authority, reference, row, prepared, params: { source_id: f.id, slug: f.slug, preview, request_id: requestId } };
}
test('repairs claimed enabled and disabled sources without topology changes and retains both preimages', async () => isolated(async engine => {
for (const enabled of [false, true]) {
const f = await fixture(engine, enabled), before = readFileSync(f.file);
await expect(prepareFileTarget(engine, { source_id: f.id, slug: f.slug, worktree_id: f.binding.worktree_id }, f.snapshot, 'next')).rejects.toMatchObject({ code: 'source_changed' });
const [sourceBefore] = await engine.executeRaw('SELECT incarnation,last_commit,last_sync_at,config FROM sources WHERE id=$1', [f.id]);
await local(engine, f.registration, async () => {
const preview = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(preview.status).toBe('ready');
expect(preview.preview.result.frontmatter).toMatchObject({ custom_database: 'kept', custom_file: 'kept', profile: { role: 'example-role', location: 'example-place' } });
expect(readFileSync(f.file)).toEqual(before);
expect((await engine.readPageSnapshot(f.slug, { sourceId: f.id }))?.revision).toBe(f.snapshot.revision);
const receipt = await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview: preview.preview, request_id: randomUUID() });
expect(receipt.state).toBe('committed');
expect(receipt.outcome).toMatchObject({ status: 'reconciled', database_changed: true, file_changed: true });
const outcome = receipt.outcome as { backup_reference: string };
const backup = join(configDir(), 'reconciliation-previews', outcome.backup_reference);
if (process.platform !== 'win32') {
expect(statSync(backup).mode & 0o777).toBe(0o600);
expect(statSync(join(configDir(), 'reconciliation-previews')).mode & 0o777).toBe(0o700);
}
expect(JSON.parse(readFileSync(backup, 'utf8')).preview.preimages.file_base64).toBe(before.toString('base64'));
const current = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
expect(current.page.frontmatter).toEqual(preview.preview.result.frontmatter);
expect(parseMarkdown(readFileSync(f.file, 'utf8'), f.slug).frontmatter).toEqual(current.page.frontmatter);
await expect(prepareFileTarget(engine, { source_id: f.id, slug: f.slug, worktree_id: f.binding.worktree_id }, current, 'next')).resolves.toBeDefined();
});
expect(await getWorktreeBinding(engine, f.id)).toEqual(f.binding);
expect((await engine.executeRaw('SELECT incarnation,last_commit,last_sync_at,config FROM sources WHERE id=$1', [f.id]))[0]).toEqual(sourceBefore);
expect((await engine.executeRaw<{ enabled: boolean }>('SELECT enabled FROM persistence_brain WHERE singleton=1'))[0].enabled).toBe(enabled);
}
}), 120_000);
test('same-ID replay precedes raw CAS, survives compaction and never allocates another backup', async () => isolated(async engine => {
const f = await fixture(engine);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const params = { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() };
const receipt = await runReconcileApply(engine, params);
const files = readdirSync(join(configDir(), 'reconciliation-previews'));
writeFileSync(f.file, 'A later independent edit.\n');
expect((await runReconcileApply(engine, params)).revision).toBe(receipt.revision);
await disposePersistenceConsumer(engine);
await engine.executeRaw("UPDATE persistence_effects SET state='committed' WHERE request_id=(SELECT id FROM persistence_requests WHERE request_id=$1::uuid)", [params.request_id]);
await engine.executeRaw("UPDATE persistence_requests SET completed_at=now()-interval '60 days' WHERE request_id=$1::uuid", [params.request_id]);
await compactWriteReceipts(engine);
expect(await runReconcileApply(engine, params)).toMatchObject({ state: 'committed', compacted: true, revision: receipt.revision });
expect(readdirSync(join(configDir(), 'reconciliation-previews'))).toEqual(files);
await expect(runReconcileApply(engine, { ...params, preview: { ...preview, preview_id: randomUUID() } })).rejects.toMatchObject({ code: 'idempotency_conflict' });
});
}), 120_000);
test('raw-byte, policy, withdrawal and owner epoch changes refuse new admission', async () => isolated(async engine => {
for (const mutation of ['raw', 'policy', 'withdrawal', 'owner']) {
const f = await fixture(engine);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
if (mutation === 'raw') writeFileSync(f.file, readFileSync(f.file, 'utf8').replace(/\n/g, '\r\n'));
if (mutation === 'policy') await engine.setConfig('content_sanity.bytes_warn', String(200000 + Math.floor(Math.random() * 100)));
if (mutation === 'withdrawal') await engine.executeRaw("INSERT INTO fact_withdrawals(source_id,visibility,fact_hash) VALUES($1,'world',$2)", [f.id, 'a'.repeat(64)]);
if (mutation === 'owner') await engine.executeRaw('UPDATE persistence_worktrees SET owner_epoch=owner_epoch+1 WHERE id=$1::uuid', [f.binding.worktree_id]);
await expect(runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() })).rejects.toMatchObject({ code: 'source_changed' });
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
});
}
}), 120_000);
test('file-only drift publishes instead of a global no-op and preserves the DB revision', async () => isolated(async engine => {
const f = await fixture(engine);
writeFileSync(f.file, serializePageToMarkdown({ ...f.snapshot.page, frontmatter: {} }, []));
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const result = await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() });
expect(result.outcome).toMatchObject({ database_changed: false, file_changed: true });
expect(result.revision).toBe(f.snapshot.revision);
expect(parseMarkdown(readFileSync(f.file, 'utf8'), f.slug).frontmatter.custom_database).toBe('kept');
});
}), 120_000);
test('original and current grants are enforced before reading either preimage', async () => isolated(async engine => {
const f = await fixture(engine);
await expect(runReconcilePreview(engine, { source_id: f.id, slug: f.slug })).rejects.toMatchObject({ code: 'permission_denied' });
const narrow = await registerLocalWriter(engine, 'stdio');
await expect(local(engine, narrow, () => runReconcilePreview(engine, { source_id: f.id, slug: f.slug }))).rejects.toMatchObject({ code: 'permission_denied' });
const originalRead = engine.readPageSnapshot;
let reads = 0;
engine.readPageSnapshot = async (...args) => { reads++; return originalRead.apply(engine, args); };
try {
await local(engine, f.registration, async () => {
await engine.executeRaw("UPDATE persistence_local_writers SET grant_ceiling=$2::text::jsonb WHERE id=$1::uuid", [f.registration.id,
JSON.stringify({ sourceIds: ['*'], scopes: ['write'], operations: ['put_page'], slugPrefixes: ['other/'] })]);
await expect(runReconcilePreview(engine, { source_id: f.id, slug: f.slug })).rejects.toMatchObject({ code: 'permission_denied' });
expect(reads).toBe(0);
});
} finally {
engine.readPageSnapshot = originalRead;
await engine.executeRaw("UPDATE persistence_local_writers SET grant_ceiling=$2::text::jsonb WHERE id=$1::uuid", [f.registration.id,
JSON.stringify({ sourceIds: ['*'], scopes: ['read', 'write'], operations: null, slugPrefixes: null })]);
}
await expect(assertReconcileOutputPath(engine, f.id, join(f.root, 'private.json'))).rejects.toMatchObject({ code: 'permission_denied' });
}), 120_000);
test('conflicting bodies require reviewed decisions and modified artifacts cannot apply', async () => isolated(async engine => {
const f = await fixture(engine);
writeFileSync(f.file, readFileSync(f.file, 'utf8').replace('A useful durable example observation.', 'A different carefully reviewed observation.'));
await local(engine, f.registration, async () => {
const initial = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(initial.status).toBe('needs_resolution');
expect(initial.conflict_paths).toEqual(['/compiled_truth']);
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug, from: initial.preview,
decisions: [{ path: '/compiled_truth', action: 'take_file' }, { path: '/frontmatter/custom_database', action: 'delete' }] });
expect(preview.status).toBe('ready');
expect(preview.result.compiled_truth).toBe('A different carefully reviewed observation.');
await expect(runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview: { ...preview, unexpected: true }, request_id: randomUUID() })).rejects.toMatchObject({ code: 'invalid_params' });
expect((await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() })).state).toBe('committed');
});
}), 120_000);
test('unchanged safety assessments reuse canonical stamps without fresh revision churn', async () => isolated(async engine => {
const f = await fixture(engine, true, 'Just a moment...\n\nChecking your browser before accessing this website.\nVerify you are human.');
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(preview.result.frontmatter.quarantine).toBeDefined();
const first = await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() });
const second = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(second.preview.result).toEqual(preview.result);
const repeated = await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview: second.preview, request_id: randomUUID() });
expect(repeated.revision).toBe(first.revision);
expect(repeated.outcome).toMatchObject({ database_changed: false, file_changed: false });
let importNoop = false;
await importFromContent(engine, f.slug, readFileSync(f.file, 'utf8'), { sourceId: f.id, sourcePath: 'notes/example.md', noEmbed: true,
prepare: async value => { importNoop = value.noop; expect(value.parsedPage.frontmatter).toEqual(preview.result.frontmatter); return value.result; } });
expect(importNoop).toBe(true);
});
}), 120_000);
test('private and withdrawn timeline facts survive file choices without resurrection', async () => isolated(async engine => {
const privateBody = upsertFactRow('Private biography.', { claim: 'Prefers a private example venue', kind: 'fact', visibility: 'private', confidence: 1, notability: 'medium' }).body;
const timeline = upsertFactRow('## Timeline\n', { claim: 'Previously preferred the old example venue', kind: 'fact', visibility: 'world', confidence: 1, notability: 'medium' }).body.replace('| 1 |', '| 2 |');
const f = await fixture(engine, false, `${privateBody}\n<!-- timeline -->\n${timeline}`);
await engine.executeRaw("INSERT INTO fact_withdrawals(source_id,visibility,fact_hash) VALUES($1,'world',$2)",
[f.id, sha256('previously preferred the old example venue')]);
writeFileSync(f.file, serializePageToMarkdown({ ...f.snapshot.page, compiled_truth: 'A revised public biography.' }, []));
await local(engine, f.registration, async () => {
const initial = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const decisions = initial.preview.conflicts.map(c => ({ path: c.path, action: 'take_file' }));
const resolved = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug, from: initial.preview, decisions });
expect(parseFactsFence(resolved.preview.result.compiled_truth).facts[0].visibility).toBe('private');
const retired = parseFactsFence(resolved.preview.result.timeline).facts[0];
expect(retired.validUntil).toBeDefined();
expect((await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview: resolved.preview, request_id: randomUUID() })).state).toBe('committed');
const current = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
expect(parseFactsFence(current.page.compiled_truth).facts[0].visibility).toBe('private');
expect(parseFactsFence(current.page.timeline).facts[0].validUntil).toBe(retired.validUntil);
});
}), 120_000);
test('matching legacy scan state migrates only during canonical publication', async () => isolated(async engine => {
const f = await fixture(engine);
const marker = f.snapshot.page.content_hash!.slice(0, 16);
await withCoordinatedWrite(engine, [f.id], () => engine.executeRaw("UPDATE pages SET frontmatter=frontmatter || $3::text::jsonb WHERE source_id=$1 AND slug=$2",
[f.id, f.slug, JSON.stringify({ atoms_scan_hash: marker, atoms_custom: 'preserve' })]), TEST_WRITE_ATTRIBUTION);
const before = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
writeFileSync(f.file, serializePageToMarkdown(before.page, before.tags));
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(preview.result.frontmatter.atoms_scan_hash).toBeUndefined();
expect(preview.result.frontmatter.atoms_custom).toBe('preserve');
expect(await engine.executeRaw('SELECT * FROM extract_atoms_page_state WHERE page_id=$1', [before.page.id])).toHaveLength(0);
const result = await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() });
expect(result.outcome).toMatchObject({ scan_state_transferred: true });
expect(await engine.executeRaw('SELECT tombstoned FROM extract_atoms_page_state WHERE page_id=$1', [before.page.id])).toEqual([{ tombstoned: true }]);
});
}), 120_000);
test('capacity refusal is bounded, preserves originals, and admits no request', async () => isolated(async engine => {
const f = await fixture(engine), raw = readFileSync(f.file);
await local(engine, f.registration, async () => {
await engine.setConfig('persistence.limits.brain_lifetime_ids', '0');
try {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
await expect(runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() })).rejects.toMatchObject({ code: 'queue_capacity' });
expect(readFileSync(f.file)).toEqual(raw);
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
} finally { await engine.executeRaw("DELETE FROM config WHERE key='persistence.limits.brain_lifetime_ids'"); }
});
}), 120_000);
test('queued intent resumes with a fresh consumer and retains its accepted request identity', async () => isolated(async engine => {
for (const enabled of [false, true]) {
const f = await fixture(engine, enabled);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const ctx = { engine, remote: false, sourceId: f.id } as OperationContext;
const authority = await submissionAuthority(ctx, 'put_page', f.id, preview.preconditions.source_incarnation, f.slug);
const requestId = randomUUID();
const reference = await retainReconcileBackup(engine, preview, authority.principal, requestId);
const callerIntent = { kind: 'canonical_reconcile', preview };
await admitWrite(engine, { principal: authority.principal, operation: 'put_page', sourceId: f.id,
sourceIncarnation: preview.preconditions.source_incarnation, slug: f.slug, pageId: f.snapshot.page.id,
worktreeId: f.binding.worktree_id, topologyGeneration: f.binding.topology_generation, requestId, authority, callerIntent,
intent: { ...callerIntent, backup_reference: reference } });
await expect(runReconcileBackups(engine, { source_id: f.id, slug: f.slug, action: 'remove', backup_reference: reference })).rejects.toMatchObject({ code: 'recovery_required' });
await disposePersistenceConsumer(engine);
const result = await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: requestId });
expect(result).toMatchObject({ state: 'committed', request_id: requestId });
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(1);
expect(JSON.parse(readFileSync(join(configDir(), 'reconciliation-previews', reference), 'utf8')).preview.result_digest).toBe(preview.result_digest);
await disposePersistenceConsumer(engine);
const listing = await runReconcileBackups(engine, { source_id: f.id, slug: f.slug, action: 'list' });
expect(listing.backups).toMatchObject([{ backup_reference: reference, retained: true, removable: true }]);
expect(await runReconcileBackups(engine, { source_id: f.id, slug: f.slug, action: 'remove', backup_reference: reference })).toMatchObject({ removed: true });
expect((await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: requestId })).revision).toBe(result.revision);
});
}
}), 120_000);
test('publication rechecks grants after preparation without touching the canonical file', async () => isolated(async engine => {
const f = await fixture(engine), raw = readFileSync(f.file);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const authority = await submissionAuthority({ engine, remote: false } as OperationContext, 'put_page', f.id, preview.preconditions.source_incarnation, f.slug);
const requestId = randomUUID(), reference = await retainReconcileBackup(engine, preview, authority.principal, requestId);
const callerIntent = { kind: 'canonical_reconcile', preview };
await admitWrite(engine, { principal: authority.principal, operation: 'put_page', sourceId: f.id, sourceIncarnation: preview.preconditions.source_incarnation,
slug: f.slug, pageId: f.snapshot.page.id, worktreeId: f.binding.worktree_id, topologyGeneration: f.binding.topology_generation,
requestId, authority, callerIntent, intent: { ...callerIntent, backup_reference: reference } });
const row = (await claimNextWrite(engine, localHostId()))!;
const prepared = await prepareReconcileMutation(engine, row, { engine: engine.kind });
await engine.executeRaw("UPDATE persistence_local_writers SET grant_ceiling=$2::text::jsonb WHERE id=$1::uuid", [f.registration.id,
JSON.stringify({ sourceIds: ['*'], scopes: ['read'], operations: null, slugPrefixes: null })]);
try {
const result = await publishMutation(engine, row, prepared);
expect(result.state).not.toBe('committed');
expect((await getWriteRequest(engine, authority.principal, requestId))?.error_code).toBe('permission_denied');
expect(readFileSync(f.file)).toEqual(raw);
} finally {
await engine.executeRaw("UPDATE persistence_local_writers SET grant_ceiling=$2::text::jsonb WHERE id=$1::uuid", [f.registration.id,
JSON.stringify({ sourceIds: ['*'], scopes: ['read', 'write'], operations: null, slugPrefixes: null })]);
}
});
}), 120_000);
test('concurrent same-ID callers replay a winner committed between lookup and live CAS', async () => isolated(async engine => {
for (const pauseLookup of [1, 3]) {
const f = await fixture(engine);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const params = { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() };
const executeRaw = engine.executeRaw;
let release!: () => void, paused!: () => void, reads = 0;
const held = new Promise<void>(resolve => { release = resolve; });
const reached = new Promise<void>(resolve => { paused = resolve; });
engine.executeRaw = async function(this: BrainEngine, sql: string, values?: unknown[]) {
const result = await executeRaw.call(this, sql, values);
if (sql.includes('SELECT * FROM persistence_requests WHERE principal_kind=') && values?.[2] === params.request_id && ++reads === pauseLookup) {
paused(); await held;
}
return result;
} as BrainEngine['executeRaw'];
try {
const delayed = runReconcileApply(engine, params);
await reached;
const winner = await runReconcileApply(engine, params);
expect(winner.state).toBe('committed');
release();
expect(await delayed).toMatchObject({ state: 'committed', request_id: params.request_id, revision: winner.revision });
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(1);
await expect(runReconcileApply(engine, { ...params, request_id: randomUUID() })).rejects.toMatchObject({ code: 'source_changed' });
} finally { release(); engine.executeRaw = executeRaw; }
});
}
}), 120_000);
test('valid empty metadata is ordinary input while malformed metadata and missing files are refused', async () => isolated(async engine => {
const f = await fixture(engine);
await local(engine, f.registration, async () => {
writeFileSync(f.file, '---\n{}\n---\nA useful durable example observation.\n');
expect((await runReconcilePreview(engine, { source_id: f.id, slug: f.slug })).preview.result.frontmatter.custom_database).toBe('kept');
for (const invalid of ['---\n[1, 2]\n---\nBody.', '---\nkey: [broken\n---\nBody.', '---\nkey: value\nBody.']) {
writeFileSync(f.file, invalid);
await expect(runReconcilePreview(engine, { source_id: f.id, slug: f.slug })).rejects.toMatchObject({ code: 'invalid_params' });
}
rmSync(f.file);
await expect(runReconcilePreview(engine, { source_id: f.id, slug: f.slug })).rejects.toMatchObject({ code: 'source_changed' });
});
}), 120_000);
test('a repaired page supports normal capture, put, delete and restore with revision-bound readback', async () => isolated(async engine => {
for (const enabled of [false, true]) {
const f = await fixture(engine, enabled);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect((await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() })).state).toBe('committed');
const ctx: OperationContext = { engine, remote: false, sourceId: f.id, config: { engine: engine.kind }, dryRun: false,
logger: { info() {}, warn() {}, error() {} } };
for (const operation of ['capture', 'put_page']) {
const before = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
const content = serializePageToMarkdown({ ...before.page, compiled_truth: `${before.page.compiled_truth}\n\nA new ${operation} observation.` }, before.tags);
const receipt = await operationsByName[operation]!.handler(ctx, { source_id: f.id, slug: f.slug, content,
expected_revision: before.revision, request_id: randomUUID() }) as Record<string, unknown>;
expect(receipt.state).toBe('committed');
const after = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
const file = parseMarkdown(readFileSync(f.file, 'utf8'), f.slug);
expect(reconcileCanonical(file, file.tags)).toEqual(reconcileCanonical(after.page, after.tags));
expect(after.page.compiled_truth).toContain(`A new ${operation} observation.`);
expect(after.page.frontmatter.custom_file).toBe('kept');
}
const before = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
const deleted = await operationsByName.delete_page!.handler(ctx, { source_id: f.id, slug: f.slug,
expected_revision: before.revision, request_id: randomUUID() }) as Record<string, unknown>;
expect(deleted.state).toBe('committed');
expect(existsSync(f.file)).toBe(false);
expect(await engine.readPageSnapshot(f.slug, { sourceId: f.id })).toBeNull();
const tombstone = (await engine.readPageSnapshot(f.slug, { sourceId: f.id, includeDeleted: true }))!;
const restored = await operationsByName.restore_page!.handler(ctx, { source_id: f.id, slug: f.slug,
expected_revision: tombstone.revision, request_id: randomUUID() }) as Record<string, unknown>;
expect(restored.state).toBe('committed');
const after = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
const file = parseMarkdown(readFileSync(f.file, 'utf8'), f.slug);
expect(reconcileCanonical(file, file.tags)).toEqual(reconcileCanonical(after.page, after.tags));
expect(after.page.compiled_truth).toBe(before.page.compiled_truth);
expect(after.page.source_kind).toBe(before.page.source_kind);
expect(after.page.ingested_via).toBe(before.page.ingested_via);
});
}
}), 120_000);
test('source substitution, changed canonical revisions and recreated pages never consume an old preview', async () => isolated(async engine => {
for (const mutation of ['source', 'revision', 'identity']) {
const f = await fixture(engine), raw = readFileSync(f.file);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
let sourceId = f.id;
if (mutation === 'source') sourceId = (await fixture(engine)).id;
else await withCoordinatedWrite(engine, [f.id], async () => {
if (mutation === 'identity') await engine.deletePage(f.slug, { sourceId: f.id });
await engine.putPage(f.slug, { type: 'note', title: 'Example', compiled_truth: 'A later database observation.', frontmatter: {} }, { sourceId: f.id });
}, TEST_WRITE_ATTRIBUTION);
await expect(runReconcileApply(engine, { source_id: sourceId, slug: f.slug, preview, request_id: randomUUID() })).rejects.toMatchObject({
code: mutation === 'source' ? 'invalid_params' : 'source_changed' });
expect(readFileSync(f.file)).toEqual(raw);
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
});
}
}), 120_000);
test('derived page telemetry does not stale canonical preimages and CRLF-only differences are explicit', async () => isolated(async engine => {
const f = await fixture(engine);
writeFileSync(f.file, serializePageToMarkdown(f.snapshot.page, f.snapshot.tags).replace(/\n/g, '\r\n'));
await local(engine, f.registration, async () => {
const result = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(result).toMatchObject({ status: 'ready', line_endings: 'crlf', formatting_only: true });
await engine.executeRaw('UPDATE pages SET emotional_weight=0.3 WHERE id=$1', [f.snapshot.page.id]);
expect((await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview: result.preview, request_id: randomUUID() })).state).toBe('committed');
expect(readFileSync(f.file, 'utf8')).not.toContain('\r\n');
expect((await engine.readPageSnapshot(f.slug, { sourceId: f.id }))?.revision).toBe(f.snapshot.revision);
});
}), 120_000);
test('unadmitted private backups cannot be removed through receipt administration', async () => isolated(async engine => {
const f = await fixture(engine);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const authority = await submissionAuthority({ engine, remote: false } as OperationContext, 'put_page', f.id, preview.preconditions.source_incarnation, f.slug);
const reference = await retainReconcileBackup(engine, preview, authority.principal, randomUUID());
await expect(runReconcileBackups(engine, { source_id: f.id, slug: f.slug, action: 'remove', backup_reference: reference })).rejects.toMatchObject({ code: 'permission_denied' });
expect(existsSync(join(configDir(), 'reconciliation-previews', reference))).toBe(true);
});
}), 120_000);
test('public warn-mode put_page rejects reserved reconciliation fields for local and remote callers before admission', async () => isolated(async engine => {
const f = await fixture(engine);
await engine.setConfig('mcp.strict_params', 'warn');
const stdio = await registerLocalWriter(engine, 'stdio');
for (const remote of [false, true]) for (const extra of [{ kind: 'canonical_reconcile' }, { preview: {} }, { backup_reference: 'private-backup' }]) {
const result = await local(engine, remote ? stdio : f.registration, () => dispatchToolCall(engine, 'put_page', {
source_id: f.id, slug: f.slug, content: 'A public caller observation.', expected_revision: f.snapshot.revision,
request_id: randomUUID(), ...extra,
}, { remote, sourceId: f.id, config: { engine: engine.kind }, auth: { token: 'fixture', clientId: 'fixture-client', scopes: ['read', 'write'], sourceId: f.id },
logger: { info() {}, warn() {}, error() {} } }));
expect(result.isError).toBe(true);
// #5970: a write refuses every undeclared parameter at dispatch, in warn mode too, so the reserved field is
// named as unknown before admission's own reserved-field refusal would run; nothing is admitted either way.
expect(JSON.parse((result.content[0] as { text: string }).text)).toMatchObject({ error: 'invalid_params', suggestion: `Unknown parameter "${Object.keys(extra)[0]}".` });
}
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
}), 120_000);
test('a real ownership transfer to a matching successor invalidates an unadmitted preview without changing canonical content', async () => isolated(async engine => {
for (const enabled of [false, true]) {
const f = await fixture(engine, enabled), before = readFileSync(f.file);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const successor = join(home, `${f.id}-successor`), successorHost = randomUUID();
cpSync(f.root, successor, { recursive: true });
const transfer = await prepareWriterTransfer(engine, f.id);
await acceptWriterTransfer(engine, f.id, successor, transfer.owner_epoch, transfer.manifest.digest, successorHost);
const binding = (await getWorktreeBinding(engine, f.id, successorHost))!;
expect(binding.owner_host_id).toBe(successorHost);
expect(binding.local_path).toBe(successor);
expect(Number(binding.owner_epoch)).toBe(Number(f.binding.owner_epoch) + 1);
await expect(runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() })).rejects.toMatchObject({ code: 'owner_unavailable' });
expect(readFileSync(f.file)).toEqual(before);
expect(readFileSync(join(successor, 'notes/example.md'))).toEqual(before);
expect(await engine.readPageSnapshot(f.slug, { sourceId: f.id })).toEqual(f.snapshot);
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
expect((await engine.executeRaw<{ enabled: boolean }>('SELECT enabled FROM persistence_brain WHERE singleton=1'))[0].enabled).toBe(enabled);
});
}
}), 120_000);
test('a publication holding the native root excludes real transfer until commit and preserves replay after transfer', async () => isolated(async engine => {
for (const enabled of [false, true]) {
const f = await fixture(engine, enabled), before = readFileSync(f.file);
await local(engine, f.registration, async () => {
const repair = await preparedRepair(engine, f);
let release!: () => void, reached!: () => void;
const held = new Promise<void>(resolve => { release = resolve; });
const preparedBoundary = new Promise<void>(resolve => { reached = resolve; });
const publication = publishMutation(engine, repair.row, repair.prepared, localHostId(), {
boundary: async name => { if (name === 'prepared') { reached(); await held; } },
});
try {
await preparedBoundary;
const competingLock = await acquireWorktree(f.binding);
if (competingLock) await competingLock.release();
expect(competingLock).toBeNull();
await expect(prepareWriterTransfer(engine, f.id)).rejects.toMatchObject({ code: 'write_pending' });
const pending = (await getWriteRequest(engine, repair.authority.principal, repair.row.request_id))!;
expect(pending.state).toBe('running');
expect(pending.recovery).not.toBeNull();
expect((await getWorktreeBinding(engine, f.id))?.state).toBe('active');
expect(readFileSync(f.file)).toEqual(before);
expect(await engine.readPageSnapshot(f.slug, { sourceId: f.id })).toEqual(f.snapshot);
} finally { release(); await publication; }
const committed = await publication;
expect(committed.state).toBe('committed');
const receipt = await runReconcileApply(engine, repair.params);
const canonical = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
const repairedBytes = readFileSync(f.file);
expect(reconcileCanonical(canonical.page, canonical.tags)).toEqual(repair.preview.result);
const successor = join(home, `${f.id}-successor`), successorHost = randomUUID();
cpSync(f.root, successor, { recursive: true });
const transfer = await prepareWriterTransfer(engine, f.id);
await acceptWriterTransfer(engine, f.id, successor, transfer.owner_epoch, transfer.manifest.digest, successorHost);
expect((await getWorktreeBinding(engine, f.id, successorHost))?.owner_host_id).toBe(successorHost);
expect(await runReconcileApply(engine, repair.params)).toEqual(receipt);
expect(readFileSync(f.file)).toEqual(repairedBytes);
expect(readFileSync(join(successor, 'notes/example.md'))).toEqual(repairedBytes);
expect(await engine.readPageSnapshot(f.slug, { sourceId: f.id })).toEqual(canonical);
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(1);
expect((await engine.executeRaw<{ enabled: boolean }>('SELECT enabled FROM persistence_brain WHERE singleton=1'))[0].enabled).toBe(enabled);
});
}
}), 120_000);
test('file and database edits after reconciliation preparation abort publication without overwriting the competing state', async () => isolated(async engine => {
for (const enabled of [false, true]) for (const mutation of ['file', 'database']) {
const f = await fixture(engine, enabled), originalBytes = readFileSync(f.file);
await local(engine, f.registration, async () => {
const repair = await preparedRepair(engine, f);
const competingBytes = Buffer.from(`${originalBytes.toString('utf8')}\nA competing local file observation.\n`);
if (mutation === 'file') writeFileSync(f.file, competingBytes);
else await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], () => tx.putPage(f.slug, {
type: f.snapshot.page.type, title: f.snapshot.page.title, compiled_truth: 'A competing database observation.',
timeline: f.snapshot.page.timeline, frontmatter: f.snapshot.page.frontmatter,
}, { sourceId: f.id, expectedRevision: f.snapshot.revision }), TEST_WRITE_ATTRIBUTION));
const competingSnapshot = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
const result = await publishMutation(engine, repair.row, repair.prepared);
expect(result.state).toBe('conflict');
expect(result.error_code).toBe(mutation === 'file' ? 'source_changed' : 'revision_conflict');
expect(readFileSync(f.file)).toEqual(mutation === 'file' ? competingBytes : originalBytes);
expect(await engine.readPageSnapshot(f.slug, { sourceId: f.id })).toEqual(competingSnapshot);
expect(competingSnapshot.revision === f.snapshot.revision).toBe(mutation === 'file');
const receipt = (await getWriteRequest(engine, repair.authority.principal, repair.row.request_id))!;
expect(receipt.recovery).toBeNull();
expect(receipt.publication_started).toBe(false);
expect(JSON.parse(readFileSync(join(configDir(), 'reconciliation-previews', repair.reference), 'utf8')).preview.preimages.file_base64).toBe(originalBytes.toString('base64'));
});
}
}), 120_000);
test('historical basename origins in separate slug directories remain distinct canonical files', async () => isolated(async engine => {
for (const enabled of [false, true]) {
const f = await fixture(engine, enabled), otherSlug = 'other/example', otherFile = join(f.root, 'other/example.md');
mkdirSync(join(f.root, 'other'), { recursive: true });
await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], async () => {
await tx.executeRaw('UPDATE pages SET source_path=$3 WHERE source_id=$1 AND slug=$2', [f.id, f.slug, 'example.md']);
await tx.putPage(otherSlug, { type: 'note', title: 'Other example', compiled_truth: 'An independent historical basename page.',
frontmatter: { independent: true } }, { sourceId: f.id });
// #6948: two pages recording one basename are legacy data no writer creates now.
await tx.executeRaw('UPDATE pages SET source_path=$3 WHERE source_id=$1 AND slug=$2', [f.id, otherSlug, 'example.md']);
}, TEST_WRITE_ATTRIBUTION));
const other = (await engine.readPageSnapshot(otherSlug, { sourceId: f.id }))!;
writeFileSync(otherFile, serializePageToMarkdown(other.page, other.tags));
const otherBytes = readFileSync(otherFile);
await local(engine, f.registration, async () => {
const result = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(result).toMatchObject({ status: 'ready', relative_path: 'notes/example.md' });
expect((await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview: result.preview, request_id: randomUUID() })).state).toBe('committed');
expect(readFileSync(otherFile)).toEqual(otherBytes);
const after = (await engine.readPageSnapshot(otherSlug, { sourceId: f.id }))!;
expect(after.revision).toBe(other.revision);
expect(reconcileCanonical(after.page, after.tags)).toEqual(reconcileCanonical(other.page, other.tags));
expect(after.page.source_path).toBe(other.page.source_path);
});
}
}), 120_000);
test('shared provenance URI does not override distinct explicit canonical paths', async () => isolated(async engine => {
for (const enabled of [false, true]) {
const f = await fixture(engine, enabled), otherSlug = 'other/provenance', otherFile = join(f.root, 'other/provenance.md');
const sharedUri = pathToFileURL(f.file).href;
mkdirSync(join(f.root, 'other'), { recursive: true });
await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], async () => {
await tx.executeRaw('UPDATE pages SET source_uri=$3 WHERE source_id=$1 AND slug=$2', [f.id, f.slug, sharedUri]);
await tx.putPage(otherSlug, { type: 'note', title: 'Independent provenance', compiled_truth: 'A distinct file sharing ingestion provenance.',
frontmatter: {}, source_path: 'other/provenance.md', source_uri: sharedUri }, { sourceId: f.id });
}, TEST_WRITE_ATTRIBUTION));
const other = (await engine.readPageSnapshot(otherSlug, { sourceId: f.id }))!;
writeFileSync(otherFile, serializePageToMarkdown(other.page, other.tags));
const otherBytes = readFileSync(otherFile);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(preview.status).toBe('ready');
expect((await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() })).state).toBe('committed');
expect(readFileSync(otherFile)).toEqual(otherBytes);
const after = (await engine.readPageSnapshot(otherSlug, { sourceId: f.id }))!;
expect(after.revision).toBe(other.revision);
expect(reconcileCanonical(after.page, after.tags)).toEqual(reconcileCanonical(other.page, other.tags));
expect(after.page.source_path).toBe(other.page.source_path);
expect(after.page.source_uri).toBe(sharedUri);
});
}
}), 120_000);
test('genuine shared-file origins through explicit paths or URI fallback still refuse reconciliation', async () => isolated(async engine => {
for (const enabled of [false, true]) for (const origin of ['path', 'dot-path', 'repeated-separators', 'uri']) {
const f = await fixture(engine, enabled), raw = readFileSync(f.file), uri = pathToFileURL(f.file).href;
await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], async () => {
const sourcePath = origin === 'uri' ? null : origin === 'dot-path' ? './notes/example.md'
: origin === 'repeated-separators' ? 'notes//example.md' : 'notes/example.md';
await tx.putPage('other/collision', { type: 'note', title: 'Collision', compiled_truth: 'Another page claiming the same file.',
frontmatter: {}, source_uri: origin === 'uri' ? uri : null }, { sourceId: f.id });
// #6948: a second live claimant of a file is legacy data no writer creates now.
if (sourcePath) await tx.executeRaw('UPDATE pages SET source_path=$3 WHERE source_id=$1 AND slug=$2', [f.id, 'other/collision', sourcePath]);
}, TEST_WRITE_ATTRIBUTION));
const snapshot = await engine.readPageSnapshot(f.slug, { sourceId: f.id });
await local(engine, f.registration, async () => {
await expect(runReconcilePreview(engine, { source_id: f.id, slug: f.slug })).rejects.toMatchObject({
code: 'source_changed', message: 'Several pages claim the recorded canonical file.' });
expect(readFileSync(f.file)).toEqual(raw);
expect(await engine.readPageSnapshot(f.slug, { sourceId: f.id })).toEqual(snapshot);
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
});
}
}), 120_000);
// #6222 (fix wave 12, W1.3): the census was capped at 100 candidates, so a common file name
// (date-named archives such as channels/<name>/2015-09.md) refused every page that had it.
// It now pages through every same-name candidate and realpath still decides ownership.
test('same-name pages in other directories and a shared provenance URI no longer refuse reconciliation', async () => isolated(async engine => {
const f = await fixture(engine, true), uri = pathToFileURL(f.file).href;
await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], async () => {
await tx.executeRaw('UPDATE pages SET source_uri=$3 WHERE source_id=$1 AND slug=$2', [f.id, f.slug, uri]);
await tx.executeRaw(`INSERT INTO pages(source_id,slug,type,title,compiled_truth,frontmatter,source_path,source_uri)
SELECT $1,'channels/c'||n||'/example','note','Channel '||n,'Independent channel '||n,'{}'::jsonb,'channels/c'||n||'/example.md',
CASE WHEN n % 2 = 0 THEN $2 END FROM generate_series(1,205) n`, [f.id, uri]);
}, TEST_WRITE_ATTRIBUTION));
for (let n = 1; n <= 205; n++) {
mkdirSync(join(f.root, 'channels', `c${n}`), { recursive: true });
writeFileSync(join(f.root, 'channels', `c${n}`, 'example.md'), `Independent channel ${n}\n`);
}
const neighbours = () => engine.executeRaw('SELECT slug,source_path,knowledge_revision FROM pages WHERE source_id=$1 AND slug<>$2 ORDER BY id', [f.id, f.slug]);
const before = await neighbours();
await local(engine, f.registration, async () => {
const result = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(result).toMatchObject({ status: 'ready', relative_path: 'notes/example.md' });
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
expect((await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview: result.preview, request_id: randomUUID() })).state).toBe('committed');
});
expect(await neighbours()).toEqual(before);
for (const n of [1, 102, 205]) expect(readFileSync(join(f.root, 'channels', `c${n}`, 'example.md'), 'utf8')).toBe(`Independent channel ${n}\n`);
}), 180_000);
test.each(['path', 'uri'])('a real second claimant behind 200 same-name pages still refuses, in preview and on a stale-preview apply (%s)', async origin => isolated(async engine => {
const f = await fixture(engine, true), raw = readFileSync(f.file);
await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], async () => {
await tx.executeRaw(`INSERT INTO pages(source_id,slug,type,title,compiled_truth,frontmatter,source_path)
SELECT $1,'channels/c'||n||'/example','note','Channel '||n,'Independent channel '||n,'{}'::jsonb,'channels/c'||n||'/example.md'
FROM generate_series(1,200) n`, [f.id]);
}, TEST_WRITE_ATTRIBUTION));
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], () => tx.putPage('other/late-claimant', {
type: 'note', title: 'Late claimant', compiled_truth: 'Another page claiming the same file.', frontmatter: {},
source_path: origin === 'path' ? './notes//example.md' : null, source_uri: origin === 'uri' ? pathToFileURL(f.file).href : null,
}, { sourceId: f.id }), TEST_WRITE_ATTRIBUTION));
const snapshot = await engine.readPageSnapshot(f.slug, { sourceId: f.id });
const collision = { code: 'source_changed', message: 'Several pages claim the recorded canonical file.' };
await expect(runReconcilePreview(engine, { source_id: f.id, slug: f.slug })).rejects.toMatchObject(collision);
await expect(runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() })).rejects.toMatchObject(collision);
expect(await engine.readPageSnapshot(f.slug, { sourceId: f.id })).toEqual(snapshot);
expect(readFileSync(f.file)).toEqual(raw);
expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
});
}), 180_000);
test('a fresh PGLite schema builds the v219 name indexes inline', async () => {
const engine = engines[0]!;
const rows = await engine.executeRaw<{ present: boolean }>("SELECT to_regclass('pages_source_path_name_idx') IS NOT NULL AS present UNION ALL SELECT to_regclass('pages_file_uri_name_idx') IS NOT NULL");
expect(rows.map(row => row.present)).toEqual([true, true]);
});
// #6254: the census runs about five times per reconciled page; on Postgres it must use the
// v219 expression indexes instead of evaluating a regexp over every page of the source.
test('the file-claim census is served by the v219 name indexes on Postgres', async () => isolated(async engine => {
if (engine.kind !== 'postgres') return;
const f = await fixture(engine);
await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], () => tx.executeRaw(`INSERT INTO pages(source_id,slug,type,title,compiled_truth,frontmatter,source_path)
SELECT $1,'bulk/p'||n,'note','Bulk '||n,'Bulk '||n,'{}'::jsonb,'bulk/p'||n||'.md' FROM generate_series(1,3000) n`, [f.id]), TEST_WRITE_ATTRIBUTION));
await engine.executeRaw('ANALYZE pages');
const census = fileClaimCandidatesQuery({ sourceId: f.id, pageId: 0, afterId: 0, maxId: 2147483647, fileName: 'example.md', uriNames: ['example.md'] }, 'linux');
const plan = (await engine.executeRaw<{ 'QUERY PLAN': string }>(`EXPLAIN ${census.sql}`, census.params))
.map(row => row['QUERY PLAN']).join('\n');
expect(plan).toContain('pages_source_path_name_idx');
expect(plan).toContain('pages_file_uri_name_idx');
}), 120_000);
// #6659: the Windows census bound a POSIX-only name it never referenced; Postgres and PGLite refuse an untyped
// unreferenced bind with 42P18, which failed every coordinated delete_page on a Windows host.
test.each(['win32', 'linux'] as const)('the %s file-claim census runs with its own binds and finds same-name pages', platform =>
isolated(async engine => {
const f = await fixture(engine);
await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], () => tx.executeRaw(`INSERT INTO pages(source_id,slug,type,title,compiled_truth,frontmatter,source_path,source_uri)
VALUES ($1,'twins/by-path','note','Path twin','x','{}'::jsonb,'other/claimed.md',NULL),
($1,'twins/by-uri','note','URI twin','x','{}'::jsonb,NULL,'file:///repo/other/claimed.md'),
($1,'twins/unrelated','note','Unrelated','x','{}'::jsonb,'other/unrelated.md',NULL)`, [f.id]), TEST_WRITE_ATTRIBUTION));
const census = fileClaimCandidatesQuery({ sourceId: f.id, pageId: 0, afterId: 0, maxId: 2147483647, fileName: 'claimed.md', uriNames: ['claimed.md'] }, platform);
const rows = await engine.executeRaw<{ slug: string }>(census.sql, census.params);
expect(rows.map(row => row.slug).sort()).toEqual(['twins/by-path', 'twins/by-uri']);
}), 120_000);
// The parser must not normalize an already-resolved identity a second time.
// Existing reconcile cases only covered extension-free page keys.
test.each(['notes/example.md', 'notes/example.md.md'])('reconciliation preserves extension-bearing identity %s', async slug =>
isolated(async engine => {
const f = await fixture(engine, true, 'A durable extension-bearing observation.', slug);
expect(readFileSync(f.file, 'utf8')).not.toContain('slug:');
await local(engine, f.registration, async () => {
const { preview, status } = await runReconcilePreview(engine, { source_id: f.id, slug });
expect(status).toBe('ready');
expect(preview.preconditions.slug).toBe(slug);
const receipt = await runReconcileApply(engine, { source_id: f.id, slug, preview, request_id: randomUUID() });
expect(receipt.state).toBe('committed');
const page = await engine.getPage(slug, { sourceId: f.id });
expect(page?.id).toBe(f.snapshot.page.id);
expect(page?.source_path).toBe(`${slug}.md`);
expect(page?.compiled_truth).toContain('A durable extension-bearing observation.');
expect(page?.frontmatter).toMatchObject({ custom_database: 'kept', custom_file: 'kept' });
expect(await engine.getPage(slug.slice(0, -3), { sourceId: f.id })).toBeNull();
const file = readFileSync(f.file, 'utf8');
writeFileSync(f.file, file.replace('---\n', '---\nslug: notes/other\n'));
await expect(runReconcilePreview(engine, { source_id: f.id, slug })).rejects.toMatchObject({ code: 'invalid_params' });
expect((await engine.getPage(slug, { sourceId: f.id }))?.id).toBe(f.snapshot.page.id);
expect(await engine.getPage('notes/other', { sourceId: f.id })).toBeNull();
});
}), 120_000);
test('a fact withdrawn between reconciliation preparation and publication leaves the canonical file and page unchanged', async () => isolated(async engine => {
for (const enabled of [false, true]) {
const claim = 'withdrawn between reconciliation preparation and publication';
const fence = renderFactsTable([{ rowNum: 1, claim, kind: 'fact', confidence: 1, visibility: 'world', notability: 'medium', active: true, context: 'test evidence' }]);
const f = await fixture(engine, enabled, `Facts: ${fence}`), originalBytes = readFileSync(f.file);
await local(engine, f.registration, async () => {
const repair = await preparedRepair(engine, f);
expect(String(repair.prepared.file?.content)).toContain(claim);
// The withdrawal row alone: a full forget would also rewrite this page and trip the revision check first.
// Either the preview's withdrawals pin or the prepared import's validation must refuse it.
await engine.executeRaw("INSERT INTO fact_withdrawals(source_id,visibility,subject,fact_hash) VALUES($1,'world','*',gbrain_fact_fingerprint($2))", [f.id, claim]);
const boundaries: string[] = [];
const result = await publishMutation(engine, repair.row, repair.prepared, localHostId(), {
boundary: async name => { boundaries.push(name); }, fileBoundary: name => { boundaries.push(name); } });
expect(result.state).toBe('conflict');
expect(boundaries).not.toContain('before_publication');
expect(boundaries).not.toContain('before_file');
expect(readFileSync(f.file)).toEqual(originalBytes);
expect((await engine.readPageSnapshot(f.slug, { sourceId: f.id }))?.revision).toBe(f.snapshot.revision);
});
}
}), 120_000);
// Subject-'*' purges ride the preview as a count/latest marker (page-state/types.ts GlobalPurgeMarker), not a list:
// a '*' tombstone added after the preview, for a claim in the page or any other, makes the preview stale; an artifact
// written before the marker existed reads stale too, never trusted.
test("a subject-'*' purge recorded after the preview makes it stale; an artifact without the purge marker is stale", async () => isolated(async engine => {
const claim = 'purged after the reconciliation preview';
const fence = renderFactsTable([{ rowNum: 1, claim, kind: 'fact', confidence: 1, visibility: 'world', notability: 'medium', active: true, context: 'test evidence' }]);
const purgeAll = (sourceId: string, text: string) => engine.executeRaw(
"INSERT INTO fact_purges(source_id,visibility,subject,fact_hash) VALUES($1,'world','*',gbrain_fact_fingerprint($2))", [sourceId, text]);
for (const target of [claim, 'an unrelated claim purged everywhere']) {
const f = await fixture(engine, false, `Facts: ${fence}`), originalBytes = readFileSync(f.file);
await local(engine, f.registration, async () => {
const { preview } = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
expect(preview.preimages.database).not.toHaveProperty('globalPurges');
await purgeAll(f.id, target);
await expect(runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview, request_id: randomUUID() })).rejects.toMatchObject({ code: 'source_changed' });
expect(readFileSync(f.file)).toEqual(originalBytes);
expect((await engine.readPageSnapshot(f.slug, { sourceId: f.id }))?.revision).toBe(f.snapshot.revision);
const fresh = (await runReconcilePreview(engine, { source_id: f.id, slug: f.slug })).preview;
expect(fresh.preimages.database.globalPurges).toMatchObject({ count: 1 });
// The purged row is still in the file but no longer in the database view, so that preview needs a decision.
if (target === claim) { expect(fresh.status).toBe('needs_resolution'); return; }
expect(fresh.status).toBe('ready');
const { globalPurges: _marker, ...legacyDatabase } = fresh.preimages.database;
const legacy = { ...fresh, preimages: { ...fresh.preimages, database: legacyDatabase } };
await expect(runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview: legacy as typeof fresh, request_id: randomUUID() }))
.rejects.toMatchObject({ code: 'source_changed' });
expect(readFileSync(f.file)).toEqual(originalBytes);
});
}
}), 120_000);
// #6137: private fact rows are identified by (row number, claim), never by claim text alone.
type FenceRow = { rowNum: number; claim: string; visibility: 'private' | 'world'; context?: string; source?: string; confidence?: number; forgotten?: boolean };
const LONG_PRIVATE_CONTEXT = 'Told in confidence at the example offsite';
function factsBody(rows: FenceRow[], prose = 'A durable example biography.') {
const facts = rows.map(r => ({ rowNum: r.rowNum, claim: r.claim, kind: 'fact' as const, confidence: r.confidence ?? 1, visibility: r.visibility,
notability: 'medium' as const, source: r.source, active: !r.forgotten, ...(r.forgotten ? { forgotten: true, context: 'forgotten: user request' } : { context: r.context }) }));
return replaceOrInsertFactsFence(prose, renderFactsTable(facts));
}
const TWIN: FenceRow[] = [{ rowNum: 1, claim: 'Prefers the example venue', visibility: 'private' }, { rowNum: 2, claim: 'Prefers the example venue', visibility: 'world' }];
const FORGOTTEN_TWIN: FenceRow[] = [{ ...TWIN[0], forgotten: true }, TWIN[1]];
const PRIVATE_AND_WORLD: FenceRow[] = [{ rowNum: 1, claim: 'Holds a private example account', visibility: 'private', context: LONG_PRIVATE_CONTEXT, source: 'Slack import' },
{ rowNum: 2, claim: 'Works at acme-example', visibility: 'world', source: 'Slack import' }];
const reconcileCases: Array<{ name: string; stored: FenceRow[]; incoming?: FenceRow[]; prose?: string; refusedRow?: number }> = [
{ name: 'a frontmatter-only edit with an active private twin', stored: TWIN },
{ name: 'a frontmatter-only edit with a forgotten private twin', stored: FORGOTTEN_TWIN },
{ name: 'a take_file body edit with an active private twin', stored: TWIN, incoming: TWIN, prose: 'A revised public biography.' },
{ name: 'a take_file body edit with a forgotten private twin', stored: FORGOTTEN_TWIN, incoming: FORGOTTEN_TWIN, prose: 'A revised public biography.' },
{ name: 'an edit of the world twin', stored: TWIN, incoming: [TWIN[0], { ...TWIN[1], claim: 'Now prefers the new example venue' }] },
{ name: 'a new unrelated world row', stored: PRIVATE_AND_WORLD, incoming: [...PRIVATE_AND_WORLD, { rowNum: 3, claim: 'Lives in example-city', visibility: 'world' }] },
{ name: 'a new world row sharing a short context and the source', stored: [{ ...PRIVATE_AND_WORLD[0], context: 'Slack import' }, PRIVATE_AND_WORLD[1]],
incoming: [{ ...PRIVATE_AND_WORLD[0], context: 'Slack import' }, PRIVATE_AND_WORLD[1], { rowNum: 3, claim: 'Joined the example guild', visibility: 'world', context: 'Slack import', source: 'Slack import' }] },
{ name: 'an existing world row whose context equals the private context', stored: [PRIVATE_AND_WORLD[0], { ...PRIVATE_AND_WORLD[1], context: LONG_PRIVATE_CONTEXT }],
incoming: [PRIVATE_AND_WORLD[0], { ...PRIVATE_AND_WORLD[1], context: LONG_PRIVATE_CONTEXT }], prose: 'A revised public biography.' },
{ name: 'editing the private twin', stored: TWIN, incoming: [{ ...TWIN[0], confidence: 0.5 }, TWIN[1]], refusedRow: 1 },
{ name: 'making a private fact world', stored: TWIN, incoming: [{ ...TWIN[0], visibility: 'world' }, TWIN[1]], refusedRow: 1 },
{ name: 'copying a private claim into a new world row', stored: PRIVATE_AND_WORLD, incoming: [...PRIVATE_AND_WORLD, { rowNum: 3, claim: PRIVATE_AND_WORLD[0].claim, visibility: 'world' }], refusedRow: 3 },
{ name: 'writing a private claim over an existing world row', stored: PRIVATE_AND_WORLD, incoming: [PRIVATE_AND_WORLD[0], { ...PRIVATE_AND_WORLD[1], claim: PRIVATE_AND_WORLD[0].claim }], refusedRow: 2 },
{ name: 'copying a private context into an existing world row', stored: PRIVATE_AND_WORLD,
incoming: [PRIVATE_AND_WORLD[0], { ...PRIVATE_AND_WORLD[1], context: LONG_PRIVATE_CONTEXT }], refusedRow: 2 },
{ name: 'copying a private context into a new world row', stored: PRIVATE_AND_WORLD,
incoming: [...PRIVATE_AND_WORLD, { rowNum: 3, claim: 'Mentioned an example plan', visibility: 'world', context: LONG_PRIVATE_CONTEXT }], refusedRow: 3 },
];
for (const c of reconcileCases) {
test(`#6137 reconcile private facts: ${c.refusedRow ? 'refuses' : 'publishes'} ${c.name}`, async () => isolated(async engine => {
const f = await fixture(engine, false, factsBody(c.stored));
if (c.incoming || c.prose) {
writeFileSync(f.file, serializePageToMarkdown({ ...f.snapshot.page, compiled_truth: factsBody(c.incoming ?? c.stored, c.prose) }, f.snapshot.tags));
}
await local(engine, f.registration, async () => {
const preview = async () => {
const initial = await runReconcilePreview(engine, { source_id: f.id, slug: f.slug });
const decisions = initial.preview.conflicts.map(conflict => ({ path: conflict.path, action: 'take_file' }));
return decisions.length ? runReconcilePreview(engine, { source_id: f.id, slug: f.slug, from: initial.preview, decisions }) : initial;
};
if (c.refusedRow) {
const error = await preview().then(() => null, (e: unknown) => e as { code: string; message: string; suggestion: string; why?: string; fix?: { argv?: string[] } });
expect(error).toMatchObject({ code: 'permission_denied' });
const text = `${error!.message} ${error!.suggestion} ${error!.why ?? ''}`;
expect(text).toContain(`Row ${c.refusedRow} `);
for (const row of [...c.stored, ...(c.incoming ?? [])]) {
expect(text).not.toContain(row.claim);
if (row.context) expect(text).not.toContain(row.context);
}
expect(error!.fix?.argv).toEqual(['gbrain', 'get', '--source', f.id, '--', f.slug]);
expect((await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!.revision).toBe(f.snapshot.revision);
return;
}
const resolved = await preview();
const receipt = await runReconcileApply(engine, { source_id: f.id, slug: f.slug, preview: resolved.preview, request_id: randomUUID() });
expect(receipt.state).toBe('committed');
const stored = (await engine.readPageSnapshot(f.slug, { sourceId: f.id }))!;
const fileFence = parseFactsFence(parseMarkdown(readFileSync(f.file, 'utf8'), f.slug).compiled_truth);
expect(renderFactsTable(fileFence.facts)).toBe(renderFactsTable(parseFactsFence(stored.page.compiled_truth).facts));
const privateRow = parseFactsFence(stored.page.compiled_truth).facts.find(fact => fact.rowNum === 1)!;
expect(privateRow.visibility).toBe(c.stored[0].visibility);
expect(privateRow.claim).toBe(c.stored[0].claim);
});
}), 120_000);
}