Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Trust on the canonical facts-fence re-projection (#5575 A5/I3, ENG-1),
* called by persistence/canonical-projections.ts inside the page publication.
*
* A page publish re-projects its `## Facts` fence: rows that changed or
* disappeared are expired and new rows inserted. Under the writer's declared
* tier (the transaction's gbrain.write_trust_tier, `unknown` when undeclared):
* - Guarded supersession: a row more trusted than the writer is never expired
* by it. The row is detached from its fence position and stays active; when
* the writer only renumbered it (same claim and visibility elsewhere in the
* fence, free slot) it moves there instead, and when the writer only made it
* private (same claim, world to private, GST-2487) it moves there and turns
* private in place, keeping its id and tier. Otherwise the new row at its old
* position is inserted contested with a `supersede_fact` proposal, or, when
* the writer removed it, a `forget` proposal asks the owner. A new world row
* that replaces a guarded non-world row, or restates the claim of a more
* trusted non-world fact of the page at any row number, is inserted at that
* row's visibility and its proposal carries the widening, which only the
* owner's accept applies (GST-2511); until then later writes of the same
* fence keep that contested row narrower.
* - Operator open (#8194): only inside `gbrain repair open-facts`
* (persistence/context.ts withOpenFacts), a named private row whose cell is
* now world at the same row number and claim is guarded at any tier and
* moves back in place as world, keeping its id and tier. Every other
* widening keeps the rules above.
* - Row gate (ENG-1): every new fence row is gated like other fact writers at
* the writer's tier; a held row is not inserted (the hold keeps it), a
* flagged row records its receipt after insert.
* - Held removals (W1 #6783 §12 (a)): the same rule for a page's takes and
* timeline rows. A row more trusted than the writer is never deleted,
* replaced or deactivated by it; it stays as it is and a `forget` proposal
* asks the owner, whose accept applies the page's text to that row
* (trust/held-removals.ts).
*/
import type { BrainEngine, NewFact } from '../engine.ts';
import { currentWriteTrust, openedFactRowSql } from '../persistence/context.ts';
import type { WriteGateConfig } from '../write-gate.ts';
import { decideFactWrite, recordFlaggedRow, recordWriteGateHold, type GatedRowDecision } from '../write-gate-store.ts';
import { gateInput } from './gate-outcomes.ts';
import { insertTrustProposal } from './proposals.ts';
import { recordContestedFact } from './supersede-handlers.ts';
import { compareTrust, storedTrustTier, trustRankSql, type TrustTier, type WriteTrust } from './tier.ts';
type FenceFact = NewFact & { row_num: number };
const WRITER_RANK = trustRankSql(`COALESCE(NULLIF(current_setting('gbrain.write_trust_tier', true), ''), 'unknown')`);
export interface FenceGuard<T extends FenceFact> {
/** The fence rows to insert (held and rejected rows removed, moved rows removed). */
rows: T[];
/** After the caller's expiry and insert: proposals for contested rows (their tp refs), receipts for flagged rows. */
finish(tx: BrainEngine): Promise<string[]>;
}
/**
* Before the caller expires stale fence rows: detaches rows the writer may
* not supersede. `expired()` runs the caller's expiry; then guarded renumbers
* move and new rows are gated.
*/
export async function guardFenceRows<T extends FenceFact>(tx: BrainEngine, input: { sourceId: string; slug: string; incoming: string; rows: T[]; cfg: (db: BrainEngine) => Promise<WriteGateConfig>;
/** #8819: rows the fence never held, which this write keeps as they are. */ kept?: readonly number[] },
expire: () => Promise<unknown>): Promise<FenceGuard<T>> {
const { sourceId, slug, incoming } = input;
// GST-2511: a contested row a widening proposal stored narrower (pending, rejected or undone) is held at its visibility
// while the fence still asks for world at its position. GST-2891: whatever the writer's tier: re-deriving the unchanged
// row (a sync after an unrelated edit, a re-put) is not the owner's accept, which alone applies the widening.
const held = `f.visibility <> 'world' AND EXISTS (SELECT 1 FROM trust_proposals tp WHERE tp.action IN ('supersede_fact', 'confirm') AND tp.related_table = 'facts'
AND tp.related_id = f.id AND tp.status IN ('pending', 'rejected', 'undone') AND tp.before_state->'visibility' IS NOT NULL)
AND EXISTS (SELECT 1 FROM jsonb_to_recordset($3::text::jsonb) AS w(row_num integer, fact text, visibility text)
WHERE w.row_num = f.row_num AND w.fact = f.fact AND w.visibility = 'world')`;
// #8194: a row `gbrain repair open-facts` opens (withOpenFacts: only private to world, same row number and claim) is guarded at
// any tier, so it is detached before the expiry and moves back in place as world, keeping its id and tier.
const opened = openedFactRowSql('f', '$3');
const guarded = (await tx.executeRaw<{ id: number; row_num: number; fact: string; visibility: string; trust_tier: string; above: boolean; opened: boolean }>(
`SELECT f.id, f.row_num, f.fact, f.visibility, f.trust_tier, ${trustRankSql('f.trust_tier')} > ${WRITER_RANK} AS above, ${opened} AS opened FROM facts f
WHERE f.source_id = $1 AND f.source_markdown_slug = $2 AND f.row_num IS NOT NULL AND f.expired_at IS NULL
AND (COALESCE(f.source, '') NOT LIKE 'cli:extract-conversation-facts%'
OR EXISTS (SELECT 1 FROM jsonb_to_recordset($3::text::jsonb) AS c(row_num integer) WHERE c.row_num = f.row_num))
AND NOT EXISTS (SELECT 1 FROM jsonb_to_recordset($3::text::jsonb) AS n(row_num integer, fact text, visibility text)
WHERE n.row_num = f.row_num AND n.fact = f.fact AND n.visibility = f.visibility)
AND (${trustRankSql('f.trust_tier')} > ${WRITER_RANK} OR (${held}) OR ${opened})
ORDER BY f.row_num FOR UPDATE`, [sourceId, slug, incoming])).filter(row => !input.kept?.includes(Number(row.id)));
if (guarded.length) await tx.executeRaw('UPDATE facts SET row_num = NULL WHERE id = ANY($1::bigint[])', [guarded.map(g => Number(g.id))]);
await expire();
// A fence with no rows and nothing guarded has nothing to place or gate (#6007: no reads on a fence-free publish).
if (!input.rows.length && !guarded.length) return { rows: [], async finish() { return []; } };
const occupied = new Set((await tx.executeRaw<{ row_num: number }>(
'SELECT row_num FROM facts WHERE source_id = $1 AND source_markdown_slug = $2 AND row_num IS NOT NULL AND expired_at IS NULL', [sourceId, slug]))
.map(r => Number(r.row_num)));
let rows = input.rows;
const contested: typeof guarded = [];
const moves: Array<{ id: number; row_num: number; visibility: string }> = [];
for (const g of guarded) {
const free = rows.filter(r => r.fact === g.fact && !occupied.has(r.row_num));
const reopened = g.opened ? free.find(r => r.row_num === Number(g.row_num) && r.visibility === 'world') : undefined;
if (reopened) {
moves.push({ id: Number(g.id), row_num: reopened.row_num, visibility: 'world' });
occupied.add(reopened.row_num);
rows = rows.filter(r => r !== reopened);
continue;
}
if (!g.above) {
const target = free.find(r => r.row_num === Number(g.row_num));
if (!target) continue;
moves.push({ id: Number(g.id), row_num: target.row_num, visibility: g.visibility });
occupied.add(target.row_num);
rows = rows.filter(r => r !== target);
continue;
}
const target = free.find(r => r.visibility === g.visibility) ?? (g.visibility === 'world' ? free.find(r => r.visibility === 'private') : undefined);
if (!target) { contested.push(g); continue; }
moves.push({ id: Number(g.id), row_num: target.row_num, visibility: target.visibility ?? g.visibility });
occupied.add(target.row_num);
rows = rows.filter(r => r !== target);
}
// #6574: every guarded row moves in one statement; each starts detached (row_num NULL), so no move collides with another.
if (moves.length) await tx.executeRaw(`UPDATE facts f SET row_num = m.row_num, visibility = m.visibility FROM jsonb_to_recordset($1::text::jsonb) AS m(id bigint, row_num integer, visibility text)
WHERE f.id = m.id`, [JSON.stringify(moves)]);
const gated: Array<{ row: T; decision: GatedRowDecision }> = [];
const inserted: T[] = [];
// Only new rows are gated; owner-tier writers (tool_observed and above) never are, so they read no gate config.
let trust: WriteTrust | null = null;
const writerTrust = async (db: BrainEngine) => trust ??= await currentWriteTrust(db) ?? { tier: 'unknown', origin: null };
const cfg = rows.some(r => !occupied.has(r.row_num)) && compareTrust((await writerTrust(tx)).tier, 'tool_observed') < 0 ? await input.cfg(tx) : null;
// Only a row this write inserts at a guarded row's old position replaces it; a moved row never does.
const fresh = new Set(rows.filter(r => !occupied.has(r.row_num)).map(r => r.row_num));
// GST-2511: a new world row that replaces a guarded non-world row, or restates the claim of a non-world fact of this page
// more trusted than the writer, is inserted at that row's visibility; its proposal carries the widening, which only the
// owner's accept applies. GST-2900: so does a row restating such a fact of its own entity kept on another page (or on
// none), while no world fact of that entity states it (restatedPrivateCopy's rule for remember).
const widened = new Map<number, { from: string; copy?: { id: number; trust_tier: string } }>();
for (const g of contested) {
const at = rows.find(r => r.row_num === Number(g.row_num) && fresh.has(r.row_num));
if (at && g.visibility !== 'world' && at.visibility === 'world') widened.set(at.row_num, { from: g.visibility });
}
const restated = rows.filter(r => fresh.has(r.row_num) && r.visibility === 'world' && !widened.has(r.row_num));
const trustedPrivate = restated.length ? await tx.executeRaw<{ row_num: number; id: number; visibility: string; trust_tier: string }>(
`SELECT DISTINCT ON (r.row_num) r.row_num, f.id, f.visibility, f.trust_tier
FROM jsonb_to_recordset($3::text::jsonb) AS r(row_num integer, fact text, entity text)
JOIN facts f ON f.source_id = $1 AND f.expired_at IS NULL AND (f.source_markdown_slug = $2 OR f.entity_slug = r.entity)
AND f.fact = r.fact AND f.visibility <> 'world' AND ${trustRankSql('f.trust_tier')} > ${WRITER_RANK}
WHERE (f.source_markdown_slug = $2
AND NOT EXISTS (SELECT 1 FROM facts w WHERE w.source_id = $1 AND w.source_markdown_slug = $2 AND w.expired_at IS NULL AND w.visibility = 'world' AND w.fact = f.fact))
OR (f.entity_slug = r.entity AND f.source_markdown_slug IS DISTINCT FROM $2 AND (f.valid_until IS NULL OR f.valid_until > now())
AND NOT EXISTS (SELECT 1 FROM facts w WHERE w.source_id = $1 AND w.entity_slug = r.entity AND w.expired_at IS NULL AND w.visibility = 'world'
AND w.fact = f.fact AND (w.valid_until IS NULL OR w.valid_until > now())))
ORDER BY r.row_num, COALESCE(f.source_markdown_slug = $2, false) DESC, f.id`,
[sourceId, slug, JSON.stringify(restated.map(r => ({ row_num: r.row_num, fact: r.fact, entity: r.entity_slug ?? null })))]) : [];
for (const r of restated) {
const copy = trustedPrivate.find(t => Number(t.row_num) === r.row_num);
if (copy) widened.set(r.row_num, { from: copy.visibility, copy: { id: Number(copy.id), trust_tier: copy.trust_tier } });
}
if (widened.size) rows = rows.map(r => fresh.has(r.row_num) && widened.has(r.row_num) ? { ...r, visibility: widened.get(r.row_num)!.from } : r);
for (const row of rows) {
if (!cfg || occupied.has(row.row_num)) { inserted.push(row); continue; }
const decision = decideFactWrite({ fact: row.fact, context: row.context ?? null, source: row.source ?? null }, { sourceId, slug,
payload: { fact: row.fact, kind: row.kind, visibility: row.visibility, entity_slug: row.entity_slug, source: row.source, context: row.context ?? null, row_num: row.row_num },
input: gateInput(await writerTrust(tx), null), cfg });
if (decision.action === 'hold') { await recordWriteGateHold(tx, decision.hold!); continue; }
if (decision.action === 'reject') continue;
inserted.push(row);
if (decision.assessment.verdict === 'flag') gated.push({ row, decision });
}
return {
rows: inserted,
async finish(db) {
const refs: string[] = [];
const at = async (rowNum: number) => (await db.executeRaw<{ id: number; trust_tier: string }>(
`SELECT id, trust_tier FROM facts WHERE source_id = $1 AND source_markdown_slug = $2 AND row_num = $3 AND expired_at IS NULL`, [sourceId, slug, rowNum]))[0];
for (const g of contested) {
const replacement = fresh.has(Number(g.row_num)) ? await at(Number(g.row_num)) : undefined;
if (replacement) {
refs.push((await recordContestedFact(db, { sourceId, oldId: Number(g.id), oldTier: storedTrustTier(g.trust_tier), newId: Number(replacement.id),
newTier: storedTrustTier(replacement.trust_tier), guard: 'fence_projection',
...(widened.has(Number(g.row_num)) ? { visibility: { from: widened.get(Number(g.row_num))!.from, to: 'world' } } : {}) })).proposal_ref);
} else {
const { id } = await insertTrustProposal(db, { action: 'forget', sourceId, target: { table: 'facts', id: Number(g.id) }, proposer: 'fence_projection',
before: { guard: 'fence_projection', fact: { id: Number(g.id), tier: storedTrustTier(g.trust_tier) }, writer_tier: (await writerTrust(db)).tier, slug } });
refs.push(`tp${id}`);
}
}
for (const [rowNum, { from, copy }] of widened) {
const restatement = copy ? await at(rowNum) : undefined;
if (!copy || !restatement) continue;
refs.push((await recordContestedFact(db, { sourceId, oldId: copy.id, oldTier: storedTrustTier(copy.trust_tier), newId: Number(restatement.id),
newTier: storedTrustTier(restatement.trust_tier), guard: 'fence_projection', visibility: { from, to: 'world' } })).proposal_ref);
}
for (const { row, decision } of gated) {
const stored = await at(row.row_num);
if (stored) await recordFlaggedRow(db, decision, { table: 'facts', id: Number(stored.id), sourceId });
}
return refs;
},
};
}
/** The page's live fence facts more trusted than the writer: the rows its field rewrite could lower. */
export async function factsAboveWriter(tx: BrainEngine, sourceId: string, slug: string): Promise<Array<{ id: number; tier: TrustTier }>> {
return (await tx.executeRaw<{ id: number; trust_tier: string }>(`SELECT id, trust_tier FROM facts WHERE source_id = $1 AND source_markdown_slug = $2
AND row_num IS NOT NULL AND expired_at IS NULL AND ${trustRankSql('trust_tier')} > ${WRITER_RANK}`, [sourceId, slug]))
.map(r => ({ id: Number(r.id), tier: storedTrustTier(r.trust_tier) }));
}
/** What a lower-tier write would have done to a held take or timeline row. */
export type HeldChange = 'removed' | 'replaced' | 'deactivated' | 'detail_changed';
export type HeldTable = 'takes' | 'timeline_entries';
export interface HeldRow { id: number; tier: TrustTier; change: HeldChange }
const OPEN_CONTEST = (table: HeldTable) => `EXISTS (SELECT 1 FROM trust_proposals tp WHERE tp.status = 'pending' AND tp.action = 'forget'
AND tp.target_table = '${table}' AND tp.target_id = x.id)`;
/**
* Of `ids`, the rows a write may not delete or overwrite, locked: rows more trusted than `writer` (the transaction's
* declared tier when omitted) and, with `pending`, rows an open contest already holds. A reconcile that restates the
* page text passes `pending`: the held row is absent from that text by design.
*/
export async function heldRows(tx: BrainEngine, table: HeldTable, ids: readonly number[], opts: { writer?: TrustTier; pending?: boolean } = {}): Promise<Map<number, TrustTier>> {
if (!ids.length) return new Map();
const writer = opts.writer ? trustRankSql('$2::text') : WRITER_RANK;
const rows = await tx.executeRaw<{ id: number; trust_tier: string }>(`SELECT x.id, x.trust_tier FROM ${table} x WHERE x.id = ANY($1::bigint[])
AND (${trustRankSql('x.trust_tier')} > ${writer}${opts.pending ? ` OR ${OPEN_CONTEST(table)}` : ''}) ORDER BY x.id FOR UPDATE`,
opts.writer ? [[...ids], opts.writer] : [[...ids]]);
return new Map(rows.map(r => [Number(r.id), storedTrustTier(r.trust_tier)]));
}
/**
* The page's takes a fence re-projection would delete (`gone` row numbers), replace (claim, kind or holder differ at the
* same row number) or deactivate, that are more trusted than the writer, locked before any of those statements run.
*/
export async function guardFenceTakes(tx: BrainEngine, pageId: number, incoming: ReadonlyArray<{ rowNum: number; claim: string; kind: string; holder: string; active: boolean }>,
gone: readonly number[], opts: { pending?: boolean } = {}): Promise<Array<HeldRow & { page_id: number; row_num: number }>> {
return guardTakeRows(tx, incoming.map(t => ({ page_id: pageId, row_num: t.rowNum, claim: t.claim, kind: t.kind, holder: t.holder, active: t.active })),
gone.map(rowNum => ({ page_id: pageId, row_num: rowNum })), opts);
}
/** guardFenceTakes over several pages' rows at once (a reconcile batch); `pending` also holds rows an open contest holds. */
export async function guardTakeRows(tx: BrainEngine, incoming: ReadonlyArray<{ page_id: number; row_num: number; claim: string; kind: string; holder: string; active: boolean }>,
gone: ReadonlyArray<{ page_id: number; row_num: number }>, opts: { pending?: boolean } = {}): Promise<Array<HeldRow & { page_id: number; row_num: number }>> {
if (!incoming.length && !gone.length) return [];
const rows = await tx.executeRaw<{ id: number; page_id: number; row_num: number; trust_tier: string; change: HeldChange }>(`SELECT x.id, x.page_id, x.row_num, x.trust_tier,
CASE WHEN n.row_num IS NULL THEN 'removed' WHEN (x.claim, x.kind, x.holder) IS DISTINCT FROM (n.claim, n.kind, n.holder) THEN 'replaced'
ELSE 'deactivated' END AS change
FROM takes x
LEFT JOIN jsonb_to_recordset($1::text::jsonb) AS n(page_id integer, row_num integer, claim text, kind text, holder text, active boolean)
ON n.page_id = x.page_id AND n.row_num = x.row_num
LEFT JOIN jsonb_to_recordset($2::text::jsonb) AS g(page_id integer, row_num integer) ON g.page_id = x.page_id AND g.row_num = x.row_num
WHERE x.page_id = ANY($3::integer[]) AND (${trustRankSql('x.trust_tier')} > ${WRITER_RANK}${opts.pending ? ` OR ${OPEN_CONTEST('takes')}` : ''})
AND (g.row_num IS NOT NULL OR (n.row_num IS NOT NULL
AND ((x.claim, x.kind, x.holder) IS DISTINCT FROM (n.claim, n.kind, n.holder) OR (x.active AND NOT n.active))))
ORDER BY x.page_id, x.row_num FOR UPDATE OF x`,
[JSON.stringify(incoming), JSON.stringify(gone), [...new Set([...incoming, ...gone].map(r => r.page_id))]]);
return rows.map(r => ({ id: Number(r.id), page_id: Number(r.page_id), row_num: Number(r.row_num), tier: storedTrustTier(r.trust_tier), change: r.change }));
}
/** Files the owner's `forget` proposal for each held row (an open one is reused); returns their tp refs. */
export async function contestHeldRows(tx: BrainEngine, input: { sourceId: string; slug: string; table: HeldTable; proposer: string; writer?: TrustTier; rows: readonly HeldRow[] }): Promise<string[]> {
if (!input.rows.length) return [];
const writer = input.writer ?? (await currentWriteTrust(tx))?.tier ?? 'unknown';
const refs: string[] = [];
for (const row of input.rows) {
const { id } = await insertTrustProposal(tx, { action: 'forget', sourceId: input.sourceId, target: { table: input.table, id: row.id }, proposer: input.proposer,
before: { guard: input.proposer, change: row.change, row: { id: row.id, tier: row.tier }, writer_tier: writer, slug: input.slug } });
refs.push(`tp${id}`);
}
return refs;
}