Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(door): commit only the planned state; refuse staged-target and changed-file writes (#7705)

garrytan19083f99ba93
diff --git a/scripts/bench/door-write-overhead.ts b/scripts/bench/door-write-overhead.ts
index 2c2c76599a..c781f0860f 100644
--- a/scripts/bench/door-write-overhead.ts
+++ b/scripts/bench/door-write-overhead.ts
@@ -150,6 +150,7 @@ function nextTarget(written: string[], files: number): string {
async function doorPhase(files: number, traced: boolean) {
const { commitThroughDoor } = await import('../../src/core/persistence/git-door.ts');
+ const { sha256 } = await import('../../src/core/persistence/digest.ts');
const root = checkout(files);
const trace = join(WORK, `trace-${process.pid}.jsonl`);
rmSync(trace, { force: true });
@@ -162,9 +163,11 @@ async function doorPhase(files: number, traced: boolean) {
for (let w = 0; w < WARMUP + WRITES; w++) {
const rel = nextTarget(written, files);
const path = join(root, `${rel}.md`);
- writeFileSync(path, pageBody(rel, `Revision ${w} of ${rel}.`));
+ const body = pageBody(rel, `Revision ${w} of ${rel}.`);
+ writeFileSync(path, body);
+ const planned = sha256(body);
const start = performance.now();
- await commitThroughDoor(root, [{ path }]);
+ await commitThroughDoor(root, [{ path, planned }]);
const ms = performance.now() - start;
if (traced) {
const read = readTrace(trace, offset);
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index 2391e66d23..83f4e1768e 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -323,11 +323,13 @@ export const CODES = {
git_worktree_link_broken: { class: 'host_only', summary: "The directory is a linked Git worktree whose link to its repository is broken (the repository's entry was pruned, or the checkout moved), so it cannot be claimed as a canonical worktree; nothing was claimed.", why: 'A linked worktree reaches its commits through a .git file naming an entry in the repository, and the repository names the worktree back. With either link broken, Git commands in the directory fail or the next git worktree prune deletes the entry, so a door commit would go nowhere.', suggestion: 'From the repository, run git worktree repair on the worktree when both still exist, or add the worktree again with git worktree add, then rerun the claim.' },
hosted_repo_refused: { class: 'caller', reasons: ['source_bound', 'source_has_pages', 'source_has_path', 'source_archived', 'dir_not_empty'], summary: "gbrain sources host-repo starts a hosted repository only for an empty, unbound source and an absent or empty directory; nothing was created.", why: 'The verb makes a new bare repository the source of truth for the source. Existing pages or an existing directory would need converting into it, which is a separate step, so it refuses instead of guessing.', docs: 'docs/designs/GIT_CANONICAL_MEMORY.md#remote-and-hosted-writes', suggestion: 'Pick a new source ID and an empty directory, or keep this source as it is.' },
git_detached_head: { class: 'host_only', summary: "The canonical checkout is on a detached HEAD, so a push would target the wrong ref.", suggestion: 'Check out the branch the remote should track (git switch <branch>) on the brain host, then rerun.' },
+ git_index_conflict: { class: 'caller', actor: 'user', summary: "A strict (canonical: git) write found a staged change of its path that is not committed, so it committed nothing and left the index as it was.", why: "The door commits a path only while the checkout's index entry for it equals HEAD's. Committing over a staged change would overwrite it in the index or publish it under a gbrain commit, so the person who staged it decides first.", suggestion: 'Commit the staged change, or unstage it (git restore --staged -- <path> keeps the file on disk), then retry the write with a new request_id. git diff --cached --name-only -- <path> prints nothing once it is resolved.' },
git_index_locked: { class: 'retryable', summary: "Another Git process holds the canonical checkout index lock." },
git_index_stale: { class: 'caller', summary: "Git index stale." },
git_target_pending: { class: 'retryable', summary: "Git still lists a removed canonical file in the index; the removal was not committed yet." },
git_operation_in_progress: { class: 'caller', summary: "A rebase, merge, cherry-pick or revert is in progress in the checkout, so gbrain will not commit or move it.", docs: 'docs/guides/shared-checkout-git.md#stuck-rebase' },
git_push_unavailable: { class: 'retryable', summary: "The canonical commit is durable locally; its push will retry." },
+ git_target_changed: { class: 'caller', summary: "A strict (canonical: git) write's file changed on disk while it was being committed, so nothing was committed and the write was not published.", why: "The door commits exactly the bytes the write published, and checks the file's hash against them before and after Git stores it. An edit landing in between would otherwise be committed while the database records other content; recovery leaves the changed file as it is.", suggestion: 'Retry the write with a new request_id once the file has settled.' },
git_target_ignored: { class: 'caller', summary: "A .gitignore rule excludes the canonical file, so its Git effect cannot commit it; the effect parks at once.", suggestion: 'Remove or narrow the rule and commit that change, then run gbrain sources writer retry-effects <source> --parked-code git_target_ignored; or keep the file out of Git and leave the effect parked.' },
git_target_unsafe: { class: 'caller', summary: "Git cannot identify the existing canonical file by its native spelling." },
git_unavailable: { class: 'retryable', summary: "A git command did not complete." },
diff --git a/src/core/persistence/coordinator.ts b/src/core/persistence/coordinator.ts
index 77d851d916..eb04ecd145 100644
--- a/src/core/persistence/coordinator.ts
+++ b/src/core/persistence/coordinator.ts
@@ -625,7 +625,7 @@ export async function publishMutation(engine: BrainEngine, row: WriteRequest, pr
decoratePublicationOutcome(row, prepared, outcome, final, files.length, skill);
await recordPublicationFenceTrend(tx, row, outcome);
// G2: a strict source's file is committed before its row; its Git effect only pushes.
- if (door?.door) Object.assign(outcome.persistence as object, { git_state: 'committed', git_commit: await commitThroughDoor(door.door.root, [{ path: door.path, note: prepared.file?.commit }], lock ?? undefined) });
+ if (door?.door) Object.assign(outcome.persistence as object, { git_state: 'committed', git_commit: await commitThroughDoor(door.door.root, [{ path: door.path, planned: door.afterHash, note: prepared.file?.commit }], lock ?? undefined) });
await timePublicationStep('effects', row.slug, () => queuePublicationEffects(tx, row, final, outcome, prepared, { pushOnly: !!door?.door }));
if (prepared.afterEffects) await withCoordinatedWrite(tx, [row.source_id], () => prepared.afterEffects!(tx, outcome), publicationAttribution(row, prepared.trust));
await hooks.boundary?.('before_commit', row);
diff --git a/src/core/persistence/git-conversion.ts b/src/core/persistence/git-conversion.ts
index aa0d5b12cf..28f0bc966f 100644
--- a/src/core/persistence/git-conversion.ts
+++ b/src/core/persistence/git-conversion.ts
@@ -364,7 +364,7 @@ async function adoptGroups(engine: BrainEngine, plan: GitConversionPlan, preview
files.push({ path: target, bytes: Buffer.from(inlineExportMarkdown(await readExportPage(engine, item, withdrawals))) });
}
for (const file of files) writeAtomically(root, file.path, file.bytes);
- const commit = await commitThroughDoor(root, files.map(file => ({ path: file.path })), lock);
+ const commit = await commitThroughDoor(root, files.map(file => ({ path: file.path, planned: sha256(file.bytes) })), lock);
if (commit) commits.push(commit);
} finally { await lock.release(); }
await faultPoint('conversion:group_committed', { sourceId: context.sourceId, round: start / CONVERSION_GROUP_MAX + 1 });
diff --git a/src/core/persistence/git-door.ts b/src/core/persistence/git-door.ts
index 36c4e64d0d..c9d3fcbbe0 100644
--- a/src/core/persistence/git-door.ts
+++ b/src/core/persistence/git-door.ts
@@ -15,6 +15,15 @@
* published entries (`update-index --cacheinfo` / `--force-remove`): `git status` shows them clean, a later commit from
* that index keeps them, and every other entry, staged or not, is left as it was.
*
+ * Each file comes with its planned state (`DoorFile.planned`): the sha256 of the bytes the publication wrote there, or
+ * null for a removal. The door commits exactly that state or nothing. The file on disk must hash to the plan before
+ * and after `hash-object -w` stores it (an edit landing during the write refuses `git_target_changed`), and each
+ * target's index entry must equal HEAD's before the commit is built (a staged change of a target refuses
+ * `git_index_conflict`, index untouched). After the branch moves, an entry someone staged meanwhile is left as it is
+ * and the write reports that its commit landed. A write whose path already holds the planned blob at HEAD only refreshes
+ * an index entry still holding the parent commit's version (the door's own interrupted refresh); any other staged
+ * entry refuses `git_index_conflict`.
+ *
* Recovery inverts for those writes: the recovery record names the HEAD it was prepared against (`door`), and a
* publication that stopped after its commit landed keeps the committed file instead of restoring the prior bytes.
* The request is queued again; its replay finds the file already holding the bytes it publishes, committed, and
@@ -64,15 +73,24 @@ export const doorSeams: { beforeUpdateRef?: (root: string, attempt: number) => P
const doorTurns = new Map<string, Promise<void>>();
/** Refusals that keep their own code: the checkout's state, not the commit, stopped the write. */
-const TYPED = new Set(['git_detached_head', 'git_branch_unborn', 'git_index_locked', 'git_index_stale']);
+const TYPED = new Set(['git_detached_head', 'git_branch_unborn', 'git_index_locked', 'git_index_stale', 'git_target_changed', 'git_index_conflict']);
const landedFailures = new WeakSet<object>();
+/** One published file of a door commit and the state the commit must give its path. */
+export interface DoorFile {
+ path: string;
+ /** The planned state: the sha256 of the bytes the publication wrote at `path`, or null for a removal. */
+ planned: string | null;
+ note?: GitCommitNote;
+}
+
/**
* Commits the published files of one publication under the caller's writer lock and returns the commit HEAD then
- * names (the commit that holds these bytes, also when every path was already committed). A target Git refuses throws,
- * so the publication rolls back and recovery restores the prior bytes.
+ * names (the commit that holds these bytes, also when every path was already committed). Each path is committed in
+ * its planned state or not at all. A target Git refuses, a file that no longer holds its plan, or a target with a
+ * staged change throws, so the publication rolls back.
*/
-export async function commitThroughDoor(root: string, files: { path: string; note?: GitCommitNote }[], writerLock?: NativeLockHandle): Promise<string | null> {
+export async function commitThroughDoor(root: string, files: DoorFile[], writerLock?: NativeLockHandle): Promise<string | null> {
let key = resolve(root);
try { key = realpathSync(root); } catch { /* the session reports a missing checkout */ }
const prior = doorTurns.get(key) ?? Promise.resolve();
@@ -94,7 +112,9 @@ export async function commitThroughDoor(root: string, files: { path: string; not
}
interface TreeEntry { mode: string; oid: Buffer }
-interface Target { rel: string; name: string; dir: string; note?: GitCommitNote; mode?: string; oid?: string }
+interface Target { rel: string; name: string; dir: string; planned: string | null; note?: GitCommitNote; mode?: string; oid?: string; head?: string }
+/** The index entries of the targets (`<mode> <oid>`, or `unmerged`) and the index file's identity when they were read. */
+interface IndexSnapshot { signature: string; entries: Map<string, string> }
const TREE_MODE = '40000';
const latin1 = (text: string) => Buffer.from(text, 'utf8').toString('latin1');
@@ -166,7 +186,7 @@ function stripspace(paragraph: string): string {
return lines.join('\n');
}
-async function doorCommit(session: GitSession, root: string, files: { path: string; note?: GitCommitNote }[]): Promise<string> {
+async function doorCommit(session: GitSession, root: string, files: DoorFile[]): Promise<string> {
const symbolic = await git(session, ['symbolic-ref', '-q', 'HEAD']);
if (symbolic.code !== 0) throw opError('git_detached_head', `${root} is on a detached HEAD, so the strict source's write has no branch to commit to; nothing was published.`,
'Check out the branch the source tracks (git switch <branch>) on the brain host, then retry the write with a new request_id.');
@@ -184,10 +204,11 @@ async function doorCommit(session: GitSession, root: string, files: { path: stri
const rel = relative(root, nativeFileTarget(root, file.path, 'git_target_unsafe')).split(sep).join('/');
const full = `${prefix}${rel}`;
const slash = full.lastIndexOf('/');
- const target = targets.get(rel) ?? { rel, dir: slash < 0 ? '' : full.slice(0, slash), name: latin1(full.slice(slash + 1)) };
+ const target = targets.get(rel) ?? { rel, dir: slash < 0 ? '' : full.slice(0, slash), name: latin1(full.slice(slash + 1)), planned: file.planned };
target.note ??= file.note;
targets.set(rel, target);
}
+ refuseChanged(root, targets.values());
const present = [...targets.values()].filter(target => existsSync(join(root, target.rel)));
if (present.length) {
const hashed = await git(session, ['hash-object', '-w', '--', ...present.map(target => target.rel)]);
@@ -196,6 +217,7 @@ async function doorCommit(session: GitSession, root: string, files: { path: stri
present.forEach((target, i) => { target.oid = oids[i]; target.mode = lstatSync(join(root, target.rel)).mode & 0o111 ? '100755' : '100644'; });
}
let fileModeTrusted: boolean | undefined;
+ refuseChanged(root, targets.values());
const temp = join(persistenceHome(), 'door');
mkdirSync(temp, { recursive: true, mode: 0o700 });
@@ -243,6 +265,7 @@ async function doorCommit(session: GitSession, root: string, files: { path: stri
for (const target of targets.values()) {
const dir = dirs.get(target.dir)!;
const before = dir.found.get(target.name);
+ target.head = before && before.mode !== TREE_MODE ? `${before.mode} ${before.oid.toString('hex')}` : undefined;
if (target.oid) {
if (!before || before.mode === TREE_MODE) fresh.push(target);
if (before && /^100[0-7]{3}$/.test(before.mode) && target.mode !== before.mode) {
@@ -258,11 +281,17 @@ async function doorCommit(session: GitSession, root: string, files: { path: stri
changed.push(target);
}
if (fresh.length) await refuseIgnored(session, root, fresh);
+ const indexed = await readIndex(session, index, [...targets.values()]);
+ const staged = [...targets.values()].filter(target => indexed.entries.get(target.rel) !== target.head);
if (!changed.length) {
- const stale = await git(session, ['diff-index', '--cached', '--quiet', head, '--', ...targets.keys()]);
- if (stale.code !== 0) await syncIndex(session, root, prefix, [...targets.values()], head);
+ if (!staged.length) return head;
+ const parent = await parentEntries(session, head, staged);
+ const foreign = staged.filter(target => indexed.entries.get(target.rel) !== parent.get(target.rel));
+ if (foreign.length) throw indexConflict(root, foreign);
+ await syncIndex(session, root, prefix, index, [...targets.values()], head, indexed);
return head;
}
+ if (staged.length) throw indexConflict(root, staged);
// The trees are rebuilt bottom-up: an emptied directory leaves its parent, the rest are written and linked.
const written: { path: string; oid: string }[] = [];
@@ -294,7 +323,7 @@ async function doorCommit(session: GitSession, root: string, files: { path: stri
await doorSeams.beforeUpdateRef?.(root, attempt);
const moved = await git(session, ['update-ref', '-m', `commit: ${message[0]!.split('\n')[0]}`, branch, created, head]);
if (moved.code === 0) {
- await syncIndex(session, root, prefix, [...targets.values()], created);
+ await syncIndex(session, root, prefix, index, [...targets.values()], created, indexed);
return created;
}
if (attempt) throw new OperationError('git_unavailable', `${branch} in ${root} moved twice while this write was being committed, so it was not committed.`,
@@ -321,21 +350,87 @@ async function refuseIgnored(session: GitSession, root: string, fresh: Target[])
});
}
+/** The targets whose file no longer holds its planned state (its bytes, or no file for a removal) refuse as `git_target_changed`. */
+function refuseChanged(root: string, targets: Iterable<Target>): void {
+ const moved = [...targets].filter(target => { try { return hashFile(join(root, target.rel)) !== target.planned; } catch { return true; } }).map(target => target.rel);
+ if (!moved.length) return;
+ throw opError('git_target_changed', `${moved.join(', ')} in ${root} no longer holds the bytes this write published, so nothing was committed and the write was not published.`,
+ 'Another process changed the file during the write; recovery leaves the changed file as it is. Retry the write with a new request_id once the file has settled.', { detail: moved.join(',') });
+}
+
+/** Targets whose index entry differs from HEAD's (a staged change, or a merge conflict) refuse as `git_index_conflict`. */
+function indexConflict(root: string, staged: Target[]): OperationError {
+ const paths = staged.map(target => target.rel);
+ return opError('git_index_conflict', `${paths.join(', ')} in ${root} has a staged change that is not committed, so this write committed nothing and the index was left as it was.`,
+ 'Commit the staged change, or unstage it (git restore --staged -- <path> keeps the file on disk), then retry the write with a new request_id.', {
+ detail: paths.join(','),
+ fix: { ask_user: true, argv: ['git', '-C', root, 'restore', '--staged', '--', ...paths], consent: [], actor: 'user', requires_exclusive: false,
+ why: 'The door commits a path only while its index entry equals HEAD\'s, so a staged change is never overwritten or committed under a gbrain commit. Unstaging keeps the file on disk; committing it publishes that change.',
+ user_message: `${paths.join(', ')} in ${root} has a staged change that is not committed, so gbrain did not commit its write there. Commit the staged change, or unstage it (its bytes stay on disk), then retry the write?`,
+ verify: { argv: ['git', '-C', root, 'diff', '--cached', '--name-only', '--', ...paths] } },
+ });
+}
+
+const indexSignature = (index: string) => {
+ try { const stat = statSync(index, { bigint: true }); return `${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`; } catch { return ''; }
+};
+
+/** The index entries of the targets, keyed by path relative to the root; the signature is read first, so a later match proves no rewrite. */
+async function readIndex(session: GitSession, index: string, targets: Target[]): Promise<IndexSnapshot> {
+ const signature = indexSignature(index);
+ const listed = await git(session, ['ls-files', '-s', '-z', '--', ...targets.map(target => target.rel)]);
+ if (listed.code !== 0) throw gitFailure('Cannot read the canonical Git index.', `git ls-files failed for ${targets.length} file(s).`);
+ const entries = new Map<string, string>();
+ for (const record of listed.stdout.split('\0')) {
+ const tab = record.indexOf('\t');
+ if (tab < 0) continue;
+ const [mode, oid, stage] = record.slice(0, tab).split(' ');
+ const path = record.slice(tab + 1);
+ entries.set(path, stage === '0' && !entries.has(path) ? `${mode} ${oid}` : 'unmerged');
+ }
+ return { signature, entries };
+}
+
+/** The blob entries of the targets in `commit`'s first parent (none when it has no parent). */
+async function parentEntries(session: GitSession, commit: string, targets: Target[]): Promise<Map<string, string>> {
+ const listed = await git(session, ['ls-tree', '-z', `${commit}^`, '--', ...targets.map(target => target.rel)]);
+ const entries = new Map<string, string>();
+ if (listed.code !== 0) return entries;
+ for (const record of listed.stdout.split('\0')) {
+ const tab = record.indexOf('\t');
+ if (tab < 0) continue;
+ const [mode, type, oid] = record.slice(0, tab).split(' ');
+ if (type === 'blob') entries.set(record.slice(tab + 1), `${mode} ${oid}`);
+ }
+ return entries;
+}
+
/**
* Points the checkout's index entries of the targets at `commit`'s (a removed target leaves the index) and touches no
- * other entry. A failure here comes after the commit landed, so it says so instead of claiming nothing was published.
+ * other entry. An entry that changed since `seen` was read (someone staged it during the write) is left as it is. A
+ * failure here comes after the commit landed, so it says so instead of claiming nothing was published.
*/
-async function syncIndex(session: GitSession, root: string, prefix: string, targets: Target[], commit: string): Promise<void> {
- const kept = targets.filter(target => target.oid), removed = targets.filter(target => !target.oid);
- let failure = '';
+async function syncIndex(session: GitSession, root: string, prefix: string, index: string, targets: Target[], commit: string, seen: IndexSnapshot): Promise<void> {
+ let failure = '', restaged: Target[] = [];
try {
- const updated = await git(session, ['update-index', '--add', ...kept.flatMap(target => ['--cacheinfo', `${target.mode},${target.oid},${prefix}${target.rel}`]),
- ...(removed.length ? ['--force-remove', '--', ...removed.map(target => target.rel)] : [])]);
- if (updated.code === 0) return;
- failure = updated.stderr.trim().slice(0, 300) || `exit ${updated.code}`;
+ if (indexSignature(index) !== seen.signature) {
+ const now = await readIndex(session, index, targets);
+ restaged = targets.filter(target => now.entries.get(target.rel) !== seen.entries.get(target.rel));
+ }
+ const synced = targets.filter(target => !restaged.includes(target));
+ const kept = synced.filter(target => target.oid), removed = synced.filter(target => !target.oid);
+ if (synced.length) {
+ const updated = await git(session, ['update-index', '--add', ...kept.flatMap(target => ['--cacheinfo', `${target.mode},${target.oid},${prefix}${target.rel}`]),
+ ...(removed.length ? ['--force-remove', '--', ...removed.map(target => target.rel)] : [])]);
+ if (updated.code !== 0) failure = updated.stderr.trim().slice(0, 300) || `exit ${updated.code}`;
+ }
} catch (error) { failure = error instanceof Error ? error.message : String(error); }
- const error = opError('git_unavailable', `The strict source's commit ${commit.slice(0, 12)} landed, but the index of ${root} was not updated for ${targets.map(target => target.rel).join(', ')}.`,
- `git update-index failed (${failure}). Git holds the write; until the index is refreshed, git status lists those paths as staged reversions and a commit made from that index would undo them. Run git reset -q -- <those paths> in that checkout on the brain host.`);
+ if (!failure && !restaged.length) return;
+ const error = failure
+ ? opError('git_unavailable', `The strict source's commit ${commit.slice(0, 12)} landed, but the index of ${root} was not updated for ${targets.map(target => target.rel).join(', ')}.`,
+ `git update-index failed (${failure}). Git holds the write; until the index is refreshed, git status lists those paths as staged reversions and a commit made from that index would undo them. Run git reset -q -- <those paths> in that checkout on the brain host.`)
+ : opError('git_unavailable', `The strict source's commit ${commit.slice(0, 12)} landed, but the index of ${root} was left as it was for ${restaged.map(target => target.rel).join(', ')}: a change was staged there during the write.`,
+ 'Git holds the write, and the staged change was not overwritten; git diff --cached -- <path> in that checkout shows it against the new commit. Commit it, or unstage it with git restore --staged -- <path> (the file stays on disk).');
landedFailures.add(error);
throw error;
}
diff --git a/src/core/persistence/group-publish.ts b/src/core/persistence/group-publish.ts
index cd15737174..babb19b051 100644
--- a/src/core/persistence/group-publish.ts
+++ b/src/core/persistence/group-publish.ts
@@ -415,7 +415,7 @@ export async function publishGroup(engine: BrainEngine, rows: WriteRequest[], pr
if (lane) { timed.apply?.turn(); await faultPoint('lane:applied', { requestId: head.request_id, sourceId: head.source_id, operation: head.operation }); await awaitLaneTurn(tx, lane, rows); timed.apply?.turned(); }
// G2: one path-only commit for every member's file, in commit order, before the rows commit; a shared lease never reclaims an index lock.
if (strict && recorded.size) {
- const commit = await commitThroughDoor(binding.local_path!, [...recorded].map(([i, member]) => ({ path: member.record.path, note: prepared[i]!.file?.commit })), lane || joined ? undefined : lock);
+ const commit = await commitThroughDoor(binding.local_path!, [...recorded].map(([i, member]) => ({ path: member.record.path, planned: member.record.afterHash, note: prepared[i]!.file?.commit })), lane || joined ? undefined : lock);
for (const i of recorded.keys()) Object.assign(outcomes[i]!.persistence as object, { git_state: 'committed', git_commit: commit });
}
const done = await completeGroup(tx, rows, outcomes);
diff --git a/test/git-door-planned-state.test.ts b/test/git-door-planned-state.test.ts
new file mode 100644
index 0000000000..39e4e8db24
--- /dev/null
+++ b/test/git-door-planned-state.test.ts
@@ -0,0 +1,214 @@
+/**
+ * The door commits exactly its planned state (src/core/persistence/git-door.ts, gbrain#7705). Protects:
+ * - D1: a target's change staged before the write is never overwritten: the publication refuses git_index_conflict,
+ * the index still names the staged blob, and HEAD, the row and the file keep the prior revision (red before: the
+ * door's index refresh wrote its own blob over the staged one);
+ * - D2: the same for a change staged while the publication runs (after its file is renamed into place);
+ * - D4: a disk edit landing during the publication is never committed: it refuses git_target_changed, HEAD and the
+ * row keep the prior revision, and recovery holds the edited file as it is (red before: HEAD held the edit while the
+ * row recorded the publication's content);
+ * - with no interference the planned blob commits and the index and status are clean;
+ * - plumbing: a file rewritten between plan and commit refuses with nothing committed or staged; a change staged
+ * after the pre-commit check and before the index refresh is left staged and the refusal says the commit landed; a
+ * commit already at HEAD refreshes an entry still holding the parent's version and refuses any other staged entry.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { gitChildEnv } from '../src/core/git-env.ts';
+import { operations, type OperationContext } from '../src/core/operations.ts';
+import { submissionAuthority } from '../src/core/persistence/authority.ts';
+import { publishMutation, type PublicationHooks } from '../src/core/persistence/coordinator.ts';
+import { sha256 } from '../src/core/persistence/digest.ts';
+import { commitThroughDoor, doorSeams } from '../src/core/persistence/git-door.ts';
+import { localHostId } from '../src/core/persistence/identity.ts';
+import { admitWrite, claimNextWrite } from '../src/core/persistence/journal.ts';
+import { getWorktreeBinding } from '../src/core/persistence/ownership.ts';
+import { preparePageMutation } from '../src/core/persistence/page-prepare.ts';
+import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
+import { durableGitRepo } from './helpers/git-publication.ts';
+import { managedBrain, settleManagedGitEffects } from './helpers/managed-brain.ts';
+import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
+
+const env = gitChildEnv();
+const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env }).trim();
+const refusal = (work: Promise<unknown>) => work.then(() => null, (error: { code?: string; message?: string }) => error);
+
+const SLUG = 'notes/probe';
+const FILE = `${SLUG}.md`;
+const page = (title: string) => `---\ntype: note\ntitle: ${title}\n---\n\nA small single-file page body.\n`;
+const setup = ({ root }: { root: string }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };
+const putPage = operations.find(op => op.name === 'put_page')!;
+
+/** A strict source holding one committed page titled First. */
+async function committedPage(engine: BrainEngine, ctx: OperationContext): Promise<void> {
+ await engine.executeRaw(`UPDATE sources SET config = config || '{"canonical":"git"}'::jsonb WHERE id='default'`);
+ expect(await putPage.handler(ctx, { slug: SLUG, content: page('First'), request_id: randomUUID(), wait_ms: 30_000 })).toMatchObject({ state: 'committed' });
+ await settleManagedGitEffects(engine);
+}
+
+/** One put_page publication of `content` through the door, with the coordinator's boundary hooks. */
+async function publish(engine: BrainEngine, ctx: OperationContext, content: string, hooks: PublicationHooks = {}) {
+ await disposePersistenceConsumer(engine);
+ const host = localHostId(), binding = (await getWorktreeBinding(engine, 'default', host))!, old = (await engine.readPageSnapshot(SLUG, { sourceId: 'default' }))!;
+ const authority = await submissionAuthority(ctx, 'put_page', 'default', binding.source_incarnation, SLUG);
+ const intent = { slug: SLUG, content, expected_revision: old.revision };
+ await admitWrite(engine, { principal: authority.principal, authority, operation: 'put_page', sourceId: 'default', sourceIncarnation: binding.source_incarnation,
+ slug: SLUG, pageId: old.page.id, requestId: randomUUID(), callerIntent: intent, intent, worktreeId: binding.worktree_id, topologyGeneration: binding.topology_generation });
+ const row = (await claimNextWrite(engine, host))!;
+ return publishMutation(engine, row, await preparePageMutation(engine, row, ctx.config), host, hooks);
+}
+
+/** Where the page stands afterwards: the row's title, HEAD's and the disk's title lines, and the index entry's blob. */
+async function standing(engine: BrainEngine, root: string) {
+ const title = (text: string) => /^title: (.*)$/m.exec(text)?.[1];
+ return {
+ row: (await engine.readPageSnapshot(SLUG, { sourceId: 'default' }))!.page.title,
+ head: title(git(root, 'show', `HEAD:${FILE}`)),
+ disk: title(readFileSync(join(root, FILE), 'utf8')),
+ index: git(root, 'rev-parse', `:${FILE}`),
+ };
+}
+
+for (const backend of testBackends()) describe(`[${backend}] the door commits only its planned state`, () => {
+ const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;
+
+ test('D1: a change staged before the write is not overwritten; the write refuses git_index_conflict', () => managedBrain(async ({ engine, ctx, root }) => {
+ await committedPage(engine, ctx);
+ const head = git(root, 'rev-parse', 'HEAD'), original = readFileSync(join(root, FILE), 'utf8');
+ writeFileSync(join(root, FILE), original.replace('title: First', 'title: USER STAGED EDIT'));
+ git(root, 'add', FILE);
+ const userOid = git(root, 'rev-parse', `:${FILE}`);
+ writeFileSync(join(root, FILE), original);
+ const result = await publish(engine, ctx, page('Second'));
+ expect(result).toMatchObject({ state: 'failed', error_code: 'git_index_conflict' });
+ expect(await standing(engine, root)).toEqual({ row: 'First', head: 'First', disk: 'First', index: userOid });
+ expect(git(root, 'rev-parse', 'HEAD')).toBe(head);
+ }, { databaseUrl, setup }), 120_000);
+
+ test('D2: a change staged during the publication is not overwritten; the write refuses git_index_conflict', () => managedBrain(async ({ engine, ctx, root }) => {
+ await committedPage(engine, ctx);
+ const head = git(root, 'rev-parse', 'HEAD');
+ let userOid = '';
+ const result = await publish(engine, ctx, page('Second'), { boundary: async name => {
+ if (name !== 'after_publication') return;
+ const disk = readFileSync(join(root, FILE), 'utf8');
+ writeFileSync(join(root, FILE), disk.replace('title: Second', 'title: USER STAGED EDIT'));
+ git(root, 'add', FILE);
+ userOid = git(root, 'rev-parse', `:${FILE}`);
+ writeFileSync(join(root, FILE), disk);
+ } });
+ expect(result).toMatchObject({ state: 'failed', error_code: 'git_index_conflict' });
+ expect(await standing(engine, root)).toEqual({ row: 'First', head: 'First', disk: 'First', index: userOid });
+ expect(git(root, 'rev-parse', 'HEAD')).toBe(head);
+ }, { databaseUrl, setup }), 120_000);
+
+ test('D4: a disk edit during the publication is not committed; it refuses git_target_changed and recovery holds the file', () => managedBrain(async ({ engine, ctx, root }) => {
+ await committedPage(engine, ctx);
+ const head = git(root, 'rev-parse', 'HEAD'), committed = git(root, 'rev-parse', `HEAD:${FILE}`);
+ const result = await publish(engine, ctx, page('Second'), { boundary: async name => {
+ if (name !== 'after_publication') return;
+ writeFileSync(join(root, FILE), readFileSync(join(root, FILE), 'utf8').replace('title: Second', 'title: USER DISK EDIT'));
+ } });
+ expect(result).toMatchObject({ state: 'recovering', error_code: 'git_target_changed', blocked_reason: 'unexpected_file_bytes' });
+ expect(await standing(engine, root)).toEqual({ row: 'First', head: 'First', disk: 'USER DISK EDIT', index: committed });
+ expect(git(root, 'rev-parse', 'HEAD')).toBe(head);
+ expect(git(root, 'status', '--porcelain')).toBe(`M ${FILE}`);
+ }, { databaseUrl, setup }), 120_000);
+
+ test('with no interference the planned blob commits, and the index and status are clean', () => managedBrain(async ({ engine, ctx, root }) => {
+ await committedPage(engine, ctx);
+ const result = await publish(engine, ctx, page('Second'));
+ expect(result).toMatchObject({ state: 'committed' });
+ expect(result.outcome).toMatchObject({ persistence: { git_state: 'committed', git_commit: git(root, 'rev-parse', 'HEAD') } });
+ expect(await standing(engine, root)).toEqual({ row: 'Second', head: 'Second', disk: 'Second', index: git(root, 'rev-parse', `HEAD:${FILE}`) });
+ expect(git(root, 'rev-parse', `HEAD:${FILE}`)).toBe(git(root, 'hash-object', '--', FILE));
+ expect(git(root, 'status', '--porcelain')).toBe('');
+ }, { databaseUrl, setup }), 120_000);
+});
+
+const OLD = new Date('2001-01-01T00:00:00Z');
+const roots: string[] = [];
+afterEach(() => { delete doorSeams.beforeUpdateRef; for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+
+function repo(files: Record<string, string>): string {
+ const root = realpathSync(mkdtempSync(join(tmpdir(), 'gbrain-door-plan-')));
+ roots.push(root);
+ git(root, 'init', '-q', '-b', 'main');
+ git(root, 'config', 'user.name', 'Example Writer'); git(root, 'config', 'user.email', '[email protected]');
+ for (const [path, body] of Object.entries(files)) put(root, path, body);
+ git(root, 'add', '-A'); git(root, 'commit', '-qm', 'seed');
+ return root;
+}
+function put(root: string, path: string, body: string): void {
+ mkdirSync(dirname(join(root, path)), { recursive: true });
+ writeFileSync(join(root, path), body);
+ utimesSync(join(root, path), OLD, OLD);
+}
+/** Writes `body` at `path` and commits it through the door with that plan. */
+const publishAt = (root: string, path: string, body: string) => { put(root, path, body); return commitThroughDoor(root, [{ path: join(root, path), planned: sha256(body) }]); };
+
+describe('door plumbing: the planned state', () => {
+ test('a file rewritten after it was planned refuses git_target_changed; nothing is committed or staged', async () => {
+ const root = repo({ 'notes/a.md': 'a\n' });
+ const head = git(root, 'rev-parse', 'HEAD');
+ put(root, 'notes/a.md', 'someone else\n');
+ put(root, 'notes/new.md', 'someone else\n');
+ for (const [path, planned] of [['notes/a.md', sha256('planned\n')], ['notes/new.md', sha256('planned\n')], ['notes/a.md', null]] as const) {
+ expect(await refusal(commitThroughDoor(root, [{ path: join(root, path), planned }]))).toMatchObject({ code: 'git_target_changed', message: expect.stringContaining(path) });
+ }
+ expect(git(root, 'rev-parse', 'HEAD')).toBe(head);
+ expect(git(root, 'diff', '--cached', '--name-only')).toBe('');
+ expect(git(root, 'ls-files', '--', 'notes/new.md')).toBe('');
+ });
+
+ test('a staged change of a target refuses git_index_conflict before the commit; the index keeps it', async () => {
+ const root = repo({ 'notes/a.md': 'a\n', 'notes/b.md': 'b\n' });
+ const head = git(root, 'rev-parse', 'HEAD');
+ put(root, 'notes/b.md', 'staged\n'); git(root, 'add', 'notes/b.md');
+ const staged = git(root, 'rev-parse', ':notes/b.md');
+ put(root, 'notes/b.md', 'b\n');
+ const error = await refusal(publishAt(root, 'notes/b.md', 'door\n')) as { code?: string; fix?: { argv?: string[]; verify?: { argv?: string[] } } };
+ expect(error).toMatchObject({ code: 'git_index_conflict' });
+ expect(error.fix).toMatchObject({ argv: ['git', '-C', root, 'restore', '--staged', '--', 'notes/b.md'], verify: { argv: ['git', '-C', root, 'diff', '--cached', '--name-only', '--', 'notes/b.md'] } });
+ expect(git(root, 'rev-parse', 'HEAD')).toBe(head);
+ expect(git(root, 'rev-parse', ':notes/b.md')).toBe(staged);
+ git(root, 'restore', '--staged', '--', 'notes/b.md');
+ expect(await publishAt(root, 'notes/b.md', 'door\n')).toBe(git(root, 'rev-parse', 'HEAD'));
+ expect(git(root, 'status', '--porcelain')).toBe('');
+ });
+
+ test('a change staged after the check and before the index refresh is left staged; the refusal says the commit landed', async () => {
+ const root = repo({ 'notes/a.md': 'a\n', 'notes/b.md': 'b\n' });
+ let staged = '';
+ doorSeams.beforeUpdateRef = () => {
+ writeFileSync(join(root, 'notes/b.md'), 'staged meanwhile\n'); git(root, 'add', 'notes/b.md');
+ staged = git(root, 'rev-parse', ':notes/b.md');
+ writeFileSync(join(root, 'notes/b.md'), 'door\n');
+ };
+ put(root, 'notes/a.md', 'door a\n'); put(root, 'notes/b.md', 'door\n');
+ const error = await refusal(commitThroughDoor(root, ['notes/a.md', 'notes/b.md'].map(path => ({ path: join(root, path), planned: sha256(readFileSync(join(root, path))) }))));
+ expect(error).toMatchObject({ code: 'git_unavailable', message: expect.stringMatching(/landed, but the index of .* was left as it was for notes\/b\.md: /) });
+ expect(git(root, 'show', 'HEAD:notes/b.md')).toBe('door');
+ expect(git(root, 'rev-parse', ':notes/b.md')).toBe(staged);
+ expect(git(root, 'rev-parse', ':notes/a.md')).toBe(git(root, 'rev-parse', 'HEAD:notes/a.md'));
+ });
+
+ test('a commit already at HEAD refreshes an entry holding the parent\'s version and refuses any other staged entry', async () => {
+ const root = repo({ 'notes/a.md': 'a\n' });
+ const commit = await publishAt(root, 'notes/a.md', 'door\n');
+ git(root, 'update-index', '--cacheinfo', `100644,${git(root, 'rev-parse', `${commit}^:notes/a.md`)},notes/a.md`);
+ expect(await commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }])).toBe(commit);
+ expect(git(root, 'status', '--porcelain')).toBe('');
+ put(root, 'notes/a.md', 'novel\n'); git(root, 'add', 'notes/a.md');
+ const novel = git(root, 'rev-parse', ':notes/a.md');
+ put(root, 'notes/a.md', 'door\n');
+ expect(await refusal(commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }]))).toMatchObject({ code: 'git_index_conflict' });
+ expect(git(root, 'rev-parse', ':notes/a.md')).toBe(novel);
+ expect(git(root, 'rev-parse', 'HEAD')).toBe(commit!);
+ });
+});
diff --git a/test/git-door-plumbing-gbra133.test.ts b/test/git-door-plumbing-gbra133.test.ts
index b77b77254a..d8c4e0b014 100644
--- a/test/git-door-plumbing-gbra133.test.ts
+++ b/test/git-door-plumbing-gbra133.test.ts
@@ -21,6 +21,7 @@ import { operations, type OperationContext } from '../src/core/operations.ts';
import { commitGitTargets } from '../src/core/persistence/effect-git.ts';
import type { GitCommitNote } from '../src/core/persistence/effect-model.ts';
import { commitThroughDoor, doorSeams } from '../src/core/persistence/git-door.ts';
+import { hashFile } from '../src/core/persistence/large-file.ts';
import { gitChildEnv } from '../src/core/git-env.ts';
import { durableGitRepo } from './helpers/git-publication.ts';
import { managedBrain } from './helpers/managed-brain.ts';
@@ -59,7 +60,7 @@ function indexEntries(root: string): Map<string, string> {
}
return entries;
}
-const door = (root: string, ...paths: string[]) => commitThroughDoor(root, paths.map(path => ({ path: join(root, path) })));
+const door = (root: string, ...paths: string[]) => commitThroughDoor(root, paths.map(path => ({ path: join(root, path), planned: hashFile(join(root, path)) })));
/** A sandbox's git wrapper may append a co-author trailer to every `git commit` (never to commit-tree): both sides are read without it. */
const unshimmed = (message: string) => message.replace(/^Co-authored-by: .*\n/gm, '').replace(/\n+$/, '\n');
const refusal = (work: Promise<unknown>) => work.then(() => null, (error: { code?: string; message?: string }) => error);
@@ -178,7 +179,7 @@ describe('G2 plumbing door commit', () => {
for (const root of [porcelain, plumbing]) for (const path of paths) put(root, path, path + ', second revision\n');
const outcomes = await commitGitTargets(porcelain, paths, undefined, new Map(paths.flatMap(path => notes[path] ? [[path, notes[path]!] as const] : [])));
expect([...outcomes.values()].every(outcome => !(outcome instanceof Error) && outcome.git === 'committed')).toBe(true);
- await commitThroughDoor(plumbing, paths.map(path => ({ path: join(plumbing, path), note: notes[path] })));
+ await commitThroughDoor(plumbing, paths.map(path => ({ path: join(plumbing, path), planned: hashFile(join(plumbing, path)), note: notes[path] })));
for (const format of ['%B', '%(trailers:only)', '%an <%ae>']) expect(unshimmed(raw(plumbing, 'log', '-1', '--format=' + format))).toBe(unshimmed(raw(porcelain, 'log', '-1', '--format=' + format)));
expect(git(plumbing, 'rev-parse', 'HEAD^{tree}')).toBe(git(porcelain, 'rev-parse', 'HEAD^{tree}'));
expect(git(plumbing, 'reflog', '-1', '--format=%gs')).toBe(git(porcelain, 'reflog', '-1', '--format=%gs'));
diff --git a/test/git-door-write-cost.test.ts b/test/git-door-write-cost.test.ts
index ba6de02e4c..43fae3f0be 100644
--- a/test/git-door-write-cost.test.ts
+++ b/test/git-door-write-cost.test.ts
@@ -33,6 +33,7 @@ import { gitChildEnv } from '../src/core/git-env.ts';
import { operations, type OperationContext } from '../src/core/operations.ts';
import { runPersistenceEffects } from '../src/core/persistence/effects.ts';
import { commitThroughDoor, doorSeams } from '../src/core/persistence/git-door.ts';
+import { hashFile } from '../src/core/persistence/large-file.ts';
import { localHostId } from '../src/core/persistence/identity.ts';
import { resetIgnoreCandidatesForTests } from '../src/core/persistence/ignore-rules.ts';
import { acquireNativeLock, type NativeLockHandle } from '../src/core/persistence/native-lock.ts';
@@ -64,7 +65,7 @@ function put(root: string, path: string, body: string): void {
writeFileSync(join(root, path), body);
utimesSync(join(root, path), OLD, OLD);
}
-const door = (root: string, ...paths: string[]) => commitThroughDoor(root, paths.map(path => ({ path: join(root, path) })));
+const door = (root: string, ...paths: string[]) => commitThroughDoor(root, paths.map(path => ({ path: join(root, path), planned: hashFile(join(root, path)) })));
const refusal = (work: Promise<unknown>) => work.then(() => null, (error: { code?: string; message?: string; suggestion?: string }) => error);
const changed = (root: string, commit: string) => lines(git(root, 'show', '--no-renames', '--name-only', '--format=', commit)).sort();
@@ -184,7 +185,7 @@ describe('door write cost', () => {
const commits: (string | null)[] = [];
for (let i = 0; i < 8; i++) {
put(root, `notes/d${i}.md`, `door ${i}\n`);
- commits.push(await underLock(lock => commitThroughDoor(root, [{ path: join(root, `notes/d${i}.md`) }], lock)));
+ commits.push(await underLock(lock => commitThroughDoor(root, [{ path: join(root, `notes/d${i}.md`), planned: hashFile(join(root, `notes/d${i}.md`)) }], lock)));
}
await outsider;
expect(commits.every(commit => typeof commit === 'string')).toBe(true);
diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txt
index 52d7f39dc8..8b9c968374 100644
--- a/test/postgres-unit-arms.txt
+++ b/test/postgres-unit-arms.txt
@@ -85,6 +85,7 @@ test/get-chunks-paging.test.ts
test/git-canonical-conversion-g8a.test.ts
test/git-canonical-declared-g7a.test.ts
test/git-canonical-indexer-g3.test.ts
+test/git-door-planned-state.test.ts
test/git-door-plumbing-gbra133.test.ts
test/git-door-remote-g7b.test.ts
test/git-door-strict-gbra133.test.ts