Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
28.6 KB
Raw Blame
/**
 * GBRA-218 (PR A2): the folder-rule policy lifecycle, one engine for both stores.
 *
 * Every source with a policy has one access_policy_state row (its lock), an
 * append-only access_policy_revisions log of desired rulebooks, and the
 * applied rulebook in access_rules, which page writes stamp folder_rule_ids
 * from (migration v283). The store (`sources.config.access_store`, git or
 * database) only decides where desired revisions come from: `gbrain access rule`
 * on a database store, the committed `.gbrain/access.yml` on a git store
 * (policy-git.ts). From there the lifecycle is the same:
 *
 *  - proposeRevision records the desired rulebook and installs the narrowing
 *    part of the change at once (classifyRulebook): new prefixes are marked
 *    pending (they read as nobody), pages are restamped in batches, a final
 *    pass under the source lock restamps anything written meanwhile, and only
 *    then does the pending coverage go and the revision count as applied.
 *  - the widening part is held: the applied rules stay until
 *    applyApproved (`gbrain access apply --yes --expect <plan_hash>`) installs a
 *    previewed revision; a plan hash over the desired and applied digests
 *    refuses `preview_changed` when either moved.
 *  - resume finishes an interrupted narrowing; it is idempotent and only ever
 *    restamps toward the applied rulebook.
 */
import { createHash, randomUUID } from 'node:crypto';
import { userInfo } from 'node:os';
import type { BrainEngine } from '../engine.ts';
import { opError } from '../ops/contract.ts';
import { classifyRulebook, coversDerived, folderRulesAllow, ruleCovers, rulebookDigest, rulesFromJson, sortRules, type Classification, type FolderRule, type RuleChange } from './folder-rules.ts';
import { identityFor } from './principals.ts';
import { listMembers } from './members.ts';

export type AccessStore = 'git' | 'database';
type Exec = Pick<BrainEngine, 'executeRaw'>;

export const RESTAMP_BATCH = 2000;

/** Test seam: runs after a narrowing is installed (rules and pending coverage committed) and before its restamp. */
export const policySeams: { afterInstall?: (sourceId: string) => Promise<void> | void } = {};

export interface RevisionRow {
  revision: number;
  rules: FolderRule[];
  digest: string;
  change_kind: Classification['kind'];
  origin: string;
  operation_id: string | null;
  proposed_by: string | null;
  approved_by: string | null;
  created_at: string;
  applied_at: string | null;
  approved_at: string | null;
}

export interface CoverageRow { prefix: string; reason: 'pending' | 'invalid'; revision: number | null; detail: unknown }

export type ProposalState = 'applied' | 'pending' | 'recorded' | 'unchanged';

export interface ProposalResult {
  source_id: string;
  operation_id: string | null;
  revision: number | null;
  /** applied: everything in force; recorded: the narrowing part is in force and a widening waits for gbrain access apply; pending: a narrowing is still being stamped (gbrain access resume finishes it); unchanged: the desired rulebook already matched. */
  state: ProposalState;
  change_kind: Classification['kind'];
  changes: RuleChange[];
  held: RuleChange[];
  pages_restamped: number;
  reconciled?: boolean;
}

/** The local operator recorded on revisions this process writes. */
export function localActor(): string {
  try { return `local:${userInfo().username}`; } catch { return 'local'; }
}

function iso(v: unknown): string | null {
  if (v === null || v === undefined) return null;
  return v instanceof Date ? v.toISOString() : String(v);
}

function toRevision(row: Record<string, unknown>): RevisionRow {
  return {
    revision: Number(row.revision), rules: rulesFromJson(row.rules), digest: String(row.digest),
    change_kind: row.change_kind as RevisionRow['change_kind'], origin: String(row.origin),
    operation_id: (row.operation_id as string | null) ?? null, proposed_by: (row.proposed_by as string | null) ?? null,
    approved_by: (row.approved_by as string | null) ?? null, created_at: iso(row.created_at)!, applied_at: iso(row.applied_at), approved_at: iso(row.approved_at),
  };
}

