Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
import { dirname, join, relative, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { loadConfig, loadConfigFileOnly, loadConfigWithEngine, type GBrainConfig } from '../config.ts';
import { loadOperatorLiterals } from '../content-sanity-literals.ts';
import { parseMarkdown } from '../markdown.ts';
import { alignWithStored } from './align-stored.ts';
import { parseDataFrontmatter } from '../data-frontmatter.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { REVISION_BACKFILL_PENDING, type PageSnapshot } from '../page-state/types.ts';
import { revisionBackfillExhausted, REVISION_BACKFILL_RESUME_COMMAND } from '../page-state/revision-backfill-schema.ts';
import { isWriteTargetContained, relativeEscapesRoot } from '../path-confine.ts';
import { recordedPathFromFileUri, scannerSlugRootMode, scannerSourcePath } from '../write-through.ts';
import { absentCanonicalPath, findLiveFileClaimants, recordedReconcilePath, type FileClaimTarget } from './file-claims.ts';
import { wholeBodySnapshot } from './segmented-apply.ts';
import { sharedOriginExit } from './sync-origin.ts';
import { originTwinsPreviewArgv } from './origin-twins.ts';
export { fileClaimCandidatesQuery } from './file-claims.ts';
import { hostIdFor } from './identity.ts';
import { isDatabaseOnlyPage, recordsNoFileOrigin, slugDerivedOrigin } from './unbound-pages.ts';
import { isUnboundSourcePage } from './unbound-source.ts';
import { getWorktreeBinding, type WorktreeBinding } from './ownership.ts';
import { digest, gitBlobOid, requireUuid, sha256, stableJson } from './digest.ts';
import { SYNC_ORIGIN_DELETED_OP } from './sync-pass-row.ts';
import { reconcileCanonical, strictReconcileKeys, validateReconcileJson, type ReconcileConflict, type ReconcileDecision } from './reconcile-merge.ts';
import type { ParsedPage } from '../import-file.ts';
import type { AutoDecision } from './reconcile-additive.ts';
import { publishesDatabaseOnly, readCanonicalAsImported } from './page-prepare.ts';
import { isMirrorOnlyPage, staleMirrorPage } from './mirror-read-only.ts';
import { hardenedGitSync } from '../hardened-git.ts';
export interface ReconcilePins {
brain_id: string; source_id: string; source_incarnation: string; slug: string; page_id: number;
worktree_id: string; binding_digest: string; owner_epoch: string; revision: string;
raw_file_hash: string; relative_path: string; policy_digest: string; withdrawals_digest: string; assessment_at: string;
}
export interface ReconcileArtifact {
/** 2 when the preview carries #5974 automatic decisions. */
format_version: 1 | 2; preview_id: string; preconditions: ReconcilePins;
preimages: { file_base64: string; database: PageSnapshot; stored_page: Record<string, unknown> };
decisions: ReconcileDecision[]; conflicts: ReconcileConflict[]; result: ParsedPage; result_digest: string;
status: 'needs_resolution' | 'ready';
auto_decisions?: AutoDecision[];
}
export interface ReconcileState {
binding: WorktreeBinding; root: string; path: string; raw: Buffer; snapshot: PageSnapshot;
/** The path the importer reads the file under (`scannerSourcePath`), for path inference (#6605). */
importPath: string;
storedPage: Record<string, unknown>; file: ParsedPage; pins: ReconcilePins;
/** `slug_derived`: a database-only page matched to the canonical file at its slug path. */
origin: 'recorded' | 'slug_derived';
/** The `source_path` apply records for a `slug_derived` origin. */
originSourcePath: string | null;
}
/**
* Cycle bookkeeping that `cycle.ts` stamps into `sources.config` after every
* successful source cycle. It is not reconcile policy, so it stays out of the
* policy digest: otherwise an autopilot cycle between preview and apply made
* every reconcile preview stale.
*/
const CYCLE_STAMP_KEYS = ['last_source_cycle_at', 'last_full_cycle_at'];
/**
* #7506: the file and environment side of the policy digest, as every consumer on the owner host resolves it: the config
* file, with the content-sanity overrides the environment sets (the import gate's env > file > DB). Any consumer on that
* host may prepare and publish an admitted reconcile, each with its own environment, so the rest of the environment
* (credentials, connection targets, model and gateway choices) stays out: none of it changes what a reconcile writes, and
* a consumer whose environment differed from the previewing process's read every preview stale.
*/
function reconcilePolicyBase(): GBrainConfig | null {
const file = loadConfigFileOnly();
const sanity = loadConfig()?.content_sanity;
return sanity ? { ...(file ?? { engine: 'postgres' }), content_sanity: sanity } : file;
}
export async function reconcilePolicyDigest(engine: BrainEngine, sourceId: string): Promise<string> {
const config = await loadConfigWithEngine(engine, reconcilePolicyBase());
const [row] = await engine.executeRaw<Record<string, unknown>>('SELECT config,contextual_retrieval_mode,trust_frontmatter_overrides FROM sources WHERE id=$1', [sourceId]);
let sourceConfig = row?.config;
if (typeof sourceConfig === 'string') {
try { sourceConfig = JSON.parse(sourceConfig); } catch { /* digest the raw text */ }
}
if (sourceConfig && typeof sourceConfig === 'object' && !Array.isArray(sourceConfig)) {
sourceConfig = Object.fromEntries(Object.entries(sourceConfig).filter(([key]) => !CYCLE_STAMP_KEYS.includes(key)));
}
const source = row ? { ...row, config: sourceConfig } : row;
return digest({ version: 1, config, source, literals: loadOperatorLiterals(), disabled: process.env.GBRAIN_NO_SANITY ?? null });
}
/**
* #6712 wave: the `raw_file_hash` pin of a preview that observed the canonical file absent (`readReconcileState` with
* `fileGone`). No file's sha256 is all zeros, so a file that reappears before apply never matches it.
*/
export const ABSENT_FILE_HASH = '0'.repeat(64);
/** The read options a stored preview implies: its slug-path adoption, and whether it observed the file absent. */
export function reconcileReadOptions(artifact: Pick<ReconcileArtifact, 'preimages' | 'preconditions'>): { adoptSlugPath: boolean; fileGone: boolean } {
return { adoptSlugPath: reconcilePreviewAdopts(artifact), fileGone: artifact.preconditions.raw_file_hash === ABSENT_FILE_HASH };
}
/**
* #6712 wave: where a missing canonical file's deletion stands in Git. `in_head`: still committed at HEAD (deleted only in
* the worktree, staged or not); `gone`: not in HEAD's tree, or the checkout has no commit or no Git; `unknown`: Git
* could not say. Filter-free plumbing only, each call bounded (hardened-git.ts).
*/
export function canonicalDeletionState(root: string, path: string): 'in_head' | 'gone' | 'unknown' {
const limits = { timeoutMs: 10_000, maxBytes: 1024 * 1024 };
const top = hardenedGitSync(root, ['rev-parse', '--show-toplevel'], limits);
if (!top.ok) return insideGitCheckout(root) ? 'unknown' : 'gone';
const head = hardenedGitSync(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], limits);
if (!head.ok) return head.reason === 'exit' && head.status === 1 ? 'gone' : 'unknown';
let repoPath: string;
try { repoPath = relative(realpathSync(top.stdout.toString('utf8').trim()), absentCanonicalPath(path)).split(sep).join('/'); } catch { return 'unknown'; }
if (!repoPath || relativeEscapesRoot(repoPath)) return 'unknown';
const listed = hardenedGitSync(root, ['ls-tree', '-z', '--full-tree', 'HEAD', '--', repoPath], limits);
if (!listed.ok) return 'unknown';
return listed.stdout.toString('utf8').split('\0').some(entry => entry.split('\t')[1] === repoPath) ? 'in_head' : 'gone';
}
/**
* #6712 PR 4b: the deleted side of a held `file_drift` file that is present (design v3.2 §4, classifier row 9). A deleted page
* still at the origin is `tombstone_edited` (the newest one; `pageId` names the held one when it is still there); with no
* page row left, a `deleted` marker at the origin (`sync-origin-deleted`) is `purged_differs`. The result pins what a
* resolution is bound to: the file's bytes, the tombstone's id and revision, the marker's value.
*/
export interface DeletedDriftTarget {
state: 'tombstone_edited' | 'purged_differs';
root: string;
/** Absolute path of the file, and its source-relative spelling. */
path: string;
relative_path: string;
source_path: string;
raw: Buffer;
raw_file_hash: string;
tombstone: { page_id: number; slug: string; revision: string } | null;
marker_digest: string | null;
}
/** Why a held path no longer has a deleted side to resolve; a fresh sync re-classifies it. */
export type DeletedDriftChange = 'file_gone' | 'live_page' | 'no_deletion' | 'deleted_same';
export async function readDeletedDriftTarget(engine: BrainEngine, sourceId: string, input: { path: string; sourcePath: string; pageId?: number | null }):
Promise<DeletedDriftTarget | { changed: DeletedDriftChange }> {
const binding = await getWorktreeBinding(engine, sourceId);
if (!binding?.local_path || binding.owner_host_id !== hostIdFor(engine) || binding.state !== 'active') {
throw new OperationError('owner_unavailable', 'Reconciliation requires the existing active owner on this host.', 'Run repair on the current owner; repair never claims or activates a source.');
}
const root = realpathSync(join(binding.local_path, binding.relative_path));
const path = join(root, ...input.path.split('/'));
if (!isWriteTargetContained(path, root)) throw opError('source_changed', 'The held file is outside its registered source.',
`Nothing changed. ${input.path} resolves outside source '${sourceId}''s checkout (a symlinked directory or a moved checkout); inspect the owner before previewing again.`);
try {
const info = lstatSync(path);
if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) throw opError('source_changed', 'The held file is not an ordinary file; repair does not replace it.',
`Nothing changed. Make ${input.path} in '${sourceId}' a regular file (not a symlink, directory or hard link), then preview again.`);
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { changed: 'file_gone' };
throw error;
}
const raw = readFileSync(path);
const pin = { root, path, relative_path: input.path, source_path: input.sourcePath, raw, raw_file_hash: sha256(raw) };
const claims = await engine.executeRaw<{ id: number; slug: string; deleted: boolean }>(
`SELECT id, slug, deleted_at IS NOT NULL AS deleted FROM pages WHERE source_id=$1 AND source_path=$2 ORDER BY deleted_at DESC NULLS FIRST, id DESC`, [sourceId, input.sourcePath]);
if (claims.some(row => !row.deleted)) return { changed: 'live_page' };
const tombstone = claims.find(row => Number(row.id) === input.pageId) ?? claims[0];
if (tombstone) {
const snapshot = await engine.readPageSnapshot(tombstone.slug, { sourceId, includeDeleted: true });
if (!snapshot || Number(snapshot.page.id) !== Number(tombstone.id) || !snapshot.page.deleted_at) staleReconcile('the deleted page changed during the preview');
return { state: 'tombstone_edited', ...pin, tombstone: { page_id: Number(tombstone.id), slug: tombstone.slug, revision: snapshot.revision }, marker_digest: null };
}
const [marker] = await engine.executeRaw<{ value: { kind?: string; blob_oids?: unknown } | null }>('SELECT completed_keys->0 AS value FROM op_checkpoints WHERE op=$1 AND fingerprint=$2',
[SYNC_ORIGIN_DELETED_OP, `${sourceId}:${binding.source_incarnation}:${input.sourcePath}`]);
if (!marker?.value || marker.value.kind === 'legacy') return { changed: 'no_deletion' };
const held = Array.isArray(marker.value.blob_oids) ? marker.value.blob_oids : [];
if (held.includes(gitBlobOid(raw, 'sha1')) || held.includes(gitBlobOid(raw, 'sha256'))) return { changed: 'deleted_same' };
return { state: 'purged_differs', ...pin, tombstone: null, marker_digest: digest(marker.value) };
}
/** Whether `root` or an ancestor holds a `.git` entry (a checkout Git should answer for). */
function insideGitCheckout(root: string): boolean {
for (let dir = root; ; dir = dirname(dir)) {
if (existsSync(join(dir, '.git'))) return true;
if (dirname(dir) === dir) return false;
}
}
/**
* #6712 wave: the route for a page whose canonical file `rel` (source-relative) is missing, by where its deletion stands
* in Git: still committed at HEAD goes to committing the deletion or `repair ghost-pages`; gone from HEAD goes to
* `repair file-drift`.
*/
export function missingFileRoute(sourceId: string, slug: string, rel: string, state: ReturnType<typeof canonicalDeletionState>): string {
const fileDrift = `gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer database`;
const ghosts = `gbrain repair ghost-pages --source ${sourceId}`;
if (state === 'in_head') return `${rel} is deleted in the worktree but still committed, so this is not file drift: commit the deletion (sync then imports it), or remove the page with ${ghosts}; to keep the page, restore the file from Git (git checkout -- ${rel}) and sync.`;
if (state === 'gone') return `${rel} is gone from the last commit. Preview the resolution with ${fileDrift} (recreates the file from the page) or with --prefer file (soft-deletes the page), then apply the printed command after the user decides.`;
return `Git could not say whether the deletion of ${rel} is committed. If it is (gone from HEAD), preview ${fileDrift} or --prefer file; if it is deleted only in the worktree, commit the deletion or remove the page with ${ghosts}.`;
}
/** The refusal for a canonical file that is gone, routed by where its deletion stands in Git (#6712 wave). */
function missingCanonicalFile(sourceId: string, slug: string, root: string, path: string): OperationError {
const rel = relative(root, path).split(sep).join('/');
return opError('source_changed', 'The recorded canonical file is missing.',
`Nothing changed. The canonical file of ${slug} in '${sourceId}' is missing. ${missingFileRoute(sourceId, slug, rel, canonicalDeletionState(root, path))}`,
{ detail: 'canonical_file_missing' });
}
export function staleReconcile(what: string): never {
throw new OperationError('source_changed', `Reconciliation preview is stale: ${what}.`, 'Generate a fresh preview; submit a corrected intent with a new request ID.');
}
/**
* Refuses when another live page of the source records the reconciled file as its own
* (`findLiveFileClaimants`, file-claims.ts: the paged same-name census, realpath deciding).
* #6517: the refusal names the exit, a soft delete of the page that should not own the file.
*/
async function assertSoleFileClaim(engine: BrainEngine, target: FileClaimTarget): Promise<void> {
const [claimant] = await findLiveFileClaimants(engine, target);
if (claimant) throw opError('source_changed', 'Several pages claim the recorded canonical file.',
`Nothing changed. Pages ${target.slug} and ${claimant.slug} in '${target.sourceId}' both record the same file, so reconcile cannot tell which owns it; decide with the user which page owns the file before reconciling either. `
+ sharedOriginExit(target.sourceId, [target.slug, claimant.slug]) + ' Then preview again.',
// #6948 (B-15): the read-only group listing names the page that keeps the file and the exact command for each other one.
{ detail: 'shared_origin', fix: readFix(`Lists the duplicate-origin group of ${target.slug} and ${claimant.slug} with the page its path names and the command that resolves each other page; writes nothing.`,
{ argv: originTwinsPreviewArgv(target.sourceId) }) });
}
/**
* #6394: the file at a page's slug path that `adoptSlugPath` reconciles it against, or null when the page records a file
* origin, publishes database-only by design (a declared db_only slug, a never-filed derive-phase page), is mirror-only, or
* its slug path cannot be derived inside the source. `root` is the realpath of the source root. Throws
* `slug_path_ambiguous` when several files import as the slug. liveFileDrift reads an origin twin's drift with it.
*/
export async function adoptableSlugOrigin(engine: BrainEngine, sourceId: string, root: string, snapshot: PageSnapshot,
mode: 'git-root' | 'source-root'): Promise<{ path: string; sourcePath: string } | null> {
if (!recordsNoFileOrigin(snapshot.page) || publishesDatabaseOnly(root, snapshot.page.slug, snapshot) || await isMirrorOnlyPage(engine, sourceId, snapshot.page.slug)) return null;
const derived = slugDerivedOrigin(root, snapshot.page.slug, mode);
return derived && isWriteTargetContained(derived.path, root) ? derived : null;
}
/**
* #6394: `adoptSlugPath` lets a live page with no recorded origin and no database-only marker reconcile against the file
* at its slug path (mode-aware, as discovery names it). A page that publishes database-only by design (a declared db_only
* slug, a never-filed derive-phase page) or a mirror-only page never adopts one.
*/
export async function readReconcileState(engine: BrainEngine, sourceId: string, slug: string, assessmentAt = new Date().toISOString(),
opts: { adoptSlugPath?: boolean; fileGone?: boolean } = {}): Promise<ReconcileState> {
const binding = await getWorktreeBinding(engine, sourceId);
if (!binding?.local_path || binding.owner_host_id !== hostIdFor(engine) || binding.state !== 'active') {
throw new OperationError('owner_unavailable', 'Reconciliation requires the existing active owner on this host.', 'Run repair on the current owner; repair never claims or activates a source.');
}
const [brain] = await engine.executeRaw<{ brain_id: string }>('SELECT brain_id FROM persistence_brain WHERE singleton=1');
// Wave B: a page stored in segments is compared and merged as strings up to 24 MiB; a larger one refuses.
const snapshot = await wholeBodySnapshot(engine, await engine.readPageSnapshot(slug, { sourceId, includeDeleted: true }), 'sources reconcile');
if (!snapshot || snapshot.page.deleted_at) throw opError('page_not_found', 'Reconciliation requires an existing live page; use the separate restore workflow for deleted pages.',
`Page ${slug} in '${sourceId}' is deleted or missing; nothing changed. If it was deleted by mistake, restore it (gbrain restore, within the 72-hour window) and then preview it again.`,
{ fix: readFix('Shows whether the page exists or is soft-deleted in this source.', { argv: ['gbrain', 'get', '--source', sourceId, '--include-deleted', '--', slug] }) });
if (binding.source_incarnation !== snapshot.sourceIncarnation) staleReconcile('source binding incarnation');
const [storedPage] = await engine.executeRaw<Record<string, unknown>>(`SELECT id,source_id,slug,type,title,compiled_truth,timeline,frontmatter,
content_hash,source_path,source_kind,source_uri,ingested_via,ingested_at,knowledge_revision,deleted_at FROM pages WHERE id=$1 AND source_id=$2`, [snapshot.page.id, sourceId]);
const root = realpathSync(join(binding.local_path, binding.relative_path));
const recorded = recordedPathFromFileUri(snapshot.page.source_uri, root);
const mode = await scannerSlugRootMode(engine, sourceId, root);
const recordedPath = recordedReconcilePath(root, snapshot.page, mode);
const marked = !recordedPath && (isDatabaseOnlyPage({ ...snapshot.page,
database_only_reason: await isUnboundSourcePage(engine, sourceId, slug) ? 'unbound_source' : null }) || await staleMirrorPage(engine, sourceId, snapshot.page));
const adoptable = !recordedPath && !marked && opts.adoptSlugPath === true;
const derived = marked ? slugDerivedOrigin(root, slug, mode) : adoptable ? await adoptableSlugOrigin(engine, sourceId, root, snapshot, mode) : null;
const origin = derived ? 'slug_derived' : 'recorded';
const path = recordedPath ?? derived?.path ?? null;
if (!path || !isWriteTargetContained(path, root)) throw opError('source_changed', 'The page has no unambiguous confined recorded Markdown origin.',
`Page ${slug} in '${sourceId}' records no Markdown file inside the source checkout, so there is nothing to reconcile it against; nothing changed. ${!recordedPath && !marked && recordsNoFileOrigin(snapshot.page) && opts.adoptSlugPath !== true
? `If the file at its slug path is this page's canonical file, preview again with --adopt-slug-path (gbrain sources reconcile ${sourceId} ${slug} --preview --adopt-slug-path) to adopt it; otherwise check its recorded source path with the command in fix.` : 'Check its recorded source path with the command in fix.'}`,
{ fix: readFix('Shows the page and its recorded source path.', { argv: ['gbrain', 'get', '--source', sourceId, '--', slug] }) });
let size: number;
try {
const info = lstatSync(path);
if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) throw new Error('not an ordinary file');
size = info.size;
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw opError('source_changed', 'The recorded canonical file is not an ordinary file; repair does not replace it.',
`Nothing changed. Make the canonical file of ${slug} in '${sourceId}' a regular file (not a symlink, directory or hard link), then preview the page again.`);
if (!opts.fileGone || origin !== 'recorded') throw missingCanonicalFile(sourceId, slug, root, path);
// #6712 wave: `repair file-drift --prefer database` recreates the file from the page; the preview pins the observed absence.
const canonicalPath = absentCanonicalPath(path);
await assertSoleFileClaim(engine, { sourceId, slug, pageId: snapshot.page.id, root, mode, path, canonicalPath,
recordedUri: recorded ? snapshot.page.source_uri ?? null : null, absent: true });
return { binding, root, path, importPath: scannerSourcePath(root, path, mode), raw: Buffer.alloc(0), snapshot, storedPage,
file: reconcileCanonical(snapshot.page, snapshot.tags), origin, originSourcePath: null,
pins: await reconcilePins(engine, { brain_id: brain.brain_id, sourceId, binding, snapshot, slug, assessmentAt, root, path, canonicalPath, rawFileHash: ABSENT_FILE_HASH }) };
}
const { readJournalLimits } = await import('./limits.ts');
const limits = await readJournalLimits(engine);
if (size > Math.min(limits.principalIntentBytes, limits.brainIntentBytes, limits.worktreeRecoveryBytes)) {
throw opError('request_too_large', 'The canonical file exceeds reconciliation capacity.',
`Nothing changed. The canonical file of ${slug} in '${sourceId}' is larger than the journal's request and recovery limits; tell the user the page needs a manual edit of that file.`);
}
const canonicalPath = realpathSync(path);
await assertSoleFileClaim(engine, { sourceId, slug, pageId: snapshot.page.id, root, mode, path, canonicalPath,
recordedUri: recorded ? snapshot.page.source_uri ?? null : null });
const raw = readFileSync(path), text = raw.toString('utf8');
if (!Buffer.from(text).equals(raw)) throw opError('invalid_params', 'The canonical file must contain valid UTF-8.',
`Nothing changed. Re-save the canonical file of ${slug} in '${sourceId}' as UTF-8, then preview the page again.`);
try { parseDataFrontmatter(text); }
catch {
throw opError('invalid_params', 'Canonical file metadata cannot be parsed losslessly; repair its syntax before previewing.',
`Nothing changed. Fix the frontmatter of the canonical file of ${slug} in '${sourceId}' (quote values containing ': ', close the --- block), then preview the page again.`);
}
// Preserve a terminal .md in the page key while parsing the canonical Markdown.
const importPath = scannerSourcePath(root, path, mode);
const reading = reconcileFileReading(text, importPath, snapshot.page);
const parsed = parseMarkdown(reading.content, `${slug}.md`, { validate: true, expectedSlug: slug });
alignWithStored(parsed, snapshot.page, reading.inferred);
const errors = parsed.errors?.filter(e => !['MISSING_OPEN', 'MISSING_CLOSE', 'EMPTY_FRONTMATTER'].includes(e.code)) ?? [];
if (!errors.length && !parsed.errors?.some(e => e.code === 'MISSING_CLOSE') && parsed.slug !== slug) {
// #5966 (W14 P1.7): a well-formed file whose path derives another slug is a legacy render of a slug the
// path cannot derive, written before renders stamped `slug:`; the frontmatter repair proposes the stamp.
throw opError('source_changed', 'The canonical file carries no slug stamp, so its path derives a different slug.',
`Nothing changed. The file of ${slug} in '${sourceId}' reads as ${parsed.slug} from its path. Preview the stamp with gbrain repair frontmatter --source ${sourceId} --only ${relative(root, path)} (a safe repair), apply it, then preview the page again.`,
{ detail: 'slug_rule_mismatch' });
}
if (errors.length || parsed.errors?.some(e => e.code === 'MISSING_CLOSE') || parsed.slug !== slug) {
throw opError('invalid_params', 'Canonical file metadata cannot be parsed losslessly; repair its syntax before previewing.',
`Nothing changed. Fix the frontmatter of the canonical file of ${slug} in '${sourceId}' (close the --- block, keep its slug), then preview the page again.`);
}
const pins = await reconcilePins(engine, { brain_id: brain.brain_id, sourceId, binding, snapshot, slug, assessmentAt, root, path, canonicalPath, rawFileHash: sha256(raw) });
return { binding, root, path, importPath, raw, snapshot, storedPage, file: reconcileCanonical(parsed, parsed.tags), pins, origin, originSourcePath: derived?.sourcePath ?? null };
}
async function reconcilePins(engine: BrainEngine, input: { brain_id: string; sourceId: string; binding: WorktreeBinding; snapshot: PageSnapshot; slug: string; assessmentAt: string;
root: string; path: string; canonicalPath: string; rawFileHash: string }): Promise<ReconcilePins> {
const { binding, snapshot, root, path } = input;
return { brain_id: input.brain_id, source_id: input.sourceId, source_incarnation: snapshot.sourceIncarnation, slug: input.slug,
page_id: snapshot.page.id, worktree_id: binding.worktree_id, binding_digest: digest({ binding, root, path: input.canonicalPath }), owner_epoch: String(binding.owner_epoch),
revision: snapshot.revision, raw_file_hash: input.rawFileHash, relative_path: relative(root, path),
policy_digest: await reconcilePolicyDigest(engine, input.sourceId), withdrawals_digest: digest({ withdrawals: snapshot.withdrawals, global_purges: snapshot.globalPurges ?? null }), assessment_at: input.assessmentAt };
}
/** #6394: a preview made with --adopt-slug-path recorded a page with no origin; apply and publication adopt the same pinned file. */
export function reconcilePreviewAdopts(artifact: Pick<ReconcileArtifact, 'preimages'>): boolean {
const stored = (artifact.preimages as { stored_page?: { source_path?: unknown; source_uri?: unknown } | null } | null)?.stored_page;
return stored != null && stored.source_path == null && recordsNoFileOrigin({ source_uri: typeof stored.source_uri === 'string' ? stored.source_uri : null });
}
/**
* GST-1555: a reconcile preview binds the page's revision, so a page the revision backfill has not reached refuses before
* anything is prepared. Its fix resumes the backfill, or, for a row that used every attempt, previews the torn-body repair.
* Read-only classification (drift class, audit) reads such a page normally; only previews call this.
*/
export async function assertReconcileRevision(engine: BrainEngine, snapshot: PageSnapshot, sourceId: string, slug: string): Promise<void> {
if (snapshot.revision !== REVISION_BACKFILL_PENDING) return;
const exhausted = await revisionBackfillExhausted(engine, Number(snapshot.page.id));
const verify = { argv: ['gbrain', 'doctor', '--only', 'revision_backfill', '--json'] };
throw opError('revision_backfill_pending', 'Reconciliation requires the page revision, and this page has none yet.',
`Nothing changed. Page ${slug} in '${sourceId}' was written before page revisions and the revision backfill has not reached it, so no reconcile preview can bind to it. `
+ (exhausted ? 'The backfill used every attempt on this row (usually a torn page body): preview gbrain repair orphan-children (the command in fix) and recover the page from a backup or a re-sync, then preview it again.'
: `Resume the backfill on the brain host with ${REVISION_BACKFILL_RESUME_COMMAND} (the command in fix), then preview the page again.`),
{ fix: exhausted
? { ...readFix('Previews orphaned child rows and lists torn page bodies (torn_pages) without changing anything.', { argv: ['gbrain', 'repair', 'orphan-children'] }), verify, docs: 'docs/guides/repair.md#orphan-children' }
: { argv: REVISION_BACKFILL_RESUME_COMMAND.split(' '), consent: [], actor: 'agent', requires_exclusive: true, verify, docs: 'docs/guides/write-refusals.md#revision-backfill',
why: 'Re-runs the schema migration pass on the brain host, which resumes the page revision backfill and prints its progress; it changes no page content.' } });
}
export function assertReconcilePins(expected: ReconcilePins, actual: ReconcilePins): void {
for (const key of Object.keys(expected) as Array<keyof ReconcilePins>) if (expected[key] !== actual[key]) staleReconcile(key);
}
export function validateReconcileArtifact(value: unknown): ReconcileArtifact {
validateReconcileJson(value);
const v2 = (value as Record<string, unknown> | null)?.format_version === 2;
strictReconcileKeys(value, ['format_version', 'preview_id', 'preconditions', 'preimages', 'decisions', 'conflicts', 'result', 'result_digest', 'status',
...(v2 ? ['auto_decisions'] : [])], ['format_version', 'preview_id', 'preconditions', 'preimages', 'decisions', 'conflicts', 'result', 'result_digest', 'status',
...(v2 ? ['auto_decisions'] : [])]);
if (v2) {
if (!Array.isArray(value.auto_decisions) || !value.auto_decisions.length || value.auto_decisions.length > 1000) throw opError('invalid_params', 'Malformed automatic reconciliation decisions.',
'Re-run the same reconcile preview with --auto-additive to recreate the file instead of editing it by hand.');
for (const entry of value.auto_decisions as unknown[]) {
strictReconcileKeys(entry, ['path', 'rule', 'rule_version', 'evidence_digest']);
if (typeof entry.path !== 'string' || typeof entry.rule !== 'string' || !Number.isSafeInteger(entry.rule_version)
|| typeof entry.evidence_digest !== 'string' || !/^[a-f0-9]{64}$/.test(entry.evidence_digest)) {
throw opError('invalid_params', 'Malformed automatic reconciliation decisions.',
'Re-run the same reconcile preview with --auto-additive to recreate the file instead of editing it by hand.');
}
}
}
strictReconcileKeys(value.preconditions, ['brain_id', 'source_id', 'source_incarnation', 'slug', 'page_id', 'worktree_id', 'binding_digest',
'owner_epoch', 'revision', 'raw_file_hash', 'relative_path', 'policy_digest', 'withdrawals_digest', 'assessment_at']);
strictReconcileKeys(value.preimages, ['file_base64', 'database', 'stored_page']);
// globalPurges is optional here so an artifact written before the '*' purge marker validates and then reads stale (assertPreimages).
// A page stored in segments (`body_storage`) is reconciled from its materialized body; its snapshot pins the body generation.
strictReconcileKeys(value.preimages.database, ['page', 'tags', 'revision', 'sourceIncarnation', 'withdrawals', 'globalPurges', 'bodyGeneration'],
['page', 'tags', 'revision', 'sourceIncarnation', 'withdrawals']);
if (value.preimages.database.globalPurges !== undefined) strictReconcileKeys(value.preimages.database.globalPurges, ['count', 'latest', 'world_only']);
strictReconcileKeys(value.preimages.database.page, ['id', 'slug', 'source_id', 'type', 'title', 'compiled_truth', 'timeline', 'frontmatter',
'content_hash', 'source_path', 'knowledge_revision', 'text_projection_revision', 'emotional_weight', 'created_at', 'updated_at', 'updated_at_iso',
'deleted_at', 'effective_date', 'effective_date_source', 'import_filename', 'salience_touched_at', 'source_kind', 'source_uri', 'ingested_via',
'ingested_at', 'contextual_retrieval_mode', 'corpus_generation', 'withheld_source_path', 'body_storage', 'body_bytes'], ['id', 'slug', 'source_id', 'type', 'title', 'compiled_truth', 'timeline', 'frontmatter']);
strictReconcileKeys(value.preimages.stored_page, ['id', 'source_id', 'slug', 'type', 'title', 'compiled_truth', 'timeline', 'frontmatter',
'content_hash', 'source_path', 'source_kind', 'source_uri', 'ingested_via', 'ingested_at', 'knowledge_revision', 'deleted_at']);
strictReconcileKeys(value.result, ['type', 'title', 'compiled_truth', 'timeline', 'frontmatter', 'tags']);
const result = value.result;
if (value.format_version !== 1 && !v2 || typeof value.preview_id !== 'string' || !['ready', 'needs_resolution'].includes(String(value.status)) ||
!Array.isArray(value.conflicts) || !Array.isArray(value.decisions) || !Array.isArray(value.preimages.database.tags) ||
!Array.isArray(value.preimages.database.withdrawals) || value.preimages.database.bodyGeneration !== undefined && !Number.isSafeInteger(value.preimages.database.bodyGeneration) ||
!Array.isArray(value.result.tags) || value.result.tags.some(v => typeof v !== 'string') ||
['type', 'title', 'compiled_truth', 'timeline'].some(key => typeof result[key] !== 'string') ||
value.result.frontmatter === null || typeof value.result.frontmatter !== 'object' || Array.isArray(value.result.frontmatter) ||
typeof value.preimages.file_base64 !== 'string' ||
digest(value.result) !== value.result_digest || typeof value.preconditions.assessment_at !== 'string' ||
!Number.isFinite(Date.parse(value.preconditions.assessment_at)) || !Number.isSafeInteger(value.preconditions.page_id) ||
Object.entries(value.preconditions).some(([key, v]) => key !== 'page_id' && typeof v !== 'string')) {
throw opError('invalid_params', 'Malformed or modified reconciliation artifact.',
'Pass the preview file exactly as reconcile wrote it with --out; change it only through --decisions. If it was edited, make a fresh preview.');
}
for (const key of ['brain_id', 'source_incarnation', 'worktree_id', 'revision']) requireUuid(value.preconditions[key] as string);
requireUuid(value.preview_id as string);
for (const key of ['binding_digest', 'raw_file_hash', 'policy_digest', 'withdrawals_digest']) {
if (!/^[a-f0-9]{64}$/.test(value.preconditions[key] as string)) {
throw opError('invalid_params', 'Invalid reconciliation fingerprint.',
'Pass the preview file exactly as reconcile wrote it with --out; if it was edited, make a fresh preview.');
}
}
for (const conflict of value.conflicts as unknown[]) strictReconcileKeys(conflict, ['path', 'file', 'database']);
for (const withdrawal of value.preimages.database.withdrawals as unknown[]) strictReconcileKeys(withdrawal, ['visibility', 'fact_hash', 'withdrawn_at', 'purged'], ['visibility', 'fact_hash', 'withdrawn_at']);
return JSON.parse(stableJson(value)) as ReconcileArtifact;
}
/**
* #6605: the file side of a reconciliation, read the way the importer stored it. A frontmatter-less file under a
* directory-inference rule was imported with the frontmatter its path infers, so its raw bytes would show every
* inferred key as a difference. The inferred reading is used when the stored row carries every key it adds (an
* inferring import wrote the row); a row imported without inference (`gbrain reindex` on an unmanaged brain) is
* compared with the raw bytes. An inferred `type:` is not one the file declared: the caller keeps the stored type.
*/
/** GBRA-133: a canonical file's text as `readReconcileState` reads it (the reconcile canonical form of the page it imports). */
export function readCanonicalFileText(state: Pick<ReconcileState, 'importPath' | 'snapshot'>, slug: string, text: string): ParsedPage {
const reading = reconcileFileReading(text, state.importPath, state.snapshot.page);
const parsed = parseMarkdown(reading.content, `${slug}.md`, { validate: true, expectedSlug: slug });
alignWithStored(parsed, state.snapshot.page, reading.inferred);
return reconcileCanonical(parsed, parsed.tags);
}
export function reconcileFileReading(text: string, sourcePath: string, stored: { frontmatter?: Record<string, unknown> | null }): { content: string; inferred: boolean } {
const reading = readCanonicalAsImported(text, sourcePath);
if (!reading.inferred) return reading;
const keys = Object.keys(parseMarkdown(reading.content, sourcePath).frontmatter);
return keys.every(key => Object.hasOwn(stored.frontmatter ?? {}, key)) ? reading : { content: text, inferred: false };
}