Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain repair file-drift --source <id> (--slug <s>... | --request <id>... | --all-drifted [--class <c>] [--since <ISO|7d>]) --prefer file|database`
* (#6643 B2): resolve pages whose canonical file differs from their database row
* (the `source_changed` / `file_database_drift` refusal) through canonical
* reconciliation, preferring one side.
*
* The preferred side wins every ordinary field (title, type, body, timeline and
* unprotected frontmatter; a key only the other side has is dropped) WITHIN
* reconcile's existing protections: protected metadata (provenance, trust,
* source and scan fields) stays as the database holds it, tags are the union of
* both sides, and protected takes and private fact rows are kept as stored.
* Each page's preview lists where its result differs from the preferred side
* (`exceptions`) and why.
*
* Explicit-only and preview-bound: the preview checks each page live on the
* canonical owner, preflights the CLI writer grant, prepares the reconcile
* result, writes every page's resolved result and exceptions to a private
* artifact under the gbrain config directory (`repair-previews/file-drift/
* <hash>.json`, outside every canonical worktree) and saves the set under the
* plan hash. `--apply --expect <hash>` applies exactly that set: each page goes
* through the reconcile apply (its preimage checks and retained backups) under
* a request id derived from the plan hash and slug, so an interrupted apply
* resumes from the saved plan and replays the same requests. Outcomes per page:
* `repaired`, `refused` (with the refusal code) or `changed_since_preview`.
*
* `--all-drifted` takes every page the conflict audit finds still drifted. It
* refuses a selection that mixes drift classes unless `--class <name>` keeps
* exactly one, so one `--prefer` never resolves differently shaped drift in bulk.
* #6696 C7: repeatable `--only` / `--skip` over the canonical file path,
* source-relative: an exact path, or a glob (`*` within a segment, `**` across
* segments; `path-glob.ts`, file-drift being the only kind that takes globs),
* narrow the selection before the class check, the bound and any preview
* work; they are part of the selection digest (so of the plan hash) and of
* every printed preview and apply command. #6712 PR 2: `--since` keeps the pages whose newest
* drift conflict is at or after one concrete instant (the CLI resolves an age once, `since.ts`), part of
* the selection digest and of every printed command. Trusted local CLI only.
*
* #6712 wave: a selected live page whose canonical file is gone from the last commit (a ghost whose deletion is
* committed, such as a held deletion whose page moved) resolves too: `--prefer database` recreates the file from the
* page through the same reconcile apply (its preview pins the observed absence, so a file that reappears is
* `changed_since_preview`), and `--prefer file` soft-deletes exactly that page through the ghost-page retirement intent
* (bound to its revision, path and owner; the mass-delete valve applies). A file deleted only in the worktree (still
* committed at HEAD) is not drift: the preview lists it `deletion_uncommitted` with its route (commit the deletion, or
* `gbrain repair ghost-pages`) and resolves nothing.
*
* #6712 PR 4b: `--held [--side both|unknown|deleted [--state tombstone_edited|purged_differs|file_gone]]` selects the
* source's held `file_drift` pages of one Decision (design v3.2 §4). A selection of several sides or states is refused
* (`file_drift_mixed_selection`) and a deleted side needs `--state` (`file_drift_state_required`), because the two
* options do opposite things in each state. Both/unknown pages resolve as above, `file_gone` as the wave's file-gone
* modes; `tombstone_edited` and `purged_differs` (a deleted page, or a deletion marker, at the origin of a file that
* differs) resolve `--prefer database` by removing the file through a coordinated publication (`prepareDriftFileRemoval`;
* the deletion stands) and `--prefer file` by importing the file's bytes through the managed file repair (the tombstone is
* restored, or a new page created; a marker stays for sync to retire). The preview lists each page's action verb.
*/
import { randomUUID } from 'node:crypto';
import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
import { join, relative, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { configDir } from '../config.ts';
import { flushDirectory } from '../fs-durable.ts';
import { OperationError, opError, type OperationContext } from '../ops/contract.ts';
import { readFix, trustedCliRequired } from '../ops/op-fix.ts';
import { validateSlug } from '../utils.ts';
import { matchesRepairPath } from './path-glob.ts';
import { shellQuote } from '../agent-output.ts';
import { commitPushCommand } from '../git/commit-push.ts';
import type { ParsedPage } from '../import-file.ts';
import { digest, sha256, stableJson } from '../persistence/digest.ts';
import { currentVerifiedLocalWriter, readLocalWriter, withVerifiedLocalRegistration } from '../persistence/identity.ts';
import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
import { canonicalFilesystemPath } from '../persistence/root-registry.ts';
import { auditDriftConflicts, DRIFT_CLASSES, driftClass, liveFileDrift, type DriftClass, type LiveDrift } from '../persistence/drift-conflicts.ts';
import { classifyDrift } from '../persistence/reconcile-additive.ts';
import { isUnboundSourcePage } from '../persistence/unbound-source.ts';
import { protectedReconcileKey, reconcileCanonical, RECONCILE_SCAN_KEYS, type ReconcileDecision } from '../persistence/reconcile-merge.ts';
import { fileWinsContent } from '../persistence/file-wins-content.ts';
import { ABSENT_FILE_HASH, canonicalDeletionState, missingFileRoute, readCanonicalFileText, readDeletedDriftTarget, readReconcileState, assertReconcileRevision, validateReconcileArtifact, type DeletedDriftChange, type DeletedDriftTarget, type ReconcileArtifact } from '../persistence/reconcile-state.ts';
import { sourceDbOnlyVerdict } from '../persistence/source-storage.ts';
import { readMovedPage } from '../persistence/moved-pages.ts';
import { clearGitHold, movedPagesPreviewArgv, readGitHold, recordKeepDeleted, fileDriftActionVerb, fileDriftSide, FILE_DRIFT_DELETED_STATES, FILE_DRIFT_SIDES, GIT_HOLD_OP, heldDriftPreviewArgv, requestGitHoldRetry, type FileDriftDeletedState, type FileDriftSide, type GitHoldRecord } from '../persistence/sync-holds.ts';
import { prepareRepairPublication, repairScreenConfig, submitManagedFileRepair } from '../persistence/file-repair.ts';
import { maintenancePreflight, submitDatabaseMaintenanceIntent, submitMaintenanceIntent } from '../persistence/prepared-maintenance.ts';
import type { PreparedMutation } from '../persistence/coordinator.ts';
import type { WriteRequest } from '../persistence/model.ts';
import { resolveSlugForPath } from '../sync.ts';
import { getWorktreeBinding } from '../persistence/ownership.ts';
import { gitDurabilityPolicy } from '../persistence/git-durability-policy.ts';
import { DETACHED_REASON } from '../persistence/detached-pages.ts';
import { DELETION_PROVENANCES, readDeletionProvenance, type DeletionProvenance } from '../persistence/sync-origin-evidence.ts';
import { ghostPageNow, scanGhostSource, type GhostOwner, type GhostPage } from '../ghost-pages.ts';
import { MASS_RECONCILE_MIN_PAGES, MASS_RECONCILE_RATIO, massReconcileAllowed } from '../sync-reconcile.ts';
import { DATABASE_AHEAD_CODE, databaseAheadDetail, ghostFileBacked, GHOST_PURGE_FUSE_HOURS, GHOST_REPAIR_LIMIT, ghostScanRefusal, massGhosts, massRefusal, retireGhost } from './ghost-pages.ts';
import { prepareReconcileResult } from '../persistence/reconcile-prepare.ts';
import { canonicalOriginPage, originConflictMessage, originTwinsFix } from '../persistence/origin-guard.ts';
import { assertReconcileOutputPath, assertReconcileSize } from '../persistence/reconcile-backup.ts';
import { authorizeReconcile, authorizeReconcileGrant, runReconcileApply } from '../persistence/reconcile.ts';
import { discardedFilePaths, unimportedFile, unimportedFileText, type UnimportedFile } from '../persistence/unimported-file.ts';
import { acceptedPendingReceipt } from '../persistence/accepted-pending.ts';
import { recordsNoFileOrigin } from '../persistence/unbound-pages.ts';
import { sourceMirrorReadOnly } from '../persistence/mirror-read-only.ts';
import { comparedListing, comparePage, heldLiveDrift, linesNotCarried, mirrorDriftRoute, newerPageParagraph, readDriftEvidence, type ComparedPage } from './file-drift-compare.ts';
import { serializePageToMarkdown } from '../markdown.ts';
import { afterCursor, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairPlanOptions, type RepairScope } from './core.ts';
export type DriftSide = 'file' | 'database';
/** Where a page's resolved result differs from the preferred side, and why. */
export interface DriftException { path: string; reason: 'protected_metadata' | 'scan_state' | 'tags_union' | 'protected_takes_or_private_facts' | 'canonical_import' }
interface ApprovedPage { source_id: string; slug: string; artifact_digest: string; selection: string }
interface DriftItem extends RepairItem { page: ApprovedPage; hash: string; last: boolean }
/** One page's prepared resolution: the ready reconcile preview its apply submits, and where it departs from the preferred side. */
export interface ArtifactPage { slug: string; prefer: DriftSide; class?: DriftClass; adopt_slug_path: boolean; exceptions: DriftException[]; result: ParsedPage; preview: ReconcileArtifact;
/** #6712 wave: the canonical file is gone from the last commit and the apply recreates it from the page. */
file_gone?: true;
/** GBRA-133: file wins appends protected keys or timeline rows to the canonical file (`fileWinsContent`). */
file_appended?: true;
/** How many lines of the side the repair overwrites the result does not carry (`linesNotCarried`, both sides rendered alike). */
lost_lines: number;
/** GST-2579: database wins writes over a file edit gbrain never imported or wrote; only an exact --slug selection keeps such a page, and its apply needs consent. */
discards?: UnimportedFile }
/** #6712 wave: a page whose canonical file is gone from the last commit, resolved `--prefer file`: soft-delete exactly that page. */
export interface SoftDeletePage { slug: string; prefer: 'file'; exceptions: DriftException[]; soft_delete: { ghost: GhostPage; owner: GhostOwner } }
/**
* #6712 PR 4b: what a held deleted-side resolution is bound to (design v3.2 §4): the file's bytes, the tombstone's id and
* revision (`tombstone_edited`) or the deletion marker's value (`purged_differs`), and the hold it clears.
*/
export interface DeletedDriftPin { state: 'tombstone_edited' | 'purged_differs'; path: string; source_path: string; raw_file_hash: string;
page_id: number | null; revision: string | null; marker_digest: string | null; observed_at: string }
/** #6712 PR 4b `--prefer database` on a deleted side: the deletion stands and the file is removed by a coordinated publication. */
export interface RemoveFilePage { slug: string; prefer: 'database'; exceptions: DriftException[]; remove_file: DeletedDriftPin }
/** #6712 PR 4b `--prefer file` on a deleted side: the file's bytes are imported (restoring the tombstone, or as a new page). */
export interface ImportFilePage { slug: string; prefer: 'file'; exceptions: DriftException[]; import_file: DeletedDriftPin & { result_digest: string } }
/**
* GBRA-133 `--provenance never_committed --prefer database`: a live page whose held file no commit ever held keeps its content
* database-only. The apply forgets the page's recorded file (`database_only_reason=detached`, as `restore --detach` does),
* writes no file and clears the hold, bound to the page's id, revision and path and to the hold it observed.
*/
export interface DetachPin { path: string; page_id: number; revision: string; observed_at: string }
export interface DetachPage { slug: string; prefer: 'database'; exceptions: DriftException[]; detach_page: DetachPin }
/**
* GBRA-133: a held page whose page and file agree now; the apply asks the next sync to re-screen (and so release) its hold.
* #7950: bound to the hold the preview observed (`observed_at`), whichever selection (`--held` or `--slug`) found it.
*/
export interface ReleasePin { path: string; incarnation: string; revision: string; file_hash: string | null; observed_at: string }
export interface ReleasePage { slug: string; prefer: DriftSide; exceptions: DriftException[]; release_hold: ReleasePin }
/**
* `--prefer database` on a read-only mirror's `tombstone_edited` hold: gbrain never writes the mirror, so instead of removing
* the file the apply records the decision on the hold (`meta.keep_deleted`), bound to the same pin; nothing else is written.
*/
export interface KeepDeletedPage { slug: string; prefer: 'database'; exceptions: DriftException[]; keep_deleted: DeletedDriftPin }
type PlannedPage = ArtifactPage | SoftDeletePage | RemoveFilePage | ImportFilePage | DetachPage | ReleasePage | KeepDeletedPage;
/** #6712 PR 4b: one held `file_drift` page a `--held` selection resolves. */
interface HeldTarget { hold: GitHoldRecord; side: FileDriftSide; state?: FileDriftDeletedState; provenance?: DeletionProvenance }
/** The coordinated removal `--prefer database` admits for a held file whose page is deleted (prepared by `prepareDriftFileRemoval`). */
export const FILE_DRIFT_REMOVE_INTENT = 'managed_maintenance_file_drift_remove';
/** GBRA-133: the database-only keep of a live page whose held file no commit ever held (`prepareDriftDetach`). */
export const FILE_DRIFT_DETACH_INTENT = 'managed_maintenance_file_drift_detach';
const DELETED_CHANGES: Record<DeletedDriftChange, string> = {
file_gone: 'the file is gone now, so nothing is left to resolve',
live_page: 'a live page records the file again, so it is no longer a deleted-side Decision',
no_deletion: 'no deleted page or deletion marker is left at its origin; the next sync re-classifies it',
deleted_same: 'the file holds the bytes the deleted page had, so the deletion already stands',
};
const ALL_DRIFTED_LIMIT = 1000;
/**
* A `--held` preview covers one window of the selected holds, in held-path order after `--cursor`: at most this many pages,
* and it starts no page after the window's time budget (or the run's deadline) has passed. Each page costs a few dozen
* database round trips, so a whole large held set in one preview ran for an hour against a remote database with no output.
*/
export const HELD_WINDOW_PAGES = 200;
const HELD_WINDOW_BUDGET_MS = 60_000;
const HELD_CURSOR_PREFIX = 'h1.';
const heldCursor = (path: string) => HELD_CURSOR_PREFIX + Buffer.from(path, 'utf8').toString('base64url');
function heldCursorPath(sourceId: string, cursor: string): string {
const path = cursor.startsWith(HELD_CURSOR_PREFIX) ? Buffer.from(cursor.slice(HELD_CURSOR_PREFIX.length), 'base64url').toString('utf8') : '';
if (!path || heldCursor(path) !== cursor) throw opError('invalid_params', `--cursor ${cursor} is not a cursor a held file-drift preview printed.`,
`Nothing was previewed. Pass the next_cursor the previous preview printed, or drop --cursor to start from the first held file of '${sourceId}'.`);
return path;
}
const TOP_FIELDS = ['title', 'type', 'compiled_truth', 'timeline'] as const;
export const artifactDirectory = () => join(canonicalFilesystemPath(configDir()), 'repair-previews', 'file-drift');
const escapePointer = (key: string) => key.replace(/~/g, '~0').replace(/\//g, '~1');
function previewCommand(sourceId: string, opts: RepairPlanOptions): string {
const select = opts.held ? ` --held${opts.side ? ` --side ${opts.side}` : ''}${opts.state ? ` --state ${opts.state}` : ''}${opts.provenance ? ` --provenance ${opts.provenance}` : ''}${opts.cursor ? ` --cursor ${opts.cursor}` : ''}`
: opts.allDrifted ? ` --all-drifted${opts.driftClass ? ` --class ${opts.driftClass}` : ''}${opts.since ? ` --since ${opts.since}` : ''}`
: [...(opts.slugs ?? []).map(slug => ` --slug ${slug}`), ...(opts.requests ?? []).map(id => ` --request ${id}`)].join('');
const globs = [...(opts.only ?? []).flatMap(glob => ['--only', glob]), ...(opts.skip ?? []).flatMap(glob => ['--skip', glob])];
return `gbrain repair file-drift --source ${sourceId}${select}${globs.length ? ` ${shellQuote(globs)}` : ''} --prefer ${opts.prefer ?? '<file|database>'}`;
}
/** Whether a canonical file path passes the `--only` / `--skip` globs (no `--only`: every path; an unknown path only then). */
export const selectedByGlobs = (path: string | undefined, opts: Pick<RepairPlanOptions, 'only' | 'skip'>) =>
path === undefined ? !opts.only?.length && !opts.skip?.length
: (!opts.only?.length || matchesRepairPath(path, opts.only)) && !matchesRepairPath(path, opts.skip);
/** #6712 PR 2: whether a page's newest drift conflict (`last_seen`) is at or after `--since` (no `--since`: every page). */
const sinceSelects = (lastSeen: string, since: string | undefined) => !since || Date.parse(lastSeen) >= Date.parse(since);
/** The reconcile decisions that make the preferred side win every field reconcile lets a decision choose. */
export function preferSideDecisions(file: ParsedPage, database: ParsedPage, prefer: DriftSide): ReconcileDecision[] {
const take = prefer === 'file' ? 'take_file' : 'take_database';
const [preferred, other] = prefer === 'file' ? [file, database] : [database, file];
const decisions: ReconcileDecision[] = TOP_FIELDS.filter(key => digest(file[key] ?? '') !== digest(database[key] ?? '')).map(key => ({ path: `/${key}`, action: take }));
const extraction = file.frontmatter.provenance === 'auto-extracted' || database.frontmatter.provenance === 'auto-extracted';
for (const key of [...new Set([...Object.keys(preferred.frontmatter), ...Object.keys(other.frontmatter)])].sort()) {
if (protectedReconcileKey(key) || extraction && key === 'status') continue;
const has = Object.hasOwn(preferred.frontmatter, key);
if (has && Object.hasOwn(other.frontmatter, key) && digest(preferred.frontmatter[key]) === digest(other.frontmatter[key])) continue;
decisions.push({ path: `/frontmatter/${escapePointer(key)}`, action: has ? take : 'delete' });
}
return decisions;
}
/** Every path where the resolved result is not the preferred side, with the protection that kept it. */
export function driftExceptions(result: ParsedPage, preferred: ParsedPage): DriftException[] {
const exceptions: DriftException[] = [];
for (const key of TOP_FIELDS) {
if (digest(result[key] ?? '') === digest(preferred[key] ?? '')) continue;
exceptions.push({ path: `/${key}`, reason: key === 'compiled_truth' || key === 'timeline' ? 'protected_takes_or_private_facts' : 'canonical_import' });
}
if (digest([...result.tags].sort()) !== digest([...preferred.tags].sort())) exceptions.push({ path: '/tags', reason: 'tags_union' });
for (const key of [...new Set([...Object.keys(result.frontmatter), ...Object.keys(preferred.frontmatter)])].sort()) {
if (digest(result.frontmatter[key] ?? null) === digest(preferred.frontmatter[key] ?? null)) continue;
exceptions.push({ path: `/frontmatter/${escapePointer(key)}`, reason: RECONCILE_SCAN_KEYS.includes(key) ? 'scan_state'
: protectedReconcileKey(key) || key === 'status' ? 'protected_metadata' : 'canonical_import' });
}
return exceptions;
}
export async function asLocalCli<T>(engine: BrainEngine, run: () => Promise<T>): Promise<T> {
const verified = currentVerifiedLocalWriter();
if (verified) {
if (verified.remote || verified.principal.kind !== 'local_cli') throw trustedCliRequired('gbrain repair file-drift runs only for the trusted local CLI.');
return run();
}
return withVerifiedLocalRegistration(engine, await readLocalWriter(engine, 'cli'), run);
}
/**
* The request id of one approved page's apply. #7931: it names the exact artifact the preview approved (a reconcile
* preview carries its own preview id), so a rerun of the same approved set replays its request, while an apply refused
* before it published reserves nothing for the next preview's apply under the same --expect.
*/
function requestIdFor(hash: string, page: Pick<ApprovedPage, 'source_id' | 'slug' | 'artifact_digest'>): string {
const h = digest(['file-drift-request-v2', hash, page.source_id, page.slug, page.artifact_digest]);
return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20, 32)}`;
}
/** Writes a private preview file (`<name>.json`) under the file-drift preview directory, atomically; the whole-class manifest uses it too. */
export function writeArtifact(name: string, value: unknown): string {
const directory = artifactDirectory();
if (!existsSync(directory)) mkdirSync(directory, { recursive: true, mode: 0o700 });
const stat = lstatSync(directory);
if (!stat.isDirectory() || stat.isSymbolicLink()) throw opError('permission_denied', 'The file-drift preview directory must be a private real directory.',
`Nothing was written. Make ${directory} a real directory owned by the user with mode 0700 (not a symlink), then preview again.`);
const path = join(directory, `${name}.json`);
const temporary = join(directory, `.${name}.${randomUUID()}.tmp`);
const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
try { writeFileSync(fd, stableJson(value)); fsyncSync(fd); } finally { closeSync(fd); }
renameSync(temporary, path);
flushDirectory(directory);
return path;
}
/**
* The parsed artifact of the newest preview read, keyed by its path and file identity. An apply reads the artifact once per
* page, and a preview of large pages writes hundreds of megabytes, so parsing it again for every page cost seconds each.
*/
let artifactMemo: { key: string; pages: Map<string, PlannedPage> } | null = null;
/** The preview artifact's pages by slug; the same parsed map while the file is unchanged. Exported for its test. */
export function readArtifact(hash: string, command: string): Map<string, PlannedPage> {
const path = join(artifactDirectory(), `${hash}.json`);
try {
const stat = lstatSync(path);
if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('not a regular file');
const key = `${path}\0${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}`;
if (artifactMemo?.key === key) return artifactMemo.pages;
const parsed = JSON.parse(readFileSync(path, 'utf8')) as { pages?: PlannedPage[] };
const pages = new Map((parsed.pages ?? []).map(page => [page.slug, page]));
artifactMemo = { key, pages };
return pages;
} catch { throw previewChangedError(hash, command); }
}
/**
* The slugs the selection names: exact slugs, the slugs of named conflict receipts, or every page the audit finds
* still drifted. `--all-drifted` is narrowed here by the `--only` / `--skip` globs over each page's canonical file
* path (`not_selected` counts the pages they leave out), before the class check and the bound; an exact selection
* is narrowed by the plan from the same live check.
*/
async function selectSlugs(engine: BrainEngine, sourceId: string, opts: RepairPlanOptions): Promise<{ slugs: string[]; classes: Map<string, DriftClass>; notSelected: number; unknown: UnknownDrift[] }> {
const classes = new Map<string, DriftClass>();
const unknown: UnknownDrift[] = [];
if (opts.allDrifted) {
const drifted: string[] = [];
let notSelected = 0;
let cursor: string | undefined;
do {
const page = await auditDriftConflicts(engine, sourceId, { trusted: true, excludePrivate: false }, { limit: 100, cursor });
for (const row of page.conflicts) {
if (row.still_present.value === false) continue;
if (!selectedByGlobs(row.path, opts) || !sinceSelects(row.last_seen, opts.since)) { notSelected++; continue; }
if (row.still_present.value === null) { unknown.push({ slug: row.slug, reason: row.still_present.reason }); continue; }
drifted.push(row.slug); classes.set(row.slug, row.class ?? 'error');
}
cursor = page.next ?? undefined;
} while (cursor && drifted.length < ALL_DRIFTED_LIMIT);
const counts = new Map<DriftClass, number>();
for (const value of classes.values()) counts.set(value, (counts.get(value) ?? 0) + 1);
if (opts.prefer && !opts.driftClass && counts.size > 1) {
const listed = [...counts].map(([name, count]) => `${name}=${count}`).join(', ');
throw opError('invalid_params', `The drifted pages of '${sourceId}' fall into ${counts.size} drift classes (${listed}); one --prefer must not resolve them in bulk.`,
`Preview one class at a time: ${previewCommand(sourceId, { ...opts, driftClass: [...counts.keys()][0] })}, and so on for each class; or name pages with --slug.`,
{ fix: readFix('Lists the drifted pages with their drift class, read-only.', { argv: ['gbrain', 'sources', 'reconcile', sourceId, '--brain', 'host', '--audit', '--conflicts', '--json'] }) });
}
return { slugs: drifted.filter(slug => !opts.driftClass || classes.get(slug) === opts.driftClass), classes, notSelected, unknown };
}
const slugs = new Set(opts.slugs ?? []);
if (opts.requests?.length) {
const rows = await engine.executeRaw<{ request_id: string; slug: string }>(
"SELECT request_id::text, slug FROM persistence_requests WHERE source_id=$1 AND request_id=ANY($2::uuid[]) AND state='conflict' AND error_code='source_changed'",
[sourceId, opts.requests]);
const missing = opts.requests.filter(id => !rows.some(row => row.request_id === id));
if (missing.length) throw opError('invalid_params', `Request ${missing[0]} is not a source_changed conflict of source '${sourceId}'.`,
`Pass the request id of a conflict receipt the audit lists (last_conflict_request_id), or select the page with --slug.`,
{ fix: readFix('Lists the conflict receipts of this source grouped by slug, read-only.', { argv: ['gbrain', 'sources', 'reconcile', sourceId, '--brain', 'host', '--audit', '--conflicts', '--json'] }) });
for (const row of rows) slugs.add(row.slug);
}
return { slugs: [...slugs].sort(), classes, notSelected: 0, unknown };
}
/** #6991: a conflicted page the live check could not classify; it is listed and counted, never repaired. */
interface UnknownDrift { slug: string; reason: string }
function unknownDriftDetail(sourceId: string, { slug, reason }: UnknownDrift): string {
const kept = 'Not classified or repaired.';
if (reason === 'not_owner_host') return `${reason}: ${kept} Run the drift audit for source ${sourceId} on its active canonical owner host.`;
if (reason === 'page_missing') return `${reason}: ${kept} The page is gone from the database; decide its content by hand, no --prefer applies to it.`;
if (reason === 'canonical_file_missing') return `${reason}: ${kept} Its canonical file is missing; preview it alone with --slug ${slug} to choose a side.`;
if (reason === 'error') return `${reason}: ${kept} The live check failed unexpectedly; rerun gbrain sources reconcile ${sourceId} --audit --conflicts --json.`;
return `${reason}: ${kept} The live check refused; preview it alone with --slug ${slug} to see the refusal.`;
}
/**
* #6712 PR 4b `--held`: the source's held `file_drift` pages of one side (and, for a deleted side, one state), narrowed by
* the `--only` / `--skip` globs over the held file path. Without `--side` the narrowed holds must all be one Decision;
* holds of several sides or states are refused (`file_drift_mixed_selection`), and a deleted side always needs `--state`
* (`file_drift_state_required`): its two actions are opposite. Holds an older gbrain wrote with `sides: database` have
* no side and are listed with their single-page route.
*/
async function selectHeld(engine: BrainEngine, sourceId: string, opts: RepairPlanOptions):
Promise<{ targets: HeldTarget[]; before: number; notSelected: number; legacy: GitHoldRecord[]; otherProvenance: number; provenance?: Record<string, number> }> {
const after = opts.cursor ? heldCursorPath(sourceId, opts.cursor) : null;
const rows = await engine.executeRaw<{ record: GitHoldRecord; in_window: boolean }>(`SELECT h.completed_keys->0 AS record,
($3::text IS NULL OR (h.completed_keys->0->>'path') COLLATE "C" > $3::text) AS in_window FROM op_checkpoints h
JOIN sources s ON s.id=h.completed_keys->0->>'source_id' AND s.incarnation::text=h.completed_keys->0->>'incarnation'
WHERE h.op=$1 AND s.id=$2 AND h.completed_keys->0->>'code'='file_drift' ORDER BY (h.completed_keys->0->>'path') COLLATE "C"`, [GIT_HOLD_OP, sourceId, after]);
const targets: Array<HeldTarget & { inWindow: boolean }> = [], legacy: GitHoldRecord[] = [];
let notSelected = 0;
for (const { record, in_window } of rows) {
if (!selectedByGlobs(record.path, opts)) { notSelected++; continue; }
const side = fileDriftSide(record.meta);
if (!side || side === 'deleted' && !record.meta.state) { if (in_window) legacy.push(record); continue; }
targets.push({ hold: record, side, ...(side === 'deleted' ? { state: record.meta.state } : {}), inWindow: in_window === true });
}
const key = (target: Pick<HeldTarget, 'side' | 'state'>) => target.state ? `${target.side}/${target.state}` : target.side;
const groups = new Map<string, { side: FileDriftSide; state?: FileDriftDeletedState; count: number }>();
for (const target of targets) {
const group = groups.get(key(target)) ?? { side: target.side, ...(target.state ? { state: target.state } : {}), count: 0 };
group.count++; groups.set(key(target), group);
}
const narrower = (group: { side: FileDriftSide; state?: FileDriftDeletedState }) => heldCommand(sourceId, group.side, group.state, opts.prefer!, opts);
const statusFix = readFix('Lists the held files of this source with their side and state, read-only.', { argv: ['gbrain', 'sources', 'status', sourceId, '--json'] });
// GST-2568: a comparison without --prefer resolves nothing, so several Decisions may be compared together.
if (opts.prefer && !opts.side && groups.size > 1) {
const listed = [...groups.entries()].map(([name, group]) => `${name}=${group.count}`).join(', ');
throw opError('file_drift_mixed_selection', `The held file-drift pages of '${sourceId}' are ${groups.size} different Decisions (${listed}); one --prefer must not resolve them in bulk.`,
`Nothing was previewed. Preview one Decision at a time: ${[...groups.values()].map(narrower).join('; ')}.`, { fix: statusFix });
}
const only = opts.prefer && !opts.side && groups.size === 1 ? [...groups.values()][0]! : null;
if (only?.side === 'deleted') throw stateRequired(sourceId, opts, [only.state!]);
const selected = targets.filter(target => !opts.side || target.side === opts.side && (!opts.state || target.state === opts.state));
let window = selected.filter(target => target.inWindow).map(({ inWindow: _inWindow, ...target }) => target);
// GBRA-133: a gone file's provenance (sync-origin-evidence.ts), read for every held file a --provenance selection filters, else for one window.
const gone = window.filter(target => target.state === 'file_gone').slice(0, opts.provenance ? undefined : HELD_WINDOW_PAGES);
const provenance: Record<string, number> = Object.fromEntries([...DELETION_PROVENANCES, 'unknown'].map(kind => [kind, 0]));
if (gone.length) {
const binding = await getWorktreeBinding(engine, sourceId);
// One walk of the history; a long one takes a while, so the preview says it is reading (stderr).
opts.progress?.start('repair.file_drift.provenance', gone.length);
let read: Map<string, DeletionProvenance>;
try {
read = await readDeletionProvenance(join(binding!.local_path!, binding!.relative_path), gone.map(target => target.hold.path),
{ onCommit: commits => opts.progress?.heartbeat(`read ${commits} commit(s) of history for ${gone.length} held file(s)`) });
} finally { opts.progress?.finish(); }
for (const target of gone) {
target.provenance = read.get(target.hold.path) ?? { kind: 'unknown' };
provenance[target.provenance.kind] = (provenance[target.provenance.kind] ?? 0) + 1;
}
}
const otherProvenance = opts.provenance ? window.filter(target => target.provenance?.kind !== opts.provenance).length : 0;
if (opts.provenance) window = window.filter(target => target.provenance?.kind === opts.provenance);
return { targets: window, before: selected.filter(target => !target.inWindow).length, notSelected, legacy, otherProvenance, ...(gone.length ? { provenance } : {}) };
}
/** #6712 PR 4b: the `--held` preview of one Decision, keeping the run's `--only` / `--skip` globs. */
function heldCommand(sourceId: string, side: FileDriftSide, state: FileDriftDeletedState | undefined, prefer: DriftSide, opts: Pick<RepairPlanOptions, 'only' | 'skip'>): string {
const argv = heldDriftPreviewArgv(sourceId, side, state, prefer);
return shellQuote([...argv.slice(0, -2), ...(opts.only ?? []).flatMap(glob => ['--only', glob]), ...(opts.skip ?? []).flatMap(glob => ['--skip', glob]), ...argv.slice(-2)]);
}
/** #6712 PR 4b: `--side deleted` without `--state` (or a held selection that is all one deleted state) names the state to resolve. */
function stateRequired(sourceId: string, opts: RepairPlanOptions, states: readonly FileDriftDeletedState[]): OperationError {
const prefer = opts.prefer ?? 'database';
const commands = states.map(state => `${heldCommand(sourceId, 'deleted', state, prefer, opts)} (--prefer ${prefer}: ${fileDriftActionVerb('deleted', state, prefer)})`);
return opError('file_drift_state_required', 'Resolving held deleted-side file drift needs --state: --prefer file and --prefer database do opposite things in each state.',
`Nothing was previewed. Name the state: ${commands.join('; ')}.`,
{ fix: readFix('Lists the held files of this source with their side and state, read-only.', { argv: ['gbrain', 'sources', 'status', sourceId, '--json'] }) });
}
const USAGE = 'gbrain repair file-drift --source <id> (--slug <slug>... | --request <id>... | --all-drifted [--class <name>] [--since <ISO-8601|7d>] | --held [--side both|unknown|deleted [--state tombstone_edited|purged_differs|file_gone [--provenance never_committed|deleted_by_commit|deletion_uncommitted]]] [--cursor <next_cursor>]) [--only <glob>]... [--skip <glob>]... [--prefer file|database]';
/** GST-2568: the selection's winner-free comparison (no --prefer), as argv: read-only, it names each page's newer side. */
function compareArgv(sourceId: string, opts: RepairPlanOptions): string[] {
const select = opts.held ? ['--held', ...(opts.side ? ['--side', opts.side] : []), ...(opts.state ? ['--state', opts.state] : []), ...(opts.provenance ? ['--provenance', opts.provenance] : []), ...(opts.cursor ? ['--cursor', opts.cursor] : [])]
: opts.allDrifted ? ['--all-drifted', ...(opts.driftClass ? ['--class', opts.driftClass] : []), ...(opts.since ? ['--since', opts.since] : [])]
: [...(opts.slugs ?? []).flatMap(slug => ['--slug', slug]), ...(opts.requests ?? []).flatMap(id => ['--request', id])];
return ['gbrain', 'repair', 'file-drift', '--source', sourceId, ...select, ...(opts.only ?? []).flatMap(glob => ['--only', glob]), ...(opts.skip ?? []).flatMap(glob => ['--skip', glob]), '--json'];
}
function validateOptions(scope: RepairScope, opts: RepairPlanOptions | undefined): asserts opts is RepairPlanOptions & { prefer: DriftSide } {
validateSelection(scope, opts);
if (opts.prefer !== 'file' && opts.prefer !== 'database') throw opError('invalid_params', 'gbrain repair file-drift needs --prefer file or --prefer database to resolve pages.',
`Nothing was written. Choose the side whose content wins (protected metadata, tags union, protected takes and private facts are kept either way); the comparison in fix shows each page's newer side first: ${USAGE}`,
{ fix: readFix('Compares each selected page with its file and names the newer side and what a repair would do, writing nothing.', { argv: compareArgv(scope.source_ids[0]!, opts) }) });
if (opts.side === 'deleted' && !opts.state) throw stateRequired(scope.source_ids[0]!, opts, FILE_DRIFT_DELETED_STATES);
}
function validateSelection(scope: RepairScope, opts: RepairPlanOptions | undefined): asserts opts is RepairPlanOptions {
if (opts?.remote !== false) throw trustedCliRequired('gbrain repair file-drift runs only for the trusted local CLI on the brain host.');
const usage = USAGE;
if (scope.source_ids.length !== 1) throw opError('invalid_params', 'gbrain repair file-drift needs exactly one --source.', `Name the source: ${usage}`);
const modes = [opts.slugs?.length ? 1 : 0, opts.requests?.length ? 1 : 0, opts.allDrifted ? 1 : 0, opts.held ? 1 : 0].reduce((a, b) => a + b, 0);
if (modes !== 1) throw opError('invalid_params', 'Select pages one way: --slug, --request, --all-drifted or --held.', `Pick one selection: ${usage}`);
if ((opts.side || opts.state) && !opts.held) throw opError('invalid_params', '--side and --state only narrow --held.', `Drop them, or select the held pages with --held: ${usage}`);
if (opts.cursor && !opts.held) throw opError('invalid_params', '--cursor only continues a --held preview.', `Drop --cursor, or continue the held preview that printed it: ${usage}`);
if (opts.side && !(FILE_DRIFT_SIDES as readonly string[]).includes(opts.side)) throw opError('invalid_params', `Unknown file-drift side '${opts.side}'.`,
`Pass --side ${FILE_DRIFT_SIDES.join(', --side ')}; gbrain sources status ${scope.source_ids[0]} --json lists each held file's side.`);
if (opts.state && !(FILE_DRIFT_DELETED_STATES as readonly string[]).includes(opts.state)) throw opError('invalid_params', `Unknown deleted-side state '${opts.state}'.`,
`Pass --state ${FILE_DRIFT_DELETED_STATES.join(', --state ')} with --side deleted; gbrain sources status ${scope.source_ids[0]} --json lists each held file's state.`);
if (opts.state && opts.side !== 'deleted') throw opError('invalid_params', '--state only narrows --side deleted.', `Drop --state, or pass --side deleted with it: ${usage}`);
if (opts.provenance && !(DELETION_PROVENANCES as readonly string[]).includes(opts.provenance)) throw opError('invalid_params', `Unknown deletion provenance '${opts.provenance}'.`,
`Pass --provenance ${DELETION_PROVENANCES.join(', --provenance ')}; each page of a --held --side deleted --state file_gone preview names its provenance.`);
if (opts.provenance && opts.state !== 'file_gone') throw opError('invalid_params', '--provenance only narrows --held --side deleted --state file_gone.',
`Add --held --side deleted --state file_gone, or drop --provenance: ${usage}`);
if (opts.provenance === 'never_committed' && opts.prefer === 'file') throw opError('invalid_params', 'A never-committed held file cannot be resolved --prefer file.',
`Nothing was previewed. No commit ever held these files, so each page holds the only copy of its content and --prefer file would soft-delete it (purged after ${GHOST_PURGE_FUSE_HOURS} h). `
+ `Keep them database-only with --prefer database, or preview one page alone with --slug when its deletion is really intended.`);
if (opts.driftClass && !opts.allDrifted) throw opError('invalid_params', '--class only narrows --all-drifted.', `Drop --class, or use it with --all-drifted: ${usage}`);
if (opts.since && !opts.allDrifted) throw opError('invalid_params', '--since only narrows --all-drifted.', `Drop --since, or use it with --all-drifted: ${usage}`);
if (opts.driftClass && !(DRIFT_CLASSES as readonly string[]).includes(opts.driftClass)) throw opError('invalid_params', `Unknown drift class '${opts.driftClass}'.`,
`Pass one of ${DRIFT_CLASSES.join(', ')}; the conflict audit lists each drifted page's class.`);
for (const slug of opts.slugs ?? []) {
try { validateSlug(slug); } catch { throw opError('invalid_params', `Invalid page slug '${slug}'.`, 'Pass each page by its exact stored slug.'); }
}
for (const glob of [...(opts.only ?? []), ...(opts.skip ?? [])]) {
try { validateSlug(glob); } catch {
throw opError('invalid_params', `Invalid file path glob '${glob}'.`,
`--only and --skip take a canonical file path relative to the source, without a leading / or .. segment: an exact path, or (file-drift only) a glob where * matches within one path segment and ** across segments (e.g. --only concepts/agi.md or --only 'concepts/**'). ${usage}`);
}
}
if (opts.requests?.some(id => !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id))) {
throw opError('invalid_params', '--request takes a conflict receipt request UUID.', 'Pass the request id the conflict audit lists (last_conflict_request_id).');
}
}
/**
* The bare `gbrain repair file-drift` (the explicit-only preview command doctor and `repair --all` print): a read-only
* survey of the drifted pages per source with their drift class and the preview command for each class. Nothing to apply.
*/
async function survey(engine: BrainEngine, scope: RepairScope, opts: Pick<RepairPlanOptions, 'since'>): Promise<RepairPlan> {
const listing: NonNullable<RepairPlan['listing']> = [];
const residuals: Record<string, number> = {};
const next: string[] = [];
for (const sourceId of scope.source_ids) {
const counts = new Map<DriftClass, number>();
let cursor: string | undefined;
let seen = 0;
do {
const page = await auditDriftConflicts(engine, sourceId, { trusted: true, excludePrivate: false }, { limit: 100, cursor });
for (const row of page.conflicts) {
if (row.still_present.value === false || !sinceSelects(row.last_seen, opts.since)) continue;
if (row.still_present.value === null) {
residuals[`unknown_${row.still_present.reason}`] = (residuals[`unknown_${row.still_present.reason}`] ?? 0) + 1;
listing.push({ item: `${sourceId}:${row.slug}`, class: 'unknown', detail: unknownDriftDetail(sourceId, { slug: row.slug, reason: row.still_present.reason }) });
continue;
}
const kind = row.class ?? 'error';
counts.set(kind, (counts.get(kind) ?? 0) + 1);
residuals[`drifted_${kind}`] = (residuals[`drifted_${kind}`] ?? 0) + 1;
listing.push({ item: `${sourceId}:${row.slug}`, class: kind, detail: `${row.drift_receipts} conflict receipt(s)` });
}
seen += page.conflicts.length;
cursor = page.next ?? undefined;
} while (cursor && seen < ALL_DRIFTED_LIMIT);
for (const kind of counts.keys()) next.push(previewCommand(sourceId, { apply: false, allDrifted: true, driftClass: kind, ...(opts.since ? { since: opts.since } : {}), prefer: 'file' }));
}
return { items: [], residuals, listing, details: { survey: true,
next_actions: next.length ? [...next.map(command => `Preview: ${command} (or --prefer database)`), 'Or preview single pages with --slug <slug>.'] : [] } };
}
/** #6948: a page is repaired from a file only when it is that file's canonical page; a twin (or an ambiguous file) is refused `origin_conflict`. */
async function refuseForeignOrigin(engine: BrainEngine, sourceId: string, slug: string, origin: string): Promise<void> {
const owner = await canonicalOriginPage(engine, sourceId, origin);
if (!owner || !('ambiguous' in owner) && owner.slug === slug) return;
throw opError('page_identity_changed', `Another live page of source ${sourceId} owns ${origin}, so ${slug} is not repaired from it.`,
'ambiguous' in owner ? originConflictMessage(sourceId, origin, owner.ambiguous)
: `Page ${owner.slug} is the canonical page of ${origin}; repair it with --slug ${owner.slug}, or preview gbrain repair origin-twins --source ${sourceId} to merge ${slug} into it.`,
{ detail: 'origin_conflict', fix: originTwinsFix(sourceId) });
}
/**
* One drifted page resolved with `prefer` winning, as a ready reconcile preview: the preferred side's decisions over
* reconcile's protections, the size check, and the exceptions. Throws `invalid_params` when a path still needs a
* human decision. The caller runs it as the trusted local CLI and has checked the page is still drifted.
*/
export async function prepareDriftPage(engine: BrainEngine, sourceId: string, slug: string, prefer: DriftSide, assessmentAt: string,
opts: { fileGone?: boolean } = {}): Promise<ArtifactPage> {
const snapshotRow = await engine.readPageSnapshot(slug, { sourceId });
if (snapshotRow?.page.source_path) await refuseForeignOrigin(engine, sourceId, slug, snapshotRow.page.source_path);
const adopt = !opts.fileGone && !!snapshotRow && recordsNoFileOrigin(snapshotRow.page);
const state = await readReconcileState(engine, sourceId, slug, assessmentAt, { adoptSlugPath: adopt, ...(opts.fileGone ? { fileGone: true } : {}) });
if (opts.fileGone && state.pins.raw_file_hash !== ABSENT_FILE_HASH) throw opError('source_changed', 'The canonical file reappeared during the preview.',
`Nothing was written. The canonical file of ${slug} in '${sourceId}' exists again; preview the page again.`);
if (adopt && state.originSourcePath) await refuseForeignOrigin(engine, sourceId, slug, state.originSourcePath);
const database = reconcileCanonical(state.snapshot.page, state.snapshot.tags);
const file = reconcileCanonical(state.file, state.file.tags);
const decisions = preferSideDecisions(state.file, database, prefer);
await assertReconcileRevision(engine, state.snapshot, sourceId, slug);
const discards = prefer === 'database' && discardedFilePaths(state.file, database, decisions).length ? await unimportedFile(engine, state) : null;
const prepared = await prepareReconcileResult(engine, state, decisions);
if (prepared.conflicts.length || !prepared.ready) throw opError('invalid_params', 'Some paths still need a decision.',
`Preview ${slug} with gbrain sources reconcile ${sourceId} ${slug} --brain host --preview --out <file> and resolve it there.`);
// GBRA-133: file wins keeps the file's bytes and only appends protected parts; a result that needs a re-render refuses here.
const raw = state.raw.toString('utf8');
const appends = prefer === 'file' && !opts.fileGone && fileWinsContent(raw, state.file, prepared.result, text => readCanonicalFileText(state, slug, text), { sourceId, slug }) !== raw;
const preview: ReconcileArtifact = { format_version: 1, preview_id: randomUUID(), preconditions: state.pins,
preimages: JSON.parse(stableJson({ file_base64: state.raw.toString('base64'), database: state.snapshot, stored_page: state.storedPage })),
decisions, conflicts: [], result: prepared.result, result_digest: digest(prepared.result), status: 'ready' };
await assertReconcileSize(engine, preview);
// The apply reads this preview back from the artifact file and refuses one its validation rejects; refuse it here instead.
try { validateReconcileArtifact(JSON.parse(stableJson(preview))); } catch (error) {
if (error instanceof OperationError && !error.fix) error.fix = readFix(`gbrain wrote a reconcile preview of ${slug} that its own apply refuses, so nothing was approved or written; report it with the output of gbrain doctor --json (the command in fix).`, { argv: ['gbrain', 'doctor', '--json'] });
throw error;
}
const rendered = (page: ParsedPage) => serializePageToMarkdown({ ...state.snapshot.page, ...page }, page.tags);
const lost_lines = opts.fileGone ? 0 : linesNotCarried(rendered(prefer === 'database' ? file : database), rendered(prepared.result));
return { slug, prefer, adopt_slug_path: adopt, exceptions: driftExceptions(prepared.result, prefer === 'file' ? file : database), result: prepared.result, preview, lost_lines,
...(opts.fileGone ? { file_gone: true as const } : {}), ...(appends ? { file_appended: true as const } : {}), ...(discards ? { discards } : {}) };
}
/**
* #6712 wave: the resolution of a selected page whose canonical file is gone (`canonical_file_missing`), or the reason it
* is skipped. Only a deletion gone from HEAD is file-drift's; one still committed at HEAD routes elsewhere.
*/
async function fileGonePage(engine: BrainEngine, sourceId: string, slug: string, opts: RepairPlanOptions & { prefer: DriftSide }, assessmentAt: string, target?: HeldTarget):
Promise<{ page: PlannedPage; detail: string } | { skip: string; detail: string }> {
const now = await ghostPageNow(engine, sourceId, slug);
if (!now.ghost) return { skip: `unknown_${now.reason}`, detail: now.reason };
if (!opts.allDrifted && !opts.held && !selectedByGlobs(now.ghost.path, opts)) return { skip: 'not_selected', detail: now.ghost.path };
const binding = await getWorktreeBinding(engine, sourceId);
const root = join(binding!.local_path!, binding!.relative_path);
const deletion = canonicalDeletionState(root, join(root, ...now.ghost.path.split('/')));
if (deletion !== 'gone') return { skip: deletion === 'in_head' ? 'deletion_uncommitted' : 'unknown_deletion_state', detail: missingFileRoute(sourceId, slug, now.ghost.path, deletion) };
// GST-2584: a file that moved left this page behind; neither side of this repair carries it, the fold does.
const deletedBy = target?.provenance ?? (await readDeletionProvenance(root, [now.ghost.path])).get(now.ghost.path) ?? { kind: 'unknown' as const };
const moved = await readMovedPage(engine, { sourceId, root, old: { page_id: now.ghost.page_id, slug, revision: now.ghost.revision, path: now.ghost.path }, provenance: deletedBy });
if (moved.verdict === 'moved') return { skip: 'moved_to', detail: `${moved.detail}; nothing is written for it here. Fold it into ${moved.survivor.slug} instead (its alias, links, facts, timeline and saved versions carried, the old page soft-deleted and restorable): ${shellQuote(movedPagesPreviewArgv(sourceId, slug))}` };
if (opts.prefer === 'file' && sourceDbOnlyVerdict(root, slug) === 'unknown') return { skip: 'storage_invalid',
detail: `gbrain.yml's storage section is invalid or ambiguous about db_only, so whether ${slug} is database-only is unknown and --prefer file would delete it (#8007): run gbrain storage status, fix gbrain.yml, commit it, then sync source ${sourceId} again` };
if (opts.provenance === 'never_committed' && target?.provenance?.kind === 'never_committed') {
return { page: { slug, prefer: 'database', exceptions: [], detach_page: { path: now.ghost.path, page_id: now.ghost.page_id, revision: now.ghost.revision, observed_at: target.hold.observed_at } },
detail: `keeps the page database-only: no commit ever held ${now.ghost.path}, so the page holds the only copy; no file is written and the page forgets that path` };
}
if (opts.prefer === 'file' && !await ghostFileBacked(engine, now.ghost, now.owner)) return { skip: DATABASE_AHEAD_CODE, detail: databaseAheadDetail(now.ghost) };
if (opts.prefer === 'file') return { page: { slug, prefer: 'file', exceptions: [], soft_delete: { ghost: now.ghost, owner: now.owner } },
detail: `soft-deletes the page: its file ${now.ghost.path} is gone from the last commit (purged after ${GHOST_PURGE_FUSE_HOURS} h; gbrain restore ${slug} --force undoes it until then)` };
// GST-2579: recreating the file undoes the commit that deleted it; in bulk the deletion is kept, an exact --slug names the commit and needs consent.
const undone: UnimportedFile | null = deletedBy.kind === 'never_committed' ? null : { path: now.ghost.path, reason: 'unimported_delete',
commit: deletedBy.kind === 'deleted_by_commit' ? { sha: deletedBy.commit, author: deletedBy.author, date: deletedBy.date } : null };
if (undone && !opts.slugs?.length) return { skip: 'kept_newer_delete', detail: `kept the deletion, nothing is written for it: recreating the file would undo ${unimportedFileText(undone)}. `
+ `Delete the page with --prefer file, or, if the user decides to bring the file back, preview the page alone: gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer database` };
const page = await prepareDriftPage(engine, sourceId, slug, 'database', assessmentAt, { fileGone: true });
if (page.preview.preconditions.revision !== now.ghost.revision || page.preview.preconditions.relative_path.split(sep).join('/') !== now.ghost.path) {
throw opError('source_changed', 'The page or its canonical path changed during the preview.', `Nothing was written. Preview ${slug} in '${sourceId}' again.`);
}
if (undone) page.discards = undone;
return { page, detail: `${undone ? `undoes ${unimportedFileText(undone)}; ` : ''}recreates its missing file ${now.ghost.path} from the page` };
}
/**
* #6712 PR 4b: the resolution of a held file whose page is deleted (design v3.2 §4): a tombstone at its origin
* (`tombstone_edited`) or a deletion marker with no page row left (`purged_differs`). `--prefer database` keeps the
* deletion and removes the file through a coordinated publication; `--prefer file` imports the file's bytes through the
* managed file repair, which restores the tombstone or creates a new page and leaves the marker for sync to retire.
*/
async function deletedPage(engine: BrainEngine, sourceId: string, target: HeldTarget & { state: 'tombstone_edited' | 'purged_differs' }, prefer: DriftSide, mirror: boolean):
Promise<{ page: PlannedPage; detail: string } | { skip: string; detail: string }> {
const { hold, state } = target;
if (mirror && prefer === 'database' && hold.meta.keep_deleted) return { skip: 'mirror_keep_deleted',
detail: `the user already kept this deletion (${hold.meta.keep_deleted.decided_at}); the hold is carried (mirror_keep_deleted) until the upstream edits ${hold.path} again` };
const live = await readDeletedDriftTarget(engine, sourceId, { path: hold.path, sourcePath: hold.source_path, pageId: hold.page_id });
if ('changed' in live) return { skip: `resolved_${live.changed}`, detail: DELETED_CHANGES[live.changed] };
if (live.state !== state) return { skip: 'state_changed', detail: `it is ${live.state} now; preview it with ${shellQuote(heldDriftPreviewArgv(sourceId, 'deleted', live.state, prefer, hold.path))}` };
const slug = live.tombstone?.slug ?? hold.slug ?? resolveSlugForPath(hold.source_path);
const pin: DeletedDriftPin = { state, path: hold.path, source_path: hold.source_path, raw_file_hash: live.raw_file_hash, page_id: live.tombstone?.page_id ?? null,
revision: live.tombstone?.revision ?? null, marker_digest: live.marker_digest, observed_at: hold.observed_at };
if (mirror && prefer === 'database' && state === 'tombstone_edited') return { page: { slug, prefer, exceptions: [], keep_deleted: pin },
detail: `${KEEP_DELETED_VERB}: ${hold.path}` };
const detail = `${fileDriftActionVerb('deleted', state, prefer)}: ${hold.path}`;
if (prefer === 'database') return { page: { slug, prefer, exceptions: [], remove_file: pin }, detail };
const snapshot = await engine.readPageSnapshot(slug, { sourceId, includeDeleted: true });
if ((snapshot ? Number(snapshot.page.id) : null) !== pin.page_id) {
return { skip: 'slug_taken', detail: `page ${slug} already exists for another file, so ${hold.path} cannot be imported under that slug; give the file a slug: line of its own, commit it and sync` };
}
const content = live.raw.toString('utf8');
if (!Buffer.from(content).equals(live.raw)) throw opError('invalid_params', 'The held file must contain valid UTF-8.', `Nothing changed. Re-save ${hold.path} in '${sourceId}' as UTF-8, then preview it again.`);
const publication = await prepareRepairPublication(engine, { sourceId, slug, sourcePath: hold.source_path, path: hold.path, root: live.root, content, snapshot, base: snapshot,
...await repairScreenConfig(engine, sourceId) });
if (publication.status !== 'ready') throw opError('invalid_params', `${hold.path} does not import as written (${publication.status === 'refused' ? publication.refusal.code : 'it would store a canonical overlay'}).`,
`Nothing changed. Fix the file, commit it and sync, or preview --prefer database to keep the deletion: ${shellQuote(heldDriftPreviewArgv(sourceId, 'deleted', state, 'database', hold.path))}`);
return { page: { slug, prefer, exceptions: [], import_file: { ...pin, result_digest: publication.digest } }, detail };
}
const KEEP_DELETED_VERB = 'keep the deletion and record it on the hold (the read-only mirror keeps its file)';
/**
* Records a mirror's kept deletion on its hold, bound to the previewed pin: the file's bytes, the tombstone's id and revision
* and the hold the preview observed. Writes no file and no page; a source that is no longer a read-only mirror is refused, and
* the caller's CLI grant must cover the page as it does for every other file-drift page.
*/
async function applyKeepDeleted(ctx: OperationContext, page: ApprovedPage, artifact: KeepDeletedPage, requestId: string): Promise<RepairItemOutcome> {
const pin = artifact.keep_deleted;
const changed = (why: string): RepairItemOutcome => ({ applied: false, outcome: 'changed_since_preview', reason: 'changed_since_preview',
detail: { request_id: requestId, action: 'keep_deleted', message: `${pin.path} changed since its keep-the-deletion was previewed: ${why}.`,
fix: repreviewFix(page, heldDriftPreviewArgv(page.source_id, 'deleted', pin.state, 'database', pin.path)) } });
if (!await sourceMirrorReadOnly(ctx.engine, page.source_id)) return changed('the source is no longer a read-only mirror');
await asLocalCli(ctx.engine, () => authorizeReconcileGrant(ctx.engine, page.source_id, page.slug));
try { await assertDeletedPin(ctx.engine, page.source_id, pin); } catch (error) {
if (error instanceof OperationError && error.code === 'changed_since_preview') return changed(error.message);
throw error;
}
const [source] = await ctx.engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [page.source_id]);
const recorded = await ctx.engine.transaction(tx => recordKeepDeleted(tx, { sourceId: page.source_id, incarnation: source!.incarnation, path: pin.path, observedAt: pin.observed_at,
state: pin.state, decision: { request_id: requestId, decided_at: new Date().toISOString(), page_id: pin.page_id, revision: pin.revision } }));
if (!recorded) return changed('its hold was re-checked or cleared');
return { applied: true, outcome: 'repaired', detail: { request_id: requestId, prefer: 'database', action: 'keep_deleted', state: pin.state } };
}
/** #6712 PR 4b: the deleted-side pin as the preview hash and the publication read it again. */
async function assertDeletedPin(engine: BrainEngine, sourceId: string, pin: DeletedDriftPin): Promise<DeletedDriftTarget> {
const live = await readDeletedDriftTarget(engine, sourceId, { path: pin.path, sourcePath: pin.source_path, pageId: pin.page_id });
const why = 'changed' in live ? DELETED_CHANGES[live.changed] : live.state !== pin.state ? `it is ${live.state} now`
: live.raw_file_hash !== pin.raw_file_hash ? 'the file bytes changed'
: (live.tombstone?.page_id ?? null) !== pin.page_id || (live.tombstone?.revision ?? null) !== pin.revision ? 'the deleted page changed'
: live.marker_digest !== pin.marker_digest ? 'its deletion marker changed' : null;
if ('changed' in live || why !== null) throw opError('changed_since_preview', `${pin.path} changed since its file-drift resolution was previewed: ${why}.`,
`Nothing was written for ${pin.path}. Preview again with ${shellQuote(heldDriftPreviewArgv(sourceId, 'deleted', pin.state, 'database', pin.path))} (or --prefer file) and apply its new hash.`,
{ fix: readFix('Lists the held files of this source with their side and state, read-only.', { argv: ['gbrain', 'sources', 'status', sourceId, '--json'] }) });
return live;
}
/**
* #6712 PR 4b: the preparer of `managed_maintenance_file_drift_remove`, the coordinated removal of a held file whose page is
* deleted. It re-reads the deleted side bound to the preview (file bytes, tombstone id and revision or marker value) here
* and again under the publication guard, removes the file through the page file target (a recovery record, the Git
* effect commits the removal) and clears the hold it resolves in the publishing transaction. The page row is untouched.
*/
export async function prepareDriftFileRemoval(engine: BrainEngine, row: WriteRequest): Promise<PreparedMutation> {
const pin = row.intent?.target as DeletedDriftPin | undefined;
if (row.authority.remote || !pin || typeof pin.path !== 'string' || typeof pin.source_path !== 'string' || typeof pin.raw_file_hash !== 'string'
|| (pin.page_id ?? null) !== (row.page_id === null || row.page_id === undefined ? null : Number(row.page_id))) {
throw opError('invalid_params', 'The file-drift removal intent does not name its held file.',
`Request ${row.request_id} in source ${row.source_id} does not name the held file it removes, so nothing changed. Preview the repair again with gbrain repair file-drift --source ${row.source_id} --held --side deleted.`);
}
const live = await assertDeletedPin(engine, row.source_id, pin);
return { observedRevision: pin.revision, file: { root: live.root, path: live.path, content: null, expectedBeforeHash: pin.raw_file_hash },
validate: async tx => { await assertDeletedPin(tx, row.source_id, pin); },
apply: async tx => ({ status: 'file_removed', slug: row.slug, source_id: row.source_id, path: pin.path, state: pin.state,
hold_cleared: await clearGitHold(tx, { sourceId: row.source_id, incarnation: row.source_incarnation, path: pin.path, observedAt: pin.observed_at }) }) };
}
/**
* GBRA-133: the preparer of `managed_maintenance_file_drift_detach`. It re-checks, here and under the publication guard, that
* the page is the previewed one (id, revision, recorded path), still live with its file missing, and that no commit of HEAD's
* history holds the path. The apply clears the page's recorded file (`database_only_reason=detached`, so no sync reads the
* missing file as a deletion again) and the hold it resolves in the publishing transaction; no file is written.
*/
export async function prepareDriftDetach(engine: BrainEngine, row: WriteRequest): Promise<PreparedMutation> {
const pin = row.intent?.target as DetachPin | undefined;
if (row.authority.remote || !pin || typeof pin.path !== 'string' || typeof pin.revision !== 'string' || typeof pin.observed_at !== 'string'
|| pin.page_id !== (row.page_id === null || row.page_id === undefined ? null : Number(row.page_id))) {
throw opError('invalid_params', 'The file-drift database-only intent does not name its page.',
`Request ${row.request_id} in source ${row.source_id} does not name the held page it keeps, so nothing changed. Preview the repair again with gbrain repair file-drift --source ${row.source_id} --held --side deleted --state file_gone --provenance never_committed --prefer database.`);
}
const changed = (why: string) => opError('changed_since_preview', `${pin.path} changed since its database-only keep was previewed: ${why}.`,
`Nothing was written for ${row.slug}. Preview again with gbrain repair file-drift --source ${row.source_id} --held --side deleted --state file_gone --provenance never_committed --prefer database and apply its new hash.`,
{ fix: readFix('Lists the held files of this source with their side and state, read-only.', { argv: ['gbrain', 'sources', 'status', row.source_id, '--json'] }) });
const now = await ghostPageNow(engine, row.source_id, row.slug);
if (!now.ghost) throw changed(`the page is no longer a live page whose file is missing (${now.reason})`);
if (now.ghost.page_id !== pin.page_id || now.ghost.revision !== pin.revision || now.ghost.path !== pin.path) throw changed('the page, its revision or its recorded path changed');
const binding = await getWorktreeBinding(engine, row.source_id);
const found = (await readDeletionProvenance(join(binding!.local_path!, binding!.relative_path), [pin.path])).get(pin.path);
if (found?.kind !== 'never_committed') throw changed(`its provenance is ${found?.kind ?? 'unknown'} now`);
const locked = async (tx: BrainEngine) => {
const [page] = await tx.executeRaw<{ id: number }>('SELECT id FROM pages WHERE id=$1 AND source_id=$2 AND slug=$3 AND deleted_at IS NULL AND source_path IS NOT NULL', [pin.page_id, row.source_id, row.slug]);
if (!page) throw changed('the page was deleted, renamed or already forgot its file');
};
return { observedRevision: pin.revision, databaseOnlyReason: 'detached',
validate: async tx => { await locked(tx); },
apply: async tx => {
await tx.executeRaw('UPDATE pages SET source_path=NULL, source_uri=NULL, database_only_reason=$2 WHERE id=$1', [pin.page_id, DETACHED_REASON]);
return { status: 'detached', slug: row.slug, source_id: row.source_id, path: pin.path,
hold_cleared: await clearGitHold(tx, { sourceId: row.source_id, incarnation: row.source_incarnation, path: pin.path, observedAt: pin.observed_at }) };
} };
}
/**
* #6712 PR 4b: one held deleted-side page applied as previewed. `remove_file` admits the coordinated removal, bound to the
* pin; `import_file` re-reads the pin and submits the managed file repair of the exact previewed bytes and result.
*/
async function applyDeletedSide(ctx: OperationContext, page: ApprovedPage, artifact: RemoveFilePage | ImportFilePage | DetachPage, requestId: string, embed: boolean): Promise<RepairItemOutcome> {
const action = 'remove_file' in artifact ? 'remove_file' : 'import_file' in artifact ? 'import_file' : 'detach_page';
try {
if ('detach_page' in artifact) {
const authority = await maintenancePreflight(ctx.engine, page.source_id);
if (!authority) throw opError('owner_unavailable', 'Keeping a held page database-only needs the managed write path.',
`Managed persistence is off for this brain, so ${artifact.detach_page.path} was not resolved. Held file-drift pages exist only on managed sources; check the source with gbrain sources status ${page.source_id} --json.`);
// Database-only: no file is staged, so the missing file the page still records is not refused before admission.
await submitDatabaseMaintenanceIntent(ctx.engine, authority, artifact.slug, { kind: FILE_DRIFT_DETACH_INTENT, expected_revision: artifact.detach_page.revision, target: artifact.detach_page }, requestId);
return { applied: true, outcome: 'repaired', detail: { request_id: requestId, prefer: 'database', action } };
}
const pin = 'remove_file' in artifact ? artifact.remove_file : artifact.import_file;
if ('remove_file' in artifact) {
await assertDeletedPin(ctx.engine, page.source_id, pin);
const authority = await maintenancePreflight(ctx.engine, page.source_id);
if (!authority) throw opError('owner_unavailable', 'Removing a held file needs the managed write path.',
`Managed persistence is off for this brain, so ${pin.path} was not removed. Held file-drift pages exist only on managed sources; check the source with gbrain sources status ${page.source_id} --json.`);
await submitMaintenanceIntent(ctx.engine, authority, artifact.slug, { kind: FILE_DRIFT_REMOVE_INTENT, expected_revision: pin.revision,
...(pin.page_id !== null ? { deleted_page: true } : {}), target: pin }, requestId);
} else {
const live = await assertDeletedPin(ctx.engine, page.source_id, pin);
await asLocalCli(ctx.engine, () => submitManagedFileRepair(ctx, { sourceId: page.source_id, requestId, slug: artifact.slug, path: pin.path, sourcePath: pin.source_path,
content: live.raw.toString('utf8'), beforeHash: pin.raw_file_hash, resultDigest: artifact.import_file.result_digest, ...(pin.revision ? { expected_revision: pin.revision } : {}),
noEmbed: !embed, holdObservedAt: pin.observed_at }));
}
return { applied: true, outcome: 'repaired', detail: { request_id: requestId, prefer: artifact.prefer, action, state: pin.state } };
} catch (error) {
if (acceptedPendingReceipt(error) || !(error instanceof OperationError) || ['owner_unavailable', 'writer_lock_unavailable', 'writer_busy', 'write_pending'].includes(error.code)) throw error;
const changed = ['changed_since_preview', 'revision_conflict', 'page_identity_changed', 'page_not_found', 'source_changed'].includes(error.code);
return { applied: false, outcome: changed ? 'changed_since_preview' : 'refused', reason: error.code,
detail: { request_id: requestId, action, message: error.message, ...(error.why ? { why: error.why } : {}), fix: error.fix ?? repreviewFix(page, 'detach_page' in artifact
? ['gbrain', 'repair', 'file-drift', '--source', page.source_id, '--held', '--side', 'deleted', '--state', 'file_gone', '--provenance', 'never_committed', '--only', artifact.detach_page.path, '--prefer', 'database']
: heldDriftPreviewArgv(page.source_id, 'deleted', ('remove_file' in artifact ? artifact.remove_file : artifact.import_file).state, artifact.prefer,
('remove_file' in artifact ? artifact.remove_file : artifact.import_file).path)) } };
}
}
/**
* GST-2579: an unbound collision (#5254: a page an unbound write left database-only, and a file at its slug path that differs)
* read as drift, so an exact --slug selection resolves it. `sources reconcile` refuses to take its database side over a file
* the database never held and names this step, whose apply records the file as the page's origin and needs consent.
*/
async function unboundCollisionDrift(engine: BrainEngine, sourceId: string, slug: string): Promise<LiveDrift | null> {
if (!await isUnboundSourcePage(engine, sourceId, slug)) return null;
try {
const state = await readReconcileState(engine, sourceId, slug);
if (classifyDrift(state.file, reconcileCanonical(state.snapshot.page, state.snapshot.tags)).verdict === 'no_drift') return null;
return { still_present: true, reason: 'unbound_collision', db_revision: state.snapshot.revision, path: relative(state.root, state.path).split(sep).join('/'), file_hash: sha256(state.raw) };
} catch (error) {
if (error instanceof OperationError) return null;
throw error;
}
}
/** GBRA-133: re-checks a held page whose page and file agreed at the preview and schedules its re-screen (`sources retry-held` for one path). */
async function releaseAgreedHold(engine: BrainEngine, page: ApprovedPage, pin: ReleasePin, requestId: string): Promise<RepairItemOutcome> {
const hold = await readGitHold(engine, page.source_id, pin.incarnation, pin.path);
if (hold?.observed_at !== pin.observed_at) {
return { applied: false, outcome: 'changed_since_preview', reason: 'hold_changed',
detail: { request_id: requestId, action: 'release_hold', message: `The hold on ${pin.path} changed since the preview; preview it again.` } };
}
const live = await heldLiveDrift(engine, page.source_id, page.slug, { hold, mirror: await sourceMirrorReadOnly(engine, page.source_id) });
if (live.reason !== 'agrees' || live.db_revision !== pin.revision || (live.file_hash ?? null) !== pin.file_hash) {
return { applied: false, outcome: 'changed_since_preview', reason: 'revision_conflict',
detail: { request_id: requestId, action: 'release_hold', message: `The page or ${pin.path} changed since the preview (${live.reason}); preview it again.` } };
}
await requestGitHoldRetry(engine, page.source_id, pin.incarnation, [pin.path]);
return { applied: true, outcome: 'repaired', detail: { request_id: requestId, action: 'release_hold', path: pin.path } };
}
/**
* Whole-class C1: why a held page on a read-only mirror is kept when letting its file win would append gbrain's protected parts
* (protected keys, takes, private facts, database-only timeline rows) to the file, and its next step.
*/
export function keptProtectedPartsDetail(sourceId: string, slug: string): string {
return `kept: letting the file win would append gbrain's protected parts of page ${slug} (protected keys, takes, private facts or timeline rows) to its file, and this read-only mirror's checkout is never written, so the page stays held with nothing written. `
+ `Carry those parts into the upstream file and commit it there, then run gbrain sync --source ${sourceId}; the comparison shows what differs: gbrain repair file-drift --source ${sourceId} --slug ${slug} --json`;
}
/** GBRA-133: one held gone file's provenance, as the preview lists it. */
function provenanceText(found: DeletionProvenance): string {
if (found.kind === 'deleted_by_commit') return `deleted by commit ${found.commit.slice(0, 12)} (${found.date}, ${found.author}: ${found.subject})`;
return found.kind === 'never_committed' ? 'never committed: no commit held the file' : found.kind === 'deletion_uncommitted' ? 'deletion uncommitted: HEAD still holds the file'
: 'provenance unknown: Git could not name the deleting commit';
}
/** The next step after a page's apply refused or found it changed: the preview that selects it again (read-only), which names its current refusal or a fresh apply command. */
function repreviewFix(page: ApprovedPage, argv: string[]) {
return readFix(`Previews ${page.slug} in '${page.source_id}' again: it re-reads the page and its file and prints the current refusal with its fix, or a new apply command.`, { argv });
}
function item(page: ApprovedPage, index: number, hash: string, last: boolean, prefer: DriftSide): DriftItem {
return { cursor: { phase: 0, id: index + 1 }, source_id: page.source_id, slug: page.slug, chars: 0, action: `prefer_${prefer}`, page, hash, last };
}
/**
* GST-2568: the selection compared with no winner named (file-drift-compare.ts): per page what differs, which side is newer
* and what a repair would do. Reads only; it prints no apply command, and a held selection is windowed as a preview is.
*/
async function compareSelection(engine: BrainEngine, sourceId: string, opts: RepairPlanOptions): Promise<RepairPlan> {
const held = opts.held ? await selectHeld(engine, sourceId, opts) : null;
const selected = held ? null : await selectSlugs(engine, sourceId, opts);
const mirror = held ? await sourceMirrorReadOnly(engine, sourceId) : false;
const targets: { slug: string | null; hold?: GitHoldRecord; mirror?: boolean }[] = held ? [...held.legacy.map(hold => ({ slug: hold.slug, hold, mirror })), ...held.targets.slice(0, HELD_WINDOW_PAGES).map(target => ({ slug: target.hold.slug, hold: target.hold, mirror }))]
: selected!.slugs.map(slug => ({ slug }));
const residuals: Record<string, number> = { ...(held?.notSelected || selected?.notSelected ? { not_selected: held?.notSelected ?? selected!.notSelected } : {}), ...(held?.before ? { before_cursor: held.before } : {}) };
const count = (key: string) => { residuals[key] = (residuals[key] ?? 0) + 1; };
const listing: NonNullable<RepairPlan['listing']> = [];
for (const row of selected?.unknown ?? []) { count(`unknown_${row.reason}`); listing.push({ item: `${sourceId}:${row.slug}`, class: 'unknown', detail: unknownDriftDetail(sourceId, row) }); }
const assessmentAt = new Date().toISOString();
const windowEnd = Math.min(Date.now() + HELD_WINDOW_BUDGET_MS, opts.deadline ?? Infinity);
const pages: ComparedPage[] = [];
let windowed = 0;
opts.progress?.start('repair.file_drift.compare', targets.length);
if (targets.length) await asLocalCli(engine, async () => {
for (const target of targets) {
if (held && pages.length && Date.now() >= windowEnd) break;
opts.progress?.tick(1, target.slug ?? target.hold?.path);
if (target.hold && fileDriftSide(target.hold.meta)) windowed++;
pages.push(await comparePage(engine, sourceId, target, assessmentAt));
}
});
opts.progress?.finish();
for (const page of pages) { count(page.would); listing.push(comparedListing(page)); }
const remaining = held ? held.targets.length - windowed : 0;
const nextCursor = remaining > 0 && windowed > 0 ? heldCursor(held!.targets[windowed - 1]!.hold.path) : undefined;
if (remaining > 0) residuals.after_window = remaining;
const filesNewer = pages.filter(page => page.would === 'prefer_file').length;
const next = [...(filesNewer ? [mirror ? `${filesNewer} page(s) have a newer file; ${mirrorDriftRoute(sourceId, opts.side)}`
: `Preview the file side for the ${filesNewer} page(s) whose file is newer: ${previewCommand(sourceId, { ...opts, prefer: 'file' })} (pages newer than their file are left held, kept_newer_page)`] : []),
...(nextCursor ? [`Compare the next window: ${shellQuote(compareArgv(sourceId, { ...opts, cursor: nextCursor }).slice(0, -1))}`] : [])];
return { items: [], residuals, listing, ...(held ? { complete: remaining === 0 } : {}), details: { compare: true, writes: 'none',
pages: pages.map(({ item: _item, ...page }) => ({ evidence: null, ...page })), ...(next.length ? { next_actions: next } : {}),
...(held ? { window: { previewed: windowed, remaining, complete: remaining === 0, ...(nextCursor ? { next_cursor: nextCursor, next_command: shellQuote(compareArgv(sourceId, { ...opts, cursor: nextCursor })) } : {}) } } : {}),
evidence: 'newer compares the file\'s last commit time at HEAD with the page\'s updated_at; unknown when the file has uncommitted bytes or either time is missing.' } };
}
/**
* GST-2579: the consent wording of a file-drift apply, naming every file edit sync never imported that the previewed
* database-wins resolutions overwrite (the artifact's `discards`), and GST-2568: how many lines of the overwritten copies the
* results do not carry (`lost_lines`).
*/
export function fileDriftConsentText(hash: string, sourceId: string | undefined): { what: string; why: string; risk: string; user_message: string } {
let discards: UnimportedFile[] = [];
let removals: string[] = [];
let losing: number[] = [];
let kept: string[] = [];
let total = 0;
try {
const pages = [...readArtifact(hash, `gbrain repair file-drift --source ${sourceId ?? '<source>'}`).values()];
total = pages.length;
kept = pages.flatMap(page => 'keep_deleted' in page ? [page.keep_deleted.path] : []);
discards = pages.flatMap(page => 'discards' in page && page.discards ? [page.discards] : []);
removals = pages.flatMap(page => 'remove_file' in page ? [page.remove_file.path] : []);
losing = pages.flatMap(page => 'lost_lines' in page && page.lost_lines ? [page.lost_lines] : []);
} catch { /* the apply itself refuses a missing or changed artifact */ }
const list = (items: string[]) => items.slice(0, 10).join('; ') + (items.length > 10 ? `; and ${items.length - 10} more (listed in the preview)` : '');
const named = list(discards.map(unimportedFileText));
const lost = losing.reduce((sum, lines) => sum + lines, 0);
const dropping = lost ? ` It drops ${lost} line(s) that the copies it overwrites hold and the result does not carry, across ${losing.length} page(s).` : '';
if (kept.length && kept.length === total) return {
what: 'Record that the user keeps the deletion of each listed page on the read-only mirror.',
why: `The preview ${hash} listed each deleted page whose file the mirror's upstream edited (${kept.length}).`,
risk: 'Each hold stays and reads as decided (mirror_keep_deleted); no file, page or tombstone changes. A new upstream edit of a file or a restore asks again; a page that changed since the preview is skipped.',
user_message: `Keep the deletion of ${kept.length} page(s) on the read-only mirror? Each hold records the decision and stops asking; nothing is deleted, restored or written: ${list(kept)}.`,
};
const removing = removals.length ? ` It also removes ${removals.length} file(s) that changed after their page was deleted, and the page does not hold what they say: ${list(removals)}.` : '';
return {
what: 'Apply the previewed file-drift resolutions: each listed page takes the preferred side, so either the canonical file is rewritten from the database copy or the page is replaced from the file.',
why: `The preview ${hash} listed each page and the side that wins it${discards.length ? `, and the file edits sync never imported that the database copy overwrites (${discards.length})` : ''}${removals.length ? `, and the files it removes (${removals.length})` : ''}${lost ? `, and the lines the overwritten copies hold that the result drops (${lost})` : ''}.`,
risk: 'The losing side is replaced: a file rewrite is a new commit (git revert brings the edit back) and reconcile keeps a private backup of the replaced copy; a removed file comes back with git revert only when it was committed; a page that changed since the preview is skipped.',
user_message: (discards.length
? `Apply the previewed file-drift repair? It overwrites file edits sync never imported with the database copy: ${named}.`
: 'Apply the previewed file-drift repair? Each listed page takes the side the preview showed, and the other copy is replaced.') + dropping + removing,
};
}
export const fileDriftRepair: RepairHandler = {
kind: 'file-drift',
outcomeItemsLimit: 1000,
async plan(engine, scope, after, opts): Promise<RepairPlan> {
if (opts?.remote === false && !opts.apply && !opts.prefer && !opts.slugs?.length && !opts.requests?.length && !opts.allDrifted && !opts.driftClass && !opts.held && !opts.side && !opts.state && !opts.cursor && !opts.provenance) return survey(engine, scope, opts);
validateSelection(scope, opts);
if (!opts.apply && !opts.prefer) return compareSelection(engine, scope.source_ids[0]!, opts);
validateOptions(scope, opts);
const sourceId = scope.source_ids[0]!;
const command = previewCommand(sourceId, opts);
const only = [...new Set(opts.only ?? [])].sort();
const skip = [...new Set(opts.skip ?? [])].sort();
const selection = digest({ prefer: opts.prefer, slugs: opts.slugs ?? [], requests: opts.requests ?? [], all: opts.allDrifted === true, class: opts.driftClass ?? null,
...(opts.since ? { since: opts.since } : {}), ...(only.length ? { only } : {}), ...(skip.length ? { skip } : {}),
...(opts.held ? { held: true, side: opts.side ?? null, state: opts.state ?? null } : {}), ...(opts.cursor ? { cursor: opts.cursor } : {}) });
if (opts.apply) {
if (!opts.expect) throw new OperationError('invalid_params', 'gbrain repair file-drift --apply applies only the set a preview printed.',
`Preview first: ${command} — then run the apply command it prints with --expect <preview-hash>.`, 'docs/guides/repair.md#explicit-only-repair-kinds');
const approved = await loadApprovedSet<ApprovedPage>(engine, { command: 'file-drift', hash: opts.expect, previewCommand: command,
emptyHash: async () => previewHash({ kind: 'file-drift-v1', brain_id: scope.brain_id, source_id: sourceId, selection, pages: [] }) });
if (approved.items.some(page => page.selection !== selection || page.source_id !== sourceId)) throw previewChangedError(opts.expect, command);
// #6712 wave: soft deletes of pages whose file is gone honor the sync mass-delete valve, as `repair ghost-pages` does.
if (opts.prefer === 'file' && approved.items.length > MASS_RECONCILE_MIN_PAGES * MASS_RECONCILE_RATIO) {
const planned = readArtifact(opts.expect, command);
const deletes = approved.items.filter(page => 'soft_delete' in (planned.get(page.slug) ?? {})).length;
if (deletes > MASS_RECONCILE_MIN_PAGES * MASS_RECONCILE_RATIO) {
const scan = await scanGhostSource(engine, sourceId, { candidateLimit: GHOST_REPAIR_LIMIT });
const refusal = ghostScanRefusal(scan);
if (refusal) throw refusal;
if (massGhosts(deletes, scan.file_backed) && !massReconcileAllowed()) throw massRefusal(sourceId, deletes, scan.file_backed);
}
}
const items = approved.items.map((page, index) => item(page, index, opts.expect!, index === approved.items.length - 1, opts.prefer));
return { items: items.filter(entry => afterCursor(entry.cursor, after)), preview_hash: opts.expect, residuals: {} };
}
const held = opts.held ? await selectHeld(engine, sourceId, opts) : null;
const mirror = held ? await sourceMirrorReadOnly(engine, sourceId) : false;
const mirrorFile = mirror && opts.prefer === 'file';
const { slugs, classes, notSelected, unknown } = held
? { slugs: [], classes: new Map<string, DriftClass>(), notSelected: held.notSelected, unknown: [] as UnknownDrift[] } : await selectSlugs(engine, sourceId, opts);
const assessmentAt = new Date().toISOString();
const pages: PlannedPage[] = [];
const listing: NonNullable<RepairPlan['listing']> = [];
const residuals: Record<string, number> = { ...(notSelected ? { not_selected: notSelected } : {}), ...(held?.before ? { before_cursor: held.before } : {}),
...(held?.otherProvenance ? { other_provenance: held.otherProvenance } : {}) };
const count = (key: string) => { residuals[key] = (residuals[key] ?? 0) + 1; };
for (const hold of held?.legacy ?? []) {
count('legacy_side');
listing.push({ item: `${sourceId}:${hold.slug ?? hold.path}`, class: 'legacy_side',
detail: `held before holds named a side; preview it alone with gbrain repair file-drift --source ${sourceId} --slug ${hold.slug ?? '<slug>'} --prefer ${opts.prefer}` });
}
for (const row of unknown) {
count(`unknown_${row.reason}`);
listing.push({ item: `${sourceId}:${row.slug}`, class: 'unknown', detail: unknownDriftDetail(sourceId, row) });
}
const targets: Array<{ slug: string | null; held?: HeldTarget }> = held ? held.targets.slice(0, HELD_WINDOW_PAGES).map(target => ({ slug: target.hold.slug, held: target })) : slugs.map(slug => ({ slug }));
const windowEnd = Math.min(Date.now() + HELD_WINDOW_BUDGET_MS, opts.deadline ?? Infinity);
let previewed = 0;
const [source] = held ? [] : await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [sourceId]);
const newerPages: string[] = [];
opts.progress?.start('repair.file_drift.preview', targets.length);
await asLocalCli(engine, async () => {
for (const { slug: targetSlug, held: target } of targets) {
if (held && previewed > 0 && Date.now() >= windowEnd) break;
previewed++;
opts.progress?.tick(1, targetSlug ?? target?.hold.path);
const label = targetSlug ?? target?.hold.path ?? '';
try {
if (target?.state === 'tombstone_edited' || target?.state === 'purged_differs') {
const resolved = await deletedPage(engine, sourceId, { ...target, state: target.state }, opts.prefer, mirror);
if ('skip' in resolved) { count(resolved.skip); listing.push({ item: `${sourceId}:${label}`, class: resolved.skip, detail: resolved.detail }); continue; }
await ('keep_deleted' in resolved.page ? authorizeReconcileGrant : authorizeReconcile)(engine, sourceId, resolved.page.slug);
pages.push(resolved.page);
listing.push({ item: `${sourceId}:${resolved.page.slug}`, class: `prefer_${opts.prefer}`, detail: resolved.detail });
continue;
}
if (targetSlug === null) { count('no_page'); listing.push({ item: `${sourceId}:${label}`, class: 'no_page', detail: 'the hold names no page; the next sync re-classifies it' }); continue; }
const slug = targetSlug;
await authorizeReconcile(engine, sourceId, slug);
const found = await heldLiveDrift(engine, sourceId, slug, { hold: target?.hold, mirror: mirrorFile });
const live = opts.slugs?.length && found.reason === 'database_only' ? await unboundCollisionDrift(engine, sourceId, slug) ?? found : found;
if (target && (target.state === 'file_gone') !== (live.reason === 'canonical_file_missing')) {
count('side_changed');
listing.push({ item: `${sourceId}:${slug}`, class: 'side_changed', detail: `its file is ${live.reason === 'canonical_file_missing' ? 'gone' : 'present'} now; gbrain sources status ${sourceId} --json shows its current Decision after the next sync` });
continue;
}
if (live.reason === 'canonical_file_missing') {
const gone = await fileGonePage(engine, sourceId, slug, opts, assessmentAt, target);
if ('skip' in gone) {
count(gone.skip);
if (gone.skip !== 'not_selected') listing.push({ item: `${sourceId}:${slug}`, class: gone.skip.startsWith('unknown_') ? 'unknown' : gone.skip, detail: gone.detail });
continue;
}
pages.push(gone.page);
listing.push({ item: `${sourceId}:${slug}`, class: `prefer_${opts.prefer}`, detail: gone.detail });
continue;
}
if (!opts.allDrifted && !opts.held && !selectedByGlobs(live.path, opts)) { count('not_selected'); continue; }
const agreedHold = live.reason !== 'agrees' || !live.db_revision ? null : target?.hold
?? (source && live.path ? await readGitHold(engine, sourceId, source.incarnation, live.path) : null);
if (agreedHold?.code === 'file_drift' && live.db_revision && (live.path !== agreedHold.path || !live.file_hash)) {
count('unknown_release_unproven');
listing.push({ item: `${sourceId}:${slug}`, class: 'unknown', detail: live.file_hash
? `the page agrees with ${live.path}, not with the held file ${agreedHold.path}; the hold stays until that file is resolved`
: `no file at ${agreedHold.path} to agree with; the hold stays` });
continue;
}
if (agreedHold?.code === 'file_drift' && live.db_revision) {
pages.push({ slug, prefer: opts.prefer, exceptions: [], release_hold: { path: agreedHold.path, incarnation: agreedHold.incarnation, revision: live.db_revision,
file_hash: live.file_hash ?? null, observed_at: agreedHold.observed_at } });
listing.push({ item: `${sourceId}:${slug}`, class: 'release_hold', detail: 'the page and its file agree now; the apply asks the next sync to re-screen the file, which releases the hold' });
continue;
}
if (live.still_present !== true) {
count(live.still_present === false ? 'no_drift' : `unknown_${live.reason}`);
listing.push({ item: `${sourceId}:${slug}`, class: live.still_present === false ? 'no_drift' : 'unknown', detail: live.reason });
continue;
}
// GST-2568: Git stays the parent, but a page edited after its file's last commit is never dropped file-wins in bulk;
// an explicit --slug still resolves it, with the warning naming the edit it drops.
if (opts.prefer === 'file') {
const evidence = await readDriftEvidence(engine, sourceId, slug, assessmentAt);
if (evidence.newer === 'database' && evidence.differs !== 'none') {
if (!opts.slugs?.length) { count('kept_newer_page'); listing.push({ item: `${sourceId}:${slug}`, class: 'kept_newer_page', detail: newerPageParagraph(sourceId, slug, evidence) }); continue; }
newerPages.push(`${slug}: ${newerPageParagraph(sourceId, slug, evidence).replace('it stays held for a person', '--prefer file named for it drops that edit')}`);
}
}
const page = await prepareDriftPage(engine, sourceId, slug, opts.prefer, assessmentAt);
if (classes.has(slug)) page.class = classes.get(slug);
// Whole-class C1: a read-only mirror's file is never written, so a page whose file-wins result needs protected parts appended stays held.
if (mirrorFile && page.file_appended) {
count('kept_protected_parts');
listing.push({ item: `${sourceId}:${slug}`, class: 'kept_protected_parts', detail: keptProtectedPartsDetail(sourceId, slug) });
continue;
}
// GST-2579: in bulk a newer file is kept (its hold stays); only an exact --slug selection may discard it, named here and in the consent.
if (page.discards && !opts.slugs?.length) {
count('kept_newer_file');
listing.push({ item: `${sourceId}:${slug}`, class: 'kept_newer_file', detail: `kept the file, nothing is written for it: it holds ${unimportedFileText(page.discards)}. `
+ `Import it with --prefer file, or, if the user decides to discard that edit, preview the page alone: gbrain repair file-drift --source ${sourceId} --slug ${slug} --prefer database` });
continue;
}
pages.push(page);
listing.push({ item: `${sourceId}:${slug}`, class: `prefer_${opts.prefer}`,
detail: `${page.discards ? `discards ${unimportedFileText(page.discards)}; ` : ''}${page.exceptions.length ? `kept: ${[...new Set(page.exceptions.map(e => e.reason))].join(', ')}` : 'exactly the preferred side'}${page.adopt_slug_path ? '; adopts the file at its slug path' : ''}`
+ (page.lost_lines ? `; drops ${page.lost_lines} line(s) the ${opts.prefer === 'database' ? 'file' : 'page'} holds` : '') });
} catch (error) {
if (!(error instanceof OperationError) || ['owner_unavailable', 'writer_registration_required'].includes(error.code)) throw error;
count(`refused_${error.code}`);
listing.push({ item: `${sourceId}:${label}`, class: 'refused', detail: `${error.code}: ${error.message}${error.why ? ` (${error.why})` : ''}`, ...(error.fix ? { fix: error.fix } : {}) });
}
}
});
opts.progress?.finish();
const remaining = held ? held.targets.length - previewed : 0;
const nextCursor = remaining > 0 ? heldCursor(held!.targets[previewed - 1]!.hold.path) : undefined;
const nextCommand = nextCursor ? previewCommand(sourceId, { ...opts, cursor: nextCursor }) : undefined;
if (remaining > 0) residuals.after_window = remaining;
const hash = previewHash({ kind: 'file-drift-v1', brain_id: scope.brain_id, source_id: sourceId, selection,
pages: pages.map(page => 'release_hold' in page ? [page.slug, page.release_hold.revision, page.release_hold.file_hash, 'release_hold', page.release_hold.path, page.release_hold.observed_at]
: 'soft_delete' in page ? [page.slug, page.soft_delete.ghost.revision, ABSENT_FILE_HASH, 'soft_delete']
: 'detach_page' in page ? [page.slug, page.detach_page.revision, ABSENT_FILE_HASH, 'detach_page', page.detach_page.page_id, page.detach_page.observed_at]
: 'remove_file' in page ? [page.slug, page.remove_file.revision, page.remove_file.raw_file_hash, 'remove_file', page.remove_file.state, page.remove_file.marker_digest]
: 'keep_deleted' in page ? [page.slug, page.keep_deleted.revision, page.keep_deleted.raw_file_hash, 'keep_deleted', page.keep_deleted.state, page.keep_deleted.page_id, page.keep_deleted.observed_at]
: 'import_file' in page ? [page.slug, page.import_file.revision, page.import_file.raw_file_hash, page.import_file.result_digest, page.import_file.state, page.import_file.marker_digest]
: [page.slug, page.preview.preconditions.revision, page.preview.preconditions.raw_file_hash, page.preview.result_digest]) });
// #6712 wave: a recreated file stays only once committed; without Git durability the next sync imports the committed deletion again.
const recreated = pages.flatMap(page => 'preview' in page && page.file_gone ? [page.preview.preconditions.relative_path] : []);
const appended = pages.flatMap(page => 'preview' in page && page.file_appended ? [page.preview.preconditions.relative_path] : []);
// #6712 PR 4b: a removed file is gone only once its deletion is committed; without Git durability the next sync finds the committed file held again.
const removed = pages.flatMap(page => 'remove_file' in page ? [page.remove_file.path] : []);
const removalWarning = removed.length ? [`The apply removes ${removed.length} file(s) that changed after their page was deleted; the deleted page does not hold what they say: ${removed.slice(0, 10).join(' ')}${removed.length > 10 ? ` and ${removed.length - 10} more` : ''}`] : [];
let warnings: string[] = nextCommand ? [`This preview covered ${previewed} of the ${held!.targets.length} selected held pages${opts.cursor ? ' after its cursor' : ''} (one window stops at ${HELD_WINDOW_PAGES} pages or ${HELD_WINDOW_BUDGET_MS / 1000} s); its hash and apply command cover only these. `
+ `After applying this window (or deciding not to), preview the next one: ${nextCommand}`] : [];
const discarded = pages.flatMap(page => 'preview' in page && page.discards ? [page.discards] : []);
if (discarded.length) warnings.unshift(`This apply writes the database copy over ${discarded.length} file change(s) sync never imported, and needs the user's consent: ${discarded.map(unimportedFileText).join('; ')}. `
+ 'Each write is a new commit, so git revert brings the change back; reconcile also keeps the replaced bytes in its private backup.');
warnings.push(...removalWarning);
if (newerPages.length) warnings.unshift(`The apply drops a database edit newer than its file for ${newerPages.length} page(s): ${newerPages.join(' ')}`);
const losing = pages.flatMap(page => 'preview' in page && page.lost_lines ? [page] : []);
const lostLines = losing.reduce((sum, page) => sum + page.lost_lines, 0);
if (lostLines) warnings.push(`The apply drops ${lostLines} line(s) the ${opts.prefer === 'database' ? 'files' : 'pages'} it overwrites hold and the result does not carry, across ${losing.length} page(s); details.pages[].lost_lines counts each. Read them before agreeing.`);
const releases = pages.filter(page => 'release_hold' in page).length;
if (releases) warnings.push(`The apply only schedules a re-screen of ${releases} held file(s) whose page and file agree; the next sync (gbrain sync --source ${sourceId}) releases each that still agrees.`);
let undoneBySync: { recreated: number; removed: number } | null = null;
if (recreated.length || removed.length || appended.length) {
const binding = await getWorktreeBinding(engine, sourceId);
const root = join(binding!.local_path!, binding!.relative_path);
if (!(await gitDurabilityPolicy(binding, root).catch(() => ({ durable: false }))).durable) {
if (removed.length) warnings.unshift(`The next sync undoes this repair unless the removals are committed: Git durability is off for ${sourceId}, so the apply leaves each removed file's deletion uncommitted (${removed.length} file(s)) and the next sync holds the committed file again. Commit them right after the apply: ${commitPushCommand(root, removed, [`gbrain: repair file drift in ${sourceId}`])}`);
if (appended.length) warnings.unshift(`Commit the appended files right after the apply: Git durability is off for ${sourceId}, so the apply leaves the protected parts it appends to each file uncommitted (${appended.length} file(s)), and the next sync holds an uncommitted file it cannot import as is. ${commitPushCommand(root, appended, [`gbrain: repair file drift in ${sourceId}`])}`);
if (recreated.length) warnings.unshift(`The next sync undoes this repair unless the recreated files are committed: Git durability is off for ${sourceId}, so the apply leaves each recreated file uncommitted (${recreated.length} file(s)) and the next sync imports their committed deletion again. Commit them right after the apply: ${commitPushCommand(root, recreated, [`gbrain: repair file drift in ${sourceId}`])}`);
if (recreated.length || removed.length) undoneBySync = { recreated: recreated.length, removed: removed.length };
}
}
const provenanceOf = new Map((held?.targets ?? []).flatMap(target => target.provenance && target.hold.slug ? [[target.hold.slug, target.provenance] as const] : []));
for (const entry of listing) {
const found = provenanceOf.get(entry.item.slice(sourceId.length + 1));
if (found) entry.detail = `${entry.detail}; ${provenanceText(found)}`;
}
let artifact: string | undefined;
if (pages.length) {
await assertReconcileOutputPath(engine, sourceId, artifactDirectory());
artifact = writeArtifact(hash, { format_version: 1, kind: 'file-drift', hash, source_id: sourceId, prefer: opts.prefer, pages });
await saveApprovedSet<ApprovedPage>(engine, { command: 'file-drift', hash }, pages.map(page => ({ source_id: sourceId, slug: page.slug,
artifact_digest: digest(page), selection })));
}
return { items: pages.map((page, index) => item({ source_id: sourceId, slug: page.slug, artifact_digest: digest(page), selection }, index, hash, index === pages.length - 1, opts.prefer)),
preview_hash: hash, residuals, listing, ...(held ? { complete: remaining === 0 } : {}), ...(warnings.length ? { warnings } : {}),
details: { prefer: opts.prefer, ...(artifact ? { artifact } : {}),
...(undoneBySync ? { undone_by_next_sync_unless_committed: undoneBySync } : {}),
...(held ? { window: { previewed, remaining, complete: remaining === 0, ...(nextCursor ? { next_cursor: nextCursor, next_command: nextCommand } : {}) } } : {}),
...(held?.provenance ? { provenance: held.provenance } : {}),
lost_lines_total: lostLines,
pages: pages.map(page => ({ ...('release_hold' in page ? { slug: page.slug, action: 'release_hold', path: page.release_hold.path, verb: 're-screen the held file (the page and the file agree)', exceptions: page.exceptions }
: 'soft_delete' in page ? { slug: page.slug, action: 'soft_delete', path: page.soft_delete.ghost.path, verb: fileDriftActionVerb('deleted', 'file_gone', 'file'), exceptions: page.exceptions }
: 'detach_page' in page ? { slug: page.slug, action: 'detach_page', path: page.detach_page.path, verb: 'keep the page database-only (no file)', exceptions: page.exceptions }
: 'keep_deleted' in page ? { slug: page.slug, action: 'keep_deleted', state: page.keep_deleted.state, path: page.keep_deleted.path, verb: KEEP_DELETED_VERB, exceptions: page.exceptions }
: 'remove_file' in page ? { slug: page.slug, action: 'remove_file', state: page.remove_file.state, path: page.remove_file.path, verb: fileDriftActionVerb('deleted', page.remove_file.state, 'database'), exceptions: page.exceptions }
: 'import_file' in page ? { slug: page.slug, action: 'import_file', state: page.import_file.state, path: page.import_file.path, verb: fileDriftActionVerb('deleted', page.import_file.state, 'file'), exceptions: page.exceptions, result_digest: page.import_file.result_digest }
: { slug: page.slug, ...(page.file_gone ? { action: 'recreate_file' } : {}), ...(page.class ? { class: page.class } : {}),
verb: page.file_gone ? fileDriftActionVerb('deleted', 'file_gone', 'database') : fileDriftActionVerb('both', undefined, page.prefer),
adopt_slug_path: page.adopt_slug_path, exceptions: page.exceptions, result_digest: page.preview.result_digest, lost_lines: page.lost_lines, ...(page.discards ? { discards: page.discards } : {}) }),
...(provenanceOf.get(page.slug) ? { provenance: provenanceOf.get(page.slug) } : {}) })),
protections: 'Protected metadata stays as the database holds it, tags are the union of both sides, and protected takes and private fact rows are kept; exceptions lists each page\'s.' } };
},
async apply(ctx, entry, opts): Promise<RepairItemOutcome> {
const { page, hash, last } = entry as DriftItem;
const command = `gbrain repair file-drift --source ${page.source_id}`;
const artifact = readArtifact(hash, command).get(page.slug);
if (!artifact || digest(artifact) !== page.artifact_digest) throw previewChangedError(opts?.expect ?? hash, command);
const requestId = requestIdFor(hash, page);
let outcome: RepairItemOutcome;
if ('release_hold' in artifact) outcome = await releaseAgreedHold(ctx.engine, page, artifact.release_hold, requestId);
else if ('keep_deleted' in artifact) outcome = await applyKeepDeleted(ctx, page, artifact, requestId);
else if ('remove_file' in artifact || 'import_file' in artifact || 'detach_page' in artifact) outcome = await applyDeletedSide(ctx, page, artifact, requestId, opts?.embed !== false);
else if ('soft_delete' in artifact) {
const retired = await retireGhost(ctx, artifact.soft_delete.ghost, artifact.soft_delete.owner, async () => requestId);
outcome = retired.applied ? { applied: true, outcome: 'repaired', detail: { request_id: requestId, prefer: 'file', action: 'soft_delete' } }
: { applied: false, outcome: 'changed_since_preview', reason: retired.outcome === 'file_restored' ? 'file_restored' : 'revision_conflict', detail: { request_id: requestId, message: retired.reason } };
} else try {
await asLocalCli(ctx.engine, () => runReconcileApply(ctx.engine, { source_id: page.source_id, slug: page.slug, preview: artifact.preview, request_id: requestId,
...(artifact.prefer === 'file' ? { keep_file_bytes: true } : {}) }, artifact.discards ? { discardFileHash: artifact.preview.preconditions.raw_file_hash } : {}));
outcome = { applied: true, outcome: 'repaired', detail: { request_id: requestId, prefer: artifact.prefer } };
} catch (error) {
if (acceptedPendingReceipt(error) || !(error instanceof OperationError) || ['owner_unavailable', 'writer_lock_unavailable', 'writer_busy', 'write_pending'].includes(error.code)) throw error;
const changed = error.code === 'revision_conflict' || error.code === 'page_identity_changed' || error.code === 'page_not_found'
|| error.code === 'source_changed' && error.message.startsWith('Reconciliation preview is stale');
outcome = { applied: false, outcome: changed ? 'changed_since_preview' : 'refused', reason: error.code,
detail: { request_id: requestId, message: error.message, ...(error.why ? { why: error.why } : {}), fix: error.fix ?? repreviewFix(page, ['gbrain', 'repair', 'file-drift', '--source', page.source_id, '--slug', page.slug, '--prefer', artifact.prefer]) } };
}
if (last) {
await clearApprovedSet(ctx.engine, { command: 'file-drift', hash });
try { unlinkSync(join(artifactDirectory(), `${hash}.json`)); } catch { /* already gone */ }
}
return outcome;
},
render(details) {
const lines: string[] = [];
for (const page of (details.pages ?? []) as Array<{ slug: string; verb?: string; path?: string }>) if (page.verb) lines.push(` ${page.slug}: ${page.verb}${page.path ? ` (${page.path})` : ''}`);
for (const action of (details.next_actions ?? []) as string[]) lines.push(` ${action}`);
if (typeof details.artifact === 'string') lines.push(` private artifact (each page's resolved result and exceptions): ${details.artifact}`);
if (typeof details.protections === 'string') lines.push(` ${details.protections}`);
for (const page of (details.pages ?? []) as Array<{ slug: string; exceptions: DriftException[] }>) {
for (const exception of page.exceptions) lines.push(` kept ${page.slug} ${exception.path}: ${exception.reason}`);
}
return lines;
},
};