/** The persisted store of a source, or null when it has never had a rule. Refuses an unknown source. */
export async function readAccessStore(engine: Exec, sourceId: string): Promise<AccessStore | null> {
  const [row] = await engine.executeRaw<{ store: string | null }>(`SELECT config->>'access_store' AS store FROM sources WHERE id = $1`, [sourceId]);
  if (!row) throw opError('unknown_source', `No source "${sourceId}".`, 'List sources with gbrain sources list.');
  return row.store === 'git' || row.store === 'database' ? row.store : null;
}

/** Persists the store (set with the first rule, changed only by gbrain access rule migrate). */
export async function writeAccessStore(engine: Exec, sourceId: string, store: AccessStore): Promise<void> {
  await engine.executeRaw(`UPDATE sources SET config = jsonb_set(COALESCE(config, '{}'::jsonb), '{access_store}', to_jsonb($2::text)) WHERE id = $1`, [sourceId, store]);
}

/** Creates the source's lock row in its own committed statement, so concurrent page writes start taking it before any rule exists. */
export async function ensurePolicyState(engine: Exec, sourceId: string): Promise<void> {
  await engine.executeRaw('INSERT INTO access_policy_state (source_id) VALUES ($1) ON CONFLICT (source_id) DO NOTHING', [sourceId]);
}

/**
 * The source row first, then its policy row: page writers hold `sources FOR SHARE` before their stamping trigger takes
 * the policy row, so the same order lets a write already in flight finish (and be stamped here) instead of deadlocking.
 */
export async function lockSource(tx: Exec, sourceId: string): Promise<void> {
  await tx.executeRaw('SELECT 1 FROM sources WHERE id = $1 FOR NO KEY UPDATE', [sourceId]);
  await tx.executeRaw('SELECT 1 FROM access_policy_state WHERE source_id = $1 FOR UPDATE', [sourceId]);
}

export async function appliedRules(engine: Exec, sourceId: string): Promise<FolderRule[]> {
  const rows = await engine.executeRaw<{ rule_id: string; prefix: string; readable_by: string[]; covers_derived: boolean }>(
    'SELECT rule_id, prefix, readable_by, covers_derived FROM access_rules WHERE source_id = $1 ORDER BY rule_id', [sourceId]);
  return sortRules(rows.map(r => ({ id: r.rule_id, prefix: r.prefix, readable_by: [...(r.readable_by ?? [])], ...(r.covers_derived === false ? { covers_derived: false as const } : {}) })));
}

export async function listRevisions(engine: Exec, sourceId: string, limit = 50): Promise<RevisionRow[]> {
  const rows = await engine.executeRaw<Record<string, unknown>>(
    'SELECT * FROM access_policy_revisions WHERE source_id = $1 ORDER BY revision DESC LIMIT $2', [sourceId, limit]);
  return rows.map(toRevision);
}

export async function getRevision(engine: Exec, sourceId: string, revision?: number): Promise<RevisionRow | null> {
  const rows = revision === undefined
    ? await engine.executeRaw<Record<string, unknown>>('SELECT * FROM access_policy_revisions WHERE source_id = $1 ORDER BY revision DESC LIMIT 1', [sourceId])
    : await engine.executeRaw<Record<string, unknown>>('SELECT * FROM access_policy_revisions WHERE source_id = $1 AND revision = $2', [sourceId, revision]);
  return rows[0] ? toRevision(rows[0]) : null;
}

export async function coverageRows(engine: Exec, sourceId: string): Promise<CoverageRow[]> {
  const rows = await engine.executeRaw<Record<string, unknown>>(
    'SELECT prefix, reason, revision, detail FROM access_pending_coverage WHERE source_id = $1 ORDER BY reason, prefix', [sourceId]);
  return rows.map(r => ({ prefix: String(r.prefix), reason: r.reason as CoverageRow['reason'], revision: r.revision === null ? null : Number(r.revision),
    detail: typeof r.detail === 'string' ? JSON.parse(r.detail) : r.detail ?? null }));
}

const key = (r: FolderRule) => `${r.id}\u0000${r.prefix}`;
const sameRule = (a: FolderRule, b: FolderRule) => a.prefix === b.prefix && a.readable_by.join('\u0000') === b.readable_by.join('\u0000') && coversDerived(a) === coversDerived(b);

/**
 * Makes `target` the applied rulebook inside the caller's locked transaction. Rules whose (id, prefix) pair is new get
 * pending coverage until the restamp finishes. Returns whether pages need restamping.
 */
