Skip to content

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.ts
index 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.ts
index 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: Sel
return { 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.ts
index 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 ori
for (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);
+ });
+});