Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
52.0 KB
Raw Blame
/**
 * gbrain repair private-labels: clear the privacy labels that writer templates
 * over-stamped on ordinary pages. Every live page that is private by its label
 * (visibility: private, or a privacy alias with no visibility) is classified:
 *
 *   KEEP (counted, never changed)
 *     pinned_question      pinned_question in frontmatter, or type question
 *     derived              an atom, a page with derived_from or source_slug, a synthesized
 *                          concept or a life-chronicle event;
 *                          its privacy follows its origin (gbrain repair visibility owns it)
 *     strong_alias         access restricted or confidential, or a private confidentiality value
 *     explicit_visibility  visibility: private with no access: private (a deliberate writer or connector)
 *
 *   CLEAR (the only pages changed)
 *     alias                access: private and no visibility: the access key is removed
 *     alias-and-visibility access: private and visibility: private: both keys are removed
 *     git-publish          either of the two in a source with canonical git; private pages
 *                          there are database-only, so clearing commits the page into Git
 *                          for the first time. Applied only when named with --class git-publish.
 *
 * The preview lists one window (--limit, default PRIVATE_LABELS_WINDOW) of clear items in
 * (class, page id) order under a hash, with every category's count over the scope before
 * and after the window; --apply --expect <hash> applies exactly that window, re-deciding
 * each page against its live revision and labels first. A bare --apply is refused. Each
 * item is one revision-bound label-only write (repair/label-write.ts), so it keeps the page's
 * trust tier (no trust_tier marker, no lower_page proposal) and its gate markers: a managed
 * brain publishes it through the maintenance door (the Git door on a repo source) with
 * keep_trust and its label edit, so the page's file changes only in the removed or re-added
 * label lines (GST-2468); an unmanaged one imports it in a maintenance transaction under the
 * page lock, also keeping the stored tier. readable_by and folder rules are left as they are.
 *
 * The preview also counts, per window and by category, the pages whose only privacy is a listed
 * page's label and that the window would expose with it (`dependents`, never slugs): derived_from
 * pages whose declared origin loses its visibility: private, and life-chronicle events extracted
 * from a listed page. On a brain without managed persistence a page whose file sits in its source's
 * checkout is held (`file_backed`): the repair writes only the database there, and the next sync or
 * re-import would put the label back from the file.
 *
 * 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 { openTwins, openTwinsLines, openTwinsWarning, type OpenTwins } from '../access/open-twins.ts';
import { ownerMemberId } from '../access/owner.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, 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';
import { digest } from '../persistence/digest.ts';
import { modeRequiresSynopsis } from '../embedding-context.ts';
import { chunkGenerationFilter } from '../search/safe-chunks.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
import { PRIVACY_ALIASES, privacyAliasSql, privacyPartSql, privateSnapshotFilterFragment, readHonorAliases } from '../search/private-visibility.ts';
import { asciiLower } from '../edge-whitespace.ts';
import { afterCursor, repairRequestId, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairPlanOptions, type RepairScope, type RepairSettlement } from './core.ts';

export type ClearClass = 'alias' | 'alias-and-visibility' | 'git-publish';
export type KeepClass = 'pinned_question' | 'derived' | 'strong_alias' | 'explicit_visibility';
type LabelsClass = ClearClass | 'restore';
const KEEP_CLASSES: readonly KeepClass[] = ['pinned_question', 'derived', 'strong_alias', 'explicit_visibility'];
const CLEAR_CLASSES: readonly ClearClass[] = ['alias', 'alias-and-visibility', 'git-publish'];
export const PRIVATE_LABELS_CLASSES: readonly LabelsClass[] = [...CLEAR_CLASSES, 'restore'];
/** Without --class a preview covers these; git-publish commits pages into Git and runs only when named. */
const DEFAULT_CLASSES: readonly ClearClass[] = ['alias', 'alias-and-visibility'];
export const PRIVATE_LABELS_WINDOW = 1000;
export const PRIVATE_LABELS_WINDOW_MAX = 10_000;
const SCAN_PAGE = 5000;
const bounded = { timeoutMs: 120_000 };

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 }
/** `tried` (GBRA-443): an earlier apply tried this page and it did not change; its decline again does not count toward the breaker. */
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; exposes?: number[]; tried?: true }
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 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. */
export function classifyPrivateLabel(row: Pick<LabelRow, 'type' | 'frontmatter' | 'git'>): Decision {
  const fm = row.frontmatter ?? {};
  const value = (key: string) => typeof fm[key] === 'string' ? asciiLower((fm[key] as string).trim()) : null;
  const aliased = Object.entries(PRIVACY_ALIASES).some(([key, values]) => values.includes(value(key) ?? ''));
  if (!(fm.visibility === 'private' || (fm.visibility == null && aliased))) return null;
  if (Object.hasOwn(fm, 'pinned_question') || row.type === 'question') return { keep: 'pinned_question' };
  if (row.type === 'atom' || Object.hasOwn(fm, 'derived_from') || Object.hasOwn(fm, 'source_slug') || (row.type === 'concept' && fm.synthesized_by != null)
    || (row.type === 'event' && typeof fm.captured_via === 'string' && fm.captured_via.startsWith('life-chronicle:'))) return { keep: 'derived' };
  const access = value('access');
  if (access === 'restricted' || access === 'confidential' || PRIVACY_ALIASES.confidentiality!.includes(value('confidentiality') ?? '')) return { keep: 'strong_alias' };
  if (access !== 'private') return { keep: 'explicit_visibility' };
  const removed: Labels = fm.visibility == null ? { access: fm.access as string } : { access: fm.access as string, visibility: 'private' };
  return { clear: row.git ? 'git-publish' : removed.visibility ? 'alias-and-visibility' : 'alias', removed };
}

