Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(repair): write-ahead private-labels undo ledger and a restore that trusts only well-formed lines (GST-2092, GST-2128 items 4, 7, 9, 10)
garrytan7f8a9add8dbd
diff --git a/src/commands/repair-private-labels.ts b/src/commands/repair-private-labels.tsindex 3b25cd0d0c..73226d59f0 100644--- a/src/commands/repair-private-labels.ts+++ b/src/commands/repair-private-labels.ts@@ -8,15 +8,15 @@import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync } from 'node:fs';import { dirname } from 'node:path';import { gbrainPath } from '../core/config.ts';-import type { PrivateLabelsLedger, PrivateLabelsLedgerLine } from '../core/repair/private-labels.ts';+import type { PrivateLabelsLedger } from '../core/repair/private-labels.ts';export function privateLabelsLedger(brainId: string): PrivateLabelsLedger {const path = gbrainPath('repair', 'private-labels', `${brainId.replace(/[^A-Za-z0-9._-]/g, '_')}.jsonl`);- const lines: PrivateLabelsLedgerLine[] = [];+ const lines: unknown[] = [];let unreadable = 0;for (const text of existsSync(path) ? readFileSync(path, 'utf8').split('\n') : []) {if (!text.trim()) continue;- try { lines.push(JSON.parse(text) as PrivateLabelsLedgerLine); } catch { unreadable++; }+ try { lines.push(JSON.parse(text)); } catch { unreadable++; }}return { path, lines, unreadable, record(line) {mkdirSync(dirname(path), { recursive: true, mode: 0o700 });diff --git a/src/core/repair/private-labels.ts b/src/core/repair/private-labels.tsindex f95edac77a..8e232ce29d 100644--- a/src/core/repair/private-labels.ts+++ b/src/core/repair/private-labels.ts@@ -29,18 +29,20 @@* keeping the stored tier. readable_by and folder* rules are left as they are.*- * Reversible: every applied item records a line with the exact removed values in the- * ledger the caller passes (`privateLabelsLedger`; the CLI keeps it at- * <gbrain home>/repair/private-labels/<brain_id>.jsonl, src/commands/repair-private-labels.ts),- * and --class restore plans from its lines: each recorded page still live and still- * without those keys gets them back (preview-bound the same way, with its own line).- * An apply or a restore preview without a ledger is refused. A git-publish clear is not fully undone: restore re-adds- * the label and the file leaves the checkout, but the commits that held it keep the page's content.+ * Reversible: the ledger the caller passes (`privateLabelsLedger`; the CLI keeps it at+ * <gbrain home>/repair/private-labels/<brain_id>.jsonl, src/commands/repair-private-labels.ts) is+ * write-ahead. Each item appends an `intent` line with the exact removed (or re-added) values before+ * its page write and a `committed` line with the revision it wrote after; a ledger that cannot take+ * the intent line refuses the item before anything is written. --class restore plans from the lines+ * (see planRestore) and re-adds only access and visibility: private; it is preview-bound the same way+ * and writes its own lines. An apply that ends with a failure, a stop or a pending write keeps its+ * approved set, so the same --apply --expect resumes it. An apply or a restore preview without a+ * ledger is refused. A git-publish clear is not fully undone: restore re-adds the label and the file+ * leaves the checkout, but the commits that held it keep the page's content.*/import type { BrainEngine } from '../engine.ts';import { serializePageToMarkdown } from '../markdown.ts';import { opError } from '../ops/contract.ts';-import { acceptedPendingReceipt } from '../persistence/accepted-pending.ts';import { maintenanceTransaction } from '../persistence/attribution.ts';import { withTrustKeep } from '../persistence/context.ts';import { maintenancePreflight, publishMaintenancePage } from '../persistence/prepared-maintenance.ts';@@ -67,11 +69,16 @@ type Labels = { access?: string; visibility?: string };interface LabelRow { id: number; source_id: string; slug: string; type: string; frontmatter: Record<string, unknown> | null; revision: string | null; chars: number; git: boolean }interface Selection { source_ids: string[]; class: LabelsClass | null }interface Approved { mode: 'clear' | 'restore'; class: LabelsClass; brain_id: string; source_id: string; slug: string; page_id: number; revision: string | null; labels: Labels; chars: number; selection: Selection }-interface LabelsItem extends RepairItem { entry: Approved; ledger: PrivateLabelsLedger; hash?: string; last?: boolean }-export interface PrivateLabelsLedgerLine { at: string; brain_id: string; source_id: string; slug: string; page_id: number; revision_before: string; request_id: string; removed?: Labels; restored?: Labels }+interface LabelsItem extends RepairItem { entry: Approved; ledger: PrivateLabelsLedger }+/**+ * One ledger line. `phase`: `intent` is appended before the page write, `committed` after it landed, with the revision it+ * wrote (`revision_after`); a line with no phase predates the write-ahead ledger and was appended after its write.+ */+export interface PrivateLabelsLedgerLine { at: string; brain_id: string; source_id: string; slug: string; page_id: number; revision_before: string; request_id: string;+ removed?: Labels; restored?: Labels; phase?: 'intent' | 'committed'; revision_after?: string }type LedgerLine = PrivateLabelsLedgerLine;-/** The undo ledger, kept by the caller: where it is, its lines (read for --class restore), unreadable line count, and the append. */-export interface PrivateLabelsLedger { path: string; lines: PrivateLabelsLedgerLine[]; unreadable: number; record(line: PrivateLabelsLedgerLine): void }+/** The undo ledger, kept by the caller: where it is, its parsed lines (untrusted; read for --class restore), unparseable line count, and the append. */+export interface PrivateLabelsLedger { path: string; lines: unknown[]; unreadable: number; record(line: PrivateLabelsLedgerLine): void }type Decision = { keep: KeepClass } | { clear: ClearClass; removed: Labels } | null;/** KEEP or CLEAR for a page that is private by its label; null for a page no label makes private. */@@ -106,6 +113,27 @@ async function scanLabelled(engine: BrainEngine, sourceIds: string[], visit: (ro}}+/** The labels a ledger line may carry: access (a string) and visibility (only private), nothing else; null otherwise. */+function ledgerLabels(value: unknown): Labels | null {+ if (!value || typeof value !== 'object' || Array.isArray(value)) return null;+ const entries = Object.entries(value);+ if (!entries.length || entries.some(([key, v]) => !(key === 'access' ? typeof v === 'string' : key === 'visibility' && v === 'private'))) return null;+ return Object.fromEntries(entries) as Labels;+}++/** A ledger line restore may plan from, or null: string identity fields, a positive integer page id, one well-formed label set. */+function readableLine(raw: unknown): LedgerLine | null {+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;+ const line = raw as Record<string, unknown>;+ if (![line.brain_id, line.source_id, line.slug].every(v => typeof v === 'string') || !Number.isSafeInteger(line.page_id) || (line.page_id as number) < 1) return null;+ if (line.phase !== undefined && line.phase !== 'intent' && line.phase !== 'committed') return null;+ if (line.revision_after !== undefined && typeof line.revision_after !== 'string') return null;+ const removed = line.removed === undefined ? undefined : ledgerLabels(line.removed);+ const restored = line.restored === undefined ? undefined : ledgerLabels(line.restored);+ if (removed === null || restored === null || (removed === undefined) === (restored === undefined)) return null;+ return { ...(line as unknown as LedgerLine), ...(removed ? { removed } : { restored: restored! }) };+}+const describeLabels = (labels: Labels) => Object.entries(labels).map(([key, value]) => `${key}: ${value}`).join(', ');const sameLabels = (a: Labels, b: Labels) => JSON.stringify(Object.entries(a).sort()) === JSON.stringify(Object.entries(b).sort());const previewCommand = (scope: RepairScope, selection: Selection) =>@@ -138,30 +166,42 @@ async function planClear(engine: BrainEngine, scope: RepairScope, selection: Selreturn { counts: counts as Record<string, number>, entries, unreadable: 0 };}-/** The ledger's latest line per page decides: a removal whose page is live and still lacks every removed key is restorable. */+/**+ * Per page (source, page id) in scope, its latest removal line (intent, committed or a pre-write-ahead line) decides what+ * restore re-adds: the page is restorable while it is live and lacks every removed key. A restore line after that removal+ * counts only when it is `committed` with the revision it wrote: a page that has moved past that revision and lacks the+ * keys again had its label removed after the restore landed (`removed_after_restore`), so it is counted, warned about+ * and not planned. A restore line with no committed revision proves nothing (an accepted write can still fail), so its+ * page stays restorable. A line restore cannot trust (not an object, a page id that is not a positive integer, a key+ * other than access or visibility: private, a value that is not a string) is counted unreadable and never planned.+ */async function planRestore(engine: BrainEngine, scope: RepairScope, selection: Selection, ledger: PrivateLabelsLedger) {- const { lines, unreadable } = ledger;- // A page's latest clear decides; a later restored line is not proof, since a restore accepted pending can still fail.+ let unreadable = ledger.unreadable;const pages = new Set<string>();- const latestRemoval = new Map<string, LedgerLine>();- for (const line of lines) {+ const latest = new Map<string, { removal: LedgerLine; landed?: LedgerLine }>();+ for (const raw of ledger.lines) {+ const line = readableLine(raw);+ if (!line) { unreadable++; continue; }if (line.brain_id !== scope.brain_id || !scope.source_ids.includes(line.source_id)) continue;- pages.add(`${line.source_id}:${line.page_id}`);- if (line.removed) latestRemoval.set(`${line.source_id}:${line.page_id}`, line);+ const key = `${line.source_id}:${line.page_id}`;+ pages.add(key);+ if (line.removed) latest.set(key, { removal: line });+ else if (line.phase === 'committed' && line.revision_after && latest.has(key)) latest.get(key)!.landed = line;}- const removals = [...latestRemoval.values()];+ const removals = [...latest.values()];const live = removals.length ? await engine.executeRaw<LabelRow>(`SELECT id, source_id, slug, type, frontmatter, knowledge_revision::text AS revision, COALESCE(body_bytes, 0) AS chars- FROM pages WHERE id = ANY($1::integer[]) AND deleted_at IS NULL`, [removals.map(line => line.page_id)], bounded) : [];+ FROM pages WHERE id = ANY($1::integer[]) AND deleted_at IS NULL`, [removals.map(({ removal }) => removal.page_id)], bounded) : [];const byId = new Map(live.map(row => [Number(row.id), row]));- const counts = { restorable: 0, already_restored: pages.size - removals.length, page_gone: 0 };+ const counts = { restorable: 0, already_restored: pages.size - removals.length, page_gone: 0, removed_after_restore: 0 };const entries: Approved[] = [];- for (const line of removals) {- const page = byId.get(line.page_id);- if (!page || page.source_id !== line.source_id) { counts.page_gone++; continue; }- if (Object.keys(line.removed!).some(key => Object.hasOwn(page.frontmatter ?? {}, key))) { counts.already_restored++; continue; }+ for (const { removal, landed } of removals) {+ const page = byId.get(removal.page_id);+ if (!page || page.source_id !== removal.source_id) { counts.page_gone++; continue; }+ if (Object.keys(removal.removed!).some(key => Object.hasOwn(page.frontmatter ?? {}, key))) { counts.already_restored++; continue; }+ if (landed && landed.revision_after !== page.revision) { counts.removed_after_restore++; continue; }counts.restorable++;entries.push({ mode: 'restore', class: 'restore', brain_id: scope.brain_id, source_id: page.source_id, slug: page.slug, page_id: Number(page.id),- revision: page.revision, labels: line.removed!, chars: Number(page.chars), selection });+ revision: page.revision, labels: removal.removed!, chars: Number(page.chars), selection });}entries.sort((a, b) => a.page_id - b.page_id);return { counts: counts as Record<string, number>, entries, unreadable };@@ -169,17 +209,17 @@ async function planRestore(engine: BrainEngine, scope: RepairScope, selection: S/*** Unmanaged brains: the legacy maintenance import (an owner path: no write gate, no trust marker, gate markers kept),- * under withTrustKeep so the page keeps its stored tier, bound to the previewed revision under the page lock. False when- * the page moved.+ * under withTrustKeep so the page keeps its stored tier, bound to the previewed revision under the page lock. The revision+ * it wrote; null when the page moved.*/-async function importAtRevision(engine: BrainEngine, entry: Approved, revision: string, content: string, embed: boolean): Promise<boolean> {+async function importAtRevision(engine: BrainEngine, entry: Approved, revision: string, content: string, embed: boolean): Promise<string | null> {return maintenanceTransaction(engine, async tx => {await tx.lockPageKeys([{ sourceId: entry.source_id, slug: entry.slug }]);- if ((await tx.readPageSnapshot(entry.slug, { sourceId: entry.source_id }))?.revision !== revision) return false;+ if ((await tx.readPageSnapshot(entry.slug, { sourceId: entry.source_id }))?.revision !== revision) return null;const result = await withTrustKeep(tx, ['pages'], () => importFromContent(tx, entry.slug, content, { sourceId: entry.source_id, noEmbed: !embed, preserveGateMarkers: true }));if (result.status === 'error') throw opError('invalid_params', `${entry.source_id}:${entry.slug} was not written: ${result.error ?? 'the import refused it'}`,'Preview gbrain repair private-labels again; the page is listed with its current state.');- return true;+ return (await tx.readPageSnapshot(entry.slug, { sourceId: entry.source_id }))?.revision ?? null;});}@@ -192,8 +232,8 @@ export const privateLabelsRepair: RepairHandler = {if (!ledger && (opts?.apply || selection.class === 'restore')) {throw opError('invalid_params', 'gbrain repair private-labels needs its undo ledger to apply or restore, and this caller passed none.', `Run it from the CLI on the brain host: ${command}`);}- const toItems = (entries: Approved[], hash: string) => entries.map((entry, index): LabelsItem => ({ cursor: { phase: 0, id: index }, source_id: entry.source_id, slug: entry.slug,- chars: entry.chars, action: `${entry.mode === 'clear' ? 'remove' : 're-add'} ${describeLabels(entry.labels)}`, entry, ledger: ledger!, hash, last: index === entries.length - 1 }));+ const toItems = (entries: Approved[]) => entries.map((entry, index): LabelsItem => ({ cursor: { phase: 0, id: index }, source_id: entry.source_id, slug: entry.slug,+ chars: entry.chars, action: `${entry.mode === 'clear' ? 'remove' : 're-add'} ${describeLabels(entry.labels)}`, entry, ledger: ledger! }));if (opts?.apply) {if (!opts.expect) {throw opError('invalid_params', 'gbrain repair private-labels --apply changes only the set a preview printed (clearing a label widens remote reads).',@@ -204,7 +244,7 @@ export const privateLabelsRepair: RepairHandler = {if (approved.items.some(entry => (entry.selection.class ?? null) !== selection.class || JSON.stringify(entry.selection.source_ids) !== JSON.stringify(selection.source_ids))) {throw previewChangedError(opts.expect, command);}- return { items: toItems(approved.items, opts.expect).filter(item => afterCursor(item.cursor, after)), preview_hash: opts.expect, residuals: {} };+ return { items: toItems(approved.items).filter(item => afterCursor(item.cursor, after)), preview_hash: opts.expect, residuals: {} };}const size = Math.min(Math.max(1, opts?.limit ?? PRIVATE_LABELS_WINDOW), PRIVATE_LABELS_WINDOW_MAX);const restore = selection.class === 'restore';@@ -233,10 +273,12 @@ export const privateLabelsRepair: RepairHandler = {...(gitPublish && selection.class !== 'git-publish' ? [`${gitPublish} page(s) of class git-publish (git-canonical sources) carry the same label and are not in this preview: `+ 'private pages there are database-only, so clearing commits each into its source\'s Git history for the first time. Preview them by name: gbrain repair private-labels --class git-publish'] : []),...(planned.unreadable ? [`${planned.unreadable} ledger line(s) could not be read and are not planned.`] : []),+ ...(restore && before.removed_after_restore ? [`${before.removed_after_restore} page(s) had their label removed after a restore landed (the page changed since the revision the restore wrote), `+ + 'so they are not listed; re-add the label by hand if that edit was a mistake.'] : []),...(restore && !Object.values(before).some(Boolean) ? [`The ledger ${ledger!.path} has no line for brain ${scope.brain_id} in this scope. Restore reads only the ledger on the host `+ 'and GBRAIN_HOME that ran the clear; run it there.'] : []),];- return { items: toItems(window, hash), preview_hash: hash, residuals: {}, warnings,+ return { items: toItems(window), preview_hash: hash, residuals: {}, warnings,listing: window.map(entry => ({ item: `${entry.source_id}:${entry.slug}`, class: entry.class,detail: entry.mode === 'restore' ? `re-add ${describeLabels(entry.labels)}` : entry.labels.visibility ? 'remove access: private, visibility: private' : 'remove access: private' })),details: { counts: { before, after: projected }, window: { size, listed: window.length, pending_past_window: pastWindow, next_preview: command },@@ -245,50 +287,55 @@ export const privateLabelsRepair: RepairHandler = {async apply(ctx, raw, opts): Promise<RepairItemOutcome> {const item = raw as LabelsItem;const { entry } = item;- try {- const changed: RepairItemOutcome = { applied: false, outcome: 'changed_since_preview' };- const snapshot = await ctx.engine.readPageSnapshot(entry.slug, { sourceId: entry.source_id });- if (!snapshot || Number(snapshot.page.id) !== entry.page_id || snapshot.revision !== entry.revision) return changed;- if (isSegmentedPage(snapshot.page)) return { applied: false, outcome: 'segmented_page', reason: 'The page body is stored in segments; edit its frontmatter by hand on the brain host.' };- const frontmatter = snapshot.page.frontmatter ?? {};- let next: Record<string, unknown>;- if (entry.mode === 'clear') {- let decided: Decision = null;- await scanLabelled(ctx.engine, [entry.source_id], row => { decided = classifyPrivateLabel(row); }, [entry.page_id]);- const current = decided as Decision;- if (!current || !('clear' in current) || current.clear !== entry.class || !sameLabels(current.removed, entry.labels)) return changed;- next = Object.fromEntries(Object.entries(frontmatter).filter(([key]) => !Object.hasOwn(entry.labels, key)));- } else {- if (Object.keys(entry.labels).some(key => Object.hasOwn(frontmatter, key))) return changed;- next = { ...frontmatter, ...entry.labels };- }- const requestId = await repairRequestId(ctx, 'private-labels', item, snapshot.revision);- const line: LedgerLine = { at: new Date().toISOString(), brain_id: entry.brain_id, source_id: entry.source_id, slug: entry.slug, page_id: entry.page_id,- revision_before: snapshot.revision, request_id: requestId, ...(entry.mode === 'clear' ? { removed: entry.labels } : { restored: entry.labels }) };- const content = serializePageToMarkdown({ ...snapshot.page, frontmatter: next }, snapshot.tags);- try {- const authority = await maintenancePreflight(ctx.engine, entry.source_id);- if (authority) await publishMaintenancePage(ctx.engine, authority, entry.slug, content, { expectedRevision: snapshot.revision, requestId, keepTrust: true });- else if (!await importAtRevision(ctx.engine, entry, snapshot.revision, content, opts?.embed === true)) return changed;- } catch (error) {- if (acceptedPendingReceipt(error)) {- try { item.ledger.record(line); } catch (ledgerError) {- ctx.logger?.warn?.(`private-labels: ${entry.source_id}:${entry.slug} was accepted but its ledger line was not saved (${ledgerError instanceof Error ? ledgerError.message : String(ledgerError)}). `- + `Keep these values to undo it by hand: ${describeLabels(entry.labels)}.`);- }- }- throw error;- }- const outcome = entry.mode === 'clear' ? 'cleared' : 'restored';- try { item.ledger.record(line); } catch (error) {- const message = error instanceof Error ? error.message : String(error);- return { applied: true, outcome, reason: `The page was written but its ledger line was not saved (${message}). Keep these values to undo it by hand: ${describeLabels(entry.labels)}.`,- detail: { ledger: item.ledger.path, ledger_error: message, labels: entry.labels } };- }- return { applied: true, outcome, detail: { ledger: item.ledger.path } };- } finally {- if (item.last && item.hash) await clearApprovedSet(ctx.engine, { command: 'private-labels', hash: item.hash });+ const changed: RepairItemOutcome = { applied: false, outcome: 'changed_since_preview' };+ const snapshot = await ctx.engine.readPageSnapshot(entry.slug, { sourceId: entry.source_id });+ if (!snapshot || Number(snapshot.page.id) !== entry.page_id || snapshot.revision !== entry.revision) return changed;+ if (isSegmentedPage(snapshot.page)) return { applied: false, outcome: 'segmented_page', reason: 'The page body is stored in segments; edit its frontmatter by hand on the brain host.' };+ const frontmatter = snapshot.page.frontmatter ?? {};+ const labels = ledgerLabels(entry.labels);+ if (!labels) return changed;+ let next: Record<string, unknown>;+ if (entry.mode === 'clear') {+ let decided: Decision = null;+ await scanLabelled(ctx.engine, [entry.source_id], row => { decided = classifyPrivateLabel(row); }, [entry.page_id]);+ const current = decided as Decision;+ if (!current || !('clear' in current) || current.clear !== entry.class || !sameLabels(current.removed, labels)) return changed;+ next = Object.fromEntries(Object.entries(frontmatter).filter(([key]) => !Object.hasOwn(labels, key)));+ } else {+ if (Object.keys(labels).some(key => Object.hasOwn(frontmatter, key))) return changed;+ next = { ...frontmatter, ...labels };+ }+ const authority = await maintenancePreflight(ctx.engine, entry.source_id);+ const requestId = await repairRequestId(ctx, 'private-labels', item, snapshot.revision);+ const line: LedgerLine = { at: new Date().toISOString(), brain_id: entry.brain_id, source_id: entry.source_id, slug: entry.slug, page_id: entry.page_id,+ revision_before: snapshot.revision, request_id: requestId, ...(entry.mode === 'clear' ? { removed: labels } : { restored: labels }) };+ try { item.ledger.record({ ...line, phase: 'intent' }); } catch (error) {+ throw opError('storage_error', `${entry.source_id}:${entry.slug} was not written: the undo ledger ${item.ledger.path} did not take its intent line (${error instanceof Error ? error.message : String(error)}).`,+ `Make ${item.ledger.path} writable by this user, then rerun the same apply command; nothing was changed and the approved preview is kept.`);+ }+ const content = serializePageToMarkdown({ ...snapshot.page, frontmatter: next }, snapshot.tags);+ let written: string | null;+ if (authority) {+ await publishMaintenancePage(ctx.engine, authority, entry.slug, content, { expectedRevision: snapshot.revision, requestId, keepTrust: true });+ written = (await ctx.engine.readPageSnapshot(entry.slug, { sourceId: entry.source_id }))?.revision ?? null;+ } else {+ written = await importAtRevision(ctx.engine, entry, snapshot.revision, content, opts?.embed === true);+ if (!written) return changed;+ }+ const outcome = entry.mode === 'clear' ? 'cleared' : 'restored';+ try { item.ledger.record({ ...line, at: new Date().toISOString(), phase: 'committed', ...(written ? { revision_after: written } : {}) }); } catch (error) {+ const message = error instanceof Error ? error.message : String(error);+ return { applied: true, outcome, reason: `The page was written and its intent line is in the ledger, so --class restore finds it, but its commit line was not saved (${message}).`,+ detail: { ledger: item.ledger.path, ledger_error: message, labels } };+ }+ return { applied: true, outcome, detail: { ledger: item.ledger.path } };+ },+ /** GST-2128 item 7: the approved set is retired only by an apply that attempted every item with no failure, stop or pending write. */+ async report(ctx, _scope, result, opts) {+ if (result.mode === 'apply' && opts.expect && result.complete && !result.stopped && !result.failed.length && !result.pending?.length) {+ await clearApprovedSet(ctx.engine, { command: 'private-labels', hash: opts.expect });}+ return {};},render(details) {const counts = details.counts as { before: Record<string, number>; after: Record<string, number> } | undefined;diff --git a/test/repair-private-labels.test.ts b/test/repair-private-labels.test.tsindex e11a8345f6..f45d3a7e06 100644--- a/test/repair-private-labels.test.ts+++ b/test/repair-private-labels.test.ts@@ -36,6 +36,8 @@ import { claimWorktree } from '../src/core/persistence/ownership.ts';import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';import type { OperationContext } from '../src/core/ops/contract.ts';import { registerLocalWriter } from '../src/core/persistence/identity.ts';+import { privateLabelsLedger } from '../src/commands/repair-private-labels.ts';+import type { PrivateLabelsLedgerLine } from '../src/core/repair/private-labels.ts';let engine: PGLiteEngine;const dir = mkdtempSync(join(tmpdir(), 'gbrain-private-labels-'));@@ -203,7 +205,7 @@ describe('repair private-labels', () => {const ledger = ledgerPath(brainId);expect(statSync(ledger).mode & 0o777).toBe(0o600);expect(statSync(dirname(ledger)).mode & 0o777).toBe(0o700);- const lines = ledgerLines(brainId);+ const lines = ledgerLines(brainId).filter(l => l.phase === 'committed');expect(lines.map(l => [l.slug, l.removed])).toEqual([['notes/alias', { access: 'private' }],['notes/alias-vis', { access: 'Private', visibility: 'private' }],@@ -211,6 +213,11 @@ describe('repair private-labels', () => {expect(lines[0]).toMatchObject({ brain_id: brainId, source_id: 'default', page_id: aliasBefore.page_id, revision_before: aliasBefore.revision });expect(lines[0].request_id).toMatch(/^[0-9a-f-]{36}$/);expect(typeof lines[0].at).toBe('string');+ // GST-2092: each committed line follows its write-ahead intent line (same request) and names the revision it wrote.+ const intents = ledgerLines(brainId).filter(l => l.phase === 'intent');+ expect(intents.map(l => [l.slug, l.removed, l.request_id])).toEqual(lines.map(l => [l.slug, l.removed, l.request_id]));+ expect(lines[0].revision_after).toBe(alias.revision);+ expect(lines[1].revision_after).toBe(vis.revision);});test('a second preview lists the skipped page; once applied, the clear counts are 0 and readers are kept', async () => {@@ -233,8 +240,8 @@ describe('repair private-labels', () => {const slugs = ['notes/alias', 'notes/alias-vis', 'notes/readers'];const cleared = Object.fromEntries(await Promise.all(slugs.map(async slug => [slug, await row(slug)] as const)));const preview = await json(['private-labels', '--class', 'restore']);- expect(preview.details.counts.before).toEqual({ restorable: 3, already_restored: 0, page_gone: 0 });- expect(preview.details.counts.after).toEqual({ restorable: 0, already_restored: 3, page_gone: 0 });+ expect(preview.details.counts.before).toEqual({ restorable: 3, already_restored: 0, page_gone: 0, removed_after_restore: 0 });+ expect(preview.details.counts.after).toEqual({ restorable: 0, already_restored: 3, page_gone: 0, removed_after_restore: 0 });expect(preview.listing).toEqual([{ item: 'default:notes/alias', class: 'restore', detail: 're-add access: private' },{ item: 'default:notes/readers', class: 'restore', detail: 're-add access: private' },@@ -246,11 +253,11 @@ describe('repair private-labels', () => {expect((await row('notes/alias-vis')).frontmatter).toEqual({ ...cleared['notes/alias-vis']!.frontmatter, access: 'Private', visibility: 'private' });expect((await row('notes/readers')).frontmatter).toEqual({ ...cleared['notes/readers']!.frontmatter, access: 'private' });for (const slug of slugs) expect((await row(slug)).compiled_truth).toBe(cleared[slug]!.compiled_truth);- expect(ledgerLines(brainId).filter(l => l.restored).map(l => [l.slug, l.restored])).toEqual([+ expect(ledgerLines(brainId).filter(l => l.restored && l.phase === 'committed').map(l => [l.slug, l.restored])).toEqual([['notes/alias', { access: 'private' }], ['notes/readers', { access: 'private' }], ['notes/alias-vis', { access: 'Private', visibility: 'private' }],]);const again = await json(['private-labels', '--class', 'restore']);- expect(again.details.counts.before).toEqual({ restorable: 0, already_restored: 3, page_gone: 0 });+ expect(again.details.counts.before).toEqual({ restorable: 0, already_restored: 3, page_gone: 0, removed_after_restore: 0 });const relisted = await json(['private-labels']);expect(relisted.details.counts.before.alias).toBe(2);expect(relisted.details.counts.before['alias-and-visibility']).toBe(1);@@ -267,7 +274,8 @@ describe('repair private-labels', () => {expect(applied.skipped).toBe(1);expect((await row('notes/alias')).frontmatter.access).toBe('restricted');expect((await row('notes/readers')).frontmatter.access).toBe('private');- expect(ledgerLines(brainId).filter(l => l.restored && l.slug === 'notes/alias')).toHaveLength(1);+ expect(ledgerLines(brainId).filter(l => l.restored && l.slug === 'notes/alias' && l.phase === 'committed')).toHaveLength(1);+ expect(ledgerLines(brainId).filter(l => l.restored && l.slug === 'notes/alias' && l.phase === 'intent')).toHaveLength(1);});test('a restore recorded while its write was only accepted, whose write then failed, stays restorable', async () => {@@ -400,7 +408,7 @@ describe('repair private-labels --class git-publish on a git-canonical source',expect(readFileSync(file, 'utf8')).not.toMatch(/^access:/m);expect(execFileSync('git', ['log', '--format=%H', '--', 'notes/g.md'], { cwd: root, encoding: 'utf8' }).trim()).not.toBe('');const brain = preview.scope.brain_id;- expect(ledgerLines(brain).filter(l => l.source_id === source).map(l => [l.slug, l.removed])).toEqual([['notes/g', { access: 'private' }]]);+ expect(ledgerLines(brain).filter(l => l.source_id === source && l.phase === 'committed').map(l => [l.slug, l.removed])).toEqual([['notes/g', { access: 'private' }]]);const restorePreview = await json(['private-labels', '--source', source, '--class', 'restore']);expect(restorePreview.listing).toEqual([{ item: source + ':notes/g', class: 'restore', detail: 're-add access: private' }]);@@ -417,28 +425,39 @@ describe('repair private-labels --class git-publish on a git-canonical source',});describe('repair private-labels when the undo ledger cannot record', () => {- test('a clear whose ledger line fails to save still reports the page as applied and names the removed values; restore then says where to run', async () => {+ test('the intent line is written before the page: a ledger that cannot record refuses the clear and leaves the label; the same --expect resumes once it can (GST-2092, GST-2128 item 7)', async () => {const source = 'source-h';const home = mkdtempSync(join(tmpdir(), 'gbrain-private-labels-ledger-'));mkdirSync(join(home, '.gbrain', 'repair'), { recursive: true });writeFileSync(join(home, '.gbrain', 'repair', 'private-labels'), 'a file where the ledger directory belongs');- const runIn = async (argv: string[]) => {- const out = JSON.parse(await withEnv({ GBRAIN_HOME: home, GBRAIN_INTERACTIVE: '0', CI: '1' }, () => capture(() => runRepairCommand(engine, [...argv, '--json'])))).results[0];- _resetCliExitVerdictForTests();- return out;- };+ const inHome = (argv: string[]) => withEnv({ GBRAIN_HOME: home, GBRAIN_INTERACTIVE: '0', CI: '1' }, () => capture(() => runRepairCommand(engine, [...argv, '--json'])));+ const runIn = async (argv: string[]) => { const out = JSON.parse(await inHome(argv)).results[0]; _resetCliExitVerdictForTests(); return out; };try {await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [source]);await seed('notes/h', 'note', { access: 'private' }, source);const preview = await runIn(['private-labels', '--source', source]);+ const refused = await refusal(() => inHome(['private-labels', '--source', source, '--apply', '--expect', preview.preview_hash]));+ _resetCliExitVerdictForTests();+ expect(refused.code).toBe('storage_error');+ expect(refused.message).toContain('ledger');+ expect((await row('notes/h', source)).frontmatter.access).toBe('private');+ rmSync(join(home, '.gbrain', 'repair', 'private-labels'));const applied = await runIn(['private-labels', '--source', source, '--apply', '--expect', preview.preview_hash]);expect(applied.failed).toEqual([]);expect(applied.applied).toBe(1);- expect(JSON.stringify(applied)).toContain('access: private');expect('access' in (await row('notes/h', source)).frontmatter).toBe(false);const restore = await runIn(['private-labels', '--source', source, '--class', 'restore']);- expect(restore.listing ?? []).toEqual([]);- expect(restore.warnings.some((w: string) => w.includes('has no line for brain') && w.includes(restore.details.ledger))).toBe(true);+ expect(restore.listing).toEqual([{ item: source + ':notes/h', class: 'restore', detail: 're-add access: private' }]);+ } finally { rmSync(home, { recursive: true, force: true }); }+ });++ test('restore in a home whose ledger has no line for the brain says where to run it', async () => {+ const home = mkdtempSync(join(tmpdir(), 'gbrain-private-labels-empty-'));+ try {+ const out = JSON.parse(await withEnv({ GBRAIN_HOME: home, GBRAIN_INTERACTIVE: '0', CI: '1' }, () => capture(() => runRepairCommand(engine, ['private-labels', '--source', 'source-h', '--class', 'restore', '--json'])))).results[0];+ _resetCliExitVerdictForTests();+ expect(out.listing ?? []).toEqual([]);+ expect(out.warnings.some((w: string) => w.includes('has no line for brain') && w.includes(out.details.ledger))).toBe(true);} finally { rmSync(home, { recursive: true, force: true }); }});});@@ -453,3 +472,129 @@ test('a page with declared lineage keeps its label whatever its type, so its orifor (const frontmatter of lineage) expect(classifyPrivateLabel({ type: 'note', frontmatter, git: false })).toEqual({ keep: 'derived' });expect(classifyPrivateLabel({ type: 'note', frontmatter: { access: 'private' }, git: false })).toEqual({ clear: 'alias', removed: { access: 'private' } });});++/**+ * GST-2092: the undo ledger is write-ahead. A crash between the page write and the line that confirms it (forced here:+ * the commit append throws, as a process that died there would leave the file) still leaves the intent line, so+ * --class restore finds the page and puts the label back.+ */+describe('repair private-labels write-ahead ledger', () => {+ test('a crash after the page write and before its commit line leaves the intent line, and restore puts the label back', async () => {+ const source = 'source-w';+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [source]);+ await seed('notes/w', 'note', { access: 'private', topic: 'kept' }, source);+ const before = await row('notes/w', source);+ const preview = await json(['private-labels', '--source', source]);+ expect(preview.listing).toEqual([{ item: source + ':notes/w', class: 'alias', detail: 'remove access: private' }]);+ const brain = preview.scope.brain_id;+ const scope = await resolveRepairScope(engine, source);+ const logger = { info() {}, warn() {}, error() {} };+ const applied = await withEnv({ GBRAIN_HOME: dir }, async () => {+ const real = privateLabelsLedger(brain);+ const crashing = { ...real, record(line: PrivateLabelsLedgerLine) {+ if (line.phase !== 'intent') throw new Error('forced crash after the page write');+ real.record(line);+ } };+ return (await repairRunner(engine, { apply: true, logger })).run('private-labels', scope, { explicit: true, expect: preview.preview_hash, privateLabelsLedger: crashing });+ });+ expect(applied.failed).toEqual([]);+ expect('access' in (await row('notes/w', source)).frontmatter).toBe(false);+ const lines = ledgerLines(brain).filter(l => l.source_id === source);+ expect(lines.map(l => [l.slug, l.phase, l.removed])).toEqual([['notes/w', 'intent', { access: 'private' }]]);+ const restorePreview = await json(['private-labels', '--source', source, '--class', 'restore']);+ expect(restorePreview.listing).toEqual([{ item: source + ':notes/w', class: 'restore', detail: 're-add access: private' }]);+ const restored = await json(['private-labels', '--source', source, '--class', 'restore', '--apply', '--expect', restorePreview.preview_hash]);+ expect(restored.applied).toBe(1);+ expect((await row('notes/w', source)).frontmatter).toEqual(before.frontmatter);+ expect(ledgerLines(brain).filter(l => l.source_id === source).map(l => [l.phase, l.restored ?? null])).toEqual([+ ['intent', null], ['intent', { access: 'private' }], ['committed', { access: 'private' }],+ ]);+ });+});++/**+ * GST-2128 item 4: restore reads ledger lines as untrusted input. Only access and visibility (visibility only as+ * private) with string values are re-added; any other line, and one whose page id is not an integer, is counted+ * unreadable instead of failing the preview or reaching a page.+ */+describe('repair private-labels restore reads only well-formed ledger lines', () => {+ test('a line with another key, a non-string value, a widening visibility or a non-integer page id is unreadable, and the rest restores', async () => {+ const source = 'source-r';+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [source]);+ await seed('notes/r1', 'note', { access: 'private' }, source);+ await seed('notes/r2', 'note', { topic: 'plain' }, source);+ const clear = await json(['private-labels', '--source', source]);+ expect((await json(['private-labels', '--source', source, '--apply', '--expect', clear.preview_hash])).applied).toBe(1);+ const brain = clear.scope.brain_id;+ const r2 = await row('notes/r2', source);+ const base = { at: new Date().toISOString(), brain_id: brain, source_id: source, slug: 'notes/r2', page_id: r2.page_id, revision_before: r2.revision, request_id: crypto.randomUUID() };+ for (const line of [+ { ...base, removed: { access: 'private', owner: 'mallory-example' } },+ { ...base, removed: { access: 7 } },+ { ...base, removed: { visibility: 'world' } },+ { ...base, page_id: 'not-a-page', removed: { access: 'private' } },+ ]) appendFileSync(ledgerPath(brain), JSON.stringify(line) + NL);+ const preview = await json(['private-labels', '--source', source, '--class', 'restore']);+ expect(preview.listing).toEqual([{ item: source + ':notes/r1', class: 'restore', detail: 're-add access: private' }]);+ expect(preview.details.counts.before.restorable).toBe(1);+ expect(preview.warnings.some((w: string) => w.startsWith('4 ledger line(s) could not be read'))).toBe(true);+ const restored = await json(['private-labels', '--source', source, '--class', 'restore', '--apply', '--expect', preview.preview_hash]);+ expect(restored.applied).toBe(1);+ expect((await row('notes/r1', source)).frontmatter.access).toBe('private');+ expect((await row('notes/r2', source)).frontmatter).toEqual(r2.frontmatter);+ });+});++/**+ * GST-2128 item 9: a restore whose write landed is recorded with the revision it wrote. A page whose label was removed+ * by hand after that is not listed again: the preview counts it as removed_after_restore and says so.+ */+describe('repair private-labels restore after a landed restore', () => {+ test('a label removed by hand after a landed restore is counted and not listed', async () => {+ const source = 'source-m';+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [source]);+ await seed('notes/m', 'note', { access: 'private' }, source);+ const clear = await json(['private-labels', '--source', source]);+ expect((await json(['private-labels', '--source', source, '--apply', '--expect', clear.preview_hash])).applied).toBe(1);+ const restore = await json(['private-labels', '--source', source, '--class', 'restore']);+ expect((await json(['private-labels', '--source', source, '--class', 'restore', '--apply', '--expect', restore.preview_hash])).applied).toBe(1);+ expect((await row('notes/m', source)).frontmatter.access).toBe('private');+ await seed('notes/m', 'note', { topic: 'edited by hand' }, source);+ const again = await json(['private-labels', '--source', source, '--class', 'restore']);+ expect(again.listing ?? []).toEqual([]);+ expect(again.details.counts.before).toEqual({ restorable: 0, already_restored: 0, page_gone: 0, removed_after_restore: 1 });+ expect(again.warnings.some((w: string) => w.includes('removed after a restore landed'))).toBe(true);+ });+});++/**+ * GST-2128 item 7: an apply whose last item fails keeps the approved set, so the same --expect resumes once the cause is gone.+ */+describe('repair private-labels resumes the same --expect after the last item failed', () => {+ test('a forced failure on the last item, then the same apply command applies it', async () => {+ const source = 'source-k';+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [source]);+ await seed('notes/k1', 'note', { access: 'private' }, source);+ await seed('notes/k2', 'note', { access: 'private' }, source);+ const preview = await json(['private-labels', '--source', source]);+ expect(preview.listing.map((l: { item: string }) => l.item)).toEqual([source + ':notes/k1', source + ':notes/k2']);+ await engine.executeRaw(`CREATE OR REPLACE FUNCTION test_refuse_k2() RETURNS trigger LANGUAGE plpgsql AS $$+ BEGIN IF NEW.source_id = 'source-k' AND NEW.slug = 'notes/k2' THEN RAISE EXCEPTION 'forced failure for notes/k2'; END IF; RETURN NEW; END $$`);+ await engine.executeRaw('CREATE TRIGGER test_refuse_k2 BEFORE UPDATE ON pages FOR EACH ROW EXECUTE FUNCTION test_refuse_k2()');+ let failed: unknown = null;+ try {+ failed = await run(['private-labels', '--source', source, '--apply', '--expect', preview.preview_hash, '--json'])+ .then(out => JSON.parse(out).results[0].failed.length ? 'item failed' : null, (error: unknown) => error);+ } finally {+ _resetCliExitVerdictForTests();+ await engine.executeRaw('DROP TRIGGER test_refuse_k2 ON pages');+ await engine.executeRaw('DROP FUNCTION test_refuse_k2()');+ }+ expect(failed).not.toBeNull();+ expect((await row('notes/k2', source)).frontmatter.access).toBe('private');+ const retried = await json(['private-labels', '--source', source, '--apply', '--expect', preview.preview_hash]);+ expect(retried.failed).toEqual([]);+ expect('access' in (await row('notes/k1', source)).frontmatter).toBe(false);+ expect('access' in (await row('notes/k2', source)).frontmatter).toBe(false);+ });+});