/** Refuses when row-level security keeps this database role from reading the folder access tables (they would read as empty). */
async function requireReadableAccessState(engine: Exec): Promise<void> {
  const [row] = await engine.executeRaw<{ unreadable: boolean }>('SELECT gbrain_access_state_unreadable() AS unreadable');
  if (row?.unreadable) {
    throw opError('permission_denied', 'This database role cannot read the folder access tables (row-level security hides them), so no folder rule was changed, applied or cleared.',
      'Run it as the owner of the access tables, or give this role the policies in docs/ENGINES.md ("Folder access tables").', { docs: 'docs/ENGINES.md#folder-access-tables' });
  }
}

async function installRulebook(tx: Exec, sourceId: string, target: readonly FolderRule[], revision: number, actor: string): Promise<boolean> {
  await requireReadableAccessState(tx);
  const current = await appliedRules(tx, sourceId);
  const before = new Map(current.map(r => [r.id, r]));
  const after = new Map(target.map(r => [r.id, r]));
  const currentKeys = new Set(current.map(key));
  const targetKeys = new Set(target.map(key));
  for (const r of current) {
    const next = after.get(r.id);
    if (!next || !sameRule(next, r)) {
      await tx.executeRaw('DELETE FROM access_rules WHERE source_id = $1 AND rule_id = $2', [sourceId, r.id]);
    }
  }
  for (const r of target) {
    const prior = before.get(r.id);
    if (prior && sameRule(prior, r)) continue;
    await tx.executeRaw('INSERT INTO access_rules (source_id, rule_id, prefix, readable_by, revision, created_by, covers_derived) VALUES ($1, $2, $3, $4::text[], $5, $6, $7)',
      [sourceId, r.id, r.prefix, r.readable_by, revision, actor, coversDerived(r)]);
  }
  const added = target.filter(r => !currentKeys.has(key(r)));
  for (const r of added) {
    await tx.executeRaw(`INSERT INTO access_pending_coverage (source_id, prefix, reason, revision) VALUES ($1, $2, 'pending', $3)
      ON CONFLICT (source_id, prefix, reason) DO UPDATE SET revision = EXCLUDED.revision`, [sourceId, r.prefix, revision]);
  }
  return added.length > 0 || current.some(r => !targetKeys.has(key(r)));
}

export interface RestampProgress { pages_scanned: number; pages_restamped: number }

/**
 * Restamps folder_rule_ids toward the applied rulebook in id-ordered windows (each its own statement, so page writes
 * are never blocked for long), then finishes under the source lock: one more pass over the whole source catches pages
 * written meanwhile, the pending coverage goes, and pending revisions count as applied, atomically.
 */
export async function restampSource(engine: BrainEngine, sourceId: string, opts: { batch?: number; onProgress?: (p: RestampProgress) => void } = {}): Promise<RestampProgress> {
  await requireReadableAccessState(engine);
  const batch = opts.batch ?? RESTAMP_BATCH;
  const progress: RestampProgress = { pages_scanned: 0, pages_restamped: 0 };
  let after = 0;
  for (;;) {
    const [row] = await engine.executeRaw<{ last: number | null; scanned: number; changed: number }>(
      `WITH w AS (SELECT id FROM pages WHERE source_id = $1 AND id > $2 ORDER BY id LIMIT $3),
        u AS (UPDATE pages p SET folder_rule_ids = gbrain_access_folder_rules(p.source_id, p.slug) FROM w
              WHERE p.id = w.id AND p.folder_rule_ids IS DISTINCT FROM gbrain_access_folder_rules(p.source_id, p.slug) RETURNING p.id)
      SELECT (SELECT max(id) FROM w) AS last, (SELECT count(*) FROM w)::int AS scanned, (SELECT count(*) FROM u)::int AS changed`,
      [sourceId, after, batch]);
    if (!row || row.last === null || row.last === undefined) break;
    after = Number(row.last);
    progress.pages_scanned += Number(row.scanned);
    progress.pages_restamped += Number(row.changed);
    opts.onProgress?.({ ...progress });
  }
  await engine.transaction(async tx => {
    await lockSource(tx, sourceId);
    const changed = await tx.executeRaw<{ id: number }>(
      `UPDATE pages SET folder_rule_ids = gbrain_access_folder_rules(source_id, slug)
        WHERE source_id = $1 AND folder_rule_ids IS DISTINCT FROM gbrain_access_folder_rules(source_id, slug) RETURNING id`, [sourceId]);
    progress.pages_restamped += changed.length;
    await tx.executeRaw(`DELETE FROM access_pending_coverage WHERE source_id = $1 AND reason = 'pending'`, [sourceId]);
    await tx.executeRaw('UPDATE access_policy_revisions SET applied_at = now() WHERE source_id = $1 AND applied_at IS NULL', [sourceId]);
  });
  return progress;
}