/** Live pages of the sources that a label makes private, in page id order (`ids` narrows to those pages). */
async function scanLabelled(engine: BrainEngine, sourceIds: string[], visit: (row: LabelRow) => void, ids?: number[]): Promise<void> {
  for (let after = 0; ;) {
    const rows = await engine.executeRaw<LabelRow>(`SELECT p.id, p.source_id, p.slug, p.type, p.frontmatter, p.knowledge_revision::text AS revision,
        COALESCE(p.body_bytes, 0) AS chars, COALESCE(s.config->>'canonical' = 'git', false) AS git
      FROM pages p JOIN sources s ON s.id = p.source_id
      WHERE p.deleted_at IS NULL AND p.source_id = ANY($1::text[]) AND p.id > $2
        AND (p.frontmatter->>'visibility' = 'private' OR (p.frontmatter->>'visibility' IS NULL AND ${privacyAliasSql('p')}))
        AND ($3::integer[] IS NULL OR p.id = ANY($3::integer[]))
      ORDER BY p.id LIMIT ${SCAN_PAGE}`, [sourceIds, after, ids ?? null], bounded);
    for (const row of rows) visit(row);
    if (rows.length < SCAN_PAGE) return;
    after = Number(rows[rows.length - 1]!.id);
  }
}

/** 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) =>
  `gbrain repair private-labels${scope.source_ids.length === 1 ? ` --source ${scope.source_ids[0]}` : ''}${selection.class ? ` --class ${selection.class}` : ''}`;

function selectedClass(opts?: RepairPlanOptions): LabelsClass | null {
  const value = opts?.driftClass;
  if (value === undefined) return null;
  if ((PRIVATE_LABELS_CLASSES as readonly string[]).includes(value)) return value as LabelsClass;
  throw opError('invalid_params', `--class for gbrain repair private-labels takes ${PRIVATE_LABELS_CLASSES.join(', ')} (got "${value}").`,
    'Preview the default classes with gbrain repair private-labels, or one with e.g. gbrain repair private-labels --class git-publish.');
}

const hashParts = (scope: RepairScope, selection: Selection, entries: Approved[]) => ({ kind: 'private-labels-v1', brain_id: scope.brain_id, selection,
  items: entries.map(e => [e.mode, e.class, e.source_id, e.page_id, e.slug, e.revision, Object.entries(e.labels).sort(), e.exposes ?? []]) });

/** Every category's count over the scope and the clear entries of the selected classes, in (class, page id) order. */
async function planClear(engine: BrainEngine, scope: RepairScope, selection: Selection, classes: readonly ClearClass[], ledger?: PrivateLabelsLedger) {
  const counts = Object.fromEntries([...KEEP_CLASSES, ...CLEAR_CLASSES].map(cls => [cls, 0])) as Record<KeepClass | ClearClass, number>;
  const entries: Approved[] = [];
  await scanLabelled(engine, scope.source_ids, row => {
    const decided = classifyPrivateLabel(row);
    if (!decided) return;
    if ('keep' in decided) { counts[decided.keep]++; return; }
    counts[decided.clear]++;
    if (classes.includes(decided.clear)) entries.push({ mode: 'clear', class: decided.clear, brain_id: scope.brain_id, source_id: row.source_id, slug: row.slug,
      page_id: Number(row.id), revision: row.revision, labels: decided.removed, chars: Number(row.chars), selection });
  });
  const tried = triedBefore(ledger, scope.brain_id);
  for (const entry of entries) if (tried.has(entry.source_id + '\0' + entry.page_id)) entry.tried = true;
  const retry = (entry: Approved) => Number(entry.tried === true);
  entries.sort((a, b) => retry(a) - retry(b) || CLEAR_CLASSES.indexOf(a.class as ClearClass) - CLEAR_CLASSES.indexOf(b.class as ClearClass) || a.page_id - b.page_id);
  return { counts: counts as Record<string, number>, entries, unreadable: 0 };
}

