Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* S9 proposal accept / undo: a CHECKED supersede of one fact by another.
*
* Unlike `expireSuperseded` (write-single.ts), which warns and continues, a
* checked supersede applies the database change (expired_at, valid_until,
* superseded_by on the old fact), the struck `## Facts` fence row and the
* proposal's status as one unit, and fails the whole operation otherwise; the
* proposal then stays `pending`. Before and after state (the three fields,
* the fence row and the page revision) are stored on the proposal so `undo`
* can restore them, refusing when either fact or the fence row changed since.
*
* Unmanaged brains: under the source filesystem lock and the page lock, the
* database writes run in one transaction whose last step publishes the file
* (atomic .tmp + parse-validate + rename); a failed commit restores the file.
* Managed brains: the same plan runs as a coordinator mutation (operation
* `decide_proposal`), whose publication makes the file and database one unit.
*/
import { createHash, randomUUID } from 'node:crypto';
import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { formatFenceDate, parseFactsFence, type ParsedFact } from '../facts-fence.ts';
import { serializePageToMarkdown } from '../markdown.ts';
import { assertInlineBody, bodyUnread } from '../page-body/page-shape.ts';
import { contentHash } from '../utils.ts';
import { withPageLock } from '../page-lock.ts';
import { assertSourceFilesystemActive, withSourceFilesystemLock } from '../minions/source-filesystem.ts';
import { isWriteThroughDisabled, resolvePageWriteTarget } from '../write-through.ts';
import { opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { getProposal, transitionProposal, type ProposalRow } from '../ai/decide/proposals-store.ts';
import { strikeFenceRow, supersededFact } from './forget.ts';
import { supersededValidUntil } from './supersede-interval.ts';
import { maintenanceTransaction } from '../persistence/attribution.ts';
import { wholeBodySnapshot } from '../persistence/segmented-apply.ts';
import { withTrustKeep } from '../persistence/context.ts';
import type { PreparedMutation } from '../persistence/coordinator.ts';
import type { WriteRequest } from '../persistence/model.ts';
import { noteBelief } from '../belief/ledger.ts';
import { beliefStreamSlugs, lockedBeliefBatch } from '../belief/writers.ts';
import { fileBodyMatchesStored, fileDatabaseDriftToken, mirrorFileBody, readStoredBody, type StoredBody } from './file-body-guard.ts';
export const DECIDE_PROPOSAL_OPERATION = 'decide_proposal';
export interface PairFact {
id: number;
source_id: string;
entity_slug: string | null;
visibility: string;
fact: string;
expired_at: string | null;
/** Read by the supersession rule (supersede-interval.ts); a pair built without it strikes with today's date. */
valid_from?: string | null;
valid_until: string | null;
superseded_by: number | null;
row_num: number | null;
source_markdown_slug: string | null;
}
export interface FactFields { expired_at: string | null; valid_until: string | null; superseded_by: number | null; fact_sha256: string }
export interface FenceState { slug: string; row_num: number; row: ParsedFact; page_revision: string | null; file: boolean }
export interface SupersedeState { old: FactFields; new: FactFields; fence: FenceState | null }
export type ProposalAction = 'accept' | 'undo';
export interface ProposalActionResult {
id: number;
action: ProposalAction | 'reject';
status: 'accepted' | 'rejected' | 'stale' | 'undone' | 'refused' | 'not_found';
reason?: string;
}
/**
* The proposal record a checked supersede reads and transitions: decide_proposals
* (S9) by default, or another typed store with the same pair shape (#5575
* trust_proposals, trust/supersede-handlers.ts TRUST_PAIR_STORE). `onAccept` /
* `onUndo` run inside the same transaction after the facts change.
*/
export type PairProposal = Pick<ProposalRow, 'id' | 'source_id' | 'old_fact_id' | 'new_fact_id' | 'status' | 'before_state' | 'after_state'>;
export interface PairProposalStore {
name: string;
get(engine: BrainEngine, id: number, lock?: boolean): Promise<PairProposal | null>;
transition(engine: BrainEngine, id: number, from: string, to: string, state?: { before?: string | null; after?: string | null }): Promise<boolean>;
onAccept?(tx: BrainEngine, proposal: PairProposal): Promise<void>;
onUndo?(tx: BrainEngine, proposal: PairProposal): Promise<void>;
}
export const DECIDE_PROPOSAL_STORE: PairProposalStore = {
name: 'decide', get: getProposal,
transition: (engine, id, from, to, state) => transitionProposal(engine, id, from as ProposalRow['status'], to as ProposalRow['status'], state),
};
/** The store a managed decide_proposal intent names; loaded lazily so the trust module and this one never cycle at init. */
async function pairStore(name: unknown): Promise<PairProposalStore | null> {
if (name === undefined || name === null) return DECIDE_PROPOSAL_STORE;
if (name === 'trust') return (await import('../trust/supersede-handlers.ts')).TRUST_PAIR_STORE;
if (name === 'trust_reverse') return (await import('../trust/supersede-handlers.ts')).TRUST_REVERSE_PAIR_STORE;
return null;
}
export class ProposalConflictError extends Error {
constructor(message: string) { super(message); this.name = 'ProposalConflictError'; }
}
const iso = (v: unknown): string | null => v === null || v === undefined ? null : new Date(v as string).toISOString();
const sha = (s: string) => createHash('sha256').update(s).digest('hex');
export async function loadPairFact(engine: BrainEngine, id: number, lock = false): Promise<PairFact | null> {
const [r] = await engine.executeRaw<Record<string, unknown>>(
`SELECT id, source_id, entity_slug, visibility, fact, expired_at, valid_from, valid_until, superseded_by, row_num, source_markdown_slug
FROM facts WHERE id = $1${lock ? ' FOR UPDATE' : ''}`, [id]);
if (!r) return null;
return {
id: Number(r.id), source_id: String(r.source_id), entity_slug: (r.entity_slug as string | null) ?? null, visibility: String(r.visibility),
fact: String(r.fact), expired_at: iso(r.expired_at), valid_from: iso(r.valid_from), valid_until: iso(r.valid_until),
superseded_by: r.superseded_by === null || r.superseded_by === undefined ? null : Number(r.superseded_by),
row_num: r.row_num === null || r.row_num === undefined ? null : Number(r.row_num), source_markdown_slug: (r.source_markdown_slug as string | null) ?? null,
};
}
export function factFields(f: PairFact): FactFields {
return { expired_at: f.expired_at, valid_until: f.valid_until, superseded_by: f.superseded_by, fact_sha256: sha(f.fact) };
}
const sameFields = (a: FactFields, b: FactFields) => a.expired_at === b.expired_at && a.valid_until === b.valid_until
&& a.superseded_by === b.superseded_by && a.fact_sha256 === b.fact_sha256;
function stableJson(v: unknown): string {
if (v === null || typeof v !== 'object') return JSON.stringify(v);
if (Array.isArray(v)) return `[${v.map(stableJson).join(',')}]`;
return `{${Object.keys(v).filter((k) => (v as Record<string, unknown>)[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${stableJson((v as Record<string, unknown>)[k])}`).join(',')}}`;
}
export const sameRow = (a: ParsedFact | undefined, b: ParsedFact | undefined) => a !== undefined && b !== undefined && stableJson(a) === stableJson(b);
/** Why an accept can no longer apply (the proposal becomes `stale`), or null. */
export function staleReason(proposal: Pick<ProposalRow, 'source_id'>, oldF: PairFact | null, newF: PairFact | null, nowMs: number): string | null {
if (!oldF || !newF) return 'fact_missing';
const active = (f: PairFact) => f.expired_at === null && (f.valid_until === null || new Date(f.valid_until).getTime() > nowMs);
if (!active(oldF)) return 'old_fact_inactive';
if (!active(newF)) return 'new_fact_inactive';
if (oldF.source_id !== proposal.source_id || newF.source_id !== proposal.source_id || oldF.entity_slug !== newF.entity_slug || oldF.visibility !== newF.visibility) return 'scope_changed';
return null;
}
/** The old fact's validity end on accept (supersede-interval.ts's rule), or undefined when the pair carries no dates. */
const acceptedUntil = (oldF: PairFact, newF: PairFact): Date | undefined =>
oldF.valid_from ? supersededValidUntil({ valid_from: oldF.valid_from, valid_until: oldF.valid_until }, newF.valid_from ? new Date(newF.valid_from) : null) : undefined;
/** The old fact's fence row struck as superseded (with `#N` when the new fact lives on the same page), ending where the rule says. */
export function planAcceptFence(body: string, oldF: PairFact, newF: PairFact, today: string): { body: string; before: ParsedFact; after: ParsedFact } | null {
if (oldF.row_num === null || !oldF.source_markdown_slug) return null;
const before = parseFactsFence(body).facts.find((f) => f.rowNum === oldF.row_num);
if (!before) return null;
const newRow = newF.source_markdown_slug === oldF.source_markdown_slug && newF.row_num !== null ? newF.row_num : null;
const until = acceptedUntil(oldF, newF);
const struck = strikeFenceRow(body, oldF.row_num, (f) => supersededFact(f, today, newRow, until && formatFenceDate(until)));
if (struck === null) return null;
const after = parseFactsFence(struck).facts.find((f) => f.rowNum === oldF.row_num);
return after ? { body: struck, before, after } : null;
}
/** The accepted fence row restored; `changed` when the row is no longer the one accept wrote. */
export function planUndoFence(body: string, fence: FenceState, after: FenceState): { body: string } | 'changed' {
const current = parseFactsFence(body).facts.find((f) => f.rowNum === fence.row_num);
if (!sameRow(current, after.row)) return 'changed';
const restored = strikeFenceRow(body, fence.row_num, () => fence.row);
return restored === null ? 'changed' : { body: restored };
}
/** Undo refusal: either fact (or the fence row) changed since accept. */
export function undoRefusal(state: { before: SupersedeState; after: SupersedeState }, oldF: PairFact | null, newF: PairFact | null): string | null {
if (!oldF || !newF) return 'fact_missing';
if (!sameFields(factFields(oldF), state.after.old)) return 'old_fact_changed';
if (!sameFields(factFields(newF), state.after.new)) return 'new_fact_changed';
return null;
}
// ---------------------------------------------------------------------------
// Database units (shared by the unmanaged and managed paths)
// ---------------------------------------------------------------------------
async function expireOld(tx: BrainEngine, proposal: PairProposal): Promise<void> {
const [oldF, newF] = await Promise.all([loadPairFact(tx, proposal.old_fact_id), loadPairFact(tx, proposal.new_fact_id)]);
const until = oldF && newF ? acceptedUntil(oldF, newF) ?? null : null;
const rows = await tx.executeRaw<{ id: number }>(
`UPDATE facts SET expired_at = now(), valid_until = COALESCE($4::timestamptz, GREATEST(valid_from, LEAST(COALESCE(valid_until, now()), now()))), superseded_by = $3
WHERE id = $1 AND source_id = $2 AND expired_at IS NULL RETURNING id`,
[proposal.old_fact_id, proposal.source_id, proposal.new_fact_id, until?.toISOString() ?? null]);
if (rows.length !== 1) throw new ProposalConflictError('the old fact changed during accept');
noteBelief({ kind: 'superseded', oldId: proposal.old_fact_id, newId: proposal.new_fact_id });
}
/** Record the after state (read back inside the transaction) and move the proposal to accepted. */
async function finishAccept(tx: BrainEngine, proposal: PairProposal, before: SupersedeState, fenceAfter: FenceState | null, store: PairProposalStore): Promise<void> {
const [oldF, newF] = await Promise.all([loadPairFact(tx, proposal.old_fact_id), loadPairFact(tx, proposal.new_fact_id)]);
const after: SupersedeState = { old: factFields(oldF!), new: factFields(newF!), fence: fenceAfter };
if (!await store.transition(tx, proposal.id, 'pending', 'accepted', { before: JSON.stringify(before), after: JSON.stringify(after) })) {
throw new ProposalConflictError('the proposal is no longer pending');
}
await store.onAccept?.(tx, proposal);
}
async function applyUndoDb(tx: BrainEngine, proposal: PairProposal, before: SupersedeState, after: SupersedeState, store: PairProposalStore): Promise<void> {
const rows = await tx.executeRaw<{ id: number }>(
`UPDATE facts SET expired_at = $3::timestamptz, valid_until = $4::timestamptz, superseded_by = $5
WHERE id = $1 AND source_id = $2 AND superseded_by IS NOT DISTINCT FROM $6 RETURNING id`,
[proposal.old_fact_id, proposal.source_id, before.old.expired_at, before.old.valid_until, before.old.superseded_by, after.old.superseded_by]);
if (rows.length !== 1) throw new ProposalConflictError('the old fact changed during undo');
if (!await store.transition(tx, proposal.id, 'accepted', 'undone')) throw new ProposalConflictError('the proposal is no longer accepted');
await store.onUndo?.(tx, proposal);
}
function parseStates(p: PairProposal): { before: SupersedeState; after: SupersedeState } | null {
try { return p.before_state && p.after_state ? { before: JSON.parse(p.before_state), after: JSON.parse(p.after_state) } : null; } catch { return null; }
}
// ---------------------------------------------------------------------------
// Unmanaged path
// ---------------------------------------------------------------------------
/** W1 #6783 §6.4: an unmanaged accept or undo runs in a belief batch over both facts' streams (the managed path's publication has its own). */
async function recordedPair(tx: BrainEngine, proposal: PairProposal, action: ProposalAction, fn: () => Promise<void>): Promise<void> {
const slugs = await beliefStreamSlugs(tx, 'facts', [proposal.old_fact_id, proposal.new_fact_id]);
await lockedBeliefBatch(tx, { sourceId: proposal.source_id, slugs, op: DECIDE_PROPOSAL_OPERATION, remote: false, cause: { proposal: proposal.id, action } }, fn);
}
class ProposalFileDrift extends ProposalConflictError {}
const proposalDrift = (slug: string, sourceId: string, when: 'before' | 'during') =>
fileDatabaseDriftToken(slug, sourceId, when, 'the proposal and its facts are unchanged');
function publishFile(filePath: string, body: string, expected: string, slug: string, sourceId: string): void {
if (!existsSync(filePath) || readFileSync(filePath, 'utf-8') !== expected) throw new ProposalFileDrift(proposalDrift(slug, sourceId, 'during'));
const tmp = `${filePath}.tmp`;
assertSourceFilesystemActive();
writeFileSync(tmp, body, 'utf-8');
if (parseFactsFence(readFileSync(tmp, 'utf-8')).warnings.length > 0) {
rmSync(tmp, { force: true });
throw new ProposalConflictError('the rewritten facts fence failed validation');
}
renameSync(tmp, filePath);
}
/** Restore a failed publication only while the checkout still carries this operation's published bytes. */
function restorePublishedFile(filePath: string, before: string, published: string, slug: string, sourceId: string): void {
if (existsSync(filePath) && readFileSync(filePath, 'utf-8') === published) {
writeFileSync(filePath, before, 'utf-8');
return;
}
console.warn(`[facts.proposal] ${slug} (file_database_drift: the proposal transaction failed after publication and the file changed again, `
+ `so its current bytes were preserved instead of restoring the old file. Check the database copy before retrying the proposal. `
+ `Import the editor's file with gbrain sync --source ${sourceId}; if the database copy should win, re-save it with write-through on; `
+ `when both changed, ask the user which edit wins)`);
}
/** Mirror the page body the fence change produced (the #4696 rule: keep the old hash so sync re-imports). */
async function mirrorBody(tx: BrainEngine, slug: string, sourceId: string, body: string, fromFile: boolean, expected: StoredBody | null): Promise<string | null> {
if (fromFile) {
if (!expected || !await mirrorFileBody(tx, sourceId, slug, body, expected)) throw new ProposalFileDrift(proposalDrift(slug, sourceId, 'during'));
return (await tx.readPageSnapshot(slug, { sourceId }))?.revision ?? null;
}
const current = await readStoredBody(tx, sourceId, slug, true);
if (!current || !expected || current.compiled_truth !== expected.compiled_truth || current.timeline !== expected.timeline) {
throw new ProposalFileDrift(`${slug} (revision_conflict: the database body changed while the proposal ran; nothing changed. Read the current page before deciding the proposal again)`);
}
const page = await tx.getPage(slug, { sourceId });
if (!page) return null;
assertInlineBody(page, 'proposal fence mirror');
await tx.createVersion(slug, { sourceId });
await tx.refreshPageBody(slug, sourceId, body, page.timeline ?? '', contentHash({ ...page, compiled_truth: body }));
return (await tx.readPageSnapshot(slug, { sourceId }))?.revision ?? null;
}
async function withFenceLocks<T>(engine: BrainEngine, slug: string | null, sourceId: string, run: (filePath: string | null) => Promise<T>): Promise<T> {
if (!slug) return run(null);
if (await isWriteThroughDisabled(engine)) return withPageLock(slug, () => run(null), { timeoutMs: 5_000 });
const target = await resolvePageWriteTarget(engine, slug, sourceId);
if (!target.ok) return withPageLock(slug, () => run(null), { timeoutMs: 5_000 });
return withSourceFilesystemLock(engine, target.writeRoot, () => withPageLock(slug, () => run(target.filePath), { timeoutMs: 5_000 }));
}
async function acceptUnmanaged(engine: BrainEngine, proposal: PairProposal, store: PairProposalStore): Promise<ProposalActionResult> {
const first = await loadPairFact(engine, proposal.old_fact_id);
return withFenceLocks(engine, first?.source_markdown_slug ?? null, proposal.source_id, async (filePath) => {
const fresh = await store.get(engine, proposal.id);
if (!fresh || fresh.status !== 'pending') return { id: proposal.id, action: 'accept', status: 'refused', reason: fresh?.status ?? 'not_found' };
const [oldF, newF] = await Promise.all([loadPairFact(engine, fresh.old_fact_id), loadPairFact(engine, fresh.new_fact_id)]);
const stale = staleReason(fresh, oldF, newF, Date.now());
if (stale) {
await store.transition(engine, fresh.id, 'pending', 'stale');
return { id: fresh.id, action: 'accept', status: 'stale', reason: stale };
}
const slug = oldF!.source_markdown_slug;
const fileBody = filePath && existsSync(filePath) ? readFileSync(filePath, 'utf-8') : null;
const snapshot = slug ? await engine.readPageSnapshot(slug, { sourceId: fresh.source_id }) : null;
if (snapshot && bodyUnread(snapshot.page)) return { id: fresh.id, action: 'accept', status: 'refused', reason: `${slug} (page_body_segmented: this proposal needs an inline page; nothing changed)` };
const stored = slug ? await readStoredBody(engine, fresh.source_id, slug) : null;
if (fileBody !== null && (!stored || !fileBodyMatchesStored(fileBody, slug!, stored))) {
return { id: fresh.id, action: 'accept', status: 'refused', reason: proposalDrift(slug!, fresh.source_id, 'before') };
}
const body = fileBody ?? stored?.compiled_truth ?? null;
const plan = slug && body !== null ? planAcceptFence(body, oldF!, newF!, formatFenceDate(new Date())) : null;
const fence = (row: ParsedFact, revision: string | null): FenceState => ({ slug: slug!, row_num: oldF!.row_num!, row, page_revision: revision, file: fileBody !== null });
const before: SupersedeState = { old: factFields(oldF!), new: factFields(newF!), fence: plan ? fence(plan.before, snapshot?.revision ?? null) : null };
let published = false;
try {
// The strike edits a managed fence without authoring the page: it keeps its trust tier (#5575 ENG-1).
await maintenanceTransaction(engine, (tx) => withTrustKeep(tx, ['pages'], async () => recordedPair(tx, fresh, 'accept', async () => {
const revision = plan ? await mirrorBody(tx, slug!, fresh.source_id, plan.body, fileBody !== null, stored) : null;
await expireOld(tx, fresh);
await finishAccept(tx, fresh, before, plan ? fence(plan.after, revision) : null, store);
if (plan && fileBody !== null) { publishFile(filePath!, plan.body, fileBody, slug!, fresh.source_id); published = true; }
})));
} catch (err) {
if (published) restorePublishedFile(filePath!, fileBody!, plan!.body, slug!, fresh.source_id);
if (err instanceof ProposalFileDrift) return { id: fresh.id, action: 'accept', status: 'refused', reason: err.message };
throw err;
}
return { id: fresh.id, action: 'accept', status: 'accepted' };
});
}
async function undoUnmanaged(engine: BrainEngine, proposal: PairProposal, store: PairProposalStore): Promise<ProposalActionResult> {
const first = await loadPairFact(engine, proposal.old_fact_id);
return withFenceLocks(engine, first?.source_markdown_slug ?? null, proposal.source_id, async (filePath) => {
const fresh = await store.get(engine, proposal.id);
if (!fresh || fresh.status !== 'accepted') return { id: proposal.id, action: 'undo', status: 'refused', reason: fresh?.status ?? 'not_found' };
const states = parseStates(fresh);
if (!states) return { id: fresh.id, action: 'undo', status: 'refused', reason: 'no_recorded_state' };
const [oldF, newF] = await Promise.all([loadPairFact(engine, fresh.old_fact_id), loadPairFact(engine, fresh.new_fact_id)]);
const refusal = undoRefusal(states, oldF, newF);
if (refusal) return { id: fresh.id, action: 'undo', status: 'refused', reason: refusal };
const { before, after } = states;
let plan: { body: string } | null = null;
let fileBody: string | null = null;
let stored: StoredBody | null = null;
if (before.fence && after.fence) {
fileBody = before.fence.file && filePath && existsSync(filePath) ? readFileSync(filePath, 'utf-8') : null;
if (before.fence.file && fileBody === null && !await isWriteThroughDisabled(engine)) return { id: fresh.id, action: 'undo', status: 'refused', reason: 'fence_file_missing' };
const page = await engine.getPage(before.fence.slug, { sourceId: fresh.source_id });
if (page && bodyUnread(page)) return { id: fresh.id, action: 'undo', status: 'refused', reason: `${before.fence.slug} (page_body_segmented: this proposal needs an inline page; nothing changed)` };
stored = await readStoredBody(engine, fresh.source_id, before.fence.slug);
const body = fileBody ?? stored?.compiled_truth ?? null;
const planned = body === null ? 'changed' : planUndoFence(body, before.fence, after.fence);
if (planned === 'changed') return { id: fresh.id, action: 'undo', status: 'refused', reason: 'fence_changed' };
if (fileBody !== null && (!stored || !fileBodyMatchesStored(fileBody, before.fence.slug, stored))) {
return { id: fresh.id, action: 'undo', status: 'refused', reason: proposalDrift(before.fence.slug, fresh.source_id, 'before') };
}
plan = planned;
}
let published = false;
try {
await maintenanceTransaction(engine, (tx) => withTrustKeep(tx, ['pages'], async () => recordedPair(tx, fresh, 'undo', async () => {
if (plan) await mirrorBody(tx, before.fence!.slug, fresh.source_id, plan.body, fileBody !== null, stored);
await applyUndoDb(tx, fresh, before, after, store);
if (plan && fileBody !== null) { publishFile(filePath!, plan.body, fileBody, before.fence!.slug, fresh.source_id); published = true; }
})));
} catch (err) {
if (published) restorePublishedFile(filePath!, fileBody!, plan!.body, before.fence!.slug, fresh.source_id);
if (err instanceof ProposalFileDrift) return { id: fresh.id, action: 'undo', status: 'refused', reason: err.message };
throw err;
}
return { id: fresh.id, action: 'undo', status: 'undone' };
});
}
// ---------------------------------------------------------------------------
// Managed path: coordinator mutation `decide_proposal`
// ---------------------------------------------------------------------------
const proposalsFix = (why: string) => readFix(why, { argv: ['gbrain', 'decide', 'proposals', 'list', '--status', 'all', '--json'] });
/** Coordinator preparer: the same plan as the unmanaged path, published by the coordinator as one unit. */
export async function prepareProposalMutation(engine: BrainEngine, row: WriteRequest, config: GBrainConfig): Promise<PreparedMutation> {
const p = row.intent as { proposal_id?: number; action?: ProposalAction; store?: string } | null;
const id = Number(p?.proposal_id);
const store = await pairStore(p?.store);
if (row.operation !== DECIDE_PROPOSAL_OPERATION || !Number.isSafeInteger(id) || (p?.action !== 'accept' && p?.action !== 'undo') || row.authority.remote || !store) {
throw opError('permission_denied', 'Unsupported decide proposal intent.',
`Request ${row.request_id} in source ${row.source_id} is not a local accept or undo of a proposal, so the coordinator refused it and nothing changed. Decide proposals from the brain host's CLI with gbrain decide proposals accept or undo.`,
{ fix: proposalsFix('Lists proposals with their ids and status, read-only.') });
}
const action = p.action;
const proposal = await store.get(engine, id);
// #8060: a segmented page within PAGE_MAX_BYTES is read back whole and its fence written as a normal put (facts-prepare.ts).
const snapshot = await wholeBodySnapshot(engine, await engine.readPageSnapshot(row.slug, { sourceId: row.source_id }), 'decide_proposal');
const observedRevision = snapshot?.revision ?? null;
const done = (outcome: Record<string, unknown>): PreparedMutation => ({ observedRevision, noop: true, apply: async () => outcome });
if (!proposal || proposal.source_id !== row.source_id) return done({ id, action, status: 'refused', reason: 'not_found' });
if (proposal.status !== (action === 'accept' ? 'pending' : 'accepted')) return done({ id, action, status: 'refused', reason: proposal.status });
const [oldF, newF] = await Promise.all([loadPairFact(engine, proposal.old_fact_id), loadPairFact(engine, proposal.new_fact_id)]);
// The belief ledger records the new fact's tier change in its own stream, so that page key is held too.
const newStream = newF?.source_markdown_slug ?? newF?.entity_slug ?? null;
const pairKeys = newStream && newStream !== row.slug ? { additionalPageKeys: [{ sourceId: row.source_id, slug: newStream }] } : {};
const unchanged = async (tx: BrainEngine) => {
const current = await store.get(tx, id, true);
const [o, n] = await Promise.all([loadPairFact(tx, proposal.old_fact_id, true), loadPairFact(tx, proposal.new_fact_id, true)]);
if (current?.status !== proposal.status || !o || !n || !oldF || !newF || !sameFields(factFields(o), factFields(oldF)) || !sameFields(factFields(n), factFields(newF))) {
throw opError('revision_conflict', 'The proposal or its facts changed during preparation.',
`Proposal ${id} or its facts changed while request ${row.request_id} was prepared, so nothing was applied. Review its current status, then decide it again if it still applies.`,
{ fix: proposalsFix(`Shows proposal ${id}'s current status, read-only.`) });
}
};
const pageFor = async (body: string): Promise<PreparedMutation | undefined> => {
if (!snapshot) return undefined;
const page = await preparePage(engine, { ...row, intent: { ...row.intent, content: serializePageToMarkdown({ ...snapshot.page, compiled_truth: body }, snapshot.tags), expected_revision: observedRevision, force: false } }, config);
if (page.observedRevision !== observedRevision) {
throw opError('revision_conflict', 'The fact page changed during preparation.',
`Fact page ${row.slug} in source ${row.source_id} changed while proposal ${id} (request ${row.request_id}) was prepared, so nothing was applied. Review the page and the proposal, then decide it again if it still applies.`,
{ fix: readFix(`Shows page ${row.slug} as it is now, read-only.`, { argv: ['gbrain', 'get', '--source', row.source_id, '--', row.slug] }) });
}
return page;
};
if (action === 'accept') {
const stale = staleReason(proposal, oldF, newF, Date.now());
if (stale) return { observedRevision, validate: unchanged, apply: async (tx) => {
await store.transition(tx, id, 'pending', 'stale');
return { id, action, status: 'stale', reason: stale };
} };
const plan = oldF!.source_markdown_slug === row.slug && snapshot ? planAcceptFence(snapshot.page.compiled_truth, oldF!, newF!, formatFenceDate(new Date())) : null;
const page = plan ? await pageFor(plan.body) : undefined;
const fence = (r: ParsedFact, revision: string | null): FenceState => ({ slug: row.slug, row_num: oldF!.row_num!, row: r, page_revision: revision, file: page?.file !== undefined });
const before: SupersedeState = { old: factFields(oldF!), new: factFields(newF!), fence: plan ? fence(plan.before, observedRevision) : null };
return { observedRevision, file: page?.file, ...pairKeys, validate: async (tx) => { await unchanged(tx); await page?.validate?.(tx); }, apply: async (tx) => {
// The page projection re-stamps the struck row's expiry from the fence, so the after state is read once it ran.
await expireOld(tx, proposal);
await page?.apply(tx);
const revision = plan ? (await tx.readPageSnapshot(row.slug, { sourceId: row.source_id }))?.revision ?? null : null;
await finishAccept(tx, proposal, before, plan ? fence(plan.after, revision) : null, store);
return { id, action, status: 'accepted' };
} };
}
const states = parseStates(proposal);
if (!states) return done({ id, action, status: 'refused', reason: 'no_recorded_state' });
const refusal = undoRefusal(states, oldF, newF);
if (refusal) return done({ id, action, status: 'refused', reason: refusal });
const { before, after } = states;
let page: PreparedMutation | undefined;
if (before.fence && after.fence) {
const planned = snapshot && before.fence.slug === row.slug ? planUndoFence(snapshot.page.compiled_truth, before.fence, after.fence) : 'changed';
if (planned === 'changed') return done({ id, action, status: 'refused', reason: 'fence_changed' });
page = await pageFor(planned.body);
}
return { observedRevision, file: page?.file, ...pairKeys, validate: async (tx) => { await unchanged(tx); await page?.validate?.(tx); }, apply: async (tx) => {
await page?.apply(tx);
await applyUndoDb(tx, proposal, before, after, store);
return { id, action, status: 'undone' };
} };
}
async function preparePage(engine: BrainEngine, row: WriteRequest, config: GBrainConfig): Promise<PreparedMutation> {
const { preparePageMutation } = await import('../persistence/page-prepare.ts');
return preparePageMutation(engine, row, config);
}
async function submitManaged(engine: BrainEngine, proposal: PairProposal, action: ProposalAction, config: GBrainConfig, store: PairProposalStore): Promise<ProposalActionResult> {
const { initializeLocalPersistence, requestPrincipalForContext } = await import('../persistence/page-mutations.ts');
const { submissionAuthority } = await import('../persistence/authority.ts');
const { admitWrite } = await import('../persistence/journal.ts');
const { assertPersistenceAccepting, waitForWrite, writeResponse } = await import('../persistence/service.ts');
const { getWorktreeBinding } = await import('../persistence/ownership.ts');
const sourceId = proposal.source_id;
const ctx = { engine, sourceId, remote: false as const, config, dryRun: false, logger: { info() {}, warn() {}, error() {} } };
assertPersistenceAccepting(engine);
await initializeLocalPersistence(ctx as never);
const principal = await requestPrincipalForContext(ctx as never);
const [source] = await engine.executeRaw<{ incarnation: string; archived: boolean }>('SELECT incarnation, archived FROM sources WHERE id = $1', [sourceId]);
if (!source || source.archived) {
throw opError('source_changed', 'The proposal source is not active.',
`Proposal ${proposal.id} belongs to source ${sourceId}, which is archived or missing, so nothing changed. Restore the source to decide it (the user's call), or reject the proposal.`,
{ fix: readFix('Lists sources with their archived state, read-only.', { argv: ['gbrain', 'sources', 'list', '--json'] }) });
}
const oldF = await loadPairFact(engine, proposal.old_fact_id);
const slug = oldF?.source_markdown_slug ?? oldF?.entity_slug ?? 'memory/unattributed';
const authority = await submissionAuthority(ctx as never, DECIDE_PROPOSAL_OPERATION, sourceId, source.incarnation, slug);
const snapshot = await engine.readPageSnapshot(slug, { sourceId });
const writeThrough = !/^(false|0|off|no)$/i.test(await engine.getConfig('sync.write_through') ?? 'true');
const binding = snapshot && writeThrough ? await getWorktreeBinding(engine, sourceId) : null;
if (!writeThrough) authority.databaseOnlyReason = 'disabled_by_config';
const intent = { proposal_id: proposal.id, action, ...(store === DECIDE_PROPOSAL_STORE ? {} : { store: store.name }) };
const row = await admitWrite(engine, {
principal, operation: DECIDE_PROPOSAL_OPERATION, sourceId, sourceIncarnation: source.incarnation, slug, pageId: snapshot?.page.id ?? null,
requestId: randomUUID(), callerIntent: intent, intent, authority, worktreeId: binding?.worktree_id ?? null, topologyGeneration: binding?.topology_generation ?? null,
});
const finished = await waitForWrite(engine, row, config, 30_000);
writeResponse(finished);
const out = finished.outcome as unknown as ProposalActionResult;
return { id: out.id, action: out.action, status: out.status, ...(out.reason ? { reason: out.reason } : {}) };
}
async function managed(engine: BrainEngine): Promise<boolean> {
const { managedPersistenceEnabled } = await import('../persistence/ownership.ts');
return managedPersistenceEnabled(engine);
}
/** Accept or undo one proposal through the brain's supersede write path. */
export async function applyProposalAction(engine: BrainEngine, id: number, action: ProposalAction, config?: GBrainConfig,
store: PairProposalStore = DECIDE_PROPOSAL_STORE): Promise<ProposalActionResult> {
const proposal = await store.get(engine, id);
if (!proposal) return { id, action, status: 'not_found' };
const want = action === 'accept' ? 'pending' : 'accepted';
if (proposal.status !== want) return { id, action, status: 'refused', reason: proposal.status };
if (await managed(engine)) return submitManaged(engine, proposal, action, config ?? ({ engine: engine.kind } as GBrainConfig), store);
return action === 'accept' ? acceptUnmanaged(engine, proposal, store) : undoUnmanaged(engine, proposal, store);
}
export async function rejectProposal(engine: BrainEngine, id: number): Promise<ProposalActionResult> {
const proposal = await getProposal(engine, id);
if (!proposal) return { id, action: 'reject', status: 'not_found' };
if (await transitionProposal(engine, id, 'pending', 'rejected')) return { id, action: 'reject', status: 'rejected' };
return { id, action: 'reject', status: 'refused', reason: (await getProposal(engine, id))?.status ?? 'not_found' };
}