export interface ProposeMeta {
  origin: 'cli' | 'git' | 'git-approved' | 'import' | 'revert' | 'migrate';
  proposedBy?: string;
  /** Idempotency key: a retry with the same id returns the recorded revision instead of writing a second one. */
  operationId?: string;
  /** The desired revision the caller previewed; a different one refuses preview_changed. */
  expectDesired?: number;
  /** Persist this store when the source has none (the first rule). */
  store?: AccessStore;
  /** Record the revision as approved whatever it classifies as (a git source's committed access.approved on a rebuild). */
  approved?: boolean;
  onProgress?: (p: RestampProgress) => void;
}

/** Records a desired rulebook and installs its narrowing part (see the module comment). */
export async function proposeRevision(engine: BrainEngine, sourceId: string, desired: readonly FolderRule[], meta: ProposeMeta): Promise<ProposalResult> {
  await readAccessStore(engine, sourceId);
  await ensurePolicyState(engine, sourceId);
  const rules = sortRules(desired);
  const digest = rulebookDigest(rules);
  const actor = meta.proposedBy ?? localActor();
  const step = await engine.transaction(async tx => {
    await lockSource(tx, sourceId);
    if (meta.operationId) {
      const [prior] = await tx.executeRaw<Record<string, unknown>>('SELECT * FROM access_policy_revisions WHERE operation_id = $1', [meta.operationId]);
      if (prior) return { reconciled: toRevision(prior) };
    }
    const latest = await getRevision(tx as BrainEngine, sourceId);
    if (meta.expectDesired !== undefined && (latest?.revision ?? 0) !== meta.expectDesired) {
      throw opError('preview_changed', `Source ${sourceId}'s folder rules changed since the preview (previewed revision ${meta.expectDesired}, now ${latest?.revision ?? 0}); nothing was written.`,
        `Preview again (gbrain access rule list --source ${sourceId}) and rerun with the new --expect value.`);
    }
    const current = await appliedRules(tx, sourceId);
    const cls = meta.approved ? { ...classifyRulebook(current, rules), target: rules, held: [] } : classifyRulebook(current, rules);
    if (meta.store && !(await readAccessStore(tx, sourceId))) await writeAccessStore(tx, sourceId, meta.store);
    if (latest && latest.digest === digest && !meta.approved) {
      const needs = rulebookDigest(cls.target) !== rulebookDigest(current) && await installRulebook(tx, sourceId, cls.target, latest.revision, actor);
      return { unchanged: latest, cls, needs };
    }
    const revision = (latest?.revision ?? 0) + 1;
    const approved = cls.held.length === 0;
    await tx.executeRaw(`INSERT INTO access_policy_revisions (source_id, revision, rules, digest, change_kind, origin, operation_id, proposed_by, approved_by, approved_at)
      VALUES ($1, $2, $3::text::jsonb, $4, $5, $6, $7, $8, $9, CASE WHEN $10::boolean THEN now() END)`,
      [sourceId, revision, JSON.stringify(rules), digest, cls.kind, meta.origin, meta.operationId ?? null, actor,
        approved ? (meta.approved ? actor : 'auto:narrowing') : null, approved]);
    const needs = await installRulebook(tx, sourceId, cls.target, revision, actor);
    if (!needs) await tx.executeRaw('UPDATE access_policy_revisions SET applied_at = now() WHERE source_id = $1 AND applied_at IS NULL', [sourceId]);
    return { revision, cls, needs };
  });
  if ('reconciled' in step && step.reconciled) {
    const rev = step.reconciled;
    const status = await policyStatus(engine, sourceId);
    return { source_id: sourceId, operation_id: rev.operation_id, revision: rev.revision, reconciled: true,
      state: status.pending.length ? 'pending' : status.held.length && status.desired?.revision === rev.revision ? 'recorded' : 'applied',
      change_kind: rev.change_kind, changes: [], held: status.desired?.revision === rev.revision ? status.held : [], pages_restamped: 0 };
  }
  if ('unchanged' in step && step.unchanged) {
    const resume = step.needs || (await coverageRows(engine, sourceId)).some(c => c.reason === 'pending');
    const restamped = resume ? (await restampSource(engine, sourceId, { onProgress: meta.onProgress })).pages_restamped : 0;
    return { source_id: sourceId, operation_id: step.unchanged.operation_id, revision: step.unchanged.revision, state: step.cls.held.length ? 'recorded' : 'unchanged',
      change_kind: 'unchanged', changes: [], held: step.cls.held, pages_restamped: restamped };
  }
  const { revision, cls, needs } = step as { revision: number; cls: Classification; needs: boolean };
  if (needs) await policySeams.afterInstall?.(sourceId);
  const restamp = needs ? await restampSource(engine, sourceId, { onProgress: meta.onProgress }) : { pages_restamped: 0 };
  return { source_id: sourceId, operation_id: meta.operationId ?? null, revision, state: cls.held.length ? 'recorded' : 'applied',
    change_kind: cls.kind, changes: cls.changes, held: cls.held, pages_restamped: restamp.pages_restamped };
}