/**
 * 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) {
  let unreadable = ledger.unreadable;
  const pages = new Set<string>();
  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;
    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 = [...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(({ 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, removed_after_restore: 0 };
  const entries: Approved[] = [];
  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: 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 };
}

/**
 * The pages of a source in `from` (source_id, slug) whose frontmatter can name one of its slugs: `event.depth` alone with
 * `depthOnly`, else also `source_slug` and a `derived_from` string or array entry, with or without `.md`. Each source's
 * slugs, 100 at a time, make one jsonpath filter that idx_pages_frontmatter answers in a single scan (every GIN scan reads
 * the index's whole pending list, so a scan per slug and shape cost more than the full read it replaced on a brain with
 * recent writes). A slug that reads as a JSON number or boolean is also matched as that scalar, since `->>` and
 * jsonb_array_elements_text read one as its text; a number with an exponent over three digits is matched as text only,
 * since the jsonpath cast of one (`1e999999`) overflows numeric and would fail the whole lookup.
 */
function namingSql(from: string, depthOnly = false): string {
  const test = depthOnly ? `'@.event.depth == ' || f.v`
    : `'@.source_slug == ' || f.v || ' || @.event.depth == ' || f.v || ' || @.derived_from == ' || f.v || ' || @.derived_from == ' || to_jsonb(n.slug || '.md')::text`;
  return `SELECT p.id, p.source_id, p.slug, p.frontmatter ? 'derived_from' AS declares FROM (
      SELECT n.source_id, ('$ ? (' || string_agg(${test}, ' || ') || ')')::jsonpath AS path
        FROM (SELECT DISTINCT source_id, slug, (dense_rank() OVER (PARTITION BY source_id ORDER BY slug) - 1) / 100 AS part FROM ${from} r) n
        CROSS JOIN LATERAL (SELECT to_jsonb(n.slug)::text AS v UNION ALL SELECT n.slug WHERE n.slug ~ '^(-?(0|[1-9][0-9]*)(\\.[0-9]+)?([eE][+-]?[0-9]{1,3})?|true|false)$') f
        GROUP BY n.source_id, n.part) q
      JOIN LATERAL (SELECT p.id, p.source_id, p.slug, p.frontmatter FROM pages p WHERE p.frontmatter @? q.path AND p.source_id = q.source_id OFFSET 0) p ON true`;
}

/**
 * The windowDependents statement: (id, cleared_id, category) for each exposed page and the cleared page it is tied to, from
 * the cleared pages ($1 ids, $2 source ids, $3 slugs, $4 comma-joined label keys). It never pairs every page with every
 * cleared page: one scan of the window's sources lists each page's references (source_slug, event.depth, each
 * derived_from slug without `.md`), and every tie is an equality join of those references, or of concept-provenance
 * links through idx_links_to, to the cleared pages. The postimage is the pages table shadowed with the window's keys
 * removed; its privacy rules read only candidate pages and the pages they name.
 *
 * GST-2689 `remove`: the postimage is the pages table with the cleared pages removed instead (their rows, so the links to
 * them go too), `keys` is unused, an atom also ties to the page a rename moved its `source_slug` to (slug_aliases and
 * slug_rename_history, read before a purge scrubs them). Its references are read only from the pages that can name a
 * cleared page, found through idx_pages_frontmatter (a containment probe per reference shape, for each cleared slug and
 * each slug a rename moved to it), and from the events whose `event.depth` names one of those pages, so the statement
 * costs the same on a large source as on a small one; the probes find a superset and `refs` keeps only exact matches.
 * A page that names readers is judged by the same privacy rules, since readable_by never relaxes them: it is returned
 * when the removal would open it to its listed readers. A soft-deleted page is a candidate too, since a restore brings it
 * back with the origin row gone, and so is a removed page tied to another removed page (judged on its own row, against
 * the postimage), since another hold may keep it from the purge.
 */
