Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #6194 (D4): a database-only write that commits to a page while managed sync imports a newer Git version of it
* failed the import with `revision_conflict`, and that terminal receipt replayed on every later sync, so the
* source stayed `blocked_by_failures`. A conflict proven to come from such a write (the live revision was written
* by a committed non-sync request for the same page) is now a `concurrent_write` hold: the sync finishes, the
* database version is kept, nothing is overwritten, and the hold points at `sources reconcile --preview`.
* Without that proof (a revision no journal request wrote) the failure still blocks.
* PGLite always; Postgres too when DATABASE_URL is set.
*/
import { describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { execFileSync } from 'node:child_process';
import { mkdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { performManagedSync } from '../src/core/persistence/sync-run.ts';
import { installFaultHook } from '../src/core/persistence/fault-points.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { readGitHold } from '../src/core/persistence/sync-holds.ts';
import { PASS_BATCH_KEY_PREFIX, readPassBatch } from '../src/core/persistence/sync-pass-batch.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
import { waitFor } from './helpers/wait-for.ts';
const SLUG = 'people/alice-example';
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', '.'); git(root, '-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', message); };
const note = (body: string) => `---\ntype: person\ntitle: Alice Example\n---\n\n${body}\n`;
/** The slug of the import the running pass froze and has not settled yet (its in-memory batch's pending entry). */
async function storedPending(engine: BrainEngine): Promise<string | null> {
const [row] = await engine.executeRaw<{ pass_id: string | null }>("SELECT completed_keys->0->'telemetry'->>'pass_id' AS pass_id FROM op_checkpoints WHERE op='managed-sync-pass' AND completed_keys->0->>'source_id'='default'");
if (!row?.pass_id) return null;
for (let batch = 0; batch < 8; batch++) {
const slug = readPassBatch<{ pending?: { slug?: string } | null }>(`${PASS_BATCH_KEY_PREFIX}${row.pass_id}:${batch}`)?.pending?.slug;
if (slug) return slug;
}
return null;
}
/** First sync imports the page; then Git gets a newer version and a database-only write races the next import. */
async function raced(engine: BrainEngine, root: string, write: () => Promise<unknown>) {
expect(await performManagedSync(engine, { sourceId: 'default', noPull: true })).toMatchObject({ status: 'first_sync' });
const before = await engine.readPageSnapshot(SLUG, { sourceId: 'default' });
writeFileSync(join(root, 'people', 'alice-example.md'), note('Works at acme-example; the Git edit.'));
commit(root, 'git edit');
let fired = false;
installFaultHook(async (point, detail) => {
if (point !== 'sync:mid_checkpoint' || detail.sourceId !== 'default' || fired || await storedPending(engine) !== SLUG) return;
fired = true;
await write();
});
try {
const first = await performManagedSync(engine, { sourceId: 'default', noPull: true });
expect(fired).toBe(true);
return { first, before: before! };
} finally { installFaultHook(undefined); }
}
for (const databaseUrl of process.env.DATABASE_URL ? [undefined, process.env.DATABASE_URL] : [undefined]) describe(`#6194 concurrent write during import (${databaseUrl ? 'postgres' : 'pglite'})`, () => {
const setup = ({ root }: { root: string }) => {
mkdirSync(join(root, 'people'), { recursive: true });
git(root, 'init', '-q');
writeFileSync(join(root, 'people', 'alice-example.md'), note('Works at acme-example.'));
commit(root, 'notes');
};
test('a proven concurrent database-only write becomes a concurrent_write hold; the sync finishes and nothing is overwritten', () => managedBrain(async ({ engine, ctx, root }) => {
await engine.setConfig('sync.write_through', 'false');
let requestId = '';
const { first } = await raced(engine, root, async () => {
requestId = randomUUID();
const current = await engine.readPageSnapshot(SLUG, { sourceId: 'default' });
await submitPageMutation(ctx as OperationContext, { operation: 'put_page', params: { slug: SLUG, request_id: requestId, expected_revision: current!.revision,
content: note('Works at acme-example; the database-only edit.') } });
await waitFor(async () => (await engine.executeRaw<{ state: string }>("SELECT state FROM persistence_requests WHERE request_id=$1::uuid", [requestId]))[0]?.state === 'committed',
{ timeoutMs: 20_000, label: 'the database-only put_page commits' });
});
expect(first.status).not.toBe('blocked_by_failures');
expect(first.held?.map(hold => ({ path: hold.path, code: hold.code }))).toEqual([{ path: 'people/alice-example.md', code: 'concurrent_write' }]);
const item = first.held![0]!;
expect(item.fix.argv).toEqual(['gbrain', 'sources', 'reconcile', 'default', SLUG, '--preview']);
expect(item.fix.why).toContain(requestId);
expect((await engine.getPage(SLUG, { sourceId: 'default' }))?.compiled_truth).toContain('the database-only edit');
const [source] = await engine.executeRaw<{ incarnation: string }>("SELECT incarnation::text FROM sources WHERE id='default'");
const record = await readGitHold(engine, 'default', source!.incarnation, 'people/alice-example.md');
expect(record).toMatchObject({ code: 'concurrent_write', meta: { competing_request_id: requestId, competing_operation: 'put_page' } });
const [summary] = await engine.executeRaw<{ concurrent: number }>("SELECT (completed_keys->0->>'concurrent')::int AS concurrent FROM op_checkpoints WHERE op='sync-hold-summary' AND fingerprint=$1", [`default:${source!.incarnation}`]);
expect(summary?.concurrent).toBe(1);
// The next sync does not replay a failure: the file stays held and the page keeps the database version.
const again = await performManagedSync(engine, { sourceId: 'default', noPull: true });
expect(again.status).not.toBe('blocked_by_failures');
expect((await engine.getPage(SLUG, { sourceId: 'default' }))?.compiled_truth).toContain('the database-only edit');
}, { databaseUrl, setup }), 120_000);
test('a database-only delete of the page during the import is held the same way and stays deleted', () => managedBrain(async ({ engine, ctx, root }) => {
await engine.setConfig('sync.write_through', 'false');
let requestId = '';
const { first } = await raced(engine, root, async () => {
requestId = randomUUID();
const current = await engine.readPageSnapshot(SLUG, { sourceId: 'default' });
await submitPageMutation(ctx as OperationContext, { operation: 'delete_page', params: { slug: SLUG, request_id: requestId, expected_revision: current!.revision } });
await waitFor(async () => (await engine.executeRaw<{ state: string }>("SELECT state FROM persistence_requests WHERE request_id=$1::uuid", [requestId]))[0]?.state === 'committed',
{ timeoutMs: 20_000, label: 'the database-only delete_page commits' });
});
expect(first.held?.map(hold => hold.code)).toEqual(['concurrent_write']);
expect(first.held![0]!.fix.why).toContain(requestId);
expect(await engine.getPage(SLUG, { sourceId: 'default' })).toBeNull();
}, { databaseUrl, setup }), 120_000);
// #6340: a page that moved with no journal request to name is held too (the revision alone is the proof the page moved); the fix stays the reconcile preview.
test('a revision conflict no journal request explains is held by its revision, not left blocking', () => managedBrain(async ({ engine, root }) => {
const { first } = await raced(engine, root, () => engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () => tx.putPage(SLUG, {
type: 'person', title: 'Alice Example', compiled_truth: 'An unattributed database edit.', timeline: '', frontmatter: {}, content_hash: 'unattributed',
}, { sourceId: 'default' }), TEST_WRITE_ATTRIBUTION)));
expect(first.status).not.toBe('blocked_by_failures');
expect(first.managedWrite).toBeUndefined();
expect(first.held?.map(hold => hold.code)).toEqual(['concurrent_write']);
expect(first.held![0]!.fix.why).toContain(`changed in the database`);
expect(first.held![0]!.fix.argv).toEqual(['gbrain', 'sources', 'reconcile', 'default', SLUG, '--preview']);
expect((await engine.getPage(SLUG, { sourceId: 'default' }))?.compiled_truth).toContain('An unattributed database edit.');
}, { databaseUrl, setup }), 120_000);
});