/** Finishes an interrupted narrowing (pending coverage or stamps that drifted from the applied rulebook). Idempotent. */
export async function resumePolicy(engine: BrainEngine, sourceId: string, onProgress?: (p: RestampProgress) => void): Promise<RestampProgress & { pending_before: string[] }> {
  await readAccessStore(engine, sourceId);
  await requireReadableAccessState(engine);
  const pending = (await coverageRows(engine, sourceId)).filter(c => c.reason === 'pending').map(c => c.prefix);
  const [state] = await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM access_policy_state WHERE source_id = $1', [sourceId]);
  if (!state?.n) return { pages_scanned: 0, pages_restamped: 0, pending_before: [] };
  const progress = await restampSource(engine, sourceId, { onProgress });
  return { ...progress, pending_before: pending };
}

export interface WideningImpact {
  change: RuleChange;
  pages: number;
  sample: string[];
  /** Members who read at least one page after the change that they cannot read now; 'every_source_reader' when unbound callers gain too. */
  gains: string[] | 'every_source_reader';
  /**
   * Raw-only rules (derived_released): no page gains readers; `pages` and `sample` are the pages the rule covers, whose
   * derived pages and facts stop being hidden by it from whoever reads those derivatives.
   */
  lineage?: true;
}

export interface ApplyPreview {
  source_id: string;
  store: AccessStore | null;
  applied_digest: string;
  desired: { revision: number; digest: string; proposed_by: string | null; created_at: string; origin: string } | null;
  proposals: Array<{ revision: number; change_kind: string; proposed_by: string | null; created_at: string }>;
  widening: WideningImpact[];
  plan_hash: string | null;
}

function planHash(sourceId: string, revision: number, desiredDigest: string, appliedDigest: string): string {
  return createHash('sha256').update(JSON.stringify({ sourceId, revision, desiredDigest, appliedDigest })).digest('hex').slice(0, 16);
}