export function dependentsSql(mode: 'clear' | 'remove' = 'clear'): string {
  const remove = mode === 'remove';
  const live = (sql: string) => remove ? '' : sql;
  return `WITH cleared AS MATERIALIZED (
      SELECT * FROM unnest($1::integer[], $2::text[], $3::text[], $4::text[]) AS c(id, source_id, slug, keys)),${remove ? `
    named AS MATERIALIZED (SELECT c.source_id, c.slug FROM cleared c
      UNION SELECT a.source_id, a.alias_slug FROM cleared c JOIN slug_aliases a ON a.source_id = c.source_id AND a.canonical_slug = c.slug AND a.notes = 'rename'
      UNION SELECT m.source_id, m.old_slug FROM cleared c JOIN slug_rename_history m ON m.source_id = c.source_id AND m.new_slug = c.slug),
    naming AS MATERIALIZED (${namingSql('named')}),
    depth_naming AS MATERIALIZED (${namingSql('(SELECT DISTINCT source_id, slug FROM naming WHERE declares)', true)}),` : ''}
    refs AS MATERIALIZED (SELECT p.id, p.source_id, p.slug, p.deleted_at, r.kind, r.ref FROM ${remove ? `(SELECT id FROM naming UNION SELECT id FROM depth_naming) k
      JOIN LATERAL (SELECT pages.id, pages.source_id, pages.slug, pages.deleted_at, pages.frontmatter FROM pages WHERE pages.id = k.id OFFSET 0) p ON true` : 'pages p'}
      CROSS JOIN LATERAL (SELECT 'source_slug' AS kind, p.frontmatter->>'source_slug' AS ref
        UNION ALL SELECT 'depth', p.frontmatter->'event'->>'depth'
        UNION ALL SELECT 'declared', regexp_replace(declared.slug, '\\.md$', '') FROM jsonb_array_elements_text(
          CASE jsonb_typeof(p.frontmatter->'derived_from') WHEN 'array' THEN p.frontmatter->'derived_from'
            WHEN 'string' THEN jsonb_build_array(p.frontmatter->'derived_from') ELSE '[]'::jsonb END) AS declared(slug)${remove ? `
        UNION ALL SELECT 'source_slug', renamed.canonical_slug FROM slug_aliases renamed WHERE renamed.source_id = p.source_id
          AND renamed.alias_slug = p.frontmatter->>'source_slug' AND renamed.notes = 'rename'
        UNION ALL SELECT 'source_slug', moved.new_slug FROM slug_rename_history moved WHERE moved.source_id = p.source_id
          AND moved.old_slug = p.frontmatter->>'source_slug'` : ''}) r
      WHERE p.source_id = ANY($2::text[]) AND r.ref IS NOT NULL),
    hits AS MATERIALIZED (SELECT r.id, r.source_id, r.slug, r.deleted_at, r.kind, c.id AS cleared_id
      FROM refs r JOIN cleared c ON c.source_id = r.source_id AND c.slug = r.ref),
    provenance AS MATERIALIZED (SELECT l.from_page_id, x.cleared_id, x.source_id
      FROM (SELECT c.id, c.id AS cleared_id, c.source_id FROM cleared c UNION ALL SELECT h.id, h.cleared_id, h.source_id FROM hits h WHERE h.kind = 'source_slug') x
      JOIN links l ON l.to_page_id = x.id WHERE l.link_source = 'concept-provenance' AND l.link_type = 'synthesized_from'),
    ties AS (SELECT h.id, h.cleared_id FROM hits h${live(' WHERE h.deleted_at IS NULL')}
      UNION ALL SELECT r.id, h.cleared_id FROM hits h JOIN refs r ON r.source_id = h.source_id AND r.kind = 'depth' AND r.ref = h.slug
        WHERE h.kind = 'declared'${live(' AND r.deleted_at IS NULL')}
      UNION ALL SELECT p.id, t.cleared_id FROM provenance t JOIN pages p ON p.id = t.from_page_id AND p.source_id = t.source_id${live(' AND p.deleted_at IS NULL')}),
    candidates AS MATERIALIZED (SELECT DISTINCT t.id, t.cleared_id FROM ties t WHERE ${remove ? 't.id <> t.cleared_id' : 'NOT EXISTS (SELECT 1 FROM cleared x WHERE x.id = t.id)'}),${remove ? `
    candidate_rows AS MATERIALIZED (SELECT a.id, a.source_id, a.slug, a.type, a.frontmatter FROM (SELECT DISTINCT id FROM candidates) k
      JOIN LATERAL (SELECT pages.id, pages.source_id, pages.slug, pages.type, pages.frontmatter FROM pages WHERE pages.id = k.id OFFSET 0) a ON true),` : ''}
    public_after AS MATERIALIZED (WITH pages AS NOT MATERIALIZED (${remove ? `SELECT pg.id, pg.source_id, pg.slug, pg.type, pg.deleted_at, pg.frontmatter
        FROM pages pg WHERE pg.id <> ALL($1::integer[])` : `SELECT pg.id, pg.source_id, pg.slug, pg.type, pg.deleted_at,
          CASE WHEN c.id IS NULL THEN pg.frontmatter ELSE pg.frontmatter - string_to_array(c.keys, ',') END AS frontmatter
        FROM pages pg LEFT JOIN cleared c ON c.id = pg.id`})
      SELECT after_clear.id FROM (${remove ? 'SELECT * FROM candidate_rows' : `SELECT a.id, a.source_id, a.slug, a.type, a.frontmatter FROM (SELECT DISTINCT id FROM candidates) k
        JOIN pages a ON a.id = k.id`} OFFSET 0) after_clear WHERE ${privacyPartSql('after_clear', true)})
    SELECT cand.id, cand.cleared_id, CASE WHEN p.type = 'event' AND p.frontmatter->>'captured_via' LIKE 'life-chronicle:%' THEN 'life_chronicle'
        WHEN p.type = 'atom' THEN 'atom' WHEN p.type = 'concept' AND p.frontmatter->>'synthesized_by' IS NOT NULL THEN 'concept' ELSE 'derived_from' END AS category
      FROM candidates cand JOIN ${remove ? 'candidate_rows' : 'pages'} p ON p.id = cand.id
      WHERE cand.id IN (SELECT id FROM public_after) AND NOT ${privacyPartSql('p')}
      ORDER BY cand.id, cand.cleared_id`;
}

type Dependents = { derived_from: number; atom: number; concept: number; life_chronicle: number };

