Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #6712 PR 4b lane A: the live pass's fences, stop reasons and completion dependencies (design v3.2 §8, §9, §3).
*
* Protects:
* - probe 51 (pass half): `sync.admission` is re-read in each admission transaction of a pass (a delete admitted after
* it turns `imports_only` is refused and the pass stops `partial` / `admission_paused`, the page live), and a pass's
* `managed_sync_delete` re-reads it at publication (completed `cancelled` / `admission_paused`, nothing written);
* once it is `normal` again the next pass deletes the page.
*
* - not_converged (design v3.2 §9): a working copy that changes under every round ends the pass `partial` / `not_converged`;
* the pass row counts the streak server-side, and from the third consecutive pass the drain's `next` is `report`.
*
* - probe 49: a re-screen-due hold alone runs a hold-only round (not a full round), which clears it.
* - item 7: a local CLI pass waits (to 30 s) on its own write while this process's consumer holds it or has yet to claim it.
* - in-flight wait: the pass waits on the open work it classified, a pending Git effect included, before stopping writer_pending.
* - probe 46 (reparse half): a parser change on a fileSame and dbSame page is a `reparse`: re-imported, no hold.
* - probe 48: a request admitted before the stamp that publishes after it (`open_at_stamp`) makes the next tick a full round, not idle.
* - probe 53: a repair that changes a candidate mid-pass meets no busy refusal (busy is open requests only), and the path
* settles in a later round with no hold.
* - kill after a group's admission commit, before the stamp: the next run resumes the pass and converges, each path imported once.
* - probe 40: a connection or pooler fault (SQLSTATE 08006, 57P01) in a pass never becomes a hold; the next run converges.
* - #6727 on the pass route: a new file whose slug folds to a legacy page (no recorded origin) the importer cannot write is
* held legacy_slug_conflict and forks no second page.
* - a committed edit under a different uncommitted edit (committed mode) is held worktree_dirty, the page and the local
* file untouched, and the next pass settles instead of counting a not_converged streak; sync.holds=fail stops the run.
* - a page written straight to the database at a new file's slug is never overwritten by the file: held file_drift (side unknown).
* - a commit during a pass: the next round reads the new HEAD and its batch freezes that commit (no storage_error from an older pin).
* - --no-schema-pack: a first pass converges (its parser expects no pack); a cost-gate deferral is no inherited opt-out;
* a source configured with a strategy, synced with that strategy named (sync --all), stamps last_commit.
* - idle-tick batching: a converged tick still clears a recorded failure, writes its pass row at the transaction clock
* (one pipelined statement set), and with no failure recorded and no tail owed at pin it issues neither the clears nor
* the post-lease tail read.
* - probe 54: a pass intent keeps what the #6862 FIFO guard reads: a `managed_sync_` kind, the slug and page, and `renameFrom.slug`.
*
* Each test fails on capy/6712-pr4b (8cda2764b), where a non-company source still runs the cursor engine: the fences do not
* cover its intents (both deletes publish), it has no pass kinds or pass row, and its manifest remainder makes a repair busy.
*/
import { afterEach, describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { installFaultHook } from '../src/core/persistence/fault-points.ts';
import { SYNC_ADMISSION_KEY } from '../src/core/persistence/sync-admission.ts';
import { SYNC_TAIL_OP } from '../src/core/persistence/sync-tail-record.ts';
import { performManagedSync } from '../src/core/persistence/sync-run.ts';
import { RECOVERY_VERSION } from '../src/core/markdown.ts';
import { readGitHold, SYNC_IMPORT_PROVENANCE_OP, writeGitHold } from '../src/core/persistence/sync-holds.ts';
import { preparePageAdmission, submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { admitWrite } from '../src/core/persistence/journal.ts';
import { createHash, randomUUID } from 'node:crypto';
import { drainNext, runDrain } from '../src/core/persistence/sync-drain.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { waitFor } from './helpers/wait-for.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { prepareRepairPublication, repairScreenConfig, submitManagedFileRepair } from '../src/core/persistence/file-repair.ts';
import { readFileSync } from 'node:fs';
const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
const commit = (root: string, message: string) => { git(root, 'add', '-A'); git(root, '-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', message); };
const note = (title: string, body: string) => `---\ntype: concept\ntitle: ${title}\n---\n\n${body}\n`;
const OPTS = { sourceId: 'default', noPull: true, noEmbed: true, noExtract: true };
const setup = ({ root }: { root: string }) => {
mkdirSync(join(root, 'notes'), { recursive: true }); git(root, 'init', '-q');
for (const slug of ['a', 'b', 'c']) writeFileSync(join(root, `notes/${slug}.md`), note(`notes/${slug}`, `The committed body of notes/${slug}.`));
commit(root, 'notes');
};
/** A durability-hardened checkout (the brain-durability post-commit hook), where a repair's Git effect commits under the checkout's own identity. */
const hardened = ({ root }: { root: string }) => {
setup({ root });
git(root, 'config', 'user.name', 'Example'); git(root, 'config', 'user.email', '[email protected]');
writeFileSync(join(root, '.git', 'hooks', 'post-commit'), '#!/bin/sh\n# gbrain brain-durability post-commit hook (v0.42.44+)\n'); chmodSync(join(root, '.git', 'hooks', 'post-commit'), 0o755);
};
const liveSlugs = async (engine: BrainEngine) => (await engine.executeRaw<{ slug: string }>("SELECT slug FROM pages WHERE source_id='default' AND deleted_at IS NULL ORDER BY slug")).map(row => row.slug);
const deletes = async (engine: BrainEngine) => (await engine.executeRaw<{ slug: string; state: string; error_code: string | null }>(
"SELECT slug, state, error_code FROM persistence_requests WHERE source_id='default' AND intent->>'kind'='managed_sync_delete' ORDER BY sequence"));
afterEach(() => installFaultHook(undefined));
describe('#6712 PR 4b live pass fences (pglite)', () => {
test('probe 51 (pass half): sync.admission is re-read in the admission transaction; a delete classified under normal and admitted after imports_only is refused, and the pass stops admission_paused', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
git(root, 'rm', '-q', 'notes/a.md', 'notes/b.md'); commit(root, 'remove a and b');
// After the pass classified both deletes under normal, before their admission transaction.
let flipped = false;
installFaultHook(async point => { if (point === 'sync:mid_checkpoint' && !flipped) { flipped = true; await engine.setConfig(SYNC_ADMISSION_KEY, 'imports_only'); } });
const paused = await performManagedSync(engine, OPTS);
installFaultHook(undefined);
expect({ status: paused.status, reason: paused.reason }).toEqual({ status: 'partial', reason: 'admission_paused' });
expect(await liveSlugs(engine)).toEqual(['notes/a', 'notes/b', 'notes/c']);
expect(await deletes(engine)).toEqual([]);
await engine.setConfig(SYNC_ADMISSION_KEY, 'normal');
expect((await performManagedSync(engine, OPTS)).status).toBe('synced');
expect(await liveSlugs(engine)).toEqual(['notes/c']);
}, { setup }), 180_000);
test('probe 51 (pass half): a managed_sync_delete re-reads sync.admission at publication: cancelled admission_paused, the page live', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
git(root, 'rm', '-q', 'notes/a.md'); commit(root, 'remove a');
installFaultHook(async (point, detail) => {
// Prepared, before its publication transaction.
if (point === 'consumer:prepared' && detail.operation === 'submit_job' && (await deletes(engine)).some(row => row.state === 'running')) await engine.setConfig(SYNC_ADMISSION_KEY, 'imports_only');
});
const paused = await performManagedSync(engine, OPTS);
installFaultHook(undefined);
expect({ status: paused.status, reason: paused.reason }).toEqual({ status: 'partial', reason: 'admission_paused' });
expect(await deletes(engine)).toEqual([{ slug: 'notes/a', state: 'cancelled', error_code: 'admission_paused' }]);
expect(await liveSlugs(engine)).toEqual(['notes/a', 'notes/b', 'notes/c']);
await engine.setConfig(SYNC_ADMISSION_KEY, 'normal');
expect((await performManagedSync(engine, OPTS)).status).toBe('synced');
expect(await liveSlugs(engine)).toEqual(['notes/b', 'notes/c']);
}, { setup }), 180_000);
test('item 7: a CLI pass keeps waiting on its own write while this process\'s consumer still holds it, past the 5 s wait: synced, not writer_pending', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'A body that takes longer than the wait to prepare.')); commit(root, 'edit a');
// The write's preparation outlasts the pass's 5 s wait, as a publication over a high-latency link does.
let slowed = false;
installFaultHook(async (point, detail) => {
if (point === 'consumer:prepared' && detail.operation === 'submit_job' && !slowed) { slowed = true; await new Promise(resolve => setTimeout(resolve, 6500)); }
});
const synced = await performManagedSync(engine, OPTS);
installFaultHook(undefined);
expect({ slowed, status: synced.status, reason: synced.reason }).toEqual({ slowed: true, status: 'synced', reason: undefined });
expect((await engine.readPageSnapshot('notes/a', { sourceId: 'default' }))?.page.compiled_truth).toContain('takes longer than the wait');
}, { setup }), 180_000);
test('item 7: a CLI pass keeps waiting on its own queued write while this process\'s consumer is busy past the 5 s wait before claiming it: synced, not writer_pending', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'A body admitted while the consumer is busy.')); commit(root, 'edit a');
// The consumer is busy (an effect pass under load) for longer than the pass's 5 s wait before it claims the import.
let slowed = false;
installFaultHook(async point => {
if (point !== 'consumer:claiming' || slowed) return;
if (!(await engine.executeRaw("SELECT 1 FROM persistence_requests WHERE state='queued' AND intent->>'kind'='managed_sync_import'")).length) return;
slowed = true; await new Promise(resolve => setTimeout(resolve, 6500));
});
const synced = await performManagedSync(engine, OPTS);
installFaultHook(undefined);
expect({ slowed, status: synced.status, reason: synced.reason }).toEqual({ slowed: true, status: 'synced', reason: undefined });
expect((await engine.readPageSnapshot('notes/a', { sourceId: 'default' }))?.page.compiled_truth).toContain('admitted while the consumer is busy');
}, { setup }), 180_000);
test('in-flight wait: a pass waits out a put_page\'s pending Git effect (its request names no page or origin), then imports the committed change', () => managedBrain(async ({ engine, ctx, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
await submitPageMutation(ctx, { operation: 'put_page', params: { slug: 'notes/d', request_id: randomUUID(), content: note('notes/d', 'The body put_page wrote.') } });
// The page's Git effect is still pending (its publication landed; the commit is 2 s out) when an agent commits a change.
const held = await engine.executeRaw("UPDATE persistence_effects SET next_attempt_at=now()+interval '2 seconds' WHERE kind='git' AND state='queued' AND set_config('gbrain.persistence_protocol','2',true)='2' RETURNING id");
expect(held).toHaveLength(1);
writeFileSync(join(root, 'notes/d.md'), note('notes/d', 'A committed agent change of notes/d.')); commit(root, 'agent change of d');
const synced = await performManagedSync(engine, OPTS);
expect({ status: synced.status, reason: synced.reason, held: synced.held ?? [] }).toEqual({ status: 'synced', reason: undefined, held: [] });
expect((await engine.readPageSnapshot('notes/d', { sourceId: 'default' }))?.page.compiled_truth).toContain('A committed agent change of notes/d.');
}, { setup: hardened }), 180_000);
test('a sliced pass that yields writer_yield reports the entries it settled in the stopped round', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
for (const slug of ['a', 'b', 'c']) writeFileSync(join(root, `notes/${slug}.md`), note(`notes/${slug}`, `An edit of notes/${slug}.`));
commit(root, 'edit all three');
const sliced = await performManagedSync(engine, OPTS, { maxPages: 1, maxMs: 120_000 });
expect({ status: sliced.status, reason: sliced.reason, filesImported: sliced.filesImported, settled: sliced.pass?.settled })
.toEqual({ status: 'partial', reason: 'writer_yield', filesImported: 1, settled: 1 });
const [row] = await engine.executeRaw<{ settled: number }>("SELECT (completed_keys->0->'telemetry'->>'settled')::int AS settled FROM op_checkpoints WHERE op='managed-sync-pass'");
expect(row?.settled).toBe(1);
}, { setup }), 180_000);
test('not_converged: a working copy that changes under every round ends the pass not_converged; the third in a row reports', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
let edits = 0;
installFaultHook(async point => { if (point === 'sync:mid_checkpoint') writeFileSync(join(root, 'notes/a.md'), note('notes/a', `An uncommitted edit ${++edits}.`)); });
const streaks: number[] = [], loops: boolean[] = [];
for (let i = 0; i < 3; i++) {
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'An uncommitted edit before the pass.'));
const drained = await runDrain({ pass: () => performManagedSync(engine, { ...OPTS, workingTree: true }) });
expect({ status: drained.status, reason: drained.reason, stop: drained.drain?.stop_reason }).toEqual({ status: 'partial', reason: 'not_converged', stop: 'not_converged' });
streaks.push(drained.pass!.not_converged_streak);
loops.push(drainNext(drained, 'gbrain sync --source default --no-pull', 'default')!.safe_to_loop);
}
installFaultHook(undefined);
expect({ streaks, loops }).toEqual({ streaks: [1, 2, 3], loops: [true, true, false] });
expect((await performManagedSync(engine, { ...OPTS, workingTree: true })).status).toBe('synced');
const [row] = await engine.executeRaw<{ streak: number }>("SELECT (completed_keys->0->'obligations'->>'not_converged_streak')::int AS streak FROM op_checkpoints WHERE op='managed-sync-pass'");
expect(row?.streak).toBe(0);
}, { setup }), 240_000);
const incarnationOf = async (engine: BrainEngine) => (await engine.executeRaw<{ incarnation: string }>("SELECT incarnation::text AS incarnation FROM sources WHERE id='default'"))[0]!.incarnation;
const passRow = async (engine: BrainEngine) => (await engine.executeRaw<{ value: { obligations: { converged?: { open_at_stamp: string[] | null } } } }>(
"SELECT completed_keys->0 AS value FROM op_checkpoints WHERE op='managed-sync-pass'"))[0]?.value;
test('probe 49: a re-screen-due hold alone runs a hold-only round, which clears it; the next tick is idle', () => managedBrain(async ({ engine }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
const incarnation = await incarnationOf(engine);
const page = (await engine.readPageSnapshot('notes/a', { sourceId: 'default' }))!;
const blob = execFileSync('git', ['-C', (await engine.executeRaw<{ p: string }>("SELECT local_path AS p FROM sources WHERE id='default'"))[0]!.p, 'rev-parse', 'HEAD:notes/a.md'], { encoding: 'utf8' }).trim();
await engine.transaction(tx => writeGitHold(tx, { source_id: 'default', incarnation, path: 'notes/a.md', source_path: 'notes/a.md', slug: 'notes/a', page_id: Number(page.page.id),
code: 'frontmatter_slug_conflict', message: 'Synthetic frontmatter_slug_conflict hold.', upstream_version: null, observed_at: new Date().toISOString(), run_id: null, mode: 'managed',
meta: { recovery_version: RECOVERY_VERSION, blob_oid: blob, page_revision: page.revision } } as never));
const round = await performManagedSync(engine, OPTS);
expect({ status: round.status, kind: round.pass?.kind }).toEqual({ status: 'synced', kind: 'hold_only' });
expect(await readGitHold(engine, 'default', incarnation, 'notes/a.md')).toBeNull();
const idle = await performManagedSync(engine, OPTS);
expect({ status: idle.status, pass: idle.pass }).toEqual({ status: 'up_to_date', pass: undefined });
}, { setup }), 180_000);
test('idle-tick batching: a converged tick clears a recorded failure and stamps the pass row at the transaction clock; with none recorded and no tail owed it issues neither the clears nor the post-lease tail read', () => managedBrain(async ({ engine }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
const incarnation = await incarnationOf(engine);
const failure = "SELECT count(*)::int AS n FROM op_checkpoints WHERE op='managed-sync-failure' AND fingerprint=$1";
await engine.executeRaw("INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES('managed-sync-failure',$1,'[{}]'::jsonb)", [`default:${incarnation}`]);
expect((await performManagedSync(engine, OPTS)).status).toBe('up_to_date');
expect((await engine.executeRaw<{ n: number }>(failure, [`default:${incarnation}`]))[0]!.n).toBe(0);
const statements: Array<{ sql: string; params: unknown[] }> = [];
const executeRaw = engine.executeRaw;
// A transaction's engine inherits this method: only the engine's own statements are recorded.
engine.executeRaw = function (this: BrainEngine, sql: string, params?: unknown[], opts?: never) {
if (this === engine) statements.push({ sql, params: params ?? [] });
return executeRaw.call(this, sql, params, opts);
} as typeof engine.executeRaw;
try { expect((await performManagedSync(engine, OPTS)).status).toBe('up_to_date'); } finally { delete (engine as { executeRaw?: unknown }).executeRaw; }
expect({ clears: statements.filter(s => /DELETE FROM op_checkpoints WHERE op='managed-sync-failure'/.test(s.sql)).length,
tailReads: statements.filter(s => s.params[0] === SYNC_TAIL_OP).length }).toEqual({ clears: 0, tailReads: 1 });
const [row] = await engine.executeRaw<{ started: string; updated: string }>(`SELECT completed_keys->0->'telemetry'->>'started_at' AS started,
to_char(updated_at AT TIME ZONE 'UTC','YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS updated FROM op_checkpoints WHERE op='managed-sync-pass' AND fingerprint=$1`, [`default:${incarnation}`]);
expect({ started: new Date(row!.started).toISOString(), updated: row!.updated }).toEqual({ started: row!.updated, updated: row!.updated });
}, { setup }), 180_000);
test('probe 46 (reparse half): a parser change on a fileSame and dbSame page re-imports it as reparse, with no hold', () => managedBrain(async ({ engine }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
const fingerprint = `default:${await incarnationOf(engine)}:${(await engine.readPageSnapshot('notes/b', { sourceId: 'default' }))!.page.id}`;
await engine.executeRaw(`UPDATE op_checkpoints SET completed_keys=jsonb_set(completed_keys,'{0,parser,parser_version}','"an-older-parser"'::jsonb) WHERE op=$1 AND fingerprint=$2`, [SYNC_IMPORT_PROVENANCE_OP, fingerprint]);
await engine.executeRaw("UPDATE op_checkpoints SET completed_keys=jsonb_set(completed_keys,'{0,obligations,converged,parser_fp}','\"an-older-parser\"'::jsonb) WHERE op='managed-sync-pass'");
const pass = await performManagedSync(engine, OPTS);
expect({ status: pass.status, kind: pass.pass?.kind, candidates: pass.pass?.candidates, held: pass.held ?? [] }).toEqual({ status: 'synced', kind: 'full', candidates: 1, held: [] });
const [record] = await engine.executeRaw<{ v: string }>("SELECT completed_keys->0->'parser'->>'parser_version' AS v FROM op_checkpoints WHERE op=$1 AND fingerprint=$2", [SYNC_IMPORT_PROVENANCE_OP, fingerprint]);
expect(record!.v).not.toBe('an-older-parser');
}, { setup }), 180_000);
test('probe 48: a write admitted before the stamp that publishes after it makes the next tick a full round', () => managedBrain(async ({ engine, ctx, root }) => {
await engine.setConfig('sync.write_through', 'false');
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'A committed change of notes/a.')); commit(root, 'change a');
let late: string | null = null, release = () => {};
const ended = new Promise<void>(resolve => { release = resolve; });
installFaultHook(async (point, detail) => {
// The late write publishes once the pass has ended: a round that saw it commit would stamp again, past it.
if (point === 'consumer:prepared' && late && detail.requestId === late) { await ended; return; }
if (point !== 'consumer:prepared' || late || detail.operation !== 'submit_job') return;
// The request that carries the pass stamp: its checkpoint, or the last import it folded into (#6926).
const [row] = await engine.executeRaw<{ stamp: boolean }>("SELECT intent ? 'stamp' AS stamp FROM persistence_requests WHERE request_id=$1::uuid", [detail.requestId]);
if (!row?.stamp) return;
const current = (await engine.readPageSnapshot('notes/c', { sourceId: 'default' }))!;
const prepared = await preparePageAdmission(ctx, { operation: 'put_page', params: { slug: 'notes/c', request_id: randomUUID(), expected_revision: current.revision, content: note('notes/c', 'A late agent edit.') } });
late = (await admitWrite(engine, prepared.admission!)).request_id;
});
const stamped = await performManagedSync(engine, OPTS).finally(release);
expect(stamped.status).toBe('synced');
installFaultHook(undefined);
expect(late).not.toBeNull();
expect((await passRow(engine))!.obligations.converged!.open_at_stamp).toContain(`r:${late}`);
await waitFor(async () => (await engine.executeRaw<{ state: string }>('SELECT state FROM persistence_requests WHERE request_id=$1::uuid', [late]))[0]?.state === 'committed', { timeoutMs: 20_000, label: 'the late put_page commits' });
const next = await performManagedSync(engine, OPTS);
expect({ status: next.status, kind: next.pass?.kind }).toEqual({ status: 'up_to_date', kind: 'full' });
const idle = await performManagedSync(engine, OPTS);
expect(idle.pass).toBeUndefined();
}, { setup }), 180_000);
test('probe 53: a repair changes a candidate mid-pass: no busy refusal, and it settles later with no hold', () => managedBrain(async ({ engine, ctx, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'A committed change of notes/a.'));
writeFileSync(join(root, 'notes/c.md'), note('notes/c', 'A committed change of notes/c.')); commit(root, 'change a and c');
const repaired = note('notes/c', 'The repaired body of notes/c.');
let outcome: Record<string, unknown> | null = null;
installFaultHook(async (point, detail) => {
if (point !== 'sync:after_freeze' || detail.path !== 'notes/a.md' || outcome) return;
const snapshot = await engine.readPageSnapshot('notes/c', { sourceId: 'default', includeDeleted: true });
const publication = await prepareRepairPublication(engine, { sourceId: 'default', slug: 'notes/c', sourcePath: 'notes/c.md', path: 'notes/c.md', root, content: repaired, snapshot, base: snapshot, ...await repairScreenConfig(engine, 'default') });
if (publication.status !== 'ready') throw new Error(`the repair publication is ${publication.status}`);
outcome = await submitManagedFileRepair(ctx, { sourceId: 'default', requestId: randomUUID(), slug: 'notes/c', path: 'notes/c.md', sourcePath: 'notes/c.md', content: repaired,
beforeHash: createHash('sha256').update(readFileSync(join(root, 'notes/c.md'))).digest('hex'), resultDigest: publication.digest, expected_revision: snapshot!.revision, noEmbed: true });
});
const rounds = [await performManagedSync(engine, OPTS)];
installFaultHook(undefined);
expect(outcome).toMatchObject({ state: 'committed', file_repaired: true });
await waitFor(async () => !(await engine.executeRaw("SELECT 1 FROM persistence_effects WHERE source_id='default' AND kind='git' AND state<>'committed'")).length,
{ timeoutMs: 20_000, label: 'the repair commit lands in Git' });
while (rounds.length < 5 && rounds.at(-1)!.status !== 'up_to_date') rounds.push(await performManagedSync(engine, OPTS));
expect({ last: rounds.at(-1)!.status, held: rounds.flatMap(round => round.held ?? []) }).toEqual({ last: 'up_to_date', held: [] });
expect((await engine.readPageSnapshot('notes/c', { sourceId: 'default' }))!.page.compiled_truth).toContain('The repaired body of notes/c.');
expect((await engine.readPageSnapshot('notes/a', { sourceId: 'default' }))!.page.compiled_truth).toContain('A committed change of notes/a.');
expect(git(root, 'show', 'HEAD:notes/c.md')).toContain('The repaired body of notes/c.');
expect(await engine.executeRaw("SELECT 1 FROM op_checkpoints WHERE op='sync-hold'")).toEqual([]);
}, { setup: hardened }), 180_000);
const lastSequence = async (engine: BrainEngine) => Number((await engine.executeRaw<{ s: number }>('SELECT COALESCE(max(sequence),0) AS s FROM persistence_requests'))[0]!.s);
const changeAll = (root: string) => { for (const slug of ['a', 'b', 'c']) writeFileSync(join(root, `notes/${slug}.md`), note(`notes/${slug}`, `A committed change of notes/${slug}.`)); commit(root, 'change all'); };
const converged = async (engine: BrainEngine, after: number) => {
for (const slug of ['a', 'b', 'c']) expect((await engine.readPageSnapshot(`notes/${slug}`, { sourceId: 'default' }))!.page.compiled_truth).toContain(`A committed change of notes/${slug}.`);
expect(await engine.executeRaw("SELECT 1 FROM op_checkpoints WHERE op='sync-hold'")).toEqual([]);
const imports = await engine.executeRaw<{ slug: string; n: number }>("SELECT slug, count(*)::int AS n FROM persistence_requests WHERE intent->>'kind'='managed_sync_import' AND state='committed' AND intent ? 'passId' AND sequence>$1 GROUP BY slug ORDER BY slug", [after]);
expect(imports.map(row => [row.slug, Number(row.n)])).toEqual([['notes/a', 1], ['notes/b', 1], ['notes/c', 1]]);
expect((await performManagedSync(engine, OPTS)).pass).toBeUndefined();
};
test('a kill after a group admission commits, before the stamp, resumes on the next run and converges', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
const after = await lastSequence(engine);
changeAll(root);
let killed = false;
installFaultHook(async point => { if (point === 'sync:mid_checkpoint' && !killed) { killed = true; throw new Error('killed after the group admission'); } });
const dead = await performManagedSync(engine, OPTS).then(result => result.status, (error: Error) => error.message);
installFaultHook(undefined);
expect(killed).toBe(true);
expect(dead).not.toBe('synced');
await disposePersistenceConsumer(engine);
const [row] = await engine.executeRaw<{ at: string | null }>("SELECT completed_keys->0->'obligations'->'converged'->>'target' AS at FROM op_checkpoints WHERE op='managed-sync-pass'");
expect(row?.at).not.toBe(git(root, 'rev-parse', 'HEAD'));
const resumed = await performManagedSync(engine, OPTS);
expect({ status: resumed.status, held: resumed.held ?? [] }).toEqual({ status: 'synced', held: [] });
await converged(engine, after);
}, { setup }), 180_000);
for (const code of ['08006', '57P01']) test(`probe 40: a connection fault (${code}) in a pass never becomes a hold, and the next run converges`, () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
const after = await lastSequence(engine);
changeAll(root);
const fault = () => Object.assign(new Error('Connection terminated unexpectedly'), { code });
const faults = new Set<string>();
installFaultHook(async (point, detail) => {
if (point === 'sync:mid_checkpoint' && !faults.has(point)) { faults.add(point); throw fault(); }
if (point === 'consumer:prepared' && detail.operation === 'submit_job' && !faults.has(point)) { faults.add(point); throw fault(); }
});
const rounds = [await performManagedSync(engine, OPTS).then(result => result, (error: Error) => ({ status: `threw: ${error.message}`, held: [] as unknown[] }))];
while (rounds.length < 5 && rounds.at(-1)!.status !== 'synced' && rounds.at(-1)!.status !== 'up_to_date')
rounds.push(await performManagedSync(engine, OPTS).then(result => result, (error: Error) => ({ status: `threw: ${error.message}`, held: [] as unknown[] })));
installFaultHook(undefined);
expect([...faults].sort()).toEqual(['consumer:prepared', 'sync:mid_checkpoint']);
expect({ last: rounds.at(-1)!.status, held: rounds.flatMap(round => round.held ?? []) }).toEqual({ last: 'synced', held: [] });
await converged(engine, after);
}, { setup }), 180_000);
test('#6727 on the pass route: a new file whose slug folds to a legacy page it cannot write is held legacy_slug_conflict, never forked', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
await engine.transaction(async tx => {
await tx.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
await tx.executeRaw("INSERT INTO pages(source_id,slug,type,page_kind,title,compiled_truth) VALUES('default','notes/Legacy Name','note','markdown','Legacy Name','A legacy page.')");
await tx.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
});
writeFileSync(join(root, 'notes/Legacy Name.md'), note('Legacy Name', 'The file of an unwritable legacy page.')); commit(root, 'legacy file');
const result = await performManagedSync(engine, OPTS);
expect((result.held ?? []).map(hold => [hold.path, hold.code])).toEqual([['notes/Legacy Name.md', 'legacy_slug_conflict']]);
const pages = await engine.executeRaw<{ slug: string; source_path: string | null; body: string }>(
"SELECT slug, source_path, compiled_truth AS body FROM pages WHERE source_id='default' AND deleted_at IS NULL AND lower(slug) LIKE 'notes/legacy%' ORDER BY slug");
expect(pages.map(page => ({ slug: page.slug, source_path: page.source_path, body: page.body.trim() }))).toEqual([{ slug: 'notes/Legacy Name', source_path: null, body: 'A legacy page.' }]);
}, { setup }), 180_000);
test('a committed edit under a different uncommitted edit is held worktree_dirty, untouched, and the next pass settles', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'A committed change of notes/a.')); commit(root, 'change a');
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'An uncommitted draft of notes/a.'));
const first = await performManagedSync(engine, OPTS);
expect((first.held ?? []).map(hold => [hold.path, hold.code])).toEqual([['notes/a.md', 'worktree_dirty']]);
expect((await engine.readPageSnapshot('notes/a', { sourceId: 'default' }))!.page.compiled_truth).toContain('The committed body of notes/a.');
expect(readFileSync(join(root, 'notes/a.md'), 'utf8')).toContain('An uncommitted draft of notes/a.');
const second = await performManagedSync(engine, OPTS);
expect({ status: second.status, streak: second.pass?.not_converged_streak ?? 0 }).toEqual({ status: second.status === 'up_to_date' ? 'up_to_date' : 'synced', streak: 0 });
}, { setup }), 180_000);
test('with sync.holds=fail the same committed edit under an uncommitted edit stops the run, the page and the file untouched', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
await engine.setConfig('sync.holds', 'fail');
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'A committed change of notes/a.')); commit(root, 'change a');
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'An uncommitted draft of notes/a.'));
const refused = await performManagedSync(engine, OPTS).then(result => ({ status: result.status, reason: result.reason ?? null }), (error: { code?: string }) => ({ status: 'threw', reason: error.code ?? null }));
expect(refused).toEqual({ status: 'blocked_by_failures', reason: null });
expect((await engine.readPageSnapshot('notes/a', { sourceId: 'default' }))!.page.compiled_truth).toContain('The committed body of notes/a.');
expect(readFileSync(join(root, 'notes/a.md'), 'utf8')).toContain('An uncommitted draft of notes/a.');
}, { setup }), 180_000);
test('a database-only page at a new file\'s slug is held file_drift and never overwritten', () => managedBrain(async ({ engine, ctx, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
await engine.setConfig('sync.write_through', 'false');
for (const [slug, body] of [['notes/d', 'A database-only page.'], ['notes/e', 'The same body.']] as const)
await submitPageMutation(ctx, { operation: 'put_page', params: { slug, request_id: randomUUID(), content: note(slug, body) } });
await waitFor(async () => (await engine.executeRaw("SELECT 1 FROM persistence_requests WHERE state<>'committed'")).length === 0, { timeoutMs: 20_000, label: 'the put_pages commit' });
writeFileSync(join(root, 'notes/d.md'), note('notes/d', 'A committed file at the same slug.'));
writeFileSync(join(root, 'notes/e.md'), note('notes/e', 'The same body.')); commit(root, 'files at database-only slugs');
const result = await performManagedSync(engine, OPTS);
// Neither page records an origin, so neither side is attested: both are held (an equal body is not proof the file wrote it).
expect((result.held ?? []).map(hold => [hold.path, hold.code])).toEqual([['notes/d.md', 'file_drift'], ['notes/e.md', 'file_drift']]);
expect((await engine.readPageSnapshot('notes/d', { sourceId: 'default' }))!.page.compiled_truth).toContain('A database-only page.');
expect((await engine.executeRaw<{ source_path: string | null }>("SELECT source_path FROM pages WHERE source_id='default' AND slug IN ('notes/d','notes/e') ORDER BY slug")).map(row => row.source_path)).toEqual([null, null]);
}, { setup }), 180_000);
test('a commit landing during a pass: the next round imports it from the new HEAD, and the pass ends there', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
writeFileSync(join(root, 'notes/a.md'), note('notes/a', 'A committed change of notes/a.')); commit(root, 'change a');
let moved = false;
installFaultHook(async (point, detail) => {
if (point !== 'consumer:prepared' || moved || detail.operation !== 'submit_job') return;
moved = true;
writeFileSync(join(root, 'notes/d.md'), note('notes/d', 'A file committed during the pass.')); commit(root, 'add d during the pass');
});
const during = await performManagedSync(engine, OPTS);
installFaultHook(undefined);
expect(moved).toBe(true);
expect({ status: during.status, to: during.toCommit, added: during.added, modified: during.modified }).toEqual({ status: 'synced', to: git(root, 'rev-parse', 'HEAD'), added: 1, modified: 1 });
expect((await engine.readPageSnapshot('notes/a', { sourceId: 'default' }))!.page.compiled_truth).toContain('A committed change of notes/a.');
expect((await engine.readPageSnapshot('notes/d', { sourceId: 'default' }))!.page.compiled_truth).toContain('A file committed during the pass.');
expect((await engine.executeRaw<{ last_commit: string }>("SELECT last_commit FROM sources WHERE id='default'"))[0]!.last_commit).toBe(git(root, 'rev-parse', 'HEAD'));
expect((await performManagedSync(engine, OPTS)).status).toBe('up_to_date');
}, { setup }), 180_000);
test('--no-schema-pack: a three-file first pass converges, and the next pass under the flag is idle', () => managedBrain(async ({ engine }) => {
const first = await performManagedSync(engine, { ...OPTS, noSchemaPack: true });
expect({ status: first.status, outcome: first.pass?.outcome, remaining: first.pass?.remaining }).toEqual({ status: 'first_sync', outcome: 'synced', remaining: 0 });
expect((await engine.executeRaw<{ last_commit: string | null }>("SELECT last_commit FROM sources WHERE id='default'"))[0]!.last_commit).not.toBeNull();
expect((await performManagedSync(engine, { ...OPTS, noSchemaPack: true })).status).toBe('up_to_date');
}, { setup }), 180_000);
test('#6696: a cost-gate deferral is the pass\'s own constraint, never an opt-out the next flagless pass inherits', () => managedBrain(async ({ engine }) => {
const deferred = await performManagedSync(engine, { sourceId: 'default', noPull: true, noEmbed: true, embedDeferred: true }, { maxPages: 1, maxMs: 60_000 });
expect(deferred.status).toBe('partial');
const [row] = await engine.executeRaw<{ episode: unknown }>("SELECT completed_keys->0->'obligations'->'episode' AS episode FROM op_checkpoints WHERE op='managed-sync-pass' AND completed_keys->0->>'source_id'='default'");
expect(row!.episode ?? null).toBeNull();
const imports = await engine.executeRaw<{ no_embed: boolean; deferred: boolean | null }>("SELECT (intent->'processingOptions'->>'noEmbed')::boolean AS no_embed, (intent->>'embedDeferred')::boolean AS deferred FROM persistence_requests WHERE source_id='default' AND intent->>'kind'='managed_sync_import'");
expect(imports.length).toBeGreaterThan(0);
expect(imports.every(request => request.no_embed === false && request.deferred === true)).toBe(true);
const next = await performManagedSync(engine, { sourceId: 'default', noPull: true });
expect(next.status).toBe('first_sync');
expect(next.inherited_options).toBeUndefined();
}, { setup }), 180_000);
test('#6696 C1: a source configured with a strategy, synced with that strategy named (sync --all), is the configured selection and stamps last_commit', () => managedBrain(async ({ engine, root }) => {
await engine.executeRaw("UPDATE sources SET config=COALESCE(config,'{}'::jsonb)||jsonb_build_object('strategy','markdown') WHERE id='default'");
const first = await performManagedSync(engine, { ...OPTS, strategy: 'markdown' });
expect({ status: first.status, reason: first.reason }).toEqual({ status: 'first_sync', reason: undefined });
expect((await engine.executeRaw<{ last_commit: string | null }>("SELECT last_commit FROM sources WHERE id='default'"))[0]!.last_commit).toBe(git(root, 'rev-parse', 'HEAD'));
expect((await performManagedSync(engine, { ...OPTS, strategy: 'markdown' })).status).toBe('up_to_date');
}, { setup }), 180_000);
test('probe 54: a pass intent keeps what the #6862 FIFO guard reads, renameFrom included', () => managedBrain(async ({ engine, root }) => {
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
git(root, 'mv', 'notes/b.md', 'notes/renamed.md'); commit(root, 'rename b');
const seen: Array<Record<string, unknown>> = [];
installFaultHook(async (point, detail) => {
if (point !== 'consumer:prepared') return;
const [row] = await engine.executeRaw<{ kind: string; slug: string; page_id: number | null; rename_slug: string | null; pass_id: string | null }>(
"SELECT intent->>'kind' AS kind, slug, page_id, intent->'renameFrom'->>'slug' AS rename_slug, intent->>'passId' AS pass_id FROM persistence_requests WHERE request_id=$1::uuid", [detail.requestId]);
if (row?.kind === 'managed_sync_import') seen.push({ kind: row.kind, slug: row.slug, page_id: row.page_id === null ? null : Number(row.page_id), rename_slug: row.rename_slug, pass: !!row.pass_id });
});
expect((await performManagedSync(engine, OPTS)).status).toBe('synced');
installFaultHook(undefined);
expect(seen).toEqual([{ kind: 'managed_sync_import', slug: 'notes/renamed', page_id: null, rename_slug: 'notes/b', pass: true }]);
}, { setup }), 180_000);
});