/** What `gbrain access apply` would install: each held widening with the pages and members gaining access, and the plan hash binding it. */
export async function previewApply(engine: BrainEngine, sourceId: string, revision?: number): Promise<ApplyPreview> {
  const store = await readAccessStore(engine, sourceId);
  const current = await appliedRules(engine, sourceId);
  const appliedDigest = rulebookDigest(current);
  const desired = await getRevision(engine, sourceId, revision);
  if (revision !== undefined && !desired) throw opError('not_found', `Source ${sourceId} has no folder-rule revision ${revision}.`, `List revisions with gbrain access rule history --source ${sourceId}.`);
  const proposals = (await listRevisions(engine, sourceId, 200)).filter(r => !r.approved_at).reverse()
    .map(r => ({ revision: r.revision, change_kind: r.change_kind, proposed_by: r.proposed_by, created_at: r.created_at }));
  const base = { source_id: sourceId, store, applied_digest: appliedDigest, proposals };
  if (!desired) return { ...base, desired: null, widening: [], plan_hash: null };
  const cls = classifyRulebook(current, desired.rules);
  const desiredView = { revision: desired.revision, digest: desired.digest, proposed_by: desired.proposed_by, created_at: desired.created_at, origin: desired.origin };
  if (!cls.held.length && rulebookDigest(cls.target) === appliedDigest) return { ...base, desired: desiredView, widening: [], plan_hash: null };
  const members = (await listMembers(engine)).filter(m => m.status === 'enabled');
  const widening: WideningImpact[] = [];
  for (const change of cls.held) {
    const old = current.find(r => r.id === change.rule);
    if (change.kind === 'derived_released') {
      const covered = (await engine.executeRaw<{ slug: string }>(
        'SELECT slug FROM pages WHERE source_id = $1 AND deleted_at IS NULL AND starts_with(slug, $2) ORDER BY slug', [sourceId, change.prefix])).map(r => r.slug).filter(s => ruleCovers(s, change.prefix));
      widening.push({ change, pages: covered.length, sample: covered.slice(0, 20), gains: 'every_source_reader', lineage: true });
      continue;
    }
    const prefixes = [...new Set([old?.prefix, change.prefix].filter((p): p is string => !!p))];
    const slugs = (await engine.executeRaw<{ slug: string }>(
      'SELECT slug FROM pages WHERE source_id = $1 AND deleted_at IS NULL AND EXISTS (SELECT 1 FROM unnest($2::text[]) AS pfx WHERE starts_with(slug, pfx)) ORDER BY slug',
      [sourceId, prefixes])).map(r => r.slug);
    const gaining = (identity: string[]) => slugs.filter(s => !folderRulesAllow(s, current, identity) && folderRulesAllow(s, desired.rules, identity));
    const unbound = gaining([]);
    const pages = new Set(unbound);
    const gainers: string[] = [];
    for (const m of members) {
      const g = gaining(identityFor(m.id, m.groups));
      if (g.length) gainers.push(m.id);
      for (const s of g) pages.add(s);
    }
    widening.push({ change, pages: pages.size, sample: [...pages].sort().slice(0, 20), gains: unbound.length ? 'every_source_reader' : gainers });
  }
  return { ...base, desired: desiredView, widening, plan_hash: planHash(sourceId, desired.revision, desired.digest, appliedDigest) };
}

/** Installs a previewed revision in full (its widening included) when `expect` still matches its plan hash. */
export async function applyApproved(engine: BrainEngine, sourceId: string, opts: { revision?: number; expect: string; approvedBy?: string; onProgress?: (p: RestampProgress) => void }): Promise<ProposalResult & { plan_hash: string }> {
  await readAccessStore(engine, sourceId);
  await ensurePolicyState(engine, sourceId);
  const actor = opts.approvedBy ?? localActor();
  const installed = await engine.transaction(async tx => {
    await lockSource(tx, sourceId);
    const current = await appliedRules(tx, sourceId);
    const desired = await getRevision(tx as BrainEngine, sourceId, opts.revision);
    const hash = desired ? planHash(sourceId, desired.revision, desired.digest, rulebookDigest(current)) : null;
    if (!desired || hash !== opts.expect) {
      throw opError('preview_changed', `Source ${sourceId}'s folder rules changed since the preview (approved plan ${opts.expect}, current plan ${hash ?? 'none'}); nothing was applied.`,
        `Preview again with gbrain access apply --source ${sourceId}${opts.revision ? ` --revision ${opts.revision}` : ''} and approve the new plan_hash.`);
    }
    const cls = classifyRulebook(current, desired.rules);
    const needs = await installRulebook(tx, sourceId, desired.rules, desired.revision, actor);
    await tx.executeRaw('UPDATE access_policy_revisions SET approved_by = $3, approved_at = now() WHERE source_id = $1 AND revision = $2', [sourceId, desired.revision, actor]);
    if (!needs) await tx.executeRaw('UPDATE access_policy_revisions SET applied_at = now() WHERE source_id = $1 AND applied_at IS NULL AND revision <= $2', [sourceId, desired.revision]);
    return { desired, cls, needs, hash: hash! };
  });
  const restamp = installed.needs ? await restampSource(engine, sourceId, { onProgress: opts.onProgress }) : { pages_restamped: 0 };
  const latest = await getRevision(engine, sourceId);
  let held: RuleChange[] = [];
  if (latest && latest.revision > installed.desired.revision) {
    held = (await proposeRevision(engine, sourceId, latest.rules, { origin: latest.origin as ProposeMeta['origin'], proposedBy: actor, onProgress: opts.onProgress })).held;
  }
  return { source_id: sourceId, operation_id: installed.desired.operation_id, revision: installed.desired.revision, state: held.length ? 'recorded' : 'applied',
    change_kind: installed.cls.kind, changes: installed.cls.changes, held, pages_restamped: restamp.pages_restamped, plan_hash: installed.hash };
}