/**
 * GST-2093: the pages a window's clears expose besides themselves, by category, judged by the remote privacy rules
 * (privacyPartSql) on each page as it is now and as it would be once the window applies. A candidate is a live page of
 * the same source tied to a cleared page the way those rules follow privacy: `derived_from`, an atom's `source_slug`, a
 * life-chronicle event's `event.depth` (or the `derived_from` of the page it names), or a concept-provenance link to a cleared atom or to an atom of a cleared origin.
 * The postimage is the pages table shadowed with the window's keys removed. Also returned, per cleared page id, the
 * exposed page ids tied to it: the preview hash binds them, and apply refuses a window that would expose a page outside them.
 */
async function windowDependents(engine: BrainEngine, window: Approved[]): Promise<{ counts: Dependents; exposes: Map<number, number[]> }> {
  const counts: Dependents = { derived_from: 0, atom: 0, concept: 0, life_chronicle: 0 };
  const exposes = new Map<number, number[]>();
  const clears = window.filter(entry => entry.mode === 'clear');
  if (!clears.length) return { counts, exposes };
  await readHonorAliases(engine);
  const rows = await engine.executeRaw<{ id: number; cleared_id: number; category: keyof Dependents }>(dependentsSql(),
    [clears.map(entry => entry.page_id), clears.map(entry => entry.source_id), clears.map(entry => entry.slug), clears.map(entry => Object.keys(entry.labels).sort().join(','))],
    { ...bounded, jitOff: true, prepare: false });
  const counted = new Set<number>();
  for (const row of rows) {
    const id = Number(row.id);
    if (!counted.has(id)) { counted.add(id); counts[row.category]++; }
    exposes.set(Number(row.cleared_id), [...(exposes.get(Number(row.cleared_id)) ?? []), id]);
  }
  return { counts, exposes };
}

/** GBRA-443: lines this run appended to its ledger, by phase (the apply result's ledger_rows_written and ledger_rows), kept on the ledger it was handed. */
type CountedLedger = PrivateLabelsLedger & { rows?: { intent: number; committed: number } };
function recordLine(ledger: CountedLedger, line: LedgerLine & { phase: 'intent' | 'committed' }): void {
  ledger.record(line);
  (ledger.rows ??= { intent: 0, committed: 0 })[line.phase]++;
}

/**
 * GBRA-443: the pages (brain, source, page id) whose latest ledger line is a removal's intent line with nothing after it:
 * an earlier apply tried to clear them and the write did not land (a declined page; a crash before its write, too). The
 * preview lists them after every page not tried yet, so a page that keeps declining stops heading each new window.
 */
function triedBefore(ledger: PrivateLabelsLedger | undefined, brainId: string): Set<string> {
  const latest = new Map<string, LedgerLine>();
  for (const raw of ledger?.lines ?? []) {
    const line = readableLine(raw);
    if (line && line.brain_id === brainId) latest.set(line.source_id + '\0' + line.page_id, line);
  }
  return new Set([...latest].flatMap(([key, line]) => line.removed && line.phase === 'intent' ? [key] : []));
}

/** GBRA-443: the listed items whose write embeds: a label-only edit keeps every stored vector except on a page stored under per-chunk synopsis; a page with a chunk that has no vector yet is counted too. */
async function reembedding(engine: BrainEngine, items: LabelsItem[]): Promise<LabelsItem[]> {
  if (!items.length) return [];
  const ids = items.map(item => item.entry.page_id);
  const rows = await engine.executeRaw<{ id: number; mode: string }>(`SELECT id, contextual_retrieval_mode AS mode FROM pages
    WHERE id = ANY($1::integer[]) AND contextual_retrieval_mode IS NOT NULL`, [ids], bounded);
  const unembedded = await engine.executeRaw<{ id: number }>(`SELECT DISTINCT cc.page_id AS id FROM content_chunks cc JOIN pages p ON p.id = cc.page_id
    WHERE cc.page_id = ANY($1::integer[]) AND cc.embedding IS NULL AND ${chunkGenerationFilter('p', 'cc')}`, [ids], bounded);
  const embeds = new Set([...rows.filter(row => modeRequiresSynopsis(row.mode as Parameters<typeof modeRequiresSynopsis>[0])).map(row => Number(row.id)),
    ...unembedded.map(row => Number(row.id))]);
  return items.filter(item => embeds.has(item.entry.page_id));
}

const CHANGED: RepairItemOutcome = { applied: false, outcome: 'changed_since_preview' };
interface Ready { revision: string; content: string; labels: Labels }

/**
 * One approved item re-decided against its live page: the page write it needs, or the outcome that leaves it alone (moved
 * since the preview, segmented, no longer this class, or held as file_backed on an unmanaged brain).
 */
