Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Label repair previews hold pages their files would refuse

garrytana386bc6bc370
diff --git a/scripts/page-body-readers-baseline.tsv b/scripts/page-body-readers-baseline.tsv
index 4bd6dfc52a..e228d1a809 100644
--- a/scripts/page-body-readers-baseline.tsv
+++ b/scripts/page-body-readers-baseline.tsv
@@ -623,7 +623,7 @@ src/core/repair/visibility.ts applyFactItem field INLINE inline pages only: a se
src/core/repair/visibility.ts planAliases sql META
src/core/repair/visibility.ts planEvents sql META
src/core/repair/visibility.ts planLineage sql META
-src/core/repair/visibility.ts visibilityRepair call:serializePageToMarkdown SEGW
+src/core/repair/visibility.ts visibilityWrite call:serializePageToMarkdown SEGW
src/core/schema-migrations/v091-pages-generation-trigger-and-bookmark.ts v091 sql NONE not the page body: historical generation trigger
src/core/schema-migrations/v123-configurable-fts-language.ts v123 sql NONE not the page body: historical
src/core/schema-migrations/v124-page-search-vector-drop-compiled-truth.ts v124 sql NONE not the page body: historical search-vector trigger
diff --git a/src/core/repair/label-write.ts b/src/core/repair/label-write.ts
index c2dcdcd243..cbf0d8ddf3 100644
--- a/src/core/repair/label-write.ts
+++ b/src/core/repair/label-write.ts
@@ -12,14 +12,18 @@
* GST-2521: every label write raises the page's label guard (raisePageLabelGuard), so an agent write at the page's own
* tier is held from widening what the owner set.
*/
+import { relative, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
-import { opError, type OperationContext } from '../ops/contract.ts';
+import { opError, OperationError, type OperationContext } from '../ops/contract.ts';
import { importFromContent } from '../import-file.ts';
+import type { PageSnapshot } from '../page-state/types.ts';
import { maintenanceTransaction } from '../persistence/attribution.ts';
import { withTrustKeep } from '../persistence/context.ts';
+import { existingHostIdFor } from '../persistence/identity.ts';
import type { LabelEdit } from '../persistence/label-edit.ts';
-import { managedPersistenceEnabled } from '../persistence/ownership.ts';
-import { labelEditFile } from '../persistence/page-prepare.ts';
+import { getWorktreeBinding, managedPersistenceEnabled } from '../persistence/ownership.ts';
+import { fileSnapshotDifference, labelEditFit, prepareFileTarget } from '../persistence/page-prepare.ts';
+import { readSyncFile } from '../persistence/sync-discovery.ts';
import { maintenancePreflight, publishMaintenancePage, publishMaintenancePages, type MaintenanceAuthority } from '../persistence/prepared-maintenance.ts';
import type { RepairItemOutcome } from './core.ts';
import { raisePageLabelGuard } from '../trust/page-write.ts';
@@ -87,7 +91,9 @@ export async function writeLabelFile(engine: BrainEngine, page: { source_id: str
const snapshot = before === null ? null : await engine.readPageSnapshot(page.slug, { sourceId: page.source_id });
if (before === null || !snapshot) return importAtRevision(engine, page, write.revision, write.content, write.embed, write.preview);
if (snapshot.revision !== write.revision) return null;
- const text = labelEditFile(page.slug, Buffer.from(before, 'utf8'), write.content, write.edit, snapshot);
+ const fit = labelEditFit(page.slug, Buffer.from(before, 'utf8'), write.content, write.edit, snapshot);
+ if (typeof fit !== 'string') throw labelEditRefused(page, fit.keys, write.edit);
+ const text = fit;
let unwritable: string | undefined;
try {
return await importAtRevision(engine, page, write.revision, text, write.embed, write.preview, async tx => {
@@ -102,6 +108,70 @@ export async function writeLabelFile(engine: BrainEngine, page: { source_id: str
}
}
+/**
+ * GST-2603: why the label write of `snapshot`'s page would not take its file, read now from the file's current bytes and
+ * changing nothing; null when it would, or when the page has no file here (a repo-less brain, a database-only page, a file
+ * this host does not own: the write decides those). `file_database_drift`: the file differs from the page (`error` is the
+ * refusal the write throws); `label_edit_refused`: the file holds the page but cannot take the edit line by line. `keys` names
+ * what differs or blocks (a frontmatter key, title, type, tags, body or timeline, never a stamp only the database holds); `next`
+ * is the step that clears it. The managed write (page-prepare.ts prepareFileTarget, labelEditFile) and the unmanaged
+ * checkout write (writeLabelFile) compare with the same rule.
+ */
+export interface LabelFileRefusal { reason: 'file_database_drift' | 'label_edit_refused'; keys: string[]; next: string; error: OperationError }
+export async function labelFileRefusal(engine: BrainEngine, snapshot: PageSnapshot, content: string, edit: LabelEdit): Promise<LabelFileRefusal | null> {
+ const { source_id: sourceId, slug } = snapshot.page;
+ const drift = (keys: string[], next: string, error: OperationError): LabelFileRefusal => ({ reason: 'file_database_drift', keys, next, error });
+ const read = (root: string, path: string) => { try { return readSyncFile(root, path); } catch { return null; } };
+ let bytes: Buffer | null;
+ if (await managedPersistenceEnabled(engine)) {
+ const hostId = existingHostIdFor(engine);
+ const binding = hostId ? await getWorktreeBinding(engine, sourceId, hostId) : null;
+ if (!binding?.local_path || binding.owner_host_id !== hostId || binding.state !== 'active') return null;
+ try {
+ const target = await prepareFileTarget(engine, { source_id: sourceId, worktree_id: binding.worktree_id, slug }, snapshot, content, hostId!);
+ bytes = target && target.content !== null ? read(target.root, target.path) : null;
+ } catch (error) {
+ if (!(error instanceof OperationError) || error.detail !== 'file_database_drift') return null;
+ const local = (error as OperationError & { localEdit?: { root: string; path: string } }).localEdit;
+ const text = local ? read(local.root, local.path) : null;
+ const keys = local && text ? await fileSnapshotDifference(engine, slug, text.toString('utf8'), snapshot, relative(local.root, local.path).split(sep).join('/')) : [];
+ return drift(keys, local ? `gbrain sources reconcile ${sourceId} ${slug} --preview` : error.suggestion ?? '', error);
+ }
+ } else {
+ if (!(await filesInCheckout(engine, [Number(snapshot.page.id)])).has(Number(snapshot.page.id))) return null;
+ const { ownerRepairFile } = await import('../trust/page-handlers.ts');
+ const file = await ownerRepairFile(engine, sourceId, slug);
+ if (!file.ok && file.reason === 'file_database_drift') {
+ const { derivedFileTarget } = await import('../cycle/derived-write-through.ts');
+ const target = await derivedFileTarget(engine, slug, sourceId);
+ const text = target.ok ? read(target.target.writeRoot, target.target.filePath) : null;
+ const keys = text ? await fileSnapshotDifference(engine, slug, text.toString('utf8'), snapshot, snapshot.page.source_path ?? `${slug}.md`) : [];
+ return drift(keys, `gbrain sync --source ${sourceId}`, opError('source_changed', `${sourceId}:${slug} was not written: its file in the source's checkout holds an edit the database lacks.`,
+ `Run gbrain sync --source ${sourceId}, then preview the repair again.`, { detail: 'file_database_drift' }));
+ }
+ if (!file.ok || !file.target?.expectedFileBytes) return null;
+ bytes = Buffer.from(file.target.expectedFileBytes, 'utf8');
+ }
+ if (!bytes) return null;
+ const fit = labelEditFit(slug, bytes, content, edit, snapshot);
+ if (typeof fit === 'string') return null;
+ const error = labelEditRefused(snapshot.page, fit.keys, edit);
+ return { reason: 'label_edit_refused', keys: fit.keys, next: error.suggestion ?? '', error };
+}
+
+/** GST-2603: a label write's refusal when the page's file holds the page but cannot take `edit` line by line (`keys`: what still differs, empty when the label line itself cannot be edited). */
+export function labelEditRefused(page: { source_id: string; slug: string }, keys: string[], edit: LabelEdit): OperationError {
+ const ref = `${page.source_id}:${page.slug}`;
+ const labels = [...Object.keys(edit.set), ...edit.remove].join(', ') || 'the label';
+ return keys.length
+ ? opError('label_edit_refused', `${ref} was not written: with only its label lines edited, its file still differs from the page in ${keys.join(', ')}.`,
+ `In the page's file, make ${keys.join(', ')} match the page (gbrain get --source ${page.source_id} -- ${page.slug} prints it), commit it, run gbrain sync --source ${page.source_id}, then preview the repair again.`,
+ { reason: 'file_differs', detail: keys.join(',') })
+ : opError('label_edit_refused', `${ref} was not written: its file's ${labels} line cannot be edited as one line.`,
+ `In the page's file, write ${labels} as one plain line in the frontmatter block (no block or multi-line value, no duplicate key; add a frontmatter block if the file has none), commit it, run gbrain sync --source ${page.source_id}, then preview the repair again.`,
+ { reason: 'label_line', detail: labels });
+}
+
/**
* One label-only page write at `revision`: the maintenance door on a managed brain (`authority`, from maintenancePreflight),
* the import under the page lock otherwise. The revision it wrote; null when the page moved before an unmanaged import.
diff --git a/src/core/repair/private-labels.ts b/src/core/repair/private-labels.ts
index 0edaad0cd7..fd5c7c953b 100644
--- a/src/core/repair/private-labels.ts
+++ b/src/core/repair/private-labels.ts
@@ -52,7 +52,7 @@ import { serializePageToMarkdown } from '../markdown.ts';
import { opError, type OperationContext } from '../ops/contract.ts';
import { maintenancePreflight, publishMaintenancePages, type MaintenanceAuthority } from '../persistence/prepared-maintenance.ts';
import { isPlainLabelValue, type LabelEdit } from '../persistence/label-edit.ts';
-import { filesInCheckout, writeLabelPage } from './label-write.ts';
+import { filesInCheckout, labelFileRefusal, writeLabelPage } from './label-write.ts';
import { getWriteRequest } from '../persistence/journal.ts';
import { isTerminal } from '../persistence/model.ts';
import { requestPrincipalForContext } from '../persistence/page-mutations.ts';
@@ -362,7 +362,11 @@ async function prepareWrite(ctx: OperationContext, item: LabelsItem): Promise<Re
+ `so the next sync or re-import would undo it from the file. ${entry.mode === 'clear' ? `Remove ${describeLabels(labels)} from that file's frontmatter`
: `Add ${describeLabels(labels)} back to that file's frontmatter if it is missing`}, commit it, then run: gbrain sync --source ${entry.source_id}` } };
}
- return { revision: snapshot.revision, content: serializePageToMarkdown({ ...snapshot.page, frontmatter: next }, snapshot.tags), labels };
+ const content = serializePageToMarkdown({ ...snapshot.page, frontmatter: next }, snapshot.tags);
+ // GST-2603: a file that holds the page but cannot take the label edit line by line declines here, before its intent line.
+ const refusal = await labelFileRefusal(ctx.engine, snapshot, content, labelEditOf(entry));
+ if (refusal?.reason === 'label_edit_refused') throw refusal.error;
+ return { revision: snapshot.revision, content, labels };
}
/** The item's ledger line under its deterministic request id (a resumed run replays the same request). */
diff --git a/src/core/repair/visibility.ts b/src/core/repair/visibility.ts
index 774e01627a..b693ee128f 100644
--- a/src/core/repair/visibility.ts
+++ b/src/core/repair/visibility.ts
@@ -53,7 +53,7 @@ import { maintenancePreflight, publishMaintenancePages, submitDatabaseMaintenanc
import { CANONICAL_FILE_MISSING } from '../persistence/publication-failure.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { afterCursor, repairRequestId, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairPlanOptions, type RepairScope, type RepairSettlement, type RepairCursor } from './core.ts';
-import { filesInCheckout, writeLabelFile, writeLabelPage } from './label-write.ts';
+import { filesInCheckout, labelFileRefusal, writeLabelFile, writeLabelPage, type LabelFileRefusal } from './label-write.ts';
import { applyReaders, planReaders, raiseGuardOnly, raiseReadersGuard, readersBatch, readersGitCounts, readersGuardOnly, readersOutcome, readersWrite, retireReaders, READERS_PHASE, type ReadersItem, type ReadersWrite } from './readers.ts';
import type { LabelEdit } from '../persistence/label-edit.ts';
import type { PageSnapshot } from '../page-state/types.ts';
@@ -332,6 +332,11 @@ function missingFileHeld(item: Pick<RepairItem, 'source_id' | 'slug'>, error: un
async function labelWrite(ctx: Parameters<RepairHandler['apply']>[0], item: RepairItem, snapshot: PageSnapshot, content: string, edit: LabelEdit, batch?: string): Promise<RepairItemOutcome | null> {
if (isSegmentedPage(snapshot.page)) return { applied: false, outcome: 'segmented_page', reason: 'The page body is stored in segments; edit it by hand on the brain host.' };
const path = (await filesInCheckout(ctx.engine, [Number(snapshot.page.id)])).get(Number(snapshot.page.id));
+ // GST-2603: a managed page whose file took a change the label edit cannot be spliced over since the preview declines here, before admission.
+ if (!path) {
+ const refusal = await labelFileRefusal(ctx.engine, snapshot, content, edit);
+ if (refusal?.reason === 'label_edit_refused') throw refusal.error;
+ }
const write = { revision: snapshot.revision, content, edit, embed: true, preview: 'gbrain repair visibility', ...(batch ? { batch } : {}) };
let written: Awaited<ReturnType<typeof writeLabelFile>>;
try {
@@ -345,6 +350,23 @@ async function labelWrite(ctx: Parameters<RepairHandler['apply']>[0], item: Repa
return typeof written === 'string' ? null : written;
}
+/** A page item's label write: the page rendered with its new visibility, and the one label line that changes in its file. */
+function visibilityWrite(snapshot: PageSnapshot, to: string): { content: string; edit: LabelEdit } {
+ return { content: serializePageToMarkdown({ ...snapshot.page, frontmatter: { ...snapshot.page.frontmatter, visibility: to } }, snapshot.tags), edit: { set: { visibility: to }, remove: [] } };
+}
+
+/** GST-2603: a previewed page whose label write its file would refuse now; listed as held, outside the preview hash and the approved set. */
+interface HeldVisibility { item: string; reason: LabelFileRefusal['reason']; keys: string[]; next: string }
+/** The preview's check of one page item against its file's current bytes, as the apply's write compares them (repair/label-write.ts labelFileRefusal). */
+async function heldPage(engine: BrainEngine, item: VisibilityItem): Promise<HeldVisibility | null> {
+ if (item.target.phase === 4 || !item.change || item.change.from === item.change.to) return null;
+ const snapshot = await engine.readPageSnapshot(item.slug, { sourceId: item.source_id });
+ if (!snapshot || Number(snapshot.page.id) !== item.target.id || isSegmentedPage(snapshot.page)) return null;
+ const write = visibilityWrite(snapshot, item.change.to);
+ const refusal = await labelFileRefusal(engine, snapshot, write.content, write.edit);
+ return refusal && { item: `${item.source_id}:${item.slug}`, reason: refusal.reason, keys: refusal.keys, next: refusal.next };
+}
+
export type VisibilityClass = 'facts' | 'events' | 'aliases' | 'lineage' | 'pages';
/** Plan order: what a remote caller can read first; only `lineage` reads concept-provenance links. */
export const VISIBILITY_CLASSES: readonly VisibilityClass[] = ['facts', 'events', 'aliases', 'lineage'];
@@ -450,8 +472,16 @@ export const visibilityRepair: RepairHandler = {
progress?.heartbeat(`${cls}: ${ordered.length} to repair${cls === 'facts' ? ` (${planned.residuals.world_facts_remotely_readable} remotely readable)` : ''} in ${Date.now() - started} ms`);
progress?.tick(1);
}
+ // GST-2603: each page item is checked against its file as its write would be; one the write would refuse is held.
+ progress?.heartbeat(`checking ${window.length} item(s) against their files`);
+ const held: HeldVisibility[] = [];
+ const items: VisibilityItem[] = [];
+ for (const { readable: _readable, ...item } of window as Array<VisibilityItem & { readable?: boolean }>) {
+ const hold = await heldPage(engine, item as VisibilityItem);
+ if (hold) held.push(hold); else items.push(item as VisibilityItem);
+ }
progress?.finish();
- const items = window.map(({ readable: _readable, ...item }: VisibilityItem & { readable?: boolean }) => item as VisibilityItem);
+ if (held.length) Object.assign(residuals, { held_file_drift: held.filter(hold => hold.reason === 'file_database_drift').length, held_label_edit: held.filter(hold => hold.reason === 'label_edit_refused').length });
const hash = previewHash(hashParts(scope, selection, items));
if (items.length) await saveApprovedSet<ApprovedVisibility>(engine, { command: 'visibility', hash },
items.map(item => ({ target: item.target, source_id: item.source_id, slug: item.slug, chars: item.chars, action: item.action, change: item.change!, selection })));
@@ -461,11 +491,12 @@ export const visibilityRepair: RepairHandler = {
+ `Apply this window (or decide not to), then preview again for the next one: ${next}`] : []),
...timedOut.map(cls => `Class ${cls} did not finish within the ${PLAN_STATEMENT_MS} ms statement bound and is not listed; the other classes are. `
+ `Preview the others with --class, or run gbrain doctor --only derived_visibility for the counts.`),
+ ...(held.length ? [`${held.length} page(s) are held and not in this preview's set: their files would refuse the label write now. details.held names what differs for each and the step that clears it; preview again after it.`] : []),
];
return { warnings, items: items.map((item, index) => ({ ...item, cursor: { phase: 0, id: index } })), preview_hash: hash,
residuals,
listing: items.map(item => ({ item: `${item.source_id}:${item.slug}`, class: CLASS_OF_PHASE[item.target.phase]!, detail: item.action })),
- details: { window: { size, listed: items.length, pending, pending_past_window: pendingPastWindow, not_read: notRead, timed_out: timedOut, next_preview: next } } };
+ details: { window: { size, listed: items.length, pending, pending_past_window: pendingPastWindow, not_read: notRead, timed_out: timedOut, next_preview: next }, ...(held.length ? { held } : {}) } };
},
/** A --readers apply: how its managed writes reached Git (`details.git`, effect states; readers.ts readersGitCounts). */
async report(ctx, scope, result, opts) {
@@ -473,7 +504,9 @@ export const visibilityRepair: RepairHandler = {
},
render(details) {
const git = details.git as Record<string, number> | undefined;
- return git ? [` git: ${Object.entries(git).map(([key, value]) => `${key}=${value}`).join(', ')} (file(s) by Git effect state; queued files commit together, up to 100 per commit)`] : [];
+ const held = (details.held as HeldVisibility[] | undefined) ?? [];
+ return [...(git ? [` git: ${Object.entries(git).map(([key, value]) => `${key}=${value}`).join(', ')} (file(s) by Git effect state; queued files commit together, up to 100 per commit)`] : []),
+ ...held.map(hold => ` held ${hold.item} (${hold.reason}${hold.keys.length ? `: ${hold.keys.join(', ')}` : ''}); next: ${hold.next}`)];
},
/**
* GST-2476: a run of readers items of one managed source at once. Each page is re-checked as apply does; the pages are
@@ -524,8 +557,8 @@ export const visibilityRepair: RepairHandler = {
.changes.find(c => c.id === target.id);
if (!fresh || fresh.from !== item.change.from || fresh.to !== item.change.to) return false;
if (item.change.from === item.change.to) return await raiseGuardOnly(ctx.engine, { ...item, target }, frontmatter => frontmatter.visibility === item.change!.to);
- const page = { ...snapshot.page, frontmatter: { ...snapshot.page.frontmatter, visibility: item.change.to } };
- return await labelWrite(ctx, item, snapshot, serializePageToMarkdown(page, snapshot.tags), { set: { visibility: item.change.to }, remove: [] }) ?? true;
+ const write = visibilityWrite(snapshot, item.change.to);
+ return await labelWrite(ctx, item, snapshot, write.content, write.edit) ?? true;
});
},
};