Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The finalization contract (docs/designs/BELIEF_LEDGER.md section 5.1).
*
* Every transaction that commits canonical state wraps its projections in
* `withBeliefBatch`: the batch reads the logical state of its streams under the
* page keys the transaction already holds, runs the projections, reads the
* state again, and `finalizeBeliefEvents` appends one event per logical key
* whose canonical value changed, last, before the terminal receipt. Guards
* that decide inside the projections (contest, hold) and identity code paths
* report through `noteBelief`, so their events exist whether or not any row
* changed. The batch is inert, and costs one source read, when the source has
* no active coverage (`gbrain beliefs enable`).
*/
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
import type { BrainEngine } from '../engine.ts';
import { assertHeldPageKeys } from '../page-state/guards.ts';
import { MANAGED_MODE_ROWS_JSON_SQL, managedModeFromRows } from '../persistence/managed-mode.ts';
import { COVERAGE_KEY, heldKey, lifetimeRef, pageKey, sha256Hex, canonicalJson, factKeySubject, slugRef } from './keys.ts';
import { readBeliefState, readFactsById, type RawPage, type RawState } from './state.ts';
import { keyedSubjects, keyFact, pageNeeds, type KeyContext, type Subject } from './subjects.ts';
import { endLifetime, mintLifetime, readOpenLifetimes, renameLifetime, resolveLifetimes } from './lifetimes.ts';
import { appendBeliefEvents, redactionReleasedDraft, type BeliefEventDraft, type BeliefOrigin, type RedactionRelease } from './append.ts';
import { missingPreimages, preimageInvariantEnforced } from './preimages.ts';
export type BeliefNote =
| { kind: 'contested'; table: string; rowId: number; proposalId: number; guard: string }
| { kind: 'held'; holdKind: string; fingerprint: string; holdId: number; slug: string; tier: string; valueHash: string }
| { kind: 'withdrawn'; factIds: number[] }
| { kind: 'superseded'; oldId: number; newId: number | null }
| { kind: 'purged'; table: 'facts' | 'takes' | 'pages'; ids: number[]; request: string; derivedWalk?: 'truncated' }
| { kind: 'transferred'; fromSlug: string; table: 'facts' | 'takes' | 'links'; ids: number[] }
/** A tier change another writer caused (derived propagation): the batch's own `trust.retiered` for the row carries this cause. */
| { kind: 'retier_cause'; table: 'facts' | 'takes' | 'pages'; rowId: number; cause: Record<string, unknown> }
/** The owner confirm released redactions on the row's key (`releaseSuppressedFields`): the batch appends its `redaction.released`. */
| { kind: 'released'; table: 'facts' | 'takes'; rowId: number; releases: RedactionRelease[] };
export interface BeliefBatchOptions {
sourceId: string;
/** Stream slugs; every one must be a page key the transaction holds. */
slugs: readonly string[];
/** persistence_requests.id for journaled writes; a fresh UUID per transaction otherwise. */
publicationId?: string | null;
op: string;
/** Overrides the managed/unmanaged origin (an unmanaged projection point passes 'unmanaged'). */
origin?: BeliefOrigin;
/** A revision change is `page.published` unless the writer names it (revert). */
pageEventType?: 'page.reverted' | 'page.view_changed' | 'page.merged';
/** The event for a page row that is gone after the transaction: purge or retention, else `page.deleted`. */
hardDeleteEvent?: 'page.purged' | 'page.expired';
/** Request authority: an owner release of a redaction needs a trusted local (remote = false) write. */
remote?: boolean;
/** An explicit owner edit of the batch's fields: the only write that can release a purge redaction (append.ts). */
ownerEdit?: boolean;
cause?: Record<string, unknown>;
/** Filled by the batch: how many events it appended, so the caller marks the commit only when there is one. */
report?: { appended: number };
}
interface Batch {
opts: BeliefBatchOptions; publicationId: string; incarnation: string; managed: boolean; purgesPossible: boolean;
pre: RawState; notes: BeliefNote[];
}
const store = new AsyncLocalStorage<Batch>();
/** A guard or identity path reports a decision to the enclosing batch; a no-op outside one. */
export function noteBelief(note: BeliefNote): void {
store.getStore()?.notes.push(note);
}
/** The enclosing batch's publication, source and stream slugs, or null outside a batch. */
export function currentBeliefBatch(): { publicationId: string; sourceId: string; slugs: readonly string[] } | null {
const batch = store.getStore();
return batch ? { publicationId: batch.publicationId, sourceId: batch.opts.sourceId, slugs: batch.opts.slugs } : null;
}
/** True when an enclosing batch on this async context already records these slugs (a nested writer must not append them twice). */
export function beliefBatchCovers(sourceId: string, slugs: readonly string[]): boolean {
const outer = store.getStore();
return !!outer && outer.opts.sourceId === sourceId && slugs.every(slug => outer.opts.slugs.includes(slug));
}
/** True inside any belief batch: a nested writer's own publication commits with the enclosing transaction, not before it. */
export const insideBeliefBatch = (): boolean => !!store.getStore();
/**
* Coverage and purge probes for one source, in one read. `coverage` is the newest coverage event other than `coverage.restored`.
* `batch` (a batch beginning) also reads the managed mode and, when coverage is active, switches the transaction to
* generic plans for the state read that follows, returning the mode to restore (`readBeliefState`'s `planModePrev`).
*/
export async function readLedgerSource(tx: Pick<BrainEngine, 'executeRaw'>, sourceId: string, opts: { batch?: boolean } = {}): Promise<{ incarnation: string; purgeEpoch: number;
coverage: string | null; purgesPossible: boolean; managedRows?: Array<{ enabled: unknown }>; planModePrev?: string } | null> {
const [row] = await tx.executeRaw<Record<string, unknown>>(`${opts.batch ? `SELECT q.*, ${MANAGED_MODE_ROWS_JSON_SQL} AS managed_rows, current_setting('plan_cache_mode') AS plan_mode_prev,
set_config('plan_cache_mode', CASE WHEN q.coverage IS NOT NULL AND q.coverage <> 'coverage.stopped' THEN 'force_generic_plan'
ELSE current_setting('plan_cache_mode') END, true) FROM (` : ''}SELECT s.incarnation::text AS incarnation, s.purge_epoch,
(SELECT e.event_type FROM belief_events e WHERE e.source_id = s.id AND e.subject_kind = 'coverage' AND e.subject_key = $2
AND e.source_incarnation = s.incarnation AND e.event_type <> 'coverage.restored' ORDER BY e.id DESC LIMIT 1) AS coverage,
(s.purge_epoch > 0 OR EXISTS (SELECT 1 FROM fact_purges WHERE source_id = s.id) OR EXISTS (SELECT 1 FROM take_purges WHERE source_id = s.id)
OR EXISTS (SELECT 1 FROM page_purges WHERE source_id = s.id)) AS purges
FROM sources s WHERE s.id = $1${opts.batch ? ') q' : ''}`, [sourceId, COVERAGE_KEY]);
if (!row) return null;
return { incarnation: String(row.incarnation), purgeEpoch: Number(row.purge_epoch), coverage: (row.coverage as string | null) ?? null,
purgesPossible: row.purges === true,
...(opts.batch ? { managedRows: row.managed_rows as Array<{ enabled: unknown }>, planModePrev: String(row.plan_mode_prev) } : {}) };
}
export const coverageActive = (coverage: string | null) => coverage != null && coverage !== 'coverage.stopped';
async function beginBeliefBatch(tx: BrainEngine, opts: BeliefBatchOptions): Promise<Batch | null> {
const source = await readLedgerSource(tx, opts.sourceId, { batch: true });
if (!source || !coverageActive(source.coverage)) return null;
try {
assertHeldPageKeys(tx, opts.slugs.map(slug => ({ sourceId: opts.sourceId, slug })));
} catch (error) {
await tx.executeRaw(`SELECT set_config('plan_cache_mode', $1, true)`, [source.planModePrev]);
throw error;
}
const pre = await readBeliefState(tx, opts.sourceId, opts.slugs, [], undefined, source.planModePrev);
return { opts, publicationId: opts.publicationId ?? randomUUID(), incarnation: source.incarnation, managed: managedModeFromRows(source.managedRows!).enabled,
purgesPossible: source.purgesPossible, pre, notes: [] };
}
/** Runs `fn` (the transaction's projections) inside a belief batch and appends its events after it. */
export async function withBeliefBatch<T>(tx: BrainEngine, opts: BeliefBatchOptions, fn: () => Promise<T>): Promise<T> {
const batch = await beginBeliefBatch(tx, opts);
if (!batch) return fn();
const result = await store.run(batch, fn);
const appended = await finalizeBeliefEvents(tx, batch);
if (opts.report) opts.report.appended += appended;
return result;
}
interface Stream { slug: string; pre: RawPage | null; post: RawPage | null }
/** Stream pages matched by id across the transaction: renames, recreates and hard deletes. */
function matchStreams(slugs: readonly string[], pre: RawState, post: RawState): Stream[] {
const preById = new Map(pre.pages.map(p => [p.id, p]));
const postIds = new Set(post.pages.map(p => p.id));
const streams: Stream[] = [];
const used = new Set<number>();
for (const page of post.pages) {
const same = preById.get(page.id);
const other = same ? null : pre.pages.find(p => p.slug === page.slug && !postIds.has(p.id)) ?? null;
if (same) used.add(same.id);
if (other) { used.add(other.id); streams.push({ slug: page.slug, pre: other, post: null }); }
streams.push({ slug: page.slug, pre: same ?? null, post: page });
}
for (const page of pre.pages) if (!used.has(page.id)) streams.push({ slug: page.slug, pre: page, post: null });
for (const slug of slugs) if (!streams.some(s => s.slug === slug || s.pre?.slug === slug)) streams.push({ slug, pre: null, post: null });
return streams;
}
/** Ends, renames and mints the stream pages' lifetimes; returns page id -> lifetime for both sides. */
async function streamLifetimes(tx: BrainEngine, sourceId: string, incarnation: string, streams: Stream[]): Promise<Map<number, string>> {
const out = new Map<number, string>();
const pairs = streams.flatMap(s => [s.pre, s.post]).filter((p): p is RawPage => !!p).map(p => ({ incarnation, slug: p.slug }));
const open = await readOpenLifetimes(tx, pairs);
const fits = (row: { page_id: number | null } | null, id: number) => !!row && (row.page_id == null || row.page_id === id);
const mint = (page: RawPage) => mintLifetime(tx, { sourceId, incarnation, slug: page.slug, pageId: page.id });
// Renamed pages keep their lifetimes. Each moving lifetime is parked first, so renames that swap or chain slugs in one
// transaction neither end one another's lifetimes nor collide on the open-slug index; the slugs they leave read as free.
const moving = new Map<number, string>();
for (const { pre, post } of streams) {
const row = pre && post && pre.slug !== post.slug ? open.get(`${incarnation}\u0000${pre.slug}`) ?? null : null;
if (row && fits(row, post!.id)) moving.set(post!.id, row.page_lifetime);
}
const movingLifetimes = new Set(moving.values());
const openAt = (slug: string) => { const row = open.get(`${incarnation}\u0000${slug}`) ?? null; return row && movingLifetimes.has(row.page_lifetime) ? null : row; };
for (const [pageId, lifetime] of moving) await renameLifetime(tx, lifetime, `~moving-${lifetime}`, pageId);
for (const { pre, post } of streams) {
if (!pre || post) continue;
const row = openAt(pre.slug);
const lifetime = fits(row, pre.id) ? row!.page_lifetime : await mint(pre);
out.set(pre.id, lifetime);
await endLifetime(tx, lifetime);
}
const renames: Array<[string, RawPage]> = [];
for (const { pre, post } of streams) {
if (!post) continue;
if (pre && pre.slug !== post.slug) {
const target = openAt(post.slug);
if (target) await endLifetime(tx, target.page_lifetime);
const lifetime = moving.get(post.id);
if (lifetime) { renames.push([lifetime, post]); out.set(post.id, lifetime); }
else out.set(post.id, await mint(post));
continue;
}
const row = openAt(post.slug);
if (row && row.page_id === post.id) { out.set(post.id, row.page_lifetime); continue; }
if (pre && row && row.page_id == null) { out.set(post.id, row.page_lifetime); continue; }
if (row) await endLifetime(tx, row.page_lifetime);
out.set(post.id, await mint(post));
}
for (const [lifetime, post] of renames) await renameLifetime(tx, lifetime, post.slug, post.id);
return out;
}
const tierOrUnknown = (tier: string | null | undefined) => tier || 'unknown';
function stateHashOf(page: RawPage | null, lifetime: string | null, subjects: Subject[]): string {
const live = page && !page.deleted;
return sha256Hex(canonicalJson({
page: page ? { lifetime, deleted: page.deleted, revision: page.revision, visible: page.visible, tier: page.tier } : null,
subjects: subjects.filter(s => live || s.dbOnly).map(s => { const row = [s.kind, s.key, s.vhash, s.tier]; return { row, order: row.join('\u0000') }; })
.sort((a, b) => (a.order < b.order ? -1 : a.order > b.order ? 1 : 0)).map(s => s.row),
}));
}
function changeType(kind: Subject['kind'], before: Subject, after: Subject): string | null {
if (before.vhash === after.vhash) return null;
if (kind === 'take') {
const resolution = ['resolved_at', 'resolved_outcome', 'resolved_value', 'resolved_unit', 'resolved_source', 'resolved_by', 'resolved_quality']
.some(f => canonicalJson(before.value[f]) !== canonicalJson(after.value[f]));
const resolvedAfter = after.value.resolved_at != null || after.value.resolved_quality != null;
if (resolution) return resolvedAfter ? 'take.resolved' : 'take.unresolved';
return 'take.revised';
}
if (kind === 'link_transition') return 'link.transition_revised';
return `${kind}.revised`;
}
const assertType = (kind: Subject['kind']) => kind === 'link_transition' ? 'link.transition_added' : `${kind}.asserted`;
const retractType = (kind: Subject['kind']) => kind === 'link_transition' ? 'link.transition_removed' : `${kind}.retracted`;
interface DiffContext {
opts: BeliefBatchOptions; batch: Batch; writerTier: string; lifetimeAt: (slug: string) => string | null; streamHash: (slug: string) => string;
cause: (extra?: Record<string, unknown>) => Record<string, unknown>; postSubjects: Subject[];
/** `kind:rowId` of each row a transfer note moved -> the subject it left and the lifetime of the page it left. */
transfers: Map<string, { from: Subject; fromLifetime: string | null }>;
}
const TRANSFER_KIND: Record<string, Subject['kind']> = { facts: 'fact', takes: 'take', links: 'link' };
/** The pre-transaction subject of each row a `transferred` note moved, keyed `kind:rowId`. */
function transferSources(notes: BeliefNote[], preSubjects: Subject[], lifetimeOfPreSlug: (slug: string) => string | null): DiffContext['transfers'] {
const out: DiffContext['transfers'] = new Map();
for (const note of notes) {
if (note.kind !== 'transferred') continue;
const kind = TRANSFER_KIND[note.table]!;
for (const id of note.ids) {
const from = preSubjects.find(s => s.kind === kind && s.stream === note.fromSlug && s.rowIds.includes(id));
if (from) out.set(`${kind}:${id}`, { from, fromLifetime: lifetimeOfPreSlug(note.fromSlug) });
}
}
return out;
}
/**
* Subject events for one stream between two keyed sides, outside a batch's
* own diff: the fallback rename re-describes the lifetime it moves onto
* another row. `transfers` maps `kind:rowId` to the subject the row left.
*/
export function streamSubjectDrafts(input: { sourceId: string; incarnation: string; slug: string; lifetime: string | null; op: string; writerTier: string | null;
stateHash: string; before: Subject[]; after: Subject[]; transfers: Map<string, { from: Subject; fromLifetime: string | null }> }): BeliefEventDraft[] {
const opts: BeliefBatchOptions = { sourceId: input.sourceId, slugs: [input.slug], op: input.op };
const batch: Batch = { opts, publicationId: '', incarnation: input.incarnation, managed: false, purgesPossible: false, notes: [],
pre: { pages: [], facts: [], takes: [], links: [], transitions: [], writerTier: null } };
return subjectDrafts({ opts, batch, writerTier: tierOrUnknown(input.writerTier), lifetimeAt: () => input.lifetime, streamHash: () => input.stateHash,
cause: (extra = {}) => ({ op: input.op, ...extra }), postSubjects: input.after, transfers: input.transfers }, input.slug, input.before, input.after);
}
const RETIER_TABLE: Record<string, string> = { fact: 'facts', take: 'takes', page: 'pages' };
/** The cause fields (minus `op`) another writer attached to this row's tier change, e.g. the inputs of a derived propagation. */
function retierCauseOf(notes: BeliefNote[], s: { kind: string; rowIds: number[] }): Record<string, unknown> {
const note = notes.find(n => n.kind === 'retier_cause' && n.table === RETIER_TABLE[s.kind] && s.rowIds.includes(n.rowId));
if (note?.kind !== 'retier_cause') return {};
const { op: _op, ...rest } = note.cause;
return rest;
}
/** Subject events of one stream side: asserted/retracted/revised, adoption, replacement links, retiering. */
function subjectDrafts(d: DiffContext, slug: string, before: Subject[], after: Subject[]): BeliefEventDraft[] {
const { batch, writerTier } = d;
const withdrawn = new Set(batch.notes.flatMap(n => n.kind === 'withdrawn' ? n.factIds : []));
const superseded = new Map(batch.notes.flatMap(n => n.kind === 'superseded' ? [[n.oldId, n.newId] as const] : []));
const purged = new Map(batch.notes.flatMap(n => n.kind === 'purged' ? n.ids.map(id => [`${n.table}:${id}`, n.request] as const) : []));
const out: BeliefEventDraft[] = [];
const preMap = new Map(before.map(s => [`${s.kind}\u0000${s.key}`, s]));
const postMap = new Map(after.map(s => [`${s.kind}\u0000${s.key}`, s]));
const draft = (s: Subject, eventType: string, value: Record<string, unknown> | null, prior: Subject | null, extra: Record<string, unknown> = {}) => {
const link = s.kind === 'link' || s.kind === 'link_transition';
out.push({ sourceId: d.opts.sourceId, incarnation: batch.incarnation, lifetime: d.lifetimeAt(slug), slug, stream: slug,
subjectKind: s.kind, subjectKey: s.key, eventType, trustTier: link ? writerTier : s.tier, writerTier: link ? null : writerTier,
tierBasis: link ? 'writer' : 'row', visibility: s.visibility, value, priorHash: prior?.vhash ?? null, stateHash: d.streamHash(slug),
claimFp: s.claimFp, validFrom: s.validFrom, validUntil: s.validUntil,
cause: d.cause({ ...(s.rowNum != null ? { row: s.rowNum } : {}), label: s.label, ...extra }) });
};
const transferOf = (s: Subject) => s.rowIds.map(id => d.transfers.get(`${s.kind}:${id}`)).find(t => t && t.from.key !== s.key);
const removed = [...preMap].filter(([id]) => !postMap.has(id)).map(([, s]) => s)
.filter(s => !s.rowIds.length || !s.rowIds.every(id => d.transfers.has(`${s.kind}:${id}`)));
const fresh = [...postMap].filter(([id]) => !preMap.has(id)).map(([, s]) => s);
const transferred = new Set<Subject>();
for (const s of after) {
const t = transferOf(s);
if (!t) continue;
transferred.add(s);
draft(s, `${s.kind}.transferred`, s.value, t.from, { from_key: t.from.key, ...(t.fromLifetime ? { from_lifetime: t.fromLifetime } : {}) });
}
const adoptedFrom = new Map<Subject, Subject>();
for (const s of fresh) {
const parts = s.kind === 'fact' ? factKeySubject(s.key) : null;
if (!parts || parts.subject.startsWith('S:')) continue;
const source = removed.find(r => r.kind === 'fact' && factKeySubject(r.key)?.subject === slugRef(batch.incarnation, slug) && factKeySubject(r.key)?.rest === parts.rest);
if (source) adoptedFrom.set(s, source);
}
const adoptedSources = new Set(adoptedFrom.values());
const replacedBy = new Map<Subject, Subject>();
for (const r of removed) {
if ((r.kind !== 'fact' && r.kind !== 'take') || r.rowNum == null || adoptedSources.has(r)) continue;
const successor = fresh.find(s => s.kind === r.kind && s.rowNum === r.rowNum && !adoptedFrom.has(s));
if (successor) replacedBy.set(r, successor);
}
for (const r of removed) {
if (adoptedSources.has(r)) continue;
const purgeRequest = r.rowIds.map(id => purged.get(`${r.kind === 'take' ? 'takes' : 'facts'}:${id}`)).find(Boolean);
const supersededBy = r.kind === 'fact' ? r.rowIds.map(id => superseded.get(id)).find(v => v !== undefined) : undefined;
const type = purgeRequest ? `${r.kind}.purged` : r.kind === 'fact' && r.rowIds.some(id => withdrawn.has(id)) ? 'fact.withdrawn'
: supersededBy !== undefined ? 'fact.superseded' : retractType(r.kind);
const successorKey = supersededBy != null ? d.postSubjects.find(s => s.kind === 'fact' && s.rowIds.includes(supersededBy))?.key : replacedBy.get(r)?.key;
draft(r, type, null, r, { ...(successorKey ? { replaced_by: successorKey } : {}), ...(purgeRequest ? { purge_request: purgeRequest } : {}) });
}
for (const s of fresh) {
if (transferred.has(s)) continue;
const from = adoptedFrom.get(s);
if (from) { draft(s, 'fact.adopted', s.value, from, { from_key: from.key }); continue; }
const replaced = [...replacedBy].find(([, v]) => v === s)?.[0];
draft(s, assertType(s.kind), s.value, null, replaced ? { replaces: replaced.key } : {});
}
for (const [id, s] of postMap) {
const prior = preMap.get(id);
if (!prior || transferred.has(s)) continue;
const type = changeType(s.kind, prior, s);
if (type) draft(s, type, s.value, prior);
if (prior.tier !== s.tier && s.kind !== 'link' && s.kind !== 'link_transition') draft(s, 'trust.retiered', { from: prior.tier, to: s.tier }, prior, retierCauseOf(batch.notes, s));
}
return out;
}
/** The page event of one page stream; `true` when the page's own subjects end or begin with it (no per-subject events). */
function pageDrafts(d: DiffContext, stream: Stream, lifetime: string, after: Subject[], push: (draft: BeliefEventDraft) => void): boolean {
const { pre: p0, post: p1 } = stream;
const page = p1 ?? p0!;
const base = { sourceId: d.opts.sourceId, incarnation: d.batch.incarnation, lifetime, slug: page.slug, stream: page.slug, subjectKind: 'page' as const,
subjectKey: pageKey(lifetime), writerTier: d.writerTier, visibility: page.visible ? 'world' : 'private', stateHash: d.streamHash(page.slug), cause: d.cause() };
const emit = (eventType: string, value: Record<string, unknown>, tier: string) => push({ ...base, eventType, trustTier: tier, value });
if (p0 && !p1) {
const purge = d.batch.notes.find(n => n.kind === 'purged' && n.table === 'pages' && n.ids.includes(p0.id));
const type = purge ? 'page.purged' : d.opts.hardDeleteEvent ?? 'page.deleted';
push({ ...base, eventType: type, trustTier: p0.tier, value: type === 'page.purged' ? null : { revision_before: p0.revision, hard: true },
purged: type === 'page.purged', cause: purge?.kind === 'purged' ? d.cause({ purge_request: purge.request, ...(purge.derivedWalk ? { derived_walk: purge.derivedWalk } : {}) }) : base.cause });
return true;
}
if (!p0 && p1) {
const counts = { facts: after.filter(s => s.kind === 'fact').length, takes: after.filter(s => s.kind === 'take').length,
links: after.filter(s => s.kind === 'link').length, link_transitions: after.filter(s => s.kind === 'link_transition').length };
emit('page.published', { revision_before: null, revision_after: p1.revision, snapshot: !p1.large, counts, ...(p1.deleted ? { deleted: true } : {}) }, p1.tier);
return !p1.large;
}
let silenced = false;
if (p0!.slug !== p1!.slug) emit('page.renamed', { old_slug: p0!.slug, new_slug: p1!.slug }, p1!.tier);
if (!p0!.deleted && p1!.deleted) { emit('page.deleted', { revision_before: p0!.revision, revision_after: p1!.revision }, p0!.tier); silenced = true; }
else if (p0!.deleted && !p1!.deleted) { emit('page.restored', { revision_before: p0!.revision, revision_after: p1!.revision }, p1!.tier); silenced = true; }
else if (p0!.revision !== p1!.revision) emit(d.opts.pageEventType ?? 'page.published', { revision_before: p0!.revision, revision_after: p1!.revision }, p1!.tier);
else if (p0!.visible !== p1!.visible) emit('page.visibility_changed', { visible: p1!.visible }, p1!.tier);
else if (d.opts.pageEventType === 'page.view_changed' && p0!.content_hash !== p1!.content_hash) {
emit('page.view_changed', { revision_before: p0!.revision, revision_after: p1!.revision, materialized: true }, p1!.tier);
}
if (p0!.tier !== p1!.tier) push({ ...base, eventType: 'trust.retiered', trustTier: p1!.tier, value: { from: p0!.tier, to: p1!.tier },
cause: d.cause(retierCauseOf(d.batch.notes, { kind: 'page', rowIds: [p1!.id] })) });
return silenced || (p0!.deleted && p1!.deleted);
}
/** Appends the batch's events, last in its transaction. */
export async function finalizeBeliefEvents(tx: BrainEngine, batch: Batch): Promise<number> {
const { opts, pre } = batch;
const post = await readBeliefState(tx, opts.sourceId, opts.slugs, pre.pages.map(p => p.id), pre);
const streams = matchStreams(opts.slugs, pre, post);
const added = streams.filter(s => s.post && !opts.slugs.includes(s.post.slug)).map(s => ({ sourceId: opts.sourceId, slug: s.post!.slug }));
if (added.length) assertHeldPageKeys(tx, added);
const writerTier = tierOrUnknown(post.writerTier ?? pre.writerTier);
const lifetimes = await streamLifetimes(tx, opts.sourceId, batch.incarnation, streams);
const contestedFactIds = batch.notes.flatMap(n => n.kind === 'contested' && n.table === 'facts' ? [n.rowId] : []);
const extraFacts = await readFactsById(tx, contestedFactIds.filter(id => !post.facts.some(f => f.id === id) && !pre.facts.some(f => f.id === id)));
const needs = [...pageNeeds(opts.sourceId, batch.incarnation, pre), ...pageNeeds(opts.sourceId, batch.incarnation, post),
...extraFacts.flatMap(f => f.entity_page_id != null && f.entity_slug ? [{ sourceId: opts.sourceId, incarnation: batch.incarnation, slug: f.entity_slug, pageId: f.entity_page_id }] : [])]
.filter(n => !lifetimes.has(n.pageId));
for (const [id, lifetime] of await resolveLifetimes(tx, needs)) lifetimes.set(id, lifetime);
const visibilityIn = (state: RawState) => (pageId: number) => state.pages.find(p => p.id === pageId)?.visible === false ? 'private' : 'world';
const ctx = (side: 'pre' | 'post'): KeyContext => ({ incarnation: batch.incarnation, lifetimes,
pagesBySlug: new Map(streams.flatMap(s => { const p = side === 'pre' ? s.pre : s.post; return p ? [[p.slug, p] as const] : []; })) });
const preSubjects = keyedSubjects(ctx('pre'), pre, visibilityIn(pre));
const postSubjects = keyedSubjects(ctx('post'), post, visibilityIn(post), { state: pre, subjects: preSubjects });
const postPageAt = (slug: string) => streams.find(s => s.post?.slug === slug)?.post ?? null;
const lifetimeAt = (slug: string) => { const page = postPageAt(slug); return page ? lifetimes.get(page.id) ?? null : null; };
const subjectsByStream = new Map<string, Subject[]>();
for (const subject of postSubjects) {
const list = subjectsByStream.get(subject.stream);
if (list) list.push(subject); else subjectsByStream.set(subject.stream, [subject]);
}
const hashes = new Map<string, string>();
const streamHash = (slug: string) => {
let hash = hashes.get(slug);
if (hash === undefined) {
const page = postPageAt(slug);
hash = stateHashOf(page, page ? lifetimes.get(page.id)! : null, subjectsByStream.get(slug) ?? []);
hashes.set(slug, hash);
}
return hash;
};
const preLifetimeAt = (slug: string) => { const page = streams.find(s => s.pre?.slug === slug)?.pre; return page ? lifetimes.get(page.id) ?? null : null; };
const d: DiffContext = { opts, batch, writerTier, lifetimeAt, streamHash, postSubjects, transfers: transferSources(batch.notes, preSubjects, preLifetimeAt),
cause: (extra = {}) => ({ op: opts.op, ...(opts.publicationId ? { request: opts.publicationId } : {}), ...opts.cause, ...extra }) };
const drafts: BeliefEventDraft[] = [];
for (const stream of streams) {
const page = stream.post ?? stream.pre;
if (!page) continue;
const before = stream.pre ? preSubjects.filter(s => !s.dbOnly && s.stream === stream.pre!.slug) : [];
const after = stream.post ? postSubjects.filter(s => !s.dbOnly && s.stream === stream.post!.slug) : [];
const silenced = pageDrafts(d, stream, lifetimes.get(page.id)!, after, draft => drafts.push(draft));
if (!silenced) drafts.push(...subjectDrafts(d, page.slug, before, after));
}
// A renamed page's database-only facts follow it: their pre side is diffed under the slug the page moved to, so a rename moves no key.
const renamedTo = new Map(streams.flatMap(s => s.pre && s.post && s.pre.slug !== s.post.slug ? [[s.pre.slug, s.post.slug] as const] : []));
const dbPre = preSubjects.filter(s => s.dbOnly), dbPost = postSubjects.filter(s => s.dbOnly);
const dbStream = (s: Subject) => renamedTo.get(s.stream) ?? s.stream;
for (const slug of new Set([...dbPre.map(dbStream), ...dbPost.map(s => s.stream)])) {
drafts.push(...subjectDrafts(d, slug, dbPre.filter(s => dbStream(s) === slug), dbPost.filter(s => s.stream === slug)));
}
// A contested fact outside the batch's streams is keyed and hashed as its own stream holds it now (its page's lifetime when the page exists).
const extraStreams = new Map<string, Awaited<ReturnType<typeof currentStateHash>>>();
for (const f of extraFacts) {
const stream = f.sms ?? f.entity_slug;
if (stream && !extraStreams.has(stream)) extraStreams.set(stream, await currentStateHash(tx, opts.sourceId, batch.incarnation, stream));
}
for (const note of batch.notes) {
if (note.kind === 'contested') drafts.push(...contestedDraft(d, note, { pre, post, preSubjects, postSubjects, extraFacts, extraStreams, lifetimes }));
else if (note.kind === 'held') {
const page = postPageAt(note.slug);
const lifetime = lifetimeAt(note.slug);
drafts.push({ sourceId: opts.sourceId, incarnation: batch.incarnation, lifetime, slug: note.slug, stream: note.slug,
subjectKind: note.holdKind === 'take' ? 'take' : 'fact', subjectKey: heldKey(lifetime ? lifetimeRef(lifetime) : slugRef(batch.incarnation, note.slug), note.holdKind, note.fingerprint), eventType: 'trust.held',
trustTier: note.tier, tierBasis: 'writer', visibility: page && !page.visible ? 'private' : 'world', value: { value_hash: note.valueHash },
stateHash: streamHash(note.slug), cause: d.cause({ hold: `wh${note.holdId}` }) });
} else if (note.kind === 'released') {
const s = postSubjects.find(x => x.kind === (note.table === 'facts' ? 'fact' : 'take') && x.rowIds.includes(note.rowId));
if (s) drafts.push(redactionReleasedDraft({ sourceId: opts.sourceId, incarnation: batch.incarnation, lifetime: lifetimeAt(s.stream), slug: s.stream, stream: s.stream,
subjectKind: s.kind as BeliefEventDraft['subjectKind'], subjectKey: s.key, trustTier: s.tier, visibility: s.visibility, stateHash: streamHash(s.stream) }, note.releases, batch.publicationId));
}
}
if (preimageInvariantEnforced()) {
const needs = streams.flatMap(s => s.pre && s.post && s.pre.id === s.post.id && s.pre.revision !== s.post.revision && !s.pre.large && !s.post.large
? [{ pageId: s.post.id, slug: s.pre.slug, revision: s.pre.revision }] : []);
const missing = await missingPreimages(tx, needs);
if (missing.length) {
throw new Error(`belief preimage invariant: ${missing.map(m => `${m.slug} moved off revision ${m.revision} with no page_versions row for it`).join('; ')} (op ${opts.op}; BELIEF_LEDGER.md section 14 item 8)`);
}
}
return appendBeliefEvents(tx, drafts, { publicationId: batch.publicationId, origin: opts.origin ?? (batch.managed ? 'live' : 'unmanaged'),
writerTier, remote: opts.remote, ownerEdit: opts.ownerEdit, purgesPossible: batch.purgesPossible || batch.notes.some(n => n.kind === 'purged') });
}
/** `trust.contested` on the held row's key: its tier as trust_tier, the challenger's as writer_tier (section 6.1). */
function contestedDraft(d: DiffContext, note: Extract<BeliefNote, { kind: 'contested' }>, s: { pre: RawState; post: RawState; preSubjects: Subject[];
postSubjects: Subject[]; extraFacts: Awaited<ReturnType<typeof readFactsById>>; extraStreams: Map<string, Awaited<ReturnType<typeof currentStateHash>>>;
lifetimes: Map<number, string> }): BeliefEventDraft[] {
const cause = d.cause({ proposal: `tp${note.proposalId}`, guard: note.guard });
const base = { sourceId: d.opts.sourceId, incarnation: d.batch.incarnation, eventType: 'trust.contested', writerTier: d.writerTier, value: null };
if (note.table === 'pages') {
const page = s.post.pages.find(p => p.id === note.rowId) ?? s.pre.pages.find(p => p.id === note.rowId);
if (!page) return [];
return [{ ...base, lifetime: s.lifetimes.get(page.id)!, slug: page.slug, stream: page.slug, subjectKind: 'page', subjectKey: pageKey(s.lifetimes.get(page.id)!),
trustTier: page.tier, visibility: page.visible ? 'world' : 'private', stateHash: d.streamHash(page.slug), cause }];
}
if (note.table !== 'facts' && note.table !== 'takes') return [];
const kind = note.table === 'facts' ? 'fact' : 'take';
const subject = [...s.postSubjects, ...s.preSubjects].find(x => x.kind === kind && x.rowIds.includes(note.rowId));
if (subject) return [{ ...base, lifetime: d.lifetimeAt(subject.stream), slug: subject.stream, stream: subject.stream, subjectKind: kind, subjectKey: subject.key,
trustTier: subject.tier, visibility: subject.visibility, claimFp: subject.claimFp, stateHash: d.streamHash(subject.stream), cause }];
const fact = kind === 'fact' ? s.extraFacts.find(f => f.id === note.rowId) : undefined;
if (!fact) return [];
const stream = fact.sms ?? fact.entity_slug ?? '';
const own = s.extraStreams.get(stream);
const page = own?.state.pages.find(p => p.slug === stream) ?? null;
const lifetimes = new Map([...s.lifetimes, ...own?.lifetimes ?? []]);
const key = keyFact({ incarnation: d.batch.incarnation, lifetimes, pagesBySlug: new Map(page ? [[stream, page]] : []) }, fact).key;
return [{ ...base, lifetime: page ? lifetimes.get(page.id) ?? null : null, slug: stream, stream, subjectKind: 'fact', subjectKey: key, trustTier: fact.tier,
visibility: fact.visibility, claimFp: fact.fp, stateHash: own?.hash ?? d.streamHash(stream), cause }];
}
/** The current belief-set hash of one stream, for the doctor drift check and reconcile. */
export async function currentStateHash(tx: BrainEngine, sourceId: string, incarnation: string, slug: string,
opts: { readOnly?: boolean } = {}): Promise<{ hash: string; state: RawState; lifetimes: Map<number, string> }> {
const state = await readBeliefState(tx, sourceId, [slug]);
const lifetimes = opts.readOnly ? await peekLifetimes(tx, pageNeeds(sourceId, incarnation, state)) : await resolveLifetimes(tx, pageNeeds(sourceId, incarnation, state));
const page = state.pages.find(p => p.slug === slug) ?? null;
const ctx: KeyContext = { incarnation, lifetimes, pagesBySlug: new Map(page ? [[slug, page]] : []) };
const subjects = keyedSubjects(ctx, state, id => state.pages.find(p => p.id === id)?.visible === false ? 'private' : 'world').filter(s => s.stream === slug);
return { hash: stateHashOf(page, page ? lifetimes.get(page.id)! : null, subjects), state, lifetimes };
}
/** resolveLifetimes without writes (a read-only drift scan): a page with no fitting open lifetime gets a placeholder, so its hash cannot match a recorded one. */
async function peekLifetimes(tx: BrainEngine, needs: ReturnType<typeof pageNeeds>): Promise<Map<number, string>> {
const open = await readOpenLifetimes(tx, needs);
return new Map(needs.map(n => {
const row = open.get(`${n.incarnation}\u0000${n.slug}`);
return [n.pageId, row && (row.page_id == null || row.page_id === n.pageId) ? row.page_lifetime : `unminted:${n.pageId}`];
}));
}
export { stateHashOf };
/**
* The journaled operations that are a direct edit of a page's facts or takes (design 6.5: a trusted local write that
* sets the field). Only these, from a local caller and with no internal intent `kind` (the `put_page` rows of
* import, file repair, quarantine clear, reconcile and managed maintenance carry one), can release a purge
* redaction; sync (`submit_job`), gate release, held accept, backfill, revert, restore and retention never do.
* append.ts still requires the writer tier at or above OWNER_TIER_FLOOR, and the trust channel records these verbs
* as agent_written even from the local CLI, so today `trust confirm` is the release that reaches it.
*
* append_page stays out (#7123). The redaction release is this list's only consumer (`ownerEdit` reaches nothing else;
* the ledger attributes every publication by its `op`, so an append's events say `append_page` either way). An append
* cannot set a fact or take field (its text refuses fence markers), so as an owner edit it could only release a
* redaction on a field its publication re-derives from text the owner did not edit. Its intent's `kind` keeps it out
* a second time. Pinned by test/belief-ledger-append-owner.test.ts.
*/
const OWNER_EDIT_OPERATIONS: ReadonlySet<string> = new Set(['put_page', 'edit_page', 'takes_update', 'takes_resolve']);
let allowlistDropped = false;
/** Tests: the forced probe that drops the allowlist, so every local publication counts as an owner edit. */
export function __dropOwnerEditAllowlistForTests(dropped: boolean): void { allowlistDropped = dropped; }
/** The batch options of one journaled page publication (single or group member). */
export function publicationBeliefOptions(row: { id: string; source_id: string; slug: string; operation: string; authority: { remote?: boolean }; intent?: Record<string, unknown> | null },
additionalKeys: readonly { sourceId: string; slug: string }[] = [], report?: { appended: number }): BeliefBatchOptions {
return { sourceId: row.source_id, slugs: [...new Set([row.slug, ...additionalKeys.filter(k => k.sourceId === row.source_id).map(k => k.slug)])],
publicationId: row.id, op: row.operation, remote: row.authority.remote !== false,
...(row.authority.remote === false && (allowlistDropped || OWNER_EDIT_OPERATIONS.has(row.operation) && row.intent?.kind == null) ? { ownerEdit: true } : {}),
...(row.operation === 'revert_version' ? { pageEventType: 'page.reverted' as const } : {}),
...(row.operation === 'trust_release' ? { cause: { hold: `wh${row.intent?.hold_id}` } } : {}),
...(row.operation === 'forget' || row.operation === 'forget_fact' ? { pageEventType: 'page.view_changed' as const } : {}),
...(row.operation === 'delete_page' && row.intent?.retention === true ? { hardDeleteEvent: 'page.expired' as const } : {}), ...(report ? { report } : {}) };
}