Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-190 G4: forget and forget_fact are fence edits. Git is the parent, so a withdrawal is one coordinated
* publication: its preparation strikes the claim (`withdrawnFact`: `~~claim~~` and `forgotten: ...`, the overlay's
* rendering) in the file of every page that carries it, the coordinator publishes those files under one recovery
* record and one Git commit (the request's page plus a CompanionPage per other page, coordinator.ts), and the
* publication transaction then writes the ledger row, the expiries and the chunk invalidation (recordFactWithdrawal's
* `publication` mode). No withdrawal-mirror effect is queued for it; that effect only drains rows queued before.
*
* A page's file is struck when the withdrawal applies to it (its subject is '*' or the page's slug, as the read overlay
* applies it) and the page has a canonical file; a deleted page, or one whose file is missing, gets no file, as the
* mirror never resurrected one. A file that differs from the database refuses the forget (the uncoordinated-edit
* refusal every coordinated page write gives) instead of leaving it unstruck.
*/
import { existsSync } from 'node:fs';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import type { PageSnapshot, PageWithdrawal } from '../page-state/types.ts';
import { verbError } from '../ops/contract.ts';
import { overlayCanonicalBodies } from '../page-state/snapshot.ts';
import { serializePageToMarkdown } from '../markdown.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { planFactWithdrawal, recordFactWithdrawal } from '../facts/withdrawal.ts';
import { rebuildPendingPageProjections } from '../page-state/projections.ts';
import { ownerReadPolicyFragment, readPolicyFragment, remoteProvenanceFloorSql, resolveExcludePrivatePages } from '../search/private-visibility.ts';
import { folderAccessForAll, memberIdentityFor } from '../access/caller.ts';
import { remoteForgetRaced, supersessionGuarded } from '../trust/supersede-handlers.ts';
import { materializedPage } from './segmented-apply.ts';
import { prepareFileTarget, snapshotLedger, unreadPageFile } from './page-prepare.ts';
import { pageIdentityError } from './page-identity.ts';
import { MEMBER_PAGE_PREFIX, onOwnedMemoryPageSql } from '../access/member-facts.ts';
import { unbackedEntitySql } from '../facts/withdrawal-schema.ts';
import { storedOwnerSpeaksForItself } from './page-visibility.ts';
import type { CompanionPage, PageMutationFile, PreparedMutation } from './coordinator.ts';
import type { WriteAuthority, WriteRequest } from './model.ts';
import { isHoldingSlug } from '../facts-fence.ts';
import { prepareFenceRowRetirement } from '../facts/fence-fact-append.ts';
interface ForgetTarget { id: number; entity_slug: string | null; trust_tier?: string | null }
/**
* A fact saved without an entity says nothing about whom it concerns, so its
* withdrawal reaches the claim under every entity. When that claim is active
* on entity-linked facts, forgetting the unlinked copy would silently withdraw
* them too, and a withdrawn claim cannot be remembered again; refuse and name them. GBRA-574: a fact on an unbacked
* name key withdraws source-wide the same way, so it is checked against every other entity's copy.
* A caller that cannot read private pages never withdraws an active copy it
* cannot see: the refusal is then one fixed text that names no fact.
*/
export async function refuseForgetReachingOtherCopies(tx: BrainEngine, sourceId: string, fact: ForgetTarget, remote: boolean, excludePrivate: boolean): Promise<void> {
const id = fact.id;
const unbacked = fact.entity_slug !== null && (await tx.executeRaw<{ unbacked: boolean }>(
`SELECT ${unbackedEntitySql('u')} AS unbacked FROM facts u WHERE u.id=$1 AND u.source_id=$2`, [id, sourceId]))[0]?.unbacked === true;
if (fact.entity_slug === null || unbacked) {
const linked = await tx.executeRaw<{ id: number; entity_slug: string }>(`SELECT l.id,l.entity_slug FROM facts u
JOIN facts l ON l.source_id=u.source_id AND l.visibility=u.visibility AND l.entity_slug IS NOT NULL AND l.entity_slug IS DISTINCT FROM u.entity_slug AND l.id<>u.id
AND l.expired_at IS NULL AND (l.valid_until IS NULL OR l.valid_until > now())
AND gbrain_fact_fingerprint(l.fact)=gbrain_fact_fingerprint(u.fact)
WHERE u.id=$1 AND u.source_id=$2 AND ($3::boolean=false OR l.visibility='world')${excludePrivate ? ` AND ${remoteProvenanceFloorSql('l')}` : ''}
ORDER BY l.id LIMIT 5`, [id, sourceId, remote]);
if (linked.length) {
const named = linked.map(row => `#${row.id} (${row.entity_slug})`).join(', ');
throw verbError('invalid_params',
`claim_linked: fact #${id} was saved ${unbacked ? `on the name tag ${fact.entity_slug}, which has no page` : 'without an entity'}, and the same claim is active as ${named}. Forgetting #${id} would withdraw those facts too, so nothing was forgotten.`,
`Keep the linked ${linked.length === 1 ? 'fact' : 'facts'}: the copy without an entity needs no cleanup (remember the claim with entity and replaces: "${id}" retires it). To withdraw the claim everywhere, forget ${linked.map(row => `#${row.id}`).join(', ')} first, then #${id}.`);
}
}
if (!excludePrivate) return;
const hidden = await tx.executeRaw(`SELECT 1 FROM facts u
JOIN facts l ON l.source_id=u.source_id AND l.visibility=u.visibility AND l.id<>u.id
AND (u.entity_slug IS NULL OR ${unbackedEntitySql('u')} OR l.entity_slug=u.entity_slug)
AND l.expired_at IS NULL AND (l.valid_until IS NULL OR l.valid_until > now())
AND gbrain_fact_fingerprint(l.fact)=gbrain_fact_fingerprint(u.fact)
WHERE u.id=$1 AND u.source_id=$2 AND NOT (${remoteProvenanceFloorSql('l')}) LIMIT 1`, [id, sourceId]);
if (!hidden.length) return;
throw verbError('invalid_params',
`claim_linked: the same claim as fact #${id} is active elsewhere in this brain. Forgetting #${id} would withdraw it there too, so nothing was forgotten.`,
'Keep the fact. To withdraw the claim everywhere, ask the user to forget it on the brain host.');
}
/** The owner's member identity and the folder rules it satisfies, as ownerReachesFact judges them. */
export interface OwnerReader { identity: readonly string[]; satisfied: readonly string[] }
/** GST-2346: the OwnerReader of a stored write's principal, re-resolved live (a member disabled or unbound reads as nobody). */
export async function storedOwnerReader(engine: BrainEngine, authority: WriteAuthority): Promise<OwnerReader> {
const identity = await memberIdentityFor(engine, authority);
return { identity, satisfied: (await folderAccessForAll(engine, [identity])).satisfiedRuleIds };
}
/**
* GST-2346 D1: whether fact id is one the brain owner's own credential withdraws besides the facts every remote caller
* reads and the facts on its member page: a fact on no member or scope page whose source page and entity page (each
* where one exists) the owner both reads under GST-2490's owner read rule and may write as a member (readers that name
* it, folder rules it satisfies, no private visibility). A fact on or about a private page, another member's page or a
* page whose readers leave the owner out stays with the brain host; the owner opt-in to read such pages never widens this.
*/
export async function ownerReachesFact(engine: BrainEngine, id: number, sourceId: string, owner: OwnerReader): Promise<boolean> {
const page = `(${ownerReadPolicyFragment('pp', owner.identity, owner.satisfied)} AND ${readPolicyFragment('pp', owner.identity, true, owner.satisfied)})`;
return (await engine.executeRaw(`SELECT 1 FROM facts WHERE id=$1 AND source_id=$2 AND NOT ${onOwnedMemoryPageSql('facts')}
AND NOT EXISTS (SELECT 1 FROM pages pp WHERE pp.source_id=facts.source_id AND pp.slug IN (facts.source_markdown_slug, facts.entity_slug) AND NOT ${page})`, [id, sourceId])).length > 0;
}
/**
* The fact a forget names, under the caller's visibility (locked inside a transaction when `lock`); null when it is not
* visible. GST-359 D: a member's forget (`ownPage`, its member page) reads only the private facts on that page while
* the page names the member among its readers; the coordinator checks the page's visibility to the stored writer.
*/
export async function readForgetTarget(engine: BrainEngine, id: number, sourceId: string, remote: boolean, excludePrivate: boolean, lock = false, ownPage: string | null = null) {
const [fact] = await engine.executeRaw<ForgetTarget & { source_markdown_slug: string | null; row_num: number | null; expired_at: Date | null }>(`SELECT id,entity_slug,source_markdown_slug,row_num,expired_at,trust_tier FROM facts
WHERE id=$1 AND source_id=$2 AND ${ownPage ? `visibility='private' AND source_markdown_slug=$3 AND EXISTS (SELECT 1 FROM pages member_page
WHERE member_page.source_id=facts.source_id AND member_page.slug=$3 AND member_page.deleted_at IS NULL AND member_page.page_readers && ARRAY[$4::text])`
: `($3::boolean=false OR visibility='world')${excludePrivate ? ` AND ${remoteProvenanceFloorSql('facts')}` : ''}`}${lock ? ' FOR UPDATE' : ''}`,
ownPage ? [id, sourceId, ownPage, `member:${ownPage.slice(MEMBER_PAGE_PREFIX.length)}`] : [id, sourceId, remote]);
return fact ?? null;
}
export async function prepareForgetMutation(engine: BrainEngine, row: WriteRequest, _config: GBrainConfig, signal?: AbortSignal): Promise<PreparedMutation> {
signal?.throwIfAborted();
const p = row.intent ?? {};
const id = Number(p.id);
const rawId = String(p.id ?? '').trim();
const sourceId = row.source_id;
const remote = row.authority.remote !== false;
const reason = typeof p.reason === 'string' && p.reason.trim() ? p.reason.trim() : null;
// GST-359 D: a member's withdrawal of a fact on its own member page (submitForgetMutation records the page).
const ownPage = remote && typeof p.member_page === 'string' && p.member_page === row.slug && row.slug.startsWith(MEMBER_PAGE_PREFIX) ? row.slug : null;
// GST-2346 D1: the owner's withdrawal of a fact off its member page that other remote callers do not reach
// (submitForgetMutation marks it). The owner and the fact's page are judged again here from the stored principal, so a
// request whose writer is no longer the owner, or whose page no longer names it, reads the fact as any remote caller
// does: not found. The fact itself is judged by ownerReachesFact; another copy of the claim on a page kept from remote
// writers still refuses the withdrawal.
const ownerReach = remote && !ownPage && p.owner_reach === true && Number.isSafeInteger(id) && id > 0
&& await storedOwnerSpeaksForItself(engine, row.authority) && await ownerReachesFact(engine, id, sourceId, await storedOwnerReader(engine, row.authority));
const worldOnly = remote && !ownerReach;
const excludePrivate = !ownerReach && await resolveExcludePrivatePages(engine, remote);
const copiesHidden = ownerReach || excludePrivate;
const missing = () => verbError(row.operation === 'forget' ? 'not_found' : 'fact_not_found',
`No fact with id "${rawId}".`, 'Ids come from remember/recall. Recall the entity first to find the right fact.');
if (!Number.isSafeInteger(id) || id <= 0) throw missing();
const fact = await readForgetTarget(engine, id, sourceId, worldOnly, excludePrivate, false, ownPage);
if (!fact) throw missing();
const plan = await planFactWithdrawal(engine, id, sourceId, worldOnly, ownPage ? undefined : excludePrivate, ownPage);
if (!plan) throw missing();
// The files are struck with this timestamp, and the ledger row records it, so the file and the read overlay agree.
const withdrawnAt = new Date().toISOString();
const withdrawal: PageWithdrawal = { visibility: plan.visibility, fact_hash: plan.fact_hash, withdrawn_at: withdrawnAt };
const struck = new Set(plan.affected.map(page => page.slug));
const strike = async (slug: string, snapshot: PageSnapshot | null): Promise<PageMutationFile | undefined> => {
if (!snapshot || snapshot.page.deleted_at || !row.worktree_id || !struck.has(slug) || (plan.subject !== '*' && plan.subject !== slug)) return undefined;
const target = { source_id: sourceId, worktree_id: row.worktree_id, slug, operation: row.operation };
if (isSegmentedPage(snapshot.page)) {
// A segmented page's file is streamed from its segments under the ledger plus this withdrawal (export's overlay),
// never rendered as one string, so a page of any size can be struck.
const struckFile = await unreadPageFile(engine, snapshot, undefined, { ...snapshotLedger(snapshot), withdrawals: [...snapshot.withdrawals, withdrawal] });
if (struckFile.hash === (await unreadPageFile(engine, snapshot)).hash) return undefined;
const file = await prepareFileTarget(engine, target, snapshot, struckFile, undefined, { allowMissing: true, remote });
return file && file.content !== null && existsSync(file.path) ? file : undefined;
}
const page = await materializedPage(engine, snapshot.page);
const query = <T,>(sql: string, params?: unknown[]) => engine.executeRaw<T & Record<string, unknown>>(sql, params) as Promise<T[]>;
const bodies = await overlayCanonicalBodies(query, page.compiled_truth, page.timeline ?? '', [...snapshot.withdrawals, withdrawal],
{ sourceId, marker: snapshot.globalPurges });
if (bodies.compiled_truth === page.compiled_truth && bodies.timeline === (page.timeline ?? '')) return undefined;
const file = await prepareFileTarget(engine, target, snapshot, serializePageToMarkdown({ ...page, ...bodies }, snapshot.tags), undefined, { allowMissing: true, remote });
// A removal (a strict page turning private, git-declared.ts) is that transition's own write, never a withdrawal's.
return file && file.content !== null && existsSync(file.path) ? file : undefined;
};
const own = await engine.readPageSnapshot(row.slug, { sourceId, includeDeleted: true });
if ((own?.page.id ?? null) !== row.page_id) throw pageIdentityError(own != null || row.page_id === null, 'The page of the forgotten fact was deleted or recreated.');
// GST-2492: a fact held on a holding page for an entity with no page is struck at its own row, in the file and the
// page, so a rebuild from Git does not bring it back; the claim-wide strike would also reach other entities' rows there.
const held = isHoldingSlug(row.slug) && fact.source_markdown_slug === row.slug && fact.entity_slug !== null && fact.row_num !== null
&& plan.subject !== '*' && own && !own.page.deleted_at && row.worktree_id
? await prepareFenceRowRetirement(engine, row, _config, row.slug, { rowNum: Number(fact.row_num), note: 'memory withdrawn', validUntil: new Date(withdrawnAt), forgotten: true }, signal)
: null;
const file = held ? held.file : await strike(row.slug, own);
const companions: CompanionPage[] = [];
for (const slug of plan.slugs) {
if (slug === row.slug) continue;
signal?.throwIfAborted();
const snapshot = await engine.readPageSnapshot(slug, { sourceId, includeDeleted: true });
const companionFile = await strike(slug, snapshot);
companions.push({ slug, pageId: snapshot?.page.id ?? null, observedRevision: snapshot?.revision ?? null,
...(companionFile ? { file: companionFile } : {}), apply: async () => undefined });
}
let pages: string[] = [];
return { observedRevision: held ? held.observedRevision : own?.revision ?? null, ...(file ? { file } : {}), ...(companions.length ? { companions } : {}),
// #8636: forget_fact on an already-expired fact still publishes its withdrawal, then answers fact_already_expired.
...(row.operation === 'forget_fact' && fact.expired_at !== null ? { failure: { code: 'fact_already_expired', message: `Fact id ${id} already expired.` } } : {}),
validate: async tx => {
// Under the publication's locks: the fact is still visible, no more trusted than a remote caller, and reaches no other copy.
const current = await readForgetTarget(tx, id, sourceId, worldOnly, excludePrivate, true, ownPage);
if (!current || (ownerReach && !(await storedOwnerSpeaksForItself(tx, row.authority)
&& await ownerReachesFact(tx, id, sourceId, await storedOwnerReader(tx, row.authority))))) throw missing();
if (remote && supersessionGuarded('agent_written', current.trust_tier)) throw remoteForgetRaced(id);
if (!ownPage) await refuseForgetReachingOtherCopies(tx, sourceId, current, worldOnly, copiesHidden);
await held?.validate?.(tx);
},
apply: async (tx, preimage) => {
if (held) await held.apply(tx, preimage ?? null);
// Even an expired legacy fact acquires a ledger row (forget_fact then finishes failed), so a stale import cannot reactivate it.
const publication = { withdrawnAt, expectedSlugs: plan.slugs };
pages = (await recordFactWithdrawal(tx, id, sourceId, worldOnly, ownPage
? { requestId: row.id, semanticReview: false, memberPage: ownPage, publication }
: { requestId: row.id, semanticReview: p.semantic_review !== false, excludePrivate, publication })).pages.map(page => page.slug);
if (reason) await tx.executeRaw(`UPDATE facts SET context=concat_ws(' | ',NULLIF(context,''),$3::text)
WHERE id=$1 AND source_id=$2`, [id, sourceId, `forgotten: ${reason}`]);
return row.operation === 'forget'
? { id: rawId, expired: fact.expired_at === null, reason, protocol_version: 1 }
: { id, expired: true, path: 'legacy_db', reason: reason ?? 'forgotten' };
},
// The publication removed the withdrawn pages' chunks; rebuild them now, as a CLI process exits without a
// resident projection worker. A failed rebuild stays queued as durable projection work.
afterCommit: async committed => {
for (let start = 0; start < pages.length; start += 100) {
await rebuildPendingPageProjections(committed, 100, { pages: { sourceId, slugs: pages.slice(start, start + 100) } }).catch(() => undefined);
}
} };
}