Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Owner trust actions (#5575: A4, CEO-9, CEO-12, DX-2, DX-3, DX-7, DX-13,
* DX-14, ENG-10, ENG-15): confirm, drop, release, revert, allow and the
* `disable --all` kill switch, shared by the local CLI, the resident owner's
* IPC administration (persistence/administration.ts) and the `confirm_memory`
* op (ops/trust.ts).
*
* Every action runs in two steps. `previewOwnerAction` reads the target and
* returns what the owner approves: a one-line summary, the typed token, the
* exact command, whether the action raises trust (CEO-9) and a `binding` that
* names the target's exact state (row content and tier, page revision,
* proposal status). `applyOwnerAction` previews again under the same rules,
* refuses with `preview_changed` when the binding moved, and refuses a
* raising action without a confirmation. The confirmation itself is
* established by the caller: the CLI's typed-token TTY prompt, or a
* memory_confirm connection (trust/confirm.ts). Over IPC the prompt happens
* in the invoking CLI and the resident owner re-runs the preview and checks
* the binding before applying (DX-2).
*/
import { createHash } from 'node:crypto';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import type { OperationContext } from '../ops/contract.ts';
import { opError } from '../ops/contract.ts';
import type { Principal } from '../persistence/model.ts';
import type { OwnerConfirmation } from './confirm.ts';
import { tierRaiseFix } from './confirm.ts';
import { releaseSuppressedFields, suppressedFields } from '../belief/purge.ts';
import { decideTrustProposal } from './decide.ts';
import { heldLabelsText } from './page-write.ts';
import { resolveContestedFactOnConfirm } from './supersede-handlers.ts';
import { getTrustProposal, pendingTrustProposalsFor, SHARE_HELD_GUARD, trustProposalRef, type TrustDecisionResult, type TrustProposalRow } from './proposals.ts';
import {
confirmPage, latestPageVersionId, lowerPageState, readPageTrustState, readPageVersion, revertLoweredPage, revertPageToVersion,
setRowTier, versionTier, type PageActionResult,
} from './page-handlers.ts';
import { formatTrustRef, pageRef, parseTrustRef, resolvePageRef, type TrustRef } from './refs.ts';
import { storedTrustTier, trustLabel, type TrustTier } from './tier.ts';
import { isQuarantined } from '../quarantine.ts';
import { getWriteGateHold, releaseWriteGateHold, type WriteGateHold } from '../write-gate-store.ts';
import type { ParsedFact } from '../facts-fence.ts';
import { withCoordinatedWrite, withTrustPromotion, withWriteAttribution, withWriteTrust } from '../persistence/context.ts';
import { maintenanceAttribution } from '../persistence/attribution.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { lockedBeliefBatch } from '../belief/writers.ts';
import { claimColumns } from '../facts/typed-claim.ts';
import {
addTrustAllowRule, getTrustAllowRule, normalizeTrustAllowRule, parseAllowRuleRef, principalLabel, removeTrustAllowRule, type TrustAllowRule,
} from './allow-rules.ts';
export const OWNER_ACTIONS = ['confirm', 'drop', 'release', 'revert', 'allow', 'allow_remove', 'disable', 'enable'] as const;
export type OwnerActionName = typeof OWNER_ACTIONS[number];
export interface OwnerActionInput {
action: OwnerActionName;
/** The typed ref (confirm, drop, release, revert, allow_remove). */
ref?: string;
/** Routing for a bare page slug, and the source of an allow rule. */
source?: string | null;
/** revert p:<source>/<slug> --version <id>. */
version?: number;
uri_prefix?: string | null;
reason_family?: string | null;
reason?: string | null;
}
export interface OwnerActionPreview {
action: OwnerActionName;
ref: string;
summary: string;
/** What the owner types on the TTY (the ref, or a hash8 for long refs). */
token: string;
/** The exact local command that performs this action (never with --yes). */
command: string[];
/** CEO-9: the action raises trust (or lowers protection), so it needs the owner's confirmation. */
raises: boolean;
/** The target's exact approved state; apply refuses when it moved. */
binding: string;
tier?: TrustTier;
target_tier?: TrustTier;
/** Page actions: the page revision and (revert) the version the owner approved. */
revision?: string;
version_id?: number;
}
export interface OwnerActionResult {
action: OwnerActionName;
ref: string;
status: string;
tier?: TrustTier;
prior_tier?: TrustTier;
detail?: Record<string, unknown>;
}
export interface OwnerApplyOptions {
/** The binding from the preview the owner approved. */
binding: string;
/** How the owner confirmed; required when the preview raises. */
confirmation: OwnerConfirmation | null;
by?: Principal | null;
config?: GBrainConfig;
/** A memory_confirm caller's context (managed page writes admit under its authority). */
ctx?: OperationContext;
}
const hash8 = (value: string): string => createHash('sha256').update(value).digest('hex').slice(0, 8);
const bindingOf = (value: unknown): string => createHash('sha256')
.update(JSON.stringify(value, (_key, v: unknown) => typeof v === 'bigint' ? v.toString() : v)).digest('hex');
/** A hold's approved state; #7656: plus the fence cell fields an index-existing release raises (`releaseCellOf`). */
const holdBinding = (hold: Pick<HoldRow, 'id' | 'status' | 'last_seen_at'>, cellFields: Record<string, unknown> | null = null): string =>
bindingOf({ id: hold.id, status: hold.status, last_seen_at: hold.last_seen_at, ...(cellFields ? { cell: cellFields } : {}) });
/**
* One printable line: control, format and default-ignorable characters (terminal escapes, bidi overrides, Hangul fillers,
* the combining grapheme joiner) and the braille blank become one space, and runs of whitespace collapse to one.
*/
const printable = (text: unknown): string => String(text ?? '')
.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029\u2800\p{Cf}\p{Default_Ignorable_Code_Point}]/gu, ' ').replace(/\s+/g, ' ').trim();
/** A free-text value in the preview: quoted and escaped, so a quote or comma in it cannot close its field and fake another. */
const quoted = (text: unknown): string => JSON.stringify(printable(text));
const snippet = (text: unknown, max = 80): string => {
const flat = printable(text);
return flat.length > max ? `${flat.slice(0, max - 3)}...` : flat;
};
const trustCommand = (...args: string[]): string[] => ['gbrain', 'trust', ...args];
function notFound(ref: string, what: string): Error {
return opError('not_found', `No ${what} ${ref}.`, 'Check the ref; gbrain trust review lists what is waiting for you.');
}
// ---------------------------------------------------------------------------
// Targets
// ---------------------------------------------------------------------------
interface RowTarget { table: 'facts' | 'takes'; id: number; sourceId: string; tier: TrustTier; text: string; binding: string; live: boolean }
async function readFactTarget(engine: BrainEngine, id: number): Promise<RowTarget | null> {
const [row] = await engine.executeRaw<Record<string, unknown>>(
`SELECT id, source_id, trust_tier, fact, entity_slug, kind, claim_metric, claim_value, claim_unit, claim_period, value, event_type, dimension, context,
expired_at, superseded_by FROM facts WHERE id = $1`, [id]);
if (!row) return null;
return { table: 'facts', id, sourceId: String(row.source_id), tier: storedTrustTier(row.trust_tier), text: String(row.fact ?? ''),
binding: bindingOf({ ...row, expired_at: row.expired_at ? String(row.expired_at) : null }), live: !row.expired_at };
}
async function readTakeTarget(engine: BrainEngine, id: number): Promise<RowTarget | null> {
const [row] = await engine.executeRaw<Record<string, unknown>>(
`SELECT t.id, p.source_id, t.trust_tier, t.claim, t.kind, t.holder, t.active, t.superseded_by
FROM takes t JOIN pages p ON p.id = t.page_id WHERE t.id = $1`, [id]);
if (!row) return null;
return { table: 'takes', id, sourceId: String(row.source_id), tier: storedTrustTier(row.trust_tier), text: String(row.claim ?? ''),
binding: bindingOf(row), live: row.active !== false };
}
// Held writes (write-gate-store.ts). Release publishes the held row at user_confirmed in the same transaction (CEO-9).
export interface HoldRow { id: number; kind: 'fact' | 'take'; source_id: string; slug: string; status: string; tier: TrustTier; reason_families: string[]; payload: Record<string, unknown>; last_seen_at: string }
export interface HoldStoreAdapter {
get(engine: BrainEngine, id: number): Promise<HoldRow | null>;
list(engine: BrainEngine, opts: { sourceId?: string; since?: Date }): Promise<HoldRow[]>;
/**
* Marks the hold released and publishes its payload at user_confirmed in `tx`; false when it was no longer held.
* #7657: `approved` re-checks the owner's preview binding on the locked hold and refuses `preview_changed` when it moved.
*/
release(tx: BrainEngine, id: number, by: string, approved?: (hold: HoldRow) => Promise<boolean>): Promise<boolean>;
drop(tx: BrainEngine, id: number, by: string): Promise<boolean>;
/** A managed release published through the page-mutation door (trust/release-publish.ts); null when the hold takes `release`. */
publish?(engine: BrainEngine, id: number, by: string, config?: GBrainConfig, approved?: string): Promise<boolean | null>;
}
async function holdTableExists(engine: BrainEngine): Promise<boolean> {
const [row] = await engine.executeRaw<{ t: string | null }>(`SELECT to_regclass('write_gate_holds')::text AS t`);
return !!row?.t;
}
const holdColumns = `id, kind, source_id, slug, status, tier, reason_families, payload, last_seen_at`;
function holdRow(r: Record<string, unknown>): HoldRow {
const payload = typeof r.payload === 'string' ? JSON.parse(r.payload) as Record<string, unknown> : (r.payload as Record<string, unknown> | null) ?? {};
return { id: Number(r.id), kind: r.kind as HoldRow['kind'], source_id: String(r.source_id), slug: String(r.slug ?? ''), status: String(r.status),
tier: storedTrustTier(r.tier), reason_families: (r.reason_families as string[] | null) ?? [], payload, last_seen_at: new Date(r.last_seen_at as string).toISOString() };
}
const decideHoldSql = (status: 'released' | 'dropped') =>
`UPDATE write_gate_holds SET status = '${status}', decided_at = now(), decided_by = $2 WHERE id = $1 AND status = 'held' RETURNING id`;
const defaultHoldStore: HoldStoreAdapter = {
async get(engine, id) {
if (!(await holdTableExists(engine))) return null;
const [row] = await engine.executeRaw<Record<string, unknown>>(`SELECT ${holdColumns} FROM write_gate_holds WHERE id = $1`, [id]);
return row ? holdRow(row) : null;
},
async list(engine, opts) {
if (!(await holdTableExists(engine))) return [];
const rows = await engine.executeRaw<Record<string, unknown>>(
`SELECT ${holdColumns} FROM write_gate_holds WHERE status = 'held' AND ($1::text IS NULL OR source_id = $1)
AND ($2::timestamptz IS NULL OR last_seen_at >= $2) ORDER BY id LIMIT 1000`, [opts.sourceId ?? null, opts.since?.toISOString() ?? null]);
return rows.map(holdRow);
},
async release(tx, id, by, approved) {
await tx.executeRaw('SELECT id FROM write_gate_holds WHERE id = $1 FOR UPDATE', [id]);
const held = await getWriteGateHold(tx, id);
if (held?.kind === 'take') {
throw opError('unavailable', `h${id} is a held take; releasing takes is not supported yet, so nothing was changed.`,
`Drop it with gbrain trust drop h${id}, or add the take yourself with gbrain takes add.`);
}
if (approved && held?.status === 'held' && !(await approved((await defaultHoldStore.get(tx, id))!))) {
throw opError('preview_changed', `h${id} changed after you approved it; nothing was changed.`,
'Run the command again: it shows the current state and asks for a new confirmation.');
}
const hold = await releaseWriteGateHold(tx, id, by);
if (!hold) return false;
await publishReleasedFact(tx, hold);
return true;
},
async drop(tx, id, by) { return (await tx.executeRaw(decideHoldSql('dropped'), [id, by])).length === 1; },
async publish(engine, id, by, config, approved) {
const { submitTrustRelease, releaseCellFields } = await import('./release-publish.ts');
return submitTrustRelease(engine, id, by, config,
approved === undefined ? undefined : async (hold, cell) => {
const row = await defaultHoldStore.get(engine, hold.id);
return !!row && holdBinding(row, cell && releaseCellFields(cell)) === approved;
});
},
};
/** #7656: the fence cell an index-existing release of this hold indexes, with the fields it raises; null for every other hold. */
async function releaseCellOf(engine: BrainEngine, hold: HoldRow): Promise<{ cell: ParsedFact; fields: Record<string, unknown> } | null> {
if (hold.kind !== 'fact' || typeof hold.payload.row_num !== 'number') return null;
const { releaseCell, releaseCellFields } = await import('./release-publish.ts');
const cell = await releaseCell(engine, hold);
return cell ? { cell, fields: releaseCellFields(cell) } : null;
}
/** #7656: what a fact release raises besides its text, for the preview: the fence cell an index-existing release indexes, else the held payload. */
function releasedFields(hold: HoldRow, cell: ParsedFact | null): string {
const p = hold.payload;
const date = (v: unknown) => typeof v === 'string' && v ? v.slice(0, 10) : null;
const entries: Array<[string, unknown]> = cell
? [['kind', cell.kind], ['visibility', cell.visibility], ['confidence', cell.confidence], ['notability', cell.notability], ['valid from', cell.validFrom],
['valid until', cell.validUntil], ['metric', cell.claimMetric], ['value', cell.claimValue], ['unit', cell.claimUnit], ['period', cell.claimPeriod],
['attributed to', cell.attributedTo], ['source', cell.source], ['context', cell.context]]
: [['kind', typeof p.kind === 'string' && p.kind ? p.kind : 'fact'], ['visibility', p.visibility === 'world' ? 'world' : 'private'], ['valid from', date(p.valid_from)],
['valid until', date(p.valid_until)], ['source', p.source], ['context', p.context]];
const shown = entries.filter(([, v]) => v !== undefined && v !== null && v !== '')
.map(([k, v]) => `${k} ${typeof v === 'number' && Number.isFinite(v) ? printable(v) : quoted(v)}`).join(', ');
return cell ? ` with fence row ${cell.rowNum} as it stands: ${shown}` : ` with ${shown}`;
}
/**
* The transactional release: the fact enters memory as the owner's confirmed row, database-only (its embedding is
* filled by the usual backfill), stamped user_confirmed under the promotion capability. A managed brain takes it only
* for a hold with no entity slug or whose page is missing; every other managed fact release publishes its fence row
* through the door (`submitTrustRelease`, trust/release-publish.ts).
*/
async function publishReleasedFact(tx: BrainEngine, hold: WriteGateHold): Promise<void> {
const p = hold.payload;
const str = (v: unknown) => (typeof v === 'string' && v ? v : null);
const trust = { tier: 'user_confirmed' as const, origin: { channel: 'trust_release', request_id: hold.request_id ?? undefined } };
// W1 #6783 §5.1: the released fact is recorded in its subject's stream, under that slug's page key.
const write = () => withTrustPromotion(tx, 'user_confirmed', () => withWriteTrust(tx, trust, () => lockedBeliefBatch(tx, { sourceId: hold.source_id,
slugs: str(p.entity_slug) ? [String(p.entity_slug)] : [], op: 'trust_release', remote: false, cause: { hold: `wh${hold.id}` } }, () => tx.insertFact({ // gbrain-allow-direct-insert: owner release of a held fact (CEO-9), inside the owner's coordinated transaction
fact: String(p.fact ?? ''), kind: (str(p.kind) ?? 'fact') as never, entity_slug: str(p.entity_slug), visibility: (p.visibility === 'world' ? 'world' : 'private'),
source: str(p.source) ?? `trust release h${hold.id}`, context: str(p.context), source_session: str(p.source_session), confidence: 1,
valid_from: str(p.valid_from) ? new Date(String(p.valid_from)) : new Date(), valid_until: str(p.valid_until) ? new Date(String(p.valid_until)) : null,
embedding: null, embedding_model: null, ...claimColumns(p as never),
}, { source_id: hold.source_id }))));
if (await managedPersistenceEnabled(tx)) await withCoordinatedWrite(tx, [hold.source_id], write, await maintenanceAttribution(tx));
else await withWriteAttribution(tx, await maintenanceAttribution(tx), write);
}
let holdStore: HoldStoreAdapter = defaultHoldStore;
/** Test seam (and the L2a merge point): the hold store the owner actions use. */
export function __setHoldStoreForTests(store: HoldStoreAdapter | null): void { holdStore = store ?? defaultHoldStore; }
export function currentHoldStore(): HoldStoreAdapter { return holdStore; }
// ---------------------------------------------------------------------------
// Kill switch (DX-13)
// ---------------------------------------------------------------------------
/** `gbrain trust disable --all`: the values it writes. */
export const TRUST_KILL_SWITCH_VALUES: Readonly<Record<string, string>> = Object.freeze({
'write_gate.external_mode': 'off',
'write_gate.agent_mode': 'off',
'trust.agent_activation': 'allow',
});
/** The receipt of the last disable/enable: who, when, and the values the disable replaced. */
export const TRUST_KILL_SWITCH_KEY = 'trust.kill_switch';
interface KillSwitchReceipt { state: 'disabled' | 'enabled'; at: string; by: string; prior?: Record<string, string | null>; disabled_at?: string }
async function readKillSwitch(engine: BrainEngine): Promise<KillSwitchReceipt | null> {
const raw = await engine.getConfig(TRUST_KILL_SWITCH_KEY);
if (!raw) return null;
try { return JSON.parse(raw) as KillSwitchReceipt; } catch { return null; }
}
async function currentSwitchValues(engine: BrainEngine): Promise<Record<string, string | null>> {
const out: Record<string, string | null> = {};
for (const key of Object.keys(TRUST_KILL_SWITCH_VALUES)) out[key] = await engine.getConfig(key);
return out;
}
// ---------------------------------------------------------------------------
// Preview
// ---------------------------------------------------------------------------
function requireRef(input: OwnerActionInput): TrustRef {
if (!input.ref) throw opError('invalid_params', `trust ${input.action} needs a ref.`, 'Pass a ref such as f12, t3, h4, tp7 or p:default/notes/alice-example; gbrain trust review lists them.');
return parseTrustRef(input.ref);
}
function unsupported(action: OwnerActionName, ref: TrustRef): Error {
return opError('invalid_params', `trust ${action} does not apply to ${formatTrustRef(ref)}.`,
'confirm takes a fact (f12), take (t3), page (p:default/notes/alice-example), trust proposal (tp7) or held write (h4); drop takes a trust proposal or held write; release takes a held write; revert takes an agent-edit trust proposal or a page; allow --remove takes an allow rule (a2). gbrain trust review lists the refs.');
}
async function pendingProposal(engine: BrainEngine, id: number): Promise<TrustProposalRow> {
const p = await getTrustProposal(engine, id);
if (!p) throw notFound(trustProposalRef(id), 'trust proposal');
if (p.status !== 'pending') throw opError('invalid_params', `${trustProposalRef(id)} is already ${p.status}; there is nothing to decide.`, 'gbrain trust review lists what is still pending.');
return p;
}
function proposalSummary(p: TrustProposalRow, verb: 'Accept' | 'Dismiss' | 'Revert'): string {
if (p.action === 'lower_page') {
const s = lowerPageState(p);
const page = pageRef(p.source_id, s.slug);
// GST-2518: the privacy labels the edit asked for and the page kept.
const labels = s.labels ? heldLabelsText(s.labels) : '';
// GST-2521: on an agent page, accept changes only the labels.
if (verb === 'Accept' && s.labels_only) return `Change the privacy labels of ${page}: ${labels}; the page stays "${trustLabel(s.edited_tier)}"`;
if (verb === 'Accept') return `Endorse the agent edit of ${page}: raise it from "${trustLabel(s.edited_tier)}" to "confirmed by you"${labels ? ` and change its privacy labels: ${labels}` : ''}`;
if (verb === 'Revert') return `Revert the agent edit of ${page}: restore version ${s.version_id ?? '?'} and its tier "${trustLabel(s.prior_tier)}"`;
return `Dismiss ${trustProposalRef(p.id)}: ${page} stays "${trustLabel(s.edited_tier)}"${labels ? ' and keeps its privacy labels' : ''}`;
}
const target = `${p.target_table === 'facts' ? 'f' : p.target_table === 'takes' ? 't' : p.target_table === 'timeline_entries' ? 'timeline row ' : ''}${p.target_id}`;
// GST-2897 B: a member's share about another member, held private.
if (p.before_state.guard === SHARE_HELD_GUARD) {
return verb === 'Accept' ? `Accept ${trustProposalRef(p.id)}: share ${target}, a fact about member ${String(p.before_state.member)}, with every reader of source ${p.source_id} (its trust stays as written)`
: `Dismiss ${trustProposalRef(p.id)}: keep ${target} private`;
}
const related = p.related_id === null ? '' : ` with ${p.related_table === 'facts' ? 'f' : p.related_table === 'takes' ? 't' : ''}${p.related_id}`;
// W1 #6783 §12 (a): a held take or timeline row names what the lower-tier write asked for.
const held = p.action === 'forget' && p.target_table !== 'facts' ? ({ removed: 'remove', replaced: 'replace', deactivated: 'deactivate', detail_changed: 'rewrite' } as Record<string, string>)[String(p.before_state.change)] : undefined;
const what = held ? `${held} ${target} as the page now says` : p.action === 'forget' ? `forget ${target}` : p.action.startsWith('supersede') ? `supersede ${target}${related}` : `${p.action.replace('_', ' ')} ${target}${related}`;
return verb === 'Accept' ? `Accept ${trustProposalRef(p.id)}: ${what} (raises trust over "${trustLabel(storedTrustTier(p.before_state.prior_tier ?? p.before_state.tier))}")`
: `Dismiss ${trustProposalRef(p.id)}: do not ${what}`;
}
async function proposalBinding(engine: BrainEngine, p: TrustProposalRow): Promise<string> {
const page = p.action === 'lower_page' ? await readPageTrustState(engine, p.source_id, lowerPageState(p).slug) : null;
return bindingOf({ id: p.id, status: p.status, updated_at: p.updated_at, page: page?.revision ?? null });
}
async function previewConfirm(engine: BrainEngine, ref: TrustRef, input: OwnerActionInput): Promise<OwnerActionPreview> {
if (ref.kind === 'fact' || ref.kind === 'take') {
const label = formatTrustRef(ref);
const row = ref.kind === 'fact' ? await readFactTarget(engine, ref.id) : await readTakeTarget(engine, ref.id);
if (!row) throw notFound(label, ref.kind);
if (!row.live) throw opError('invalid_params', `${label} is no longer active (expired, superseded or forgotten); there is nothing to confirm.`, 'Confirm the row that replaced it instead; gbrain trust explain shows its history.');
const release = await suppressedFields(engine, row.table, row.id);
return { action: 'confirm', ref: label, token: label, command: trustCommand('confirm', label), raises: row.tier !== 'user_confirmed' || release.length > 0, binding: row.binding,
tier: row.tier, target_tier: 'user_confirmed', summary: `Raise ${ref.kind} ${label} (${JSON.stringify(snippet(row.text))}) from "${trustLabel(row.tier)}" to "confirmed by you"`
+ (release.length ? ` and release its purge-redacted ${release.join(', ')} in recorded history` : '') };
}
if (ref.kind === 'page') {
const { sourceId, slug } = await resolvePageRef(engine, ref, input.source);
const label = pageRef(sourceId, slug);
const state = await readPageTrustState(engine, sourceId, slug);
if (!state) throw notFound(label, 'page');
if (isQuarantined(state.snapshot.page.frontmatter)) {
throw opError('invalid_params', `${label} is quarantined; confirming it would not make it visible.`,
`Review it first; clearing the quarantine is a separate owner step: gbrain quarantine clear ${slug} --source-id ${sourceId}.`);
}
return { action: 'confirm', ref: label, token: hash8(`${label}@${state.revision}`), command: trustCommand('confirm', label),
raises: state.tier !== 'user_confirmed' || state.hasMarker, binding: state.revision, tier: state.tier, target_tier: 'user_confirmed', revision: state.revision,
summary: `Raise page ${label} from "${trustLabel(state.tier)}" to "confirmed by you"${state.hasMarker ? ' and remove its trust_tier marker' : ''}` };
}
if (ref.kind === 'proposal') {
const p = await pendingProposal(engine, ref.id);
return { action: 'confirm', ref: trustProposalRef(p.id), token: trustProposalRef(p.id), command: trustCommand('confirm', trustProposalRef(p.id)),
raises: true, binding: await proposalBinding(engine, p), target_tier: 'user_confirmed', summary: proposalSummary(p, 'Accept') };
}
if (ref.kind === 'hold') return previewHold(engine, ref.id, 'release');
throw unsupported('confirm', ref);
}
async function previewHold(engine: BrainEngine, id: number, action: 'release' | 'drop'): Promise<OwnerActionPreview> {
const label = `h${id}`;
const hold = await holdStore.get(engine, id);
if (!hold) throw notFound(label, 'held write');
const text = hold.payload.fact ?? hold.payload.claim ?? '';
const entity = hold.kind === 'fact' && typeof hold.payload.entity_slug === 'string' && hold.payload.entity_slug ? ` for ${quoted(`${hold.source_id}/${hold.payload.entity_slug}`)}` : '';
const cell = action === 'release' ? await releaseCellOf(engine, hold) : null;
return { action, ref: label, token: label, command: trustCommand(action, label), raises: action === 'release',
binding: holdBinding(hold, cell?.fields ?? null), tier: hold.tier,
...(action === 'release' ? { target_tier: 'user_confirmed' as TrustTier } : {}),
summary: action === 'release'
? `Release held ${hold.kind} ${label} (${hold.kind === 'fact' ? quoted(text) : JSON.stringify(snippet(text))}, ${hold.reason_families.join(', ') || 'detector error'})${entity} into memory as "confirmed by you"`
+ (hold.kind === 'fact' ? releasedFields(hold, cell?.cell ?? null) : '')
: `Drop held ${hold.kind} ${label} (${JSON.stringify(snippet(text))}); it stays out of memory` };
}
async function previewRevert(engine: BrainEngine, ref: TrustRef, input: OwnerActionInput): Promise<OwnerActionPreview> {
if (ref.kind === 'proposal') {
const p = await pendingProposal(engine, ref.id);
if (p.action !== 'lower_page') throw opError('invalid_params', `${trustProposalRef(p.id)} is a ${p.action} proposal; only agent-edit items (lower_page) revert.`, `Use gbrain trust confirm ${trustProposalRef(p.id)} or gbrain trust drop ${trustProposalRef(p.id)}.`);
const s = lowerPageState(p);
return { action: 'revert', ref: trustProposalRef(p.id), token: trustProposalRef(p.id), command: trustCommand('revert', trustProposalRef(p.id)),
raises: true, binding: await proposalBinding(engine, p), tier: s.edited_tier, target_tier: s.prior_tier, summary: proposalSummary(p, 'Revert') };
}
if (ref.kind !== 'page') throw unsupported('revert', ref);
const { sourceId, slug } = await resolvePageRef(engine, ref, input.source);
const label = pageRef(sourceId, slug);
const state = await readPageTrustState(engine, sourceId, slug);
if (!state) throw notFound(label, 'page');
let versionId = input.version ?? null;
if (versionId === null) {
const lowered = (await pendingTrustProposalsFor(engine, 'pages', state.pageId)).find(p => p.action === 'lower_page');
versionId = (lowered ? lowerPageState(lowered).version_id : null) ?? await latestPageVersionId(engine, state.pageId);
}
if (versionId === null) throw opError('not_found', `${label} has no earlier version to revert to.`, `gbrain history ${slug} lists a page's versions.`);
const version = await readPageVersion(engine, state.pageId, versionId);
if (!version) throw opError('not_found', `Version ${versionId} is not in the history of ${label}.`, `List the page's versions with gbrain history ${slug} and pass one of their ids to --version.`);
const tier = versionTier(version);
return { action: 'revert', ref: label, token: hash8(`${label}@${state.revision}#${versionId}`), command: [...trustCommand('revert', label), '--version', String(versionId)],
raises: true, binding: bindingOf({ revision: state.revision, version: versionId }), tier: state.tier, target_tier: tier, revision: state.revision, version_id: versionId,
summary: `Revert page ${label} to version ${versionId}: restore its content and its tier "${trustLabel(tier)}"${version.trust_tier ? '' : ' (a version from before trust tiers reads as unverified origin)'}` };
}
/** Reads the target and returns what the owner approves. Read-only. */
export async function previewOwnerAction(engine: BrainEngine, input: OwnerActionInput): Promise<OwnerActionPreview> {
switch (input.action) {
case 'confirm': return previewConfirm(engine, requireRef(input), input);
case 'release': {
const ref = requireRef(input);
if (ref.kind !== 'hold') throw unsupported('release', ref);
return previewHold(engine, ref.id, 'release');
}
case 'drop': {
const ref = requireRef(input);
if (ref.kind === 'hold') return previewHold(engine, ref.id, 'drop');
if (ref.kind !== 'proposal') throw unsupported('drop', ref);
const p = await pendingProposal(engine, ref.id);
return { action: 'drop', ref: trustProposalRef(p.id), token: trustProposalRef(p.id), command: trustCommand('drop', trustProposalRef(p.id)),
raises: false, binding: await proposalBinding(engine, p), summary: proposalSummary(p, 'Dismiss') };
}
case 'revert': return previewRevert(engine, requireRef(input), input);
case 'allow': {
const rule = normalizeTrustAllowRule({ sourceId: input.source ?? '', uriPrefix: input.uri_prefix, reasonFamily: input.reason_family, reason: input.reason });
const command = [...trustCommand('allow', '--source', rule.sourceId), ...(rule.uriPrefix ? ['--uri-prefix', rule.uriPrefix] : []),
...(rule.reasonFamily ? ['--reason-family', rule.reasonFamily] : [])];
return { action: 'allow', ref: `allow:${rule.sourceId}`, token: `allow-${rule.sourceId}`, command, raises: true, binding: bindingOf(rule),
summary: `Stop holding ${rule.reasonFamily ? `"${rule.reasonFamily}" ` : ''}instruction-like content from source ${rule.sourceId}${rule.uriPrefix ? ` under ${rule.uriPrefix}` : ''}` };
}
case 'allow_remove': {
const id = input.ref ? parseAllowRuleRef(input.ref) : null;
if (id === null) throw opError('invalid_params', 'trust allow --remove needs an allow rule ref a<id>.', 'gbrain trust review lists the allow rules with their refs.');
const rule = await getTrustAllowRule(engine, id);
if (!rule || rule.removed_at) throw notFound(`a${id}`, 'active allow rule');
return { action: 'allow_remove', ref: rule.ref, token: rule.ref, command: trustCommand('allow', '--remove', rule.ref), raises: false,
binding: bindingOf(rule), summary: `Remove allow rule ${rule.ref} (source ${rule.source_id}${rule.uri_prefix ? `, ${rule.uri_prefix}` : ''})` };
}
case 'disable': {
const values = await currentSwitchValues(engine);
return { action: 'disable', ref: 'trust:all', token: 'disable-all', command: trustCommand('disable', '--all'), raises: true, binding: bindingOf(values),
summary: 'Turn the memory trust protections off: write_gate.external_mode=off, write_gate.agent_mode=off, trust.agent_activation=allow' };
}
case 'enable': {
const receipt = await readKillSwitch(engine);
return { action: 'enable', ref: 'trust:all', token: 'enable-all', command: trustCommand('disable', '--all', '--undo'), raises: false,
binding: bindingOf({ receipt, values: await currentSwitchValues(engine) }), summary: 'Restore the memory trust protections the last disable --all turned off' };
}
}
}
/** DX-3: the fix an owner action emits when it needs the user. Tier-raising actions never carry --yes and are never `run`. */
export function ownerActionFix(preview: OwnerActionPreview) {
return tierRaiseFix(preview.command, `${preview.summary}. Only the owner can do this, in an interactive terminal on the brain host.`,
`Run on the brain host, in a terminal: ${preview.command.join(' ')}`);
}
// ---------------------------------------------------------------------------
// Apply
// ---------------------------------------------------------------------------
function fromDecision(action: OwnerActionName, d: TrustDecisionResult): OwnerActionResult {
if (d.status === 'stale' || d.status === 'refused' || d.status === 'not_found') {
throw opError('preview_changed', `${d.ref} could not be decided (${d.status}${d.reason ? `: ${d.reason}` : ''}); nothing was changed.`,
'Run gbrain trust review to see its current state.');
}
return { action, ref: d.ref, status: d.status, ...(d.detail ? { detail: d.detail } : {}) };
}
function asPageResult(action: OwnerActionName, r: PageActionResult): OwnerActionResult {
return { action, ref: r.ref, status: r.status, tier: r.tier, prior_tier: r.prior_tier,
detail: { ...(r.marker_removed !== undefined ? { marker_removed: r.marker_removed } : {}), ...(r.version_id !== undefined ? { version_id: r.version_id } : {}) } };
}
/**
* Applies one owner action the owner approved. Re-reads the target, refuses
* when it changed since the preview (`preview_changed`) or when a raising
* action has no confirmation (`confirmation_required`), then performs it.
*/
export async function applyOwnerAction(engine: BrainEngine, input: OwnerActionInput, opts: OwnerApplyOptions): Promise<OwnerActionResult> {
const preview = await previewOwnerAction(engine, input);
if (preview.binding !== opts.binding) {
throw opError('preview_changed', `${preview.ref} changed after you approved it; nothing was changed.`,
'Run the command again: it shows the current state and asks for a new confirmation.');
}
if (preview.raises && !opts.confirmation) {
throw opError('confirmation_required', `${preview.summary} needs the owner's confirmation; nothing was changed.`,
'Do not retry with --yes. Tell the user to run the command in fix in an interactive terminal on the brain host.', { fix: ownerActionFix(preview) });
}
const confirmation = opts.confirmation ?? { via: 'tty' as const };
const by = opts.by ?? null;
const decision = { confirmation, decidedBy: by, ...(opts.config ? { config: opts.config } : {}) };
const ref = input.ref ? parseTrustRef(input.ref) : null;
switch (input.action) {
case 'confirm':
case 'release': {
if (ref?.kind === 'fact' || ref?.kind === 'take') {
const read = ref.kind === 'fact' ? readFactTarget : readTakeTarget;
const row = (await read(engine, ref.id))!;
// A contested fact: confirming either side resolves its supersede_fact proposal (one value stays current), even when it is already confirmed.
const resolved = ref.kind === 'fact' && row.binding === opts.binding ? await resolveContestedFactOnConfirm(engine, ref.id, decision) : null;
if (resolved?.status === 'accepted') return { action: input.action, ref: preview.ref, status: 'confirmed', tier: 'user_confirmed', prior_tier: row.tier, detail: { resolved_proposal: resolved.ref } };
if (!preview.raises) return { action: input.action, ref: preview.ref, status: 'unchanged', tier: 'user_confirmed', prior_tier: 'user_confirmed' };
// BELIEF_LEDGER.md 6.5: the release is part of the confirm's publication, which released_by names.
let released: string[] = [];
const ok = await setRowTier(engine, { table: row.table, id: row.id, sourceId: row.sourceId, tier: 'user_confirmed', ceiling: 'user_confirmed', by,
note: { via: confirmation.via, action: 'confirm', by: principalLabel(by) },
expect: async tx => (await read(tx, ref.id))?.binding === opts.binding,
also: async (tx, publicationId) => { released = await releaseSuppressedFields(tx, row.table, row.id, publicationId); } });
if (!ok) throw opError('preview_changed', `${preview.ref} changed after you approved it; nothing was changed.`, 'Run the command again.');
return { action: input.action, ref: preview.ref, status: 'confirmed', tier: 'user_confirmed', prior_tier: row.tier, ...(released.length ? { detail: { released_redactions: released } } : {}) };
}
if (ref?.kind === 'page') {
const { sourceId, slug } = await resolvePageRef(engine, ref, input.source);
if (!preview.raises) return { action: 'confirm', ref: preview.ref, status: 'unchanged', tier: 'user_confirmed', prior_tier: 'user_confirmed' };
return asPageResult('confirm', await confirmPage(engine, { sourceId, slug, expectedRevision: preview.revision!, confirmation, by, config: opts.config, ctx: opts.ctx }));
}
if (ref?.kind === 'proposal') return fromDecision('confirm', await decideTrustProposal(engine, ref.id, 'accept', decision));
if (ref?.kind === 'hold') {
const released = await holdStore.publish?.(engine, ref.id, principalLabel(by), opts.config, opts.binding)
?? await engine.transaction(tx => holdStore.release(tx, ref.id, principalLabel(by),
async row => holdBinding(row, (await releaseCellOf(tx, row))?.fields ?? null) === opts.binding));
if (!released) throw opError('preview_changed', `h${ref.id} was decided meanwhile; nothing was changed.`, 'Run gbrain trust review.');
return { action: 'release', ref: preview.ref, status: 'released', tier: 'user_confirmed', prior_tier: preview.tier };
}
throw unsupported(input.action, ref!);
}
case 'drop': {
if (ref?.kind === 'hold') {
if (!(await engine.transaction(tx => holdStore.drop(tx, ref.id, principalLabel(by))))) throw opError('preview_changed', `h${ref.id} was decided meanwhile; nothing was changed.`, 'Run gbrain trust review.');
return { action: 'drop', ref: preview.ref, status: 'dropped' };
}
if (ref?.kind === 'proposal') return fromDecision('drop', await decideTrustProposal(engine, ref.id, 'reject', decision));
throw unsupported('drop', ref!);
}
case 'revert': {
if (ref?.kind === 'proposal') {
const p = (await getTrustProposal(engine, ref.id))!;
if (p.status !== 'pending') throw opError('preview_changed', `${trustProposalRef(p.id)} is ${p.status}; nothing was changed.`, 'Run gbrain trust review.');
return fromDecision('revert', await revertLoweredPage(engine, p, decision));
}
if (ref?.kind === 'page') {
const { sourceId, slug } = await resolvePageRef(engine, ref, input.source);
return asPageResult('revert', await revertPageToVersion(engine, { sourceId, slug, expectedRevision: preview.revision!, versionId: preview.version_id!, confirmation, by, config: opts.config, ctx: opts.ctx }));
}
throw unsupported('revert', ref!);
}
case 'allow': {
const { rule, created } = await addTrustAllowRule(engine, { sourceId: input.source ?? '', uriPrefix: input.uri_prefix, reasonFamily: input.reason_family, reason: input.reason }, by);
return { action: 'allow', ref: rule.ref, status: created ? 'added' : 'unchanged', detail: { rule } };
}
case 'allow_remove': {
const rule = await removeTrustAllowRule(engine, parseAllowRuleRef(input.ref!)!, by);
if (!rule) throw opError('preview_changed', `${preview.ref} was removed meanwhile.`, 'Run gbrain trust review.');
return { action: 'allow_remove', ref: rule.ref, status: 'removed', detail: { rule: rule as TrustAllowRule } };
}
case 'disable': {
const prior = await currentSwitchValues(engine);
const at = new Date().toISOString();
const receipt: KillSwitchReceipt = { state: 'disabled', at, by: principalLabel(by), prior };
for (const [key, value] of Object.entries(TRUST_KILL_SWITCH_VALUES)) await engine.setConfig(key, value);
await engine.setConfig(TRUST_KILL_SWITCH_KEY, JSON.stringify(receipt));
return { action: 'disable', ref: preview.ref, status: 'disabled', detail: { values: { ...TRUST_KILL_SWITCH_VALUES }, prior, at } };
}
case 'enable': {
const last = await readKillSwitch(engine);
const current = await currentSwitchValues(engine);
const restored: string[] = [];
for (const [key, wrote] of Object.entries(TRUST_KILL_SWITCH_VALUES)) {
// Restore only what the disable still owns: a value the owner changed since stays.
if (last?.state !== 'disabled' || current[key] !== wrote) continue;
const prior = last.prior?.[key] ?? null;
if (prior === null) await engine.unsetConfig(key); else await engine.setConfig(key, prior);
restored.push(key);
}
const at = new Date().toISOString();
await engine.setConfig(TRUST_KILL_SWITCH_KEY, JSON.stringify({ state: 'enabled', at, by: principalLabel(by), ...(last?.at ? { disabled_at: last.at } : {}) } satisfies KillSwitchReceipt));
return { action: 'enable', ref: preview.ref, status: last?.state === 'disabled' ? 'enabled' : 'unchanged', detail: { restored, at } };
}
}
}
/** The kill switch receipt and current values (review and explain show it). */
export async function trustKillSwitchState(engine: BrainEngine): Promise<{ receipt: KillSwitchReceipt | null; values: Record<string, string | null> }> {
return { receipt: await readKillSwitch(engine), values: await currentSwitchValues(engine) };
}