async function prepareWrite(ctx: OperationContext, item: LabelsItem): Promise<Ready | { outcome: RepairItemOutcome }> {
  const { entry } = item;
  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 { outcome: CHANGED };
  if (isSegmentedPage(snapshot.page)) return { outcome: { 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 { outcome: 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 { outcome: 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 { outcome: CHANGED };
    if (!Object.values(labels).every(isPlainLabelValue)) {
      return { outcome: { applied: false, outcome: 'label_not_plain', reason: `${describeLabels(labels)} cannot be written back as plain label lines; add it to the page's file by hand, commit it, then run: gbrain sync --source ${entry.source_id}` } };
    }
    next = { ...frontmatter, ...labels };
  }
  const file = (await filesInCheckout(ctx.engine, [entry.page_id])).get(entry.page_id);
  if (file) {
    return { outcome: { applied: false, outcome: 'file_backed', detail: { path: file },
      reason: `${entry.source_id}:${entry.slug} has a file in its source's checkout (${file}); on a brain without managed persistence this repair writes only the database, `
        + `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}` } };
  }
  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). */
async function ledgerLine(ctx: OperationContext, item: LabelsItem, ready: Ready): Promise<LedgerLine> {
  const { entry } = item;
  return { at: new Date().toISOString(), brain_id: entry.brain_id, source_id: entry.source_id, slug: entry.slug, page_id: entry.page_id,
    revision_before: ready.revision, request_id: await repairRequestId(ctx, 'private-labels', item, ready.revision),
    ...(entry.mode === 'clear' ? { removed: ready.labels } : { restored: ready.labels }) };
}

/** Write-ahead: the intent line lands before the page write, or the item is refused with nothing written. */
function recordIntent(item: LabelsItem, line: LedgerLine): void {
  try { recordLine(item.ledger, { ...line, phase: 'intent' }); } catch (error) {
    throw opError('storage_error', `${line.source_id}:${line.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.`);
  }
}

/** The landed write's committed line, with the revision it wrote; a ledger that cannot take it still leaves the intent line restore reads. */
function committedOutcome(item: LabelsItem, line: LedgerLine, written: string | null): RepairItemOutcome {
  const outcome = item.entry.mode === 'clear' ? 'cleared' : 'restored';
  try { recordLine(item.ledger, { ...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: line.removed ?? line.restored } };
  }
  return { applied: true, outcome, detail: { ledger: item.ledger.path } };
}

const writtenRevision = async (engine: BrainEngine, entry: Approved) => (await engine.readPageSnapshot(entry.slug, { sourceId: entry.source_id }))?.revision ?? null;

/** The label edit an item makes: a clear removes its recorded keys, a restore sets them back. */
const labelEditOf = (entry: Approved): LabelEdit => entry.mode === 'clear' ? { set: {}, remove: Object.keys(entry.labels) }
  : { set: entry.labels as Record<string, string>, remove: [] };

/** One item's page write after its intent line (repair/label-write.ts): the maintenance door on a managed brain, the legacy import under the page lock otherwise. */
async function writeOne(ctx: OperationContext, item: LabelsItem, ready: Ready, line: LedgerLine, authority: MaintenanceAuthority | null, embed: boolean): Promise<RepairItemOutcome> {
  recordIntent(item, line);
  const written = await writeLabelPage(ctx, item.entry, { revision: ready.revision, content: ready.content, edit: labelEditOf(item.entry), requestId: line.request_id, embed,
    preview: 'gbrain repair private-labels' }, authority);
  if (!written && !authority) return CHANGED;
  return committedOutcome(item, line, written);
}

export const privateLabelsRepair: RepairHandler = {
  kind: 'private-labels',
  /** GBRA-443: a label-only edit keeps every stored vector; the plan names the pages that re-embed anyway (embedding_items). */
  embeds: false,
  async plan(engine, scope, after, opts): Promise<RepairPlan> {
    const selection: Selection = { source_ids: scope.source_ids, class: selectedClass(opts) };
    const command = previewCommand(scope, selection);
    const ledger = opts?.privateLabelsLedger;
    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[]) => 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!,
      ...(entry.tried ? { retried: true } : {}) }));
    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).',
          `Preview first: ${command} — then run the apply command it prints: ${command} --apply --expect <preview-hash>`);
      }
      const approved = await loadApprovedSet<Approved>(engine, { command: 'private-labels', hash: opts.expect, previewCommand: command,
        emptyHash: async () => previewHash(hashParts(scope, selection, [])) });
      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);
      }
      const approvedExposes = new Set(approved.items.flatMap(entry => entry.exposes ?? []));
      if ([...(await windowDependents(engine, approved.items)).exposes.values()].flat().some(id => !approvedExposes.has(id))) throw previewChangedError(opts.expect, command);
      (ledger as CountedLedger).rows = { intent: 0, committed: 0 };
      const items = toItems(approved.items).filter(item => afterCursor(item.cursor, after));
      return { items, preview_hash: opts.expect, residuals: {}, embedding_items: await reembedding(engine, items) };
    }
    const size = Math.min(Math.max(1, opts?.limit ?? PRIVATE_LABELS_WINDOW), PRIVATE_LABELS_WINDOW_MAX);
    const restore = selection.class === 'restore';
    const planned = restore ? await planRestore(engine, scope, selection, ledger!)
      : await planClear(engine, scope, selection, selection.class ? [selection.class as ClearClass] : DEFAULT_CLASSES, ledger);
    const window = planned.entries.slice(0, size);
    const retried = window.filter(entry => entry.tried).length;
    const pastWindow = planned.entries.length - window.length;
    const before = { ...planned.counts };
    const projected = { ...before };
    for (const entry of window) {
      if (entry.class !== 'restore') { projected[entry.class]!--; continue; }
      projected.restorable!--;
      projected.already_restored!++;
    }
    const found = restore ? null : await windowDependents(engine, window);
    for (const entry of window) if (found?.exposes.has(entry.page_id)) entry.exposes = found.exposes.get(entry.page_id);
    const hash = previewHash(hashParts(scope, selection, window));
    if (window.length) await saveApprovedSet<Approved>(engine, { command: 'private-labels', hash }, window);
    const gitPublish = restore ? 0 : before['git-publish'] ?? 0;
    const dependents = found?.counts ?? null;
    const exposed = dependents ? Object.values(dependents).reduce((sum, n) => sum + n, 0) : 0;
    const fileBacked = (await filesInCheckout(engine, window.map(entry => entry.page_id))).size;
    const owner = await ownerMemberId(engine);
    const twins = await openTwins(engine, restore ? window : [], owner ? [owner] : [],
      (source, slugs) => `gbrain repair visibility --source ${source}${slugs.map(slug => ` --slug ${slug}`).join('')}`);
    const warnings = [
      ...(pastWindow ? [`This preview lists one window of ${window.length} item(s); ${pastWindow} more found past it. Apply this window (or decide not to), then preview again for the next one: ${command}`] : []),
      restore ? 'Restoring re-adds each recorded label, so remote callers that are not the brain owner stop reading these pages again.'
        : 'Clearing a label widens what remote callers that are not the brain owner can read: each cleared page becomes readable remotely (readable_by and folder rules still apply). '
          + 'Undo with: gbrain repair private-labels --class restore',
      ...(gitPublish && selection.class === 'git-publish' ? [`${gitPublish} page(s) of class git-publish live in git-canonical sources, where private pages are database-only; `
        + 'clearing commits each listed page into its source\'s Git history for the first time. That part is one-way: --class restore re-adds the label and removes the file '
        + 'from the checkout, but every earlier commit, and any remote it was pushed to, keeps the page\'s content.'] : []),
      ...(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'] : []),
      ...(exposed ? [`Clearing this window also exposes ${exposed} page(s) whose only privacy is a listed page's label: ${dependents!.derived_from} derived_from page(s), `
        + `${dependents!.atom} atom(s), ${dependents!.concept} synthesized concept(s) and ${dependents!.life_chronicle} life-chronicle event(s) extracted from a listed page. Remote callers that are not the brain owner `
        + 'can read them once this window applies (readable_by and folder rules still apply). To keep one private, give it its own label first; --class restore re-hides them with their origins.'] : []),
      ...(fileBacked ? [`${fileBacked} listed page(s) have a file in their source's checkout on a brain without managed persistence. This repair writes only the database there, `
        + 'and the next sync or re-import would put the label back from the file, so the apply holds each (outcome file_backed) with the file to edit.'] : []),
      ...(retried ? [`${retried} listed page(s) were tried by an earlier apply and did not change (the ledger has their intent line and nothing after it); `
        + 'they are listed after every page not tried yet. Each is tried again and, if its page still declines, left unchanged with its reason; '
        + 'such a decline does not count toward the run\'s systemic-failure stop.'] : []),
      ...openTwinsWarning(twins),
      ...(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.'] : []),
    ];
    const items = toItems(window);
    return { items, preview_hash: hash, residuals: {}, warnings, embedding_items: await reembedding(engine, items),
      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, file_backed: fileBacked, tried_before: retried },
        ...(dependents ? { dependents } : {}), ...(twins.count ? { open_twins: twins } : {}),
        ledger: ledger?.path ?? null, class: selection.class } };
  },
  async apply(ctx, raw, opts): Promise<RepairItemOutcome> {
    const item = raw as LabelsItem;
    const ready = await prepareWrite(ctx, item);
    if ('outcome' in ready) return ready.outcome;
    const authority = await maintenancePreflight(ctx.engine, item.entry.source_id);
    return writeOne(ctx, item, ready, await ledgerLine(ctx, item, ready), authority, opts?.embed === true);
  },
  /**
   * GBRA-443: a run of approved items at once. Each is re-decided as apply does; on a managed brain every page of a source
   * gets its intent line first (write-ahead for the whole run), then the pages are admitted together and the owner publishes
   * them in groups (publishMaintenancePages), each page its own fate: a declined page fails alone. The batch id is the
   * approval hash, so a window resumed at any item replays its pending requests. An unmanaged source writes one page at a
   * time, as apply does.
   */
  async applyBatch(ctx, raw, opts) {
    const items = raw as LabelsItem[];
    const out: RepairSettlement[] = new Array(items.length);
    // Once any page of this call may have been written, a later throw settles the pages it left instead of discarding the batch.
    let wrote = false;
    const settle = (index: number, write: () => Promise<RepairItemOutcome>) => { wrote = true; return write().then(value => { out[index] = { value }; }, error => { out[index] = { error }; }); };
    const ready: Array<Ready | null> = [];
    for (const [index, item] of items.entries()) {
      const prepared = await prepareWrite(ctx, item).catch((error: unknown) => ({ error }));
      ready.push('revision' in prepared ? prepared : null);
      if ('error' in prepared) out[index] = { error: prepared.error };
      else if ('outcome' in prepared) out[index] = { value: prepared.outcome };
    }
    const principal = await requestPrincipalForContext(ctx);
    for (const sourceId of new Set(items.map(item => item.entry.source_id))) {
      const indices = items.flatMap((item, index) => item.entry.source_id === sourceId && ready[index] ? [index] : []);
      if (!indices.length) continue;
      try {
        const preflight = await maintenancePreflight(ctx.engine, sourceId).then(authority => ({ authority }), (error: unknown) => ({ error }));
        if ('error' in preflight) { for (const index of indices) out[index] = { error: preflight.error }; continue; }
        const { authority } = preflight;
        const batch: Array<{ index: number; line: LedgerLine }> = [];
        for (const index of indices) {
          const line = await ledgerLine(ctx, items[index]!, ready[index]!);
          // An unmanaged source, or a request a single-page apply admitted before batching (its intent has no batch id), writes on its own.
          const prior = authority ? await getWriteRequest(ctx.engine, principal, line.request_id) : null;
          if (!authority || (prior && !isTerminal(prior) && typeof prior.intent?.maintenance_batch !== 'string')) {
            await settle(index, () => writeOne(ctx, items[index]!, ready[index]!, line, authority, opts.embed));
            continue;
          }
          batch.push({ index, line });
        }
        if (!batch.length || !authority) continue;
        const admitted: typeof batch = [];
        for (const [position, entry] of batch.entries()) {
          try { recordIntent(items[entry.index]!, entry.line); admitted.push(entry); } catch (error) {
            // A ledger that refuses one intent line refuses the rest too: nothing after it is written.
            for (const rest of batch.slice(position)) out[rest.index] = { error };
            break;
          }
        }
        if (!admitted.length) continue;
        const published = await publishMaintenancePages(ctx.engine, authority, admitted.map(({ index, line }) => ({ slug: items[index]!.entry.slug, content: ready[index]!.content,
          expectedRevision: ready[index]!.revision, requestId: line.request_id, keepTrust: true as const, labelEdit: labelEditOf(items[index]!.entry) })), { batch: digest(['private-labels-batch-v1', opts.expect ?? opts.runId ?? '', sourceId]) });
        wrote = true;
        for (const [position, { index, line }] of admitted.entries()) {
          const settled = published[position]!;
          if ('error' in settled) { out[index] = { error: settled.error }; continue; }
          // A failed read of the written revision still records the committed line (without revision_after).
          out[index] = { value: committedOutcome(items[index]!, line, await writtenRevision(ctx.engine, items[index]!.entry).catch(() => null)) };
        }
      } catch (error) {
        if (!wrote) throw error;
        for (const index of indices) out[index] ??= { error };
      }
    }
    return out;
  },
  /** GBRA-443: a write still pending when its run moved on, committed later in the run: its committed line, as apply writes for one that landed in its wait. */
  async onCommitted(ctx, raw, requestId) {
    const item = raw as LabelsItem;
    const { entry } = item;
    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: entry.revision ?? '', request_id: requestId, ...(entry.mode === 'clear' ? { removed: entry.labels } : { restored: entry.labels }) };
    committedOutcome(item, line, await writtenRevision(ctx.engine, entry));
  },
  /**
   * GST-2128 item 7: the approved set is retired only by an apply that attempted every item with no failure, stop or pending write.
   * GBRA-443: an apply reports where its ledger is and how many lines it appended (intent and committed), so a caller can
   * check the file grew by ledger_rows_written and that every applied page has its committed line.
   */
  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 });
    }
    const ledger = opts.privateLabelsLedger;
    if (result.mode !== 'apply' || !ledger) return {};
    const rows = (ledger as CountedLedger).rows ?? { intent: 0, committed: 0 };
    return { details: { ...result.details, ledger: ledger.path, ledger_rows_written: rows.intent + rows.committed, ledger_rows: { ...rows } } };
  },
  render(details) {
    const counts = details.counts as { before: Record<string, number>; after: Record<string, number> } | undefined;
    const line = (values: Record<string, number>) => Object.entries(values).map(([key, value]) => `${key}=${value}`).join(', ');
    const dependents = details.dependents as Record<string, number> | undefined;
    const rows = details.ledger_rows as { intent: number; committed: number } | undefined;
    return [...(counts ? [`  before: ${line(counts.before)}`, `  after (this window applied): ${line(counts.after)}`] : []),
      ...(dependents ? [`  also exposed by this window: ${line(dependents)}`] : []),
      ...openTwinsLines(details.open_twins as OpenTwins | undefined),
      ...(details.ledger ? [`  ledger: ${String(details.ledger)}${rows ? ` (this run appended ${rows.intent + rows.committed} line(s): ${rows.intent} intent, ${rows.committed} committed)` : ''}`] : [])];
  },
};