export interface PolicyStatus {
  source_id: string;
  store: AccessStore | null;
  rules: FolderRule[];
  applied_digest: string;
  desired: RevisionRow | null;
  applied_revision: number | null;
  approved_revision: number | null;
  held: RuleChange[];
  pending: CoverageRow[];
  invalid: CoverageRow[];
  operation?: { operation_id: string; revision: number | null; state: ProposalState | 'not_found' };
}

/** Where a source's folder policy stands: store, applied rules, desired, applied and approved revisions, held and pending work. */
export async function policyStatus(engine: BrainEngine, sourceId: string, operationId?: string): Promise<PolicyStatus> {
  const store = await readAccessStore(engine, sourceId);
  const rules = await appliedRules(engine, sourceId);
  const desired = await getRevision(engine, sourceId);
  const [marks] = await engine.executeRaw<{ applied: number | null; approved: number | null }>(
    'SELECT max(revision) FILTER (WHERE applied_at IS NOT NULL) AS applied, max(revision) FILTER (WHERE approved_at IS NOT NULL) AS approved FROM access_policy_revisions WHERE source_id = $1', [sourceId]);
  const coverage = await coverageRows(engine, sourceId);
  const held = desired ? classifyRulebook(rules, desired.rules).held : [];
  const status: PolicyStatus = {
    source_id: sourceId, store, rules, applied_digest: rulebookDigest(rules), desired,
    applied_revision: marks?.applied === null || marks?.applied === undefined ? null : Number(marks.applied),
    approved_revision: marks?.approved === null || marks?.approved === undefined ? null : Number(marks.approved),
    held, pending: coverage.filter(c => c.reason === 'pending'), invalid: coverage.filter(c => c.reason === 'invalid'),
  };
  if (operationId !== undefined) {
    const [row] = await engine.executeRaw<{ revision: number; applied_at: unknown; approved_at: unknown }>(
      'SELECT revision, applied_at, approved_at FROM access_policy_revisions WHERE source_id = $1 AND operation_id = $2', [sourceId, operationId]);
    status.operation = !row ? { operation_id: operationId, revision: null, state: 'not_found' }
      : { operation_id: operationId, revision: Number(row.revision),
        state: !row.applied_at ? 'pending' : held.length && desired?.revision === Number(row.revision) ? 'recorded' : 'applied' };
  }
  return status;
}

/** A new idempotency key for one rule edit (printed so a lost reply can be reconciled with gbrain access rule status --operation). */
export function newOperationId(): string {
  return `acc_${randomUUID()}`;
}

/** Installs `invalid` coverage for prefixes a policy file that does not validate touches ('' for the whole source), replacing any earlier. */
export async function markPolicyInvalid(engine: BrainEngine, sourceId: string, prefixes: string[] | null, detail: unknown): Promise<void> {
  await ensurePolicyState(engine, sourceId);
  await engine.transaction(async tx => {
    await lockSource(tx, sourceId);
    await tx.executeRaw(`DELETE FROM access_pending_coverage WHERE source_id = $1 AND reason = 'invalid'`, [sourceId]);
    for (const prefix of prefixes ?? ['']) {
      await tx.executeRaw(`INSERT INTO access_pending_coverage (source_id, prefix, reason, detail) VALUES ($1, $2, 'invalid', $3::text::jsonb)`, [sourceId, prefix, JSON.stringify(detail)]);
    }
  });
}

export async function clearPolicyInvalid(engine: Exec, sourceId: string): Promise<void> {
  await requireReadableAccessState(engine);
  await engine.executeRaw(`DELETE FROM access_pending_coverage WHERE source_id = $1 AND reason = 'invalid'`, [sourceId]);
}