Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
28.9 KB
Raw Blame
/**
 * GST-1601 part 2: a remember, capture or add_timeline_entry refused `source_changed` / `file_database_drift` because its
 * page's canonical file holds a one-sided local edit (git HEAD still holds the database's copy, only the worktree file
 * moved) adopts that edit, then applies on top. Per source and off by default: `persistence.adopt_local_edits.source.<id>`.
 *
 * The owner publishes the edit first as its own write: a `managed_file_repair` (file-repair.ts) carrying `adoptLocalEdit`,
 * admitted under this installation's CLI writer (never the caller's principal) with a request id derived from the
 * caller's, so a write adopts at most once. It imports the file's exact bytes under the hash it read (an edit landing
 * before publication ends `raw_file_changed` and nothing is written; a commit that moved HEAD or a cancelled caller
 * adopts nothing), archives the replaced revision with change_reason
 * `adopted_local_edit`, and, on a Git-durable checkout, commits only that file before its row commits: subject
 * `gbrain: adopt local edit to <path>`, trailers `gbrain-adopted:` and `gbrain-author: unknown`, a commit-ledger line
 * (`adopted`). A repo-less brain records the adoption in the database alone. The caller's claim is then released and its
 * write prepared again from scratch; its receipt names `adopted: { path, blob, replaced_revision }`.
 *
 * Everything else keeps the refusal: another operation, a batch, the flag off, a held file, a two-sided edit (HEAD holds
 * neither the database's copy nor any entry), a file that does not import cleanly, and an edit to the title, the type or
 * a protected frontmatter key (page-prepare.ts protectedLocalEdit). A file still changing is adopted only once it has
 * been quiet for `persistence.adopt_quiet_ms` (default 5000); one that is not quiet within three windows keeps the refusal.
 *
 * #8755 hardening: the quiet wait is capped at the foreground preparation budget (30 s), since the caller's running claim
 * holds its worktree's queue meanwhile; a file over PAGE_MAX_BYTES (checked before it is read) or a page stored in
 * segments keeps the refusal; so do an unmerged path or a merge, cherry-pick, revert or rebase in progress, a file equal to
 * an earlier stored revision, and one missing a Facts or timeline row the last revision added (a stale editor buffer
 * saved over gbrain's write). The repo-less test walks up for `.git` (a source in a subdirectory of its repository). A
 * publication that failed after the adoption's commit landed is requeued by recovery and published again (its validate
 * accepts HEAD holding the adopted blob; the commit is then named, not repeated). An adoption another task is
 * publishing is waited on, never left to commit after its caller was refused. The adoption names its caller's claim and
 * publishes nothing once that claim is gone (a crash between admission and settling); its own claim carries the owner
 * stamp like any other. A caller whose claim was lost meanwhile is reported as such, never as released.
 *
 * #8824/#8767: the caller check runs only until the adoption's own commit lands. A replay that finds HEAD holding it
 * (`landedAdoptionCommit`) publishes it whatever became of the caller, a requeued one is never cancelled, and recovery
 * names the commit on the receipt (`landed_before_row`) whether the adoption then commits or ends without committing.
 * #8826: a bisect or an uncommitted squash merge also keeps the refusal (`operationMarkerPaths`).
 */
import { randomUUID } from 'node:crypto';
import { existsSync, readFileSync, statSync } from 'node:fs';
import { dirname, join, relative, resolve, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { OperationError, opError, type OperationContext } from '../ops/contract.ts';
import { PAGE_MAX_BYTES } from '../page-size-policy.ts';
import { assertInlineBody, isSegmentedPage } from '../page-body/page-shape.ts';
import { parseMarkdown } from '../markdown.ts';
import type { PageSnapshot } from '../page-state/types.ts';
import { gitBlobOid, sha256 } from './digest.ts';
import { commitGitTargets } from './effect-git.ts';
import { sourceCanonicalGit } from './git-door.ts';
import { gitDurabilityPolicy } from './git-durability-policy.ts';
import { withRegisteredLocalWriter } from './identity.ts';
import { admitWrite, getWriteRequest, getWriteRequestById, publicationGroupKey, releaseUnpublishedClaim } from './journal.ts';
import { isTerminal, requestPrincipal, type WriteRequest } from './model.ts';
import { declarePersistenceProtocol } from './protocol.ts';
import type { WorktreeBinding } from './ownership.ts';
import { getWorktreeBinding } from './ownership.ts';
import { fileMatchesSnapshot, protectedLocalEdit } from './page-prepare.ts';
import { blobAt, blobText, commitMessage, commitParent, headBlob, headCommit, landedCommit, operationMarkerPaths, unmergedPath } from './pending-import.ts';
import { ledgerLocation, messageDigest, readLedger } from '../git/commit-ledger.ts';
import { adoptedBy, localEditAdoptionCommit, type GitCommitNote } from './effect-model.ts';
import { claimOwner } from './claim-phase.ts';
import type { PreparedMutation } from './coordinator.ts';
import { EDGE_WHITESPACE } from '../edge-whitespace.ts';

export const ADOPTED_CHANGE_REASON = 'adopted_local_edit';
export const ADOPT_QUIET_KEY = 'persistence.adopt_quiet_ms';
const ADOPT_QUIET_DEFAULT_MS = 5_000;
/** A file is waited on for at most this many quiet windows. */
const QUIET_WINDOWS = 3;
/** #8755: the inline quiet wait never passes the foreground preparation budget: the caller's claim holds its worktree queue. */
const ADOPT_WAIT_MAX_MS = 30_000;
/** How long the adoption retries a worktree lock another owner task holds. */
const LOCK_RETRY_MS = 10_000;
/** #8755: how long an adoption another task is publishing is waited on past LOCK_RETRY_MS before the caller keeps its refusal. */
const PUBLISHING_WAIT_MS = 120_000;
/** Earlier stored revisions a stale editor save is compared with. */
const STALE_REVISIONS = 50;
const ADOPTING_OPERATIONS: readonly string[] = ['remember', 'capture', 'add_timeline_entry'];

/** Test seams: `beforePublish` runs between the adoption's preparation and its publication, with the file's path; `maxWaitMs` lowers the quiet-wait cap. */
export const localEditAdoptionSeams: { beforePublish?: (path: string) => void | Promise<void>; maxWaitMs?: number } = {};

/** The drifted file a `file_database_drift` refusal carries (page-prepare.ts compareFileTarget). */
interface LocalEditTarget { root: string; path: string }
export interface AdoptedLocalEdit { path: string; blob: string; replaced_revision: string }

export async function adoptLocalEditsOn(engine: BrainEngine, sourceId: string): Promise<boolean> {
  const value = await engine.getConfig(`persistence.adopt_local_edits.source.${sourceId}`).catch(() => null);
  return ['1', 'true', 'yes', 'on'].includes(String(value ?? '').trim().toLowerCase());
}
async function quietMs(engine: BrainEngine): Promise<number> {
  const raw = String(await engine.getConfig(ADOPT_QUIET_KEY).catch(() => null) ?? '').trim();
  const value = raw ? Number(raw) : ADOPT_QUIET_DEFAULT_MS;
  return Number.isFinite(value) && value >= 0 ? Math.min(value, 60_000) : ADOPT_QUIET_DEFAULT_MS;
}
/** #8755: whether a `.git` entry sits at `root` or above it (reconcile-state.ts insideGitCheckout): only a brain with none is repo-less. */
function insideGitCheckout(root: string): boolean {
  for (let dir = resolve(root); ; dir = dirname(dir)) {
    if (existsSync(join(dir, '.git'))) return true;
    if (dirname(dir) === dir) return false;
  }
}
const logAdoption = (row: WriteRequest, reason: string, error: unknown) => process.stderr.write(`[persistence] phase=adoption reason=${reason} source=${row.source_id} request=${row.request_id} `
  + `message="${String(error instanceof Error ? error.message : error).replace(/\s+/g, ' ').slice(0, 300)}"; the write keeps its file_database_drift refusal\n`);
/** The adoption's request id, derived from the caller's write so a write adopts at most once. */
function adoptionRequestId(row: Pick<WriteRequest, 'id'>): string {
  const h = sha256(`gbrain:adopt-local-edit:${row.id}`);
  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${(8 + (parseInt(h[16]!, 16) & 3)).toString(16)}${h.slice(17, 20)}-${h.slice(20, 32)}`;
}

/** Waits until `path` has not changed for the quiet window; false when it is still changing after QUIET_WINDOWS windows or the cap. */
async function settled(path: string, quiet: number): Promise<boolean> {
  const deadline = Date.now() + Math.min(quiet * QUIET_WINDOWS, localEditAdoptionSeams.maxWaitMs ?? ADOPT_WAIT_MAX_MS);
  for (;;) {
    const age = Date.now() - statSync(path).mtimeMs;
    if (age >= quiet) return true;
    if (Date.now() + quiet - age > deadline) return false;
    await new Promise(resolve => setTimeout(resolve, quiet - age));
  }
}

const edgeTrim = (text: string | null | undefined) => (text ?? '').trim();
/** Body lines that are Facts or timeline fence rows (list items and table rows, not a table's separator line). */
function fenceRows(...texts: Array<string | null | undefined>): Set<string> {
  return new Set(texts.flatMap(text => (text ?? '').split('\n')).map(line => line.trim()).filter(line => /^(- |\|)/.test(line) && !/^\|[\s:|-]*\|?$/.test(line)));
}
/**
 * #8755: a stale editor save: the file equals one of the last STALE_REVISIONS stored revisions' bodies (both trimmed in
 * TypeScript, so the match holds on any database encoding), or lacks a Facts or timeline row the last revision added
 * (rows the page holds that its newest archived version, the revision before, did not). Inline pages only: adoptionIntent
 * refuses a segmented page first.
 */
export async function staleEditorSave(engine: BrainEngine, slug: string, text: string, snapshot: PageSnapshot, activePack: unknown): Promise<boolean> {
  assertInlineBody(snapshot.page, 'staleEditorSave');
  const file = parseMarkdown(text, slug, { activePack } as never);
  const [compiled, timeline] = [edgeTrim(file.compiled_truth), edgeTrim(file.timeline)];
  if (compiled !== edgeTrim(snapshot.page.compiled_truth) || timeline !== edgeTrim(snapshot.page.timeline)) {
    const earlier = await engine.executeRaw<{ compiled_truth: string; timeline: string | null }>(
      'SELECT compiled_truth, timeline FROM page_versions WHERE page_id=$1 AND compiled_truth IS NOT NULL ORDER BY id DESC LIMIT $2', [snapshot.page.id, STALE_REVISIONS]);
    if (earlier.some(v => edgeTrim(v.compiled_truth) === compiled && edgeTrim(v.timeline) === timeline)) return true;
  }
  const [previous] = await engine.executeRaw<{ compiled_truth: string; timeline: string | null }>(
    'SELECT compiled_truth, timeline FROM page_versions WHERE page_id=$1 AND compiled_truth IS NOT NULL ORDER BY id DESC LIMIT 1', [snapshot.page.id]);
  if (!previous) return false;
  const before = fenceRows(previous.compiled_truth, previous.timeline);
  const kept = fenceRows(file.compiled_truth, file.timeline);
  return [...fenceRows(snapshot.page.compiled_truth, snapshot.page.timeline)].some(line => !before.has(line) && !kept.has(line));
}

/** What adopting the edit to `target` admits, or null when the edit is not one-sided and safe. */
async function adoptionIntent(engine: BrainEngine, row: WriteRequest, target: LocalEditTarget, binding: WorktreeBinding) {
  const snapshot = await engine.readPageSnapshot(row.slug, { sourceId: row.source_id });
  const sourcePath = snapshot?.page.source_path;
  if (!snapshot || !sourcePath || snapshot.page.deleted_at || isSegmentedPage(snapshot.page)) return null;
  if (statSync(target.path).size > PAGE_MAX_BYTES) return null;
  const bytes = readFileSync(target.path);
  const text = bytes.toString('utf8');
  // An edit whose bytes do not decode losslessly would be rewritten by its own adoption, so it keeps the refusal.
  if (!Buffer.from(text, 'utf8').equals(bytes)) return null;
  const commit = await headCommit(target.root);
  // A checkout whose HEAD git cannot read keeps the refusal; only a brain with no repository has no HEAD to ask.
  if (!commit && insideGitCheckout(binding.local_path!)) return null;
  const head = commit ? await headBlob(target.root, target.path) : undefined;
  if (head === null) return null;
  if (commit && await conflictOrOperation(target.root, target.path)) return null;
  const { prepareRepairPublication, repairScreenConfig } = await import('./file-repair.ts');
  const screen = await repairScreenConfig(engine, row.source_id);
  // A checkout whose HEAD holds the database's copy: only the worktree file moved. A repo-less brain has no HEAD to ask.
  const committed = head ? await blobText(target.root, head) : null;
  if (head && (committed === null || !await fileMatchesSnapshot(engine, row.slug, committed, snapshot, sourcePath, screen.activePack))) return null;
  if (await protectedLocalEdit(engine, row.slug, text, snapshot, screen.activePack)) return null;
  if (await staleEditorSave(engine, row.slug, text, snapshot, screen.activePack)) return null;
  const path = relative(target.root, target.path).split(sep).join('/');
  const publication = await prepareRepairPublication(engine, { sourceId: row.source_id, slug: row.slug, sourcePath, path, root: target.root,
    content: text, snapshot, base: snapshot, ...screen });
  if (publication.status !== 'ready') return null;
  const adopted: AdoptedLocalEdit = { path, blob: gitBlobOid(bytes, head?.length === 64 ? 'sha256' : 'sha1'), replaced_revision: snapshot.revision };
  return { adopted, params: { kind: 'managed_file_repair', slug: row.slug, path, sourcePath, content: text, beforeHash: sha256(bytes),
    resultDigest: publication.digest, ownerEpoch: String(binding.owner_epoch), expected_revision: snapshot.revision, noEmbed: true,
    adoptLocalEdit: { blob: adopted.blob, replaced_revision: adopted.replaced_revision, head: head ?? null, caller: { id: row.id, token: row.execution_token } },
    source_id: row.source_id, request_id: adoptionRequestId(row) } };
}

/**
 * Conflict markers from a merge, stash pop, cherry-pick or rebase are never adopted (`git add` would mark them resolved):
 * true when `path` has unmerged stages or an operation is in progress, or when git cannot tell. Checked at admission and
 * again in the publication transaction, since either can start in between.
 */
export async function conflictOrOperation(root: string, path: string): Promise<boolean> {
  return await unmergedPath(root, path) !== false || (await operationMarkerPaths(root))?.every(marker => !existsSync(marker)) !== true;
}

/** Whether the caller still holds the claim its refusal is being answered under (a cancelled caller adopts nothing). */
async function callerHolds(engine: BrainEngine, caller: WriteRequest): Promise<boolean> {
  return (await engine.executeRaw(`SELECT 1 FROM persistence_requests WHERE id=$1::uuid AND state='running' AND execution_token=$2::uuid`,
    [caller.id, caller.execution_token])).length > 0;
}

/**
 * Publication's recheck (file-repair.ts validate): HEAD still holds the blob the adoption read, so no newer commit is
 * overwritten; or the adopted blob itself (#8755: this adoption's own commit landed before a publication that failed
 * after it, and recovery requeued it).
 */
export async function adoptedHeadHolds(binding: WorktreeBinding, root: string, path: string, head: string | null, blob?: string): Promise<boolean> {
  if (head === null) return !insideGitCheckout(binding.local_path!);
  const current = await headBlob(root, path);
  return current === head || (blob !== undefined && current === blob);
}

/**
 * #8755: the claim an adoption is made under (`adoptLocalEdit.caller`) still holds, checked as the adoption prepares: an
 * adoption whose caller is gone (cancelled, finished, or reclaimed after a crash between admission and settling)
 * publishes nothing. In the publication transaction (`lock`) the caller row is held FOR SHARE, so a cancel waits until it ends.
 */
export async function assertAdoptionCaller(engine: BrainEngine, row: WriteRequest, caller: { id?: unknown; token?: unknown } | undefined, lock = false): Promise<void> {
  if (!caller) return;
  const [held] = typeof caller.id === 'string' && typeof caller.token === 'string' ? await engine.executeRaw(
    `SELECT 1 FROM persistence_requests WHERE id=$1::uuid AND state='running' AND execution_token=$2::uuid${lock ? ' FOR SHARE' : ''}`, [caller.id, caller.token]) : [];
  if (held) return;
  throw opError('write_claim_lost', 'The write this local edit adoption was made for no longer waits on it.',
    `Adoption request ${row.request_id} in source ${row.source_id} belongs to a write whose claim ended (it was cancelled, finished, or reclaimed after its process stopped), so the local edit was not adopted and nothing was written.`);
}

/**
 * #8824: the commit of this adoption when HEAD already holds it: the newest commit on the path is `gbrain: adopt local edit
 * to <path>` carrying this adoption's `gbrain-adopted:` trailer and commit-ledger line, its parent held the pre-adoption
 * blob, and HEAD holds the adopted blob. The ledger's commit line is best-effort (written after `git commit`), so the
 * intent line written before it also proves the commit when its `head_before` is the commit's parent and its message
 * digest is the commit's. Null otherwise, on a repo-less brain, or when Git or the ledger cannot be read.
 * A replay that finds it publishes whatever became of its caller (the commit is durable), and its receipt names it.
 */
export async function landedAdoptionCommit(root: string, target: string, adopted: { path: string; blob: string; replaced_revision: string; head: string | null }): Promise<string | null> {
  if (adopted.head === null || await headBlob(root, target) !== adopted.blob) return null;
  const commit = await landedCommit(root, null, target);
  if (!commit || await blobAt(root, `${commit}^`, target) !== adopted.head) return null;
  const note = localEditAdoptionCommit(adopted.path, adopted.blob, adopted.replaced_revision);
  const message = await commitMessage(root, commit);
  const lines = message?.split('\n') ?? [];
  if (lines[0] !== note.subject || !note.trailers?.every(trailer => lines.includes(trailer))) return null;
  const [trailer] = adoptedBy(note.trailers);
  const location = ledgerLocation(root);
  let records: ReturnType<typeof readLedger>;
  try { records = location ? readLedger(location.common) : []; } catch { return null; }
  if (records.some(record => record.e === 'commit' && record.sha === commit && record.adopted?.includes(trailer!))) return commit;
  const parent = await commitParent(root, commit), digest = messageDigest(message!);
  return parent && records.some(record => record.e === 'intent' && record.head_before === parent && record.msg_sha256 === digest) ? commit : null;
}

/** #8824/#8767: `landedAdoptionCommit` for an adoption request `row` (any other request answers null), read on `binding`'s checkout. */
export async function adoptionCommitLanded(engine: BrainEngine, row: WriteRequest, binding?: WorktreeBinding | null): Promise<string | null> {
  const intent = row.intent as { kind?: unknown; path?: unknown; adoptLocalEdit?: { blob?: unknown; replaced_revision?: unknown; head?: unknown } } | null;
  const adopted = intent?.adoptLocalEdit;
  if (intent?.kind !== 'managed_file_repair' || typeof intent.path !== 'string' || typeof adopted?.blob !== 'string'
    || typeof adopted.replaced_revision !== 'string' || typeof adopted.head !== 'string') return null;
  const bound = binding === undefined ? await getWorktreeBinding(engine, row.source_id) : binding;
  if (!bound?.local_path) return null;
  const root = join(bound.local_path, bound.relative_path);
  return landedAdoptionCommit(root, join(root, intent.path), { path: intent.path, blob: adopted.blob, replaced_revision: adopted.replaced_revision, head: adopted.head });
}

/**
 * #8869: `adoptionCommitLanded` with the HEAD it was read at, for `recoverPublication` to read under the worktree lock
 * before its transaction, so Git history and the whole commit ledger are never read under the recovery's row locks. Null
 * for any other request.
 */
export async function adoptionRecoveryEvidence(engine: BrainEngine, row: WriteRequest, binding: WorktreeBinding): Promise<{ root: string; head: string | null; landed: string | null } | null> {
  if (!binding.local_path || !(row.intent as { adoptLocalEdit?: unknown } | null)?.adoptLocalEdit) return null;
  const root = join(binding.local_path, binding.relative_path);
  const head = await headCommit(root);
  return { root, head, landed: await adoptionCommitLanded(engine, row, binding) };
}

/** Claims, prepares and publishes the admitted adoption, retrying while another owner task holds the worktree lock. */
async function publishAdoption(engine: BrainEngine, caller: WriteRequest, admitted: WriteRequest, path: string): Promise<WriteRequest> {
  const { finishUnpublishedFailure, publishMutation } = await import('./coordinator.ts');
  const { prepareManagedFileRepairMutation } = await import('./file-repair.ts');
  const deadline = Date.now() + LOCK_RETRY_MS;
  let row = admitted;
  for (;;) {
    if (!await callerHolds(engine, caller)) return (await getWriteRequestById(engine, row.id))!;
    const [claimed] = await engine.transaction(async tx => {
      await declarePersistenceProtocol(tx);
      return tx.executeRaw<WriteRequest>(`UPDATE persistence_requests SET state='running',execution_token=$2::uuid,
        claim_expires_at=now()+interval '60 seconds',updated_at=now(),blocked_reason=NULL,
        claim_phase=jsonb_build_object('token',$2::text,'owner',$3::text::jsonb,'claimed_at',to_jsonb(now())) WHERE id=$1::uuid AND state='queued' RETURNING *`, [row.id, randomUUID(), JSON.stringify(claimOwner())]);
    });
    if (!claimed) return (await getWriteRequestById(engine, row.id))!;
    try {
      const prepared = await prepareManagedFileRepairMutation(engine, claimed, { engine: engine.kind } as GBrainConfig);
      await localEditAdoptionSeams.beforePublish?.(path);
      row = await publishMutation(engine, claimed, prepared);
    } catch (error) { row = await finishUnpublishedFailure(engine, claimed, error, 'preparation'); }
    // #8755: any release is retried, a publication recovery requeued after the adoption's commit landed included.
    if (isTerminal(row) || Date.now() > deadline || row.state !== 'queued') return row;
    await new Promise(resolve => setTimeout(resolve, 100));
  }
}

/**
 * An adoption `publishAdoption` left unfinished (still blocked on the worktree lock, or claimed by the resident consumer
 * before its publication started) is cancelled, so a caller that keeps its refusal never has its local edit adopted later.
 * #8755: one whose publication another task already started (or a recovery record holds) cannot be cancelled; it is
 * waited on for PUBLISHING_WAIT_MS more, so it does not commit after its caller was refused.
 */
async function settleAdoption(engine: BrainEngine, row: WriteRequest): Promise<WriteRequest> {
  if (isTerminal(row)) return row;
  const { cancelWriteRequest } = await import('./control.ts');
  const deadline = Date.now() + LOCK_RETRY_MS;
  for (;;) {
    // #8824: a requeued adoption whose commit already landed is left for the consumer, which publishes it naming that
    // commit; cancelling it would orphan the commit.
    const latest = (await getWriteRequestById(engine, row.id)) ?? row;
    if (latest.state === 'queued' && await adoptionCommitLanded(engine, latest)) return latest;
    const current = await cancelWriteRequest(engine, requestPrincipal(row), row.request_id) ?? row;
    if (isTerminal(current)) return current;
    const publishing = current.publication_started || current.recovery != null;
    if (Date.now() > deadline + (publishing ? PUBLISHING_WAIT_MS : 0)) return current;
    await new Promise(resolve => setTimeout(resolve, 100));
  }
}

/**
 * The owner's answer to a drift refusal of `row` (coordinator.ts finishUnpublishedFailure): `released` once the local edit
 * is adopted and the write queued to prepare again, `error` when the adoption found the file changed under it (the
 * write ends with that refusal), null when the write keeps its own refusal.
 */
export async function adoptLocalEdit(engine: BrainEngine, row: WriteRequest, error: unknown): Promise<{ released: WriteRequest } | { claimLost: WriteRequest } | { error: OperationError } | null> {
  const target = (error as { localEdit?: LocalEditTarget } | null)?.localEdit;
  if (!target || !(error instanceof OperationError) || error.code !== 'source_changed' || error.detail !== 'file_database_drift' || error.reason
    || !ADOPTING_OPERATIONS.includes(row.operation) || (row.target_kind ?? 'page') !== 'page' || !row.worktree_id || row.intent?.adopted_local_edit
    || publicationGroupKey(row) !== null || !await adoptLocalEditsOn(engine, row.source_id)) return null;
  const binding = await getWorktreeBinding(engine, row.source_id);
  if (!binding?.local_path) return null;
  let admission: Awaited<ReturnType<typeof adoptionIntent>>;
  let admitted: WriteRequest | null;
  try {
    if (!await settled(target.path, await quietMs(engine)) || !await callerHolds(engine, row)) return null;
    admission = await adoptionIntent(engine, row, target, binding);
    if (!admission) return null;
    const params = admission.params;
    const ctx = { engine, sourceId: row.source_id, remote: false, dryRun: false, config: { engine: engine.kind } as GBrainConfig,
      logger: { info() {}, warn() {}, error() {} } } as OperationContext;
    admitted = await withRegisteredLocalWriter(engine, 'cli', async writer => {
      if (await getWriteRequest(engine, writer.principal, params.request_id)) return null;
      const { preparePageAdmission } = await import('./page-mutations.ts');
      const prepared = await preparePageAdmission(ctx, { operation: 'put_page', params, managedFileImport: true });
      return prepared.prior ? null : admitWrite(engine, prepared.admission);
    });
  } catch (failure) { logAdoption(row, 'admission_failed', failure); return null; }
  if (!admitted) return null;
  const done = await settleAdoption(engine, await publishAdoption(engine, row, admitted, target.path));
  if (done.state === 'committed') {
    // #8755: the release is fenced on the caller's token; a claim lost meanwhile is reported as lost, never as released.
    const kept = await engine.transaction(async tx => {
      await declarePersistenceProtocol(tx);
      const [held] = await tx.executeRaw(`UPDATE persistence_requests SET intent=intent||$3::text::jsonb WHERE id=$1::uuid AND execution_token=$2::uuid AND state='running' RETURNING id`,
        [row.id, row.execution_token, JSON.stringify({ adopted_local_edit: admission.adopted })]);
      if (held) await releaseUnpublishedClaim(tx, row, 'local_edit_adopted');
      return !!held;
    });
    const current = (await getWriteRequestById(engine, row.id))!;
    return kept ? { released: current } : { claimLost: current };
  }
  if (done.error_code === 'source_changed' && (done.error_detail as { origin?: string } | null)?.origin === 'raw_file_changed') {
    return { error: new OperationError('source_changed', done.error_message ?? 'The canonical file changed after preparation.',
      `The canonical file of ${row.slug} in source ${row.source_id} changed again while gbrain adopted its local edit, so nothing was written. Read the file, then submit the write again with a new request_id.`) };
  }
  return null;
}

/**
 * The adoption's Git commit, made in its publication transaction before the row commits (file-repair.ts afterEffects):
 * only the adopted file, with the adoption's note, on a Git-durable checkout. A strict source's door already committed
 * it; a repo-less brain has nothing to commit. A commit that fails rolls the adoption back.
 */
export async function commitAdoptedLocalEdit(tx: BrainEngine, sourceId: string, binding: WorktreeBinding, path: string, note: GitCommitNote, outcome: Record<string, unknown>): Promise<void> {
  const root = binding.local_path!;
  if (await sourceCanonicalGit(tx, sourceId) || !await headCommit(root) || !(await gitDurabilityPolicy(binding, root)).durable) return;
  const rel = relative(root, path).split(sep).join('/');
  const result = (await commitGitTargets(root, [rel], undefined, new Map([[rel, note]]))).get(rel);
  if (result instanceof OperationError) throw result;
  if (result?.git === 'committed') Object.assign(outcome.persistence as object, { git_state: 'committed', git_commit: await headCommit(root) });
  // #8755: a replay after the commit landed (validate accepted HEAD holding the adopted blob) names that commit.
  else if (result?.git === 'unchanged') {
    const landed = await landedCommit(root, null, path);
    if (landed) Object.assign(outcome.persistence as object, { git_state: 'committed', git_commit: landed, landed_before_row: true });
  }
}

/** A write prepared again after its local edit was adopted names the adoption on its receipt (`adopted`). */
export function withAdoptedLocalEdit(row: WriteRequest, prepared: PreparedMutation): PreparedMutation {
  const adopted = row.intent?.adopted_local_edit as AdoptedLocalEdit | undefined;
  if (!adopted) return prepared;
  const apply = prepared.apply.bind(prepared);
  prepared.apply = async (tx, preimage) => ({ ...await apply(tx, preimage) as Record<string, unknown>, adopted });
  return prepared;
}