Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #5988 `managed_file_repair`: the owner-internal intent `gbrain repair
* frontmatter --apply` publishes on a managed brain. One coordinated write
* replaces a canonical file with the exact bytes the operator approved and
* imports them through the same screen, preparation and canonical projections
* a managed sync import uses, in the same publication: a held new file gets
* its page, a held modified file updates its page, a held renamed file moves
* its page (same id) through `renameFrom`, and the path's hold clears in the
* publishing transaction. Every file write queues the Git target effect a
* page write queues.
*
* Bindings: the file write is conditional on the sha256 the preview read
* (`beforeHash`; anything else is `changed_since_preview` and nothing is
* written), the import on the page revision the preview read, and the whole
* publication on the canonical result digest the preview showed (file bytes
* plus resulting page fields). The `file_database_drift` guard ordinary
* `put_page` applies does not run here: this intent replaces divergent bytes
* only under that hash binding. A repaired file whose import would need a
* canonical overlay (retained tags, a withdrawal, sanitization) is refused,
* never written with the overlay bypassed.
*
* A fence repair (`gbrain repair fences`) carries its `FenceRepairReceipt` in
* the intent (`fenceRepair`): the preparer refuses a malformed receipt or one
* whose before/after sha256 are not the previewed and the written bytes, the
* receipt rides the publication outcome as `fence_repair`, the file's Git
* commit takes `fenceRepairCommitSubject` with the `gbrain-repair:` trailer,
* and every refusal routes to `gbrain repair fences` instead of
* `gbrain repair frontmatter`. #6377: a slug-conflict repair (`gbrain repair
* content`, the `slug-conflicts` kind) rides the same way with its
* `ContentRepairReceipt` (`contentRepair`), outcome field `content_repair`,
* subject `gbrain: repair frontmatter slug in <path>` and trailer
* `gbrain-repair: frontmatter_slug_conflict <tier> <confidence>`; its
* refusals route to `gbrain repair content`. #6696 C8: an intent carrying
* `holdObservedAt` (the slug-conflict `import` of unchanged held bytes)
* clears the hold only while it is that observation, so a hold a sync wrote
* after the repair read it stays.
*
* Trusted local CLI only: admission refuses remote and delegated callers, the
* `put_page` reserved-field gate refuses the kind from MCP, and the preparer
* refuses any request whose authority is remote. Every path is confined to
* the source root and walked component by component with `lstat`, so a
* symlinked directory or file is never written through.
*/
import { existsSync, lstatSync, readFileSync } from 'node:fs';
import { basename, isAbsolute, join, resolve, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import type { ParsedPage } from '../import-file.ts';
import { importFromContent } from '../import-file.ts';
import { ownerGateInput, ownerImportTrust, ownerSourceGateInput } from '../trust/channel.ts';
import { withoutSafetyAssessments } from './reconcile-safety.ts';
import { ContentSanityBlockError } from '../content-sanity.ts';
import { loadImportSanityConfig, type ContentRefusal, type ImportSanityConfig } from '../import-screen.ts';
import { loadActivePackForEngine } from '../schema-pack/engine-resolution.ts';
import { comparableFrontmatter, parseMarkdown, resolveParsedSubtype, type ParseOpts } from '../markdown.ts';
import { isWriteTargetContained } from '../path-confine.ts';
import { OperationError, opError, type OperationContext } from '../ops/contract.ts';
import { readFix, trustedCliRequired } from '../ops/op-fix.ts';
import type { Action } from '../agent-output.ts';
import { assertPageRevision, type PageSnapshot } from '../page-state/types.ts';
import { sealPageTextProjection } from '../page-state/projections.ts';
import { currentSubmissionAuthority } from '../minions/submission-authority.ts';
import { VERSION } from '../../version.ts';
import { parseFenceRepairReceipt, type FenceRepairReceipt } from '../fence-repair/receipt.ts';
import { parseContentRepairReceipt, type ContentRepairReceipt } from '../content-repair/receipt.ts';
import { prepareCanonicalProjections } from './canonical-projections.ts';
import { digest, sha256 } from './digest.ts';
import { currentVerifiedLocalWriter, hostIdFor } from './identity.ts';
import { getWorktreeBinding } from './ownership.ts';
import { checkOwner, ownerUnavailableError } from './owner-refusal.ts';
import { loadRepairBusySet, repairBusy, repairBusyError } from './repair-busy.ts';
import { submitPageMutation } from './page-mutations.ts';
import { clearGitHold, recordSyncImportProvenance, syncDiskProvenance, syncImportParserFor } from './sync-holds.ts';
import { screenSyncImport } from './sync-prepare.ts';
import type { SyncRename } from './sync-discovery.ts';
import type { PreparedContentImport } from './prepared-import.ts';
import type { PreparedMutation } from './coordinator.ts';
import { contentRepairCommit, fenceRepairCommit, localEditAdoptionCommit } from './effect-model.ts';
import { ADOPTED_CHANGE_REASON, adoptedHeadHolds, assertAdoptionCaller, commitAdoptedLocalEdit, conflictOrOperation, landedAdoptionCommit } from './local-edit-adoption.ts';
import { recordSlugLineAlias } from '../page-state/rename-alias.ts';
import type { WriteRequest } from './model.ts';
import { bindOrigin } from './origin-guard.ts';
export interface ManagedFileRepairIntent extends Record<string, unknown> {
kind: 'managed_file_repair';
slug: string;
/** Source-root-relative file path (the hold key). */
path: string;
/** The page origin the file maps to. */
sourcePath: string;
/** The exact repaired file, written byte for byte (UTF-8). */
content: string;
/** sha256 of the file bytes the preview read. */
beforeHash: string;
/** Digest of the canonical page result the preview showed. */
resultDigest: string;
ownerEpoch: string;
expected_revision?: string;
/** A held renamed file: the page it moves, bound to the revision the preview read. */
renameFrom?: SyncRename;
noEmbed: boolean;
/** A fence repair's receipt (location and hashes only). */
fenceRepair?: FenceRepairReceipt;
/** #6377 a slug-conflict repair's receipt (codes and hashes only). */
contentRepair?: ContentRepairReceipt;
/** #6696 C8: the hold observation the repair read; the publication clears the path's hold only while it is that observation (a newer hold stays). */
holdObservedAt?: string;
/** GST-1601: an adopted one-sided local edit (local-edit-adoption.ts): the worktree blob and the revision it replaces. */
adoptLocalEdit?: { blob: string; replaced_revision: string; head: string | null; caller?: { id: string; token: string | null } };
}
/** The repair command a refusal names (D6 router): a fence repair's, the content repair's, or the frontmatter repair's. */
export type FileRepairKind = 'frontmatter' | 'fences' | 'content';
const WORK: Record<FileRepairKind, string> = { frontmatter: 'frontmatter', fences: 'fence', content: 'slug-conflict' };
const ownerStatusFix = (sourceId: string): Action => readFix(`Shows source ${sourceId}'s canonical owner and its state, read-only.`,
{ argv: ['gbrain', 'sources', 'writer', 'status', '--source', sourceId, '--json'] });
const previewFix = (sourceId: string, kind: FileRepairKind): Action => ({ argv: ['gbrain', 'repair', kind, '--source', sourceId], consent: [], actor: 'agent',
requires_exclusive: false, why: `Previews the ${WORK[kind]} repair of source ${sourceId} again from the files as they are now; nothing is written.` });
/**
* #6865: a stray slug-line removal whose receipt records the declared alias (the sync-time `absent_page` heal) publishes
* only while that slug still names no page, no alias of another page and no file at its path: one written since the heal
* read the source refuses the write, and the next run judges the file again.
*/
async function assertDeclaredSlugAbsent(tx: BrainEngine, sourceId: string, root: string, p: { path: string; sourcePath: string }, alias: string, slug: string, kind: FileRepairKind) {
const named = await tx.readPageSnapshot(alias, { sourceId, resolveAlias: true });
if (named && named.page.slug !== slug) throw changedSincePreview(sourceId, p.path, `its slug: line now names page ${named.page.slug}`, kind);
const prefix = p.sourcePath.endsWith(p.path) ? p.sourcePath.slice(0, p.sourcePath.length - p.path.length) : '';
const rel = prefix && alias.startsWith(prefix) ? alias.slice(prefix.length) : alias;
const file = ['.md', '.mdx'].map(ext => rel + ext).find(candidate => candidate !== p.path && existsSync(join(root, candidate)));
if (file) throw changedSincePreview(sourceId, p.path, `its slug: line now names the file ${file}`, kind);
}
function changedSincePreview(sourceId: string, path: string, why: string, kind: FileRepairKind) {
return opError('changed_since_preview', `${path} changed since its repair was previewed: ${why}.`,
`Nothing was written for ${path}. Preview again with gbrain repair ${kind} --source ${sourceId}, review the new proposal, and approve its new hash.`,
{ fix: previewFix(sourceId, kind) });
}
/**
* The well-formed fence repair receipt of a repair request, or undefined for
* a frontmatter repair. Refuses (`invalid_params`, nothing written) a
* malformed receipt or one whose hashes are not the previewed bytes
* (`beforeHash`) and the bytes it writes (`content`).
*/
function checkedFenceRepair(input: { fenceRepair?: unknown; beforeHash: string; content: string; path: string }, sourceId: string): FenceRepairReceipt | undefined {
if (input.fenceRepair === undefined) return undefined;
const refuse = (why: string): never => { throw opError('invalid_params', `The fence repair receipt for ${input.path} ${why}, so nothing was written.`,
`gbrain repair fences builds this receipt from the bytes it previewed and writes; this one does not describe them. Preview again with gbrain repair fences --source ${sourceId} and apply its new plan; if the apply refuses the same way, tell the user and include gbrain doctor --json.`,
{ fix: previewFix(sourceId, 'fences') }); };
const receipt = parseFenceRepairReceipt(input.fenceRepair);
if (!receipt) return refuse('is malformed');
if (receipt.before_sha256 !== input.beforeHash) return refuse('does not name the previewed file bytes');
if (receipt.after_sha256 !== sha256(Buffer.from(input.content, 'utf8'))) return refuse('does not name the repaired file bytes');
return receipt;
}
/** #6377: the slug-conflict receipt of a repair request, checked the same way; undefined when the request carries none. */
function checkedContentRepair(input: { contentRepair?: unknown; beforeHash: string; content: string; path: string }, sourceId: string): ContentRepairReceipt | undefined {
if (input.contentRepair === undefined) return undefined;
const refuse = (why: string): never => { throw opError('invalid_params', `The content repair receipt for ${input.path} ${why}, so nothing was written.`,
`gbrain repair content builds this receipt from the bytes it previewed and writes; this one does not describe them. Preview again with gbrain repair content --source ${sourceId} and apply its new plan; if the apply refuses the same way, tell the user and include gbrain doctor --json.`,
{ fix: previewFix(sourceId, 'content') }); };
const receipt = parseContentRepairReceipt(input.contentRepair);
if (!receipt) return refuse('is malformed');
if (receipt.before_sha256 !== input.beforeHash) return refuse('does not name the previewed file bytes');
if (receipt.after_sha256 !== sha256(Buffer.from(input.content, 'utf8'))) return refuse('does not name the repaired file bytes');
return receipt;
}
/** Which repair command a request belongs to, from the receipt it carries. */
function repairKindOf(input: { fenceRepair?: unknown; contentRepair?: unknown }): FileRepairKind {
return input.fenceRepair !== undefined ? 'fences' : input.contentRepair !== undefined ? 'content' : 'frontmatter';
}
/**
* The absolute target of a source-relative repair path. Refuses an absolute
* or climbing path, a target outside the root, and any symlink on the way
* (each component below the root is `lstat`ed); the target must be a file.
*/
export function confinedRepairTarget(root: string, path: string, sourceId: string, kind: FileRepairKind = 'frontmatter'): string {
const refuse = (why: string): never => { throw opError('source_changed', `The repair target ${JSON.stringify(path)} ${why}, so nothing was written.`,
`gbrain repair ${kind} writes only regular files inside source ${sourceId}'s root, never through a symlink. Replace the link with the real file (or leave it out), then preview again.`,
{ fix: ownerStatusFix(sourceId) }); };
if (!path || path.includes('\0') || isAbsolute(path) || path.split(/[\\/]/).some(part => part === '..' || part === '')) refuse('is not a confined source-relative path');
const target = resolve(root, path);
if (!isWriteTargetContained(target, root)) refuse('resolves outside the source root');
let current = resolve(root);
for (const part of path.split(/[\\/]/)) {
current = join(current, part);
let stat;
try { stat = lstatSync(current); } catch { return refuse('does not exist'); }
if (stat.isSymbolicLink()) refuse(`is or sits under a symlink (${current.slice(resolve(root).length + 1).split(sep).join('/')})`);
}
if (!lstatSync(target).isFile()) refuse('is not a regular file');
return target;
}
/** sha256 of the file as it is now (hex). */
export function fileSha256(path: string): string {
return sha256(readFileSync(path));
}
/** The canonical page fields a publication stores; what the preview hash binds besides the bytes. The gate's markers are re-derived from the bytes, so they are not bound. */
export function canonicalRepairFields(page: Pick<ParsedPage, 'type' | 'title' | 'compiled_truth' | 'timeline' | 'frontmatter'>, tags: string[]) {
return { type: page.type, title: page.title, body: page.compiled_truth, timeline: page.timeline ?? '', frontmatter: comparableFrontmatter(withoutSafetyAssessments(page.frontmatter)), tags: [...new Set(tags)].sort() };
}
export interface RepairPublicationInput {
sourceId: string; slug: string; sourcePath: string; path: string; root: string;
/** The repaired file as written (a BOM, if any, is stripped for the import as sync strips it). */
content: string;
snapshot: PageSnapshot | null;
/** The page the import is prepared against: the rename source for a renamed file, else `snapshot`. */
base: PageSnapshot | null;
activePack?: ParseOpts['activePack'];
sanity?: ImportSanityConfig;
}
export type RepairPublication =
| { status: 'refused'; refusal: ContentRefusal }
/** Importing these bytes would store something other than the file says (retained tags, a withdrawal, sanitization); `noop`: the page already holds that result. */
| { status: 'overlay'; noop: boolean }
| { status: 'ready'; ready: PreparedContentImport; digest: string; fields: ReturnType<typeof canonicalRepairFields>; renamedType?: string };
/**
* What publishing `content` would store, computed exactly as a managed sync
* import prepares it, without writing anything. Shared by the preview (whose
* hash binds `digest`) and the preparer (which refuses a different result).
*/
export async function prepareRepairPublication(engine: BrainEngine, input: RepairPublicationInput): Promise<RepairPublication> {
const content = input.content.replace(/^\uFEFF/, '');
const renamed = !!input.base && input.base.page.slug !== input.slug;
const { screen, parsedInput } = screenSyncImport({ content, rawHash: sha256(content), lineEndingOnly: false, slug: input.slug, sourcePath: input.sourcePath,
path: input.path, root: input.root, snapshot: input.snapshot, base: input.base, renamed, activePack: input.activePack, ...(input.sanity ? { sanity: input.sanity } : {}) });
if (screen.status === 'refused') return { status: 'refused', refusal: screen.refusal };
let prepared: PreparedContentImport | undefined;
let result;
try {
result = await importFromContent(engine, renamed ? input.base!.page.slug : input.slug, content, { sourceId: input.sourceId, noEmbed: true, remote: false, preserveGateMarkers: true,
writeGate: await ownerSourceGateInput(engine, input.sourceId, parsedInput.frontmatter, input.sourcePath),
activePack: input.activePack, filename: basename(input.sourcePath).replace(/\.mdx?$/i, ''), sourcePath: input.sourcePath, allowEmptyOverwrite: true,
prepare: async value => { prepared = value; return value.result; } });
} catch (error) {
if (error instanceof ContentSanityBlockError) return { status: 'refused', refusal: { code: 'content_rejected', message: error.message } };
if (error instanceof OperationError && error.code === 'write_gate_rejected') return { status: 'refused', refusal: { code: 'write_gate_rejected', message: error.message } };
throw error;
}
if (!prepared) return { status: 'refused', refusal: result.refusal ?? { code: 'invalid_frontmatter', reason: 'yaml_parse', message: result.error ?? 'The file could not be prepared.' } };
const parsed = parseMarkdown(content, `${input.slug}.md`, { activePack: input.activePack });
resolveParsedSubtype(parsed, input.base?.page);
const renamedType = renamed && parsedInput.typeExplicit !== true ? parsedInput.type : undefined;
const tags = [...new Set([...(input.base?.tags ?? []), ...prepared.parsedPage.tags])].sort();
const fields = canonicalRepairFields({ ...prepared.parsedPage, type: renamedType ?? prepared.parsedPage.type }, tags);
if (digest(canonicalRepairFields(parsed, parsed.tags)) !== digest(fields)) return { status: 'overlay', noop: prepared.noop };
return { status: 'ready', ready: prepared, digest: digest(fields), fields, ...(renamedType ? { renamedType } : {}) };
}
/** The schema pack and content-sanity settings a repair preview and its publication both read, so their results agree. */
export async function repairScreenConfig(engine: BrainEngine, sourceId: string): Promise<Pick<RepairPublicationInput, 'activePack' | 'sanity'> & { packIdentity: string | null }> {
const pack = await loadActivePackForEngine(engine, { remote: false, sourceId }).catch(() => null);
return { ...(pack?.manifest ? { activePack: pack.manifest } : {}), sanity: await loadImportSanityConfig(engine), packIdentity: pack?.identity ?? null };
}
function assertTrustedRepairCaller(ctx: Pick<OperationContext, 'remote'>): void {
const caller = currentSubmissionAuthority();
if (ctx.remote !== false || (caller && caller.kind !== 'application') || currentVerifiedLocalWriter()?.remote) {
throw trustedCliRequired('A managed file repair requires the trusted local CLI.');
}
}
/**
* The active local owner's canonical root of a source, or an `owner_unavailable` refusal whose reason names the
* condition (owner-refusal.ts). `remote` (default true) keeps the local identity path out of the text.
*/
export async function managedRepairRoot(engine: BrainEngine, sourceId: string, kind: FileRepairKind = 'frontmatter', opts: { remote?: boolean } = {}): Promise<{ root: string; ownerEpoch: string; incarnation: string }> {
const [source] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [sourceId]);
const binding = await getWorktreeBinding(engine, sourceId);
const hostId = hostIdFor(engine);
const owner = checkOwner(binding, source?.incarnation ?? '', hostId);
if (owner.reason) throw ownerUnavailableError({ sourceId, reason: owner.reason, binding, incarnation: source?.incarnation ?? '', hostId, remote: opts.remote !== false, work: `the ${WORK[kind]} repair` });
return { root: join(owner.binding.local_path, owner.binding.relative_path), ownerEpoch: String(owner.binding.owner_epoch), incarnation: owner.binding.source_incarnation };
}
/**
* Admits and waits for one `managed_file_repair` write. Refuses before
* admission when the caller is not the trusted local CLI, the path is not a
* confined regular file, the file no longer has the previewed bytes, or a
* write in flight or an unfinished sync's frozen manifest names the path or
* page (`sync_in_progress`, #6278: the plan's busy check is repeated here
* because a sync can start while a repair waits on its model call).
*/
export interface ManagedFileRepairInput {
sourceId: string; requestId: string; slug: string; path: string; sourcePath: string; content: string;
beforeHash: string; resultDigest: string; expected_revision?: string; renameFrom?: SyncRename; noEmbed: boolean;
/** Set by `gbrain repair fences`: the write's receipt, and its refusals route there. */
fenceRepair?: FenceRepairReceipt;
/** #6377 set by the `slug-conflicts` kind: the write's receipt, and its refusals route to `gbrain repair content`. */
contentRepair?: ContentRepairReceipt;
/** #6696 C8: clear the hold only while it is this observation. */
holdObservedAt?: string;
}
export async function submitManagedFileRepair(ctx: OperationContext, input: ManagedFileRepairInput): Promise<Record<string, unknown>> {
assertTrustedRepairCaller(ctx);
const kind = repairKindOf(input);
checkedFenceRepair(input, input.sourceId);
checkedContentRepair(input, input.sourceId);
const { root, ownerEpoch, incarnation } = await managedRepairRoot(ctx.engine, input.sourceId, kind, { remote: false });
const target = confinedRepairTarget(root, input.path, input.sourceId, kind);
if (fileSha256(target) !== input.beforeHash) throw changedSincePreview(input.sourceId, input.path, 'the file bytes differ from the previewed hash', kind);
const busy = await loadRepairBusySet(ctx.engine, input.sourceId, incarnation);
if (repairBusy(busy, { path: input.path, sourcePath: input.sourcePath, slug: input.slug }) || (input.renameFrom && repairBusy(busy, { sourcePath: input.renameFrom.sourcePath, slug: input.renameFrom.slug }))) {
throw repairBusyError(busy, input.sourceId, input.path);
}
const { sourceId, requestId, expected_revision, ...rest } = input;
const params: Record<string, unknown> = { ...rest, kind: 'managed_file_repair', ownerEpoch, source_id: sourceId, request_id: requestId,
...(expected_revision ? { expected_revision } : {}) };
return submitPageMutation({ ...ctx, sourceId }, { operation: 'put_page', params, waitMs: 30_000, managedFileImport: true });
}
export async function prepareManagedFileRepairMutation(engine: BrainEngine, row: WriteRequest, _config: GBrainConfig): Promise<PreparedMutation> {
const p = row.intent as ManagedFileRepairIntent | null;
const kind = repairKindOf(p ?? {});
if (row.authority.remote || row.principal_kind !== 'local_cli') throw trustedCliRequired('A managed file repair requires a trusted local CLI writer.');
if (!p || p.kind !== 'managed_file_repair' || typeof p.content !== 'string' || typeof p.path !== 'string' || typeof p.sourcePath !== 'string'
|| typeof p.beforeHash !== 'string' || typeof p.resultDigest !== 'string' || (p.holdObservedAt !== undefined && typeof p.holdObservedAt !== 'string')) {
throw opError('invalid_params', 'The durable file repair intent is incomplete.',
`Repair request ${row.request_id} in source ${row.source_id} has no complete intent, so it published nothing. Preview the repair again: gbrain repair ${kind} --source ${row.source_id}.`,
{ fix: previewFix(row.source_id, kind) });
}
const fenceRepair = checkedFenceRepair(p, row.source_id);
const contentRepair = checkedContentRepair(p, row.source_id);
const adopted = p.adoptLocalEdit;
if (adopted !== undefined && (typeof adopted?.blob !== 'string' || typeof adopted.replaced_revision !== 'string' || (typeof adopted.head !== 'string' && adopted.head !== null) || p.expected_revision !== adopted.replaced_revision)) {
throw opError('invalid_params', 'The local edit adoption intent is incomplete.', `Adoption request ${row.request_id} in source ${row.source_id} names no worktree blob or replaced revision, so it published nothing.`);
}
const binding = await getWorktreeBinding(engine, row.source_id);
if (!row.worktree_id || !binding?.local_path || String(binding.owner_epoch) !== p.ownerEpoch) throw opError('owner_unavailable', 'A managed file repair requires its accepted canonical owner.',
`Source ${row.source_id}'s canonical owner changed or went away after repair request ${row.request_id} was accepted, so it published nothing. Check the owner, then preview the repair again on the host that owns the source.`,
{ fix: ownerStatusFix(row.source_id) });
const root = join(binding.local_path, binding.relative_path);
const adoptNote = adopted ? localEditAdoptionCommit(p.path, adopted.blob, adopted.replaced_revision) : undefined;
const bytes = Buffer.from(p.content, 'utf8');
const fileChanges = sha256(bytes) !== p.beforeHash;
if (adopted && fileChanges) throw opError('invalid_params', 'A local edit adoption may not rewrite the file it adopts.',
`Adoption request ${row.request_id} in source ${row.source_id} would change ${p.path} instead of recording it as it is, so it published nothing.`);
const checkFile = () => {
const target = confinedRepairTarget(root, p.path, row.source_id, kind);
if (fileSha256(target) !== p.beforeHash) throw changedSincePreview(row.source_id, p.path, 'the file bytes differ from the previewed hash', kind);
return target;
};
const target = checkFile();
// #8824: the caller's claim is checked only before the adoption's commit lands; a replay after it publishes that commit.
const adoptionLanded = () => adopted ? landedAdoptionCommit(root, target, { path: p.path, ...adopted }) : Promise.resolve(null);
if (adopted && !await adoptionLanded()) await assertAdoptionCaller(engine, row, adopted.caller);
const source = { sourceId: row.source_id };
const snapshot = await engine.readPageSnapshot(row.slug, { ...source, includeDeleted: true });
assertPageRevision(snapshot, { expectedRevision: p.expected_revision ?? null }); // null: admitted against an absent page; still a revision_conflict if one appeared (#5385)
if ((snapshot?.page.id ?? null) !== row.page_id || (snapshot?.page.source_path != null && snapshot.page.source_path !== p.sourcePath)) {
throw opError('page_identity_changed', 'The repaired path no longer names the previewed page.',
`Page ${row.slug} in source ${row.source_id} was replaced, removed, or now maps to a different file than ${p.sourcePath}, so repair request ${row.request_id} published nothing. Preview the repair again.`,
{ fix: previewFix(row.source_id, kind) });
}
const moved = p.renameFrom && p.renameFrom.slug !== row.slug ? p.renameFrom : undefined;
const assertRenameSource = async (tx: BrainEngine) => {
if (!moved) return null;
const previous = await tx.readPageSnapshot(moved.slug, { ...source, includeDeleted: true });
if (previous?.page.id !== moved.pageId || previous.revision !== moved.revision || previous.page.deleted_at != null) {
throw changedSincePreview(row.source_id, p.path, `page ${moved.slug}, which it was renamed from, changed or was deleted`, kind);
}
return previous;
};
const base = moved ? await assertRenameSource(engine) : snapshot;
const screenConfig = await repairScreenConfig(engine, row.source_id);
const publication = await prepareRepairPublication(engine, { sourceId: row.source_id, slug: row.slug, sourcePath: p.sourcePath, path: p.path, root,
content: p.content, snapshot, base, ...screenConfig });
if (publication.status === 'refused') throw changedSincePreview(row.source_id, p.path, `the repaired content now refuses to import (${publication.refusal.code})`, kind);
if (publication.status === 'overlay') throw changedSincePreview(row.source_id, p.path, 'importing it would now store a canonical overlay instead of the file as written', kind);
if (publication.digest !== p.resultDigest) throw changedSincePreview(row.source_id, p.path, 'the page it would publish differs from the previewed result', kind);
const ready = publication.ready;
const project = await prepareCanonicalProjections(engine, ready.parsedPage, row.slug, row.source_id, base, 'file');
const importContent = p.content.replace(/^\uFEFF/, '');
const writeGate = await ownerGateInput(engine, row, parseMarkdown(importContent, `${row.slug}.md`, { activePack: screenConfig.activePack }).frontmatter, p.sourcePath);
const importOptions = { ...source, noEmbed: true, remote: false, preserveGateMarkers: true, writeGate, activePack: screenConfig.activePack, filename: basename(p.sourcePath).replace(/\.mdx?$/i, ''), sourcePath: p.sourcePath, allowEmptyOverwrite: true };
// afterCommit follows the import that published (a page stored in segments chunks what its publication left unsealed).
let published = ready;
return { observedRevision: snapshot?.revision ?? null, noop: ready.noop && !fileChanges && !moved, contentUnchanged: ready.noop && !fileChanges && !moved,
trust: await ownerImportTrust(engine, row, ready.parsedPage.frontmatter, p.sourcePath), deferEmbedding: p.noEmbed, ...(moved ? { additionalPageKeys: [{ sourceId: row.source_id, slug: moved.slug }] } : {}),
...(ready.afterCommit || moved ? { afterCommit: async (target: BrainEngine) => { await published.afterCommit?.(target); } } : {}),
...(fileChanges || adopted ? { file: { root, path: target, content: bytes, expectedBeforeHash: p.beforeHash,
...(adoptNote ? { commit: adoptNote }
: fenceRepair ? { commit: fenceRepairCommit(p.path, fenceRepair.classes, fenceRepair.tier) } : contentRepair ? { commit: contentRepairCommit(p.path, contentRepair) } : {}) } } : {}),
...(adoptNote ? { afterEffects: (tx: BrainEngine, outcome: Record<string, unknown>) => commitAdoptedLocalEdit(tx, row.source_id, binding, target, adoptNote, outcome) } : {}),
validate: async tx => {
const current = await getWorktreeBinding(tx, row.source_id);
if (!current || current.worktree_id !== row.worktree_id || String(current.owner_epoch) !== p.ownerEpoch) throw opError('owner_unavailable', 'The repair owner changed.',
`Source ${row.source_id}'s canonical owner changed while repair request ${row.request_id} was prepared, so it published nothing. Check the owner, then preview the repair again.`,
{ fix: ownerStatusFix(row.source_id) });
checkFile();
if (adopted && !await adoptedHeadHolds(binding, root, target, adopted.head, adopted.blob)) throw changedSincePreview(row.source_id, p.path, 'git HEAD moved after its local edit was read', kind);
// #8755: the caller's claim and the index are read again here, where the adoption commits: a cancel or a conflict may come after preparation.
if (adopted && !await adoptionLanded()) await assertAdoptionCaller(tx, row, adopted.caller, true);
if (adopted && adopted.head !== null && await conflictOrOperation(root, target)) throw changedSincePreview(row.source_id, p.path, 'a merge, rebase or conflicted path appeared after its local edit was read', kind);
if (contentRepair?.declared_alias) await assertDeclaredSlugAbsent(tx, row.source_id, root, p, contentRepair.declared_alias, row.slug, kind);
await assertRenameSource(tx);
await ready.validate(tx);
},
apply: async tx => {
let applied = ready;
if (moved) {
if (await tx.updateSlug(moved.slug, row.slug, source) !== 1) throw changedSincePreview(row.source_id, p.path, `page ${moved.slug} could not move to ${row.slug}`, kind);
if (publication.renamedType) await tx.executeRaw('UPDATE pages SET type=$3 WHERE source_id=$1 AND slug=$2', [row.source_id, row.slug, publication.renamedType]);
let movedImport: PreparedContentImport | undefined;
await importFromContent(tx, row.slug, importContent, { ...importOptions, prepare: async value => { movedImport = value; return value.result; } });
if (!movedImport || movedImport.slug !== row.slug) throw changedSincePreview(row.source_id, p.path, `page ${moved.slug} could not be prepared at ${row.slug}`, kind);
await movedImport.validate(tx);
applied = movedImport;
}
published = applied;
const [last] = adopted && snapshot ? await tx.executeRaw<{ id: number | string | null }>('SELECT max(id) AS id FROM page_versions WHERE page_id=$1', [snapshot.page.id]) : [];
const installed = await applied.apply(tx);
if (adopted && snapshot) await tx.executeRaw('UPDATE page_versions SET change_reason=$2 WHERE page_id=$1 AND id>$3', [snapshot.page.id, ADOPTED_CHANGE_REASON, Number(last?.id ?? 0)]);
await bindOrigin(tx, { sourceId: row.source_id, slug: row.slug, sourcePath: p.sourcePath });
// A body stored in segments was sealed by its import's apply when complete (sealSegmentedPage); the inline text seal reads the whole timeline.
if (!applied.noop) { await project(tx); if (!installed?.segmented) await sealPageTextProjection(tx, row.slug, row.source_id); }
const holdCleared = await clearGitHold(tx, { sourceId: row.source_id, incarnation: row.source_incarnation, path: p.path, observedAt: p.holdObservedAt ?? new Date().toISOString() });
if (contentRepair?.declared_alias) await recordSlugLineAlias(tx, row.source_id, contentRepair.declared_alias, row.slug);
// #6712 PR 1: the record names what is on disk now (the approved bytes), the page revision they produced and the parser, so the next discovery prescreens the file.
const page = await tx.readPageSnapshot(row.slug, { ...source, includeDeleted: true });
if (page && page.page.deleted_at == null) await recordSyncImportProvenance(tx, { source_id: row.source_id, incarnation: row.source_incarnation, page_id: Number(page.page.id), origin: p.sourcePath,
raw_sha256: sha256(importContent), gbrain_version: VERSION, revision: page.revision, parser: syncImportParserFor(p.sourcePath, screenConfig.packIdentity), ...syncDiskProvenance(bytes, null) });
return { status: moved ? 'renamed' : applied.noop ? 'skipped' : snapshot ? 'updated' : 'created', slug: row.slug, source_id: row.source_id,
chunks: applied.result.chunks, imported_file: true, file_repaired: fileChanges, hold_cleared: holdCleared, ...(moved ? { renamed_from: moved.slug } : {}),
...(fenceRepair ? { fence_repair: fenceRepair } : {}), ...(contentRepair ? { content_repair: contentRepair } : {}),
...(adopted ? { adopted_local_edit: { path: p.path, blob: adopted.blob, replaced_revision: adopted.replaced_revision } } : {}) };
} };
}