Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-161 PR 3: the Life Chronicle event adapter (kind `chronicle_event`, one owner key per depth page:
* `depth:<slug>`). The items are the event pages a judged revision of the depth page yields, each with the timeline
* projection row it puts on the depth page. A re-judged revision publishes a new generation: changed events are
* versioned and overwritten, and the events it dropped retire (versioned, soft-deleted, `retired_by: life-chronicle`)
* together with their projection rows, in the activation. Chronicle pages are database-only, so a managed source runs the
* same activation in one coordinated request (`databaseOnly`).
*
* Ownership stays content-addressed (#5876): an event is the depth page's while it names that page as its depth and its
* content hash is one the chronicle ledger recorded for it, or its identity is the one the live generation recorded. An
* operator-edited event (any other content) and an operator-deleted one (deleted without a verified retirement) are not
* items at all: the adapter never overwrites, retires or revives them.
*/
import type { BrainEngine } from '../../engine.ts';
import type { PageSnapshot } from '../../page-state/types.ts';
import { pageBodyBytes } from '../../page-body/page-shape.ts';
import { digest } from '../../persistence/digest.ts';
import { RESERVED_RETIREMENT_KEYS, retireDerivedPagesInTransaction } from '../../persistence/derived-retirement-hold.ts';
import { withWriteTrust } from '../../persistence/context.ts';
import { effectiveVisibility, withFolderRestricted, type Visibility } from '../../search/private-visibility.ts';
import { deriveTrust, lowerDerivedPageIn } from '../../trust/taint.ts';
import { derivedGateConfig, derivedGateInput, timelineRowAllowed } from '../../trust/derived-gate.ts';
import { assessTimelineForGate, type WriteGateAssessment } from '../../write-gate.ts';
import { recordWriteGateReceipt } from '../../write-gate-store.ts';
import type { EmptySourceProof } from '../proofs.ts';
import type { GenerationAdapter, GenerationKey, InputState, ItemRow, ProposedItem } from '../contract.ts';
import { markdownItem, pageIdentityHash, pagePreimage, preimageIdentity, readPageRows, type PageRowData } from './page.ts';
export const CHRONICLE_EVENT_KIND = 'chronicle_event';
export const CHRONICLE_RETIRED_BY = 'life-chronicle';
/** Ineligibility reasons that retire a depth page's events with no model call (chronicle/ledger.ts RETIRE_REASONS). */
export const CHRONICLE_INELIGIBLE_REASONS = ['not_chronicle_shaped', 'dream_generated', 'too_short'] as const;
/** The judged depth page; publication re-checks every field. */
export interface ChronicleDepthPin {
slug: string;
pageId: number;
revision: string;
contentHash: string;
incarnation: string;
visibility: Visibility;
}
export async function pinDepth(engine: Pick<BrainEngine, 'executeRaw'>, snapshot: PageSnapshot): Promise<ChronicleDepthPin> {
return {
slug: snapshot.page.slug, pageId: Number(snapshot.page.id), revision: snapshot.revision,
contentHash: String(snapshot.page.content_hash ?? ''), incarnation: snapshot.sourceIncarnation,
visibility: effectiveVisibility({ kind: 'page', page: await withFolderRestricted(engine, snapshot.page) }),
};
}
/** null while the pin holds; otherwise why the generation is superseded. `decisionRequestId`: the writer grant is rechecked too. */
export async function depthPinBroken(tx: BrainEngine, sourceId: string, pin: ChronicleDepthPin, decisionRequestId: string | null): Promise<string | null> {
const current = await tx.readPageSnapshot(pin.slug, { sourceId });
if (!current) return 'page_missing';
if (Number(current.page.id) !== pin.pageId || current.revision !== pin.revision
|| String(current.page.content_hash ?? '') !== pin.contentHash || current.sourceIncarnation !== pin.incarnation
|| effectiveVisibility({ kind: 'page', page: await withFolderRestricted(tx, current.page) }) !== pin.visibility) return 'superseded';
return decisionRequestId && !await grantHolds(tx, decisionRequestId) ? 'superseded' : null;
}
async function grantHolds(tx: BrainEngine, decisionRequestId: string): Promise<boolean> {
const [request] = await tx.executeRaw<import('../../persistence/model.ts').WriteRequest>('SELECT * FROM persistence_requests WHERE id=$1::uuid', [decisionRequestId]);
if (!request) return false;
const { authorizeFactsBackstop } = await import('../../persistence/effect-facts.ts');
const { OperationError } = await import('../../ops/contract.ts');
try { await authorizeFactsBackstop(tx, request); return true; }
catch (error) { if (error instanceof OperationError) return false; throw error; }
}
export const chronicleOwnerKey = (depthSlug: string) => `depth:${depthSlug}`;
const depthOf = (key: GenerationKey) => {
if (!key.ownerKey.startsWith('depth:')) throw new Error(`not a chronicle owner key: ${key.ownerKey}`);
return key.ownerKey.slice('depth:'.length);
};
/** The input pin of a judged depth page: every field the pin rechecks, so any change refuses activation (`pin_moved`). */
export const depthInputPin = (pin: ChronicleDepthPin) => digest(['chronicle-depth-v1', pin.pageId, pin.revision, pin.contentHash, pin.incarnation, pin.visibility]);
/**
* What one publication hands the adapter: the writer grant the activation rechecks (null: none, e.g. a retire-only run),
* and the identity of each event it proposes. An event live at exactly its proposed identity is the extractor's output,
* so the activation recognises what this publication wrote before the chronicle ledger records its hash.
*/
export interface ChronicleGenerationContext { decisionRequestId: string | null; planned?: Record<string, string> }
/** One proposed event: the markdown its page is written from and the projection row it puts on the depth page. */
export interface ChronicleEventContent {
markdown: string;
title: string;
compiledTruth: string;
frontmatter: Record<string, unknown>;
when: string;
day: string;
summary: string;
}
export function chronicleEventItem(slug: string, event: ChronicleEventContent): ProposedItem {
return { key: slug, content: JSON.stringify(event), identityHash: markdownItem(slug, event.markdown).identityHash };
}
function safeDate(value: unknown): Date | null {
const date = new Date(String(value ?? ''));
return Number.isNaN(date.getTime()) ? null : date;
}
type EventRow = PageRowData & { content_hash: string | null };
type Projection = { date: string; summary: string; detail: string };
/** The depth page row (a live one first), for its id; null when it was purged. */
async function depthRow(db: BrainEngine, sourceId: string, slug: string): Promise<{ id: number; live: boolean } | null> {
const [row] = await db.executeRaw<{ id: number; live: boolean }>(
'SELECT id, deleted_at IS NULL AS live FROM pages WHERE source_id=$1 AND slug=$2 ORDER BY deleted_at NULLS FIRST, id DESC LIMIT 1', [sourceId, slug]);
return row ? { id: Number(row.id), live: row.live } : null;
}
/** Every event content hash the chronicle ledger recorded for the depth page `pageId`. */
export async function ownedEventHashes(db: BrainEngine, sourceId: string, pageId: number): Promise<Set<string>> {
const rows = await db.executeRaw<{ hash: string }>('SELECT DISTINCT unnest(event_hashes) AS hash FROM chronicle_page_state WHERE source_id=$1 AND page_id=$2', [sourceId, pageId]);
return new Set(rows.map(row => row.hash));
}
/** Slugs of `sourceId` the chronicle ledger records as retired by a generation (the verified half of a retirement stamp). */
async function ledgerRetired(db: BrainEngine, sourceId: string, slugs: readonly string[]): Promise<Set<string>> {
if (!slugs.length) return new Set();
const rows = await db.executeRaw<{ item_key: string }>(
`SELECT DISTINCT i.item_key FROM derived_generation_items i JOIN derived_generations g ON g.id=i.generation_id
WHERE g.source_id=$1 AND g.kind=$2 AND i.action='retired' AND i.item_key=ANY($3::text[])`, [sourceId, CHRONICLE_EVENT_KIND, [...slugs]]);
return new Set(rows.map(row => row.item_key));
}
/**
* Whether a deleted event page is one the extractor retired, verified rather than read off its stamp alone: the stamp
* names a derived retirement and either the generation ledger recorded it, or (a retirement from before the ledger) its
* content hash is one the chronicle ledger recorded for its depth page.
*/
export async function verifiedChronicleRetirement(db: BrainEngine, sourceId: string, page: { slug: string; content_hash?: string | null; frontmatter?: Record<string, unknown> | null }): Promise<boolean> {
const stamp = page.frontmatter?.retired_by;
if (stamp !== CHRONICLE_RETIRED_BY && stamp !== 'generation-restore') return false;
if ((await ledgerRetired(db, sourceId, [page.slug])).has(page.slug)) return true;
const depth = (page.frontmatter?.event as { depth?: unknown } | undefined)?.depth;
if (stamp !== CHRONICLE_RETIRED_BY || typeof depth !== 'string' || !page.content_hash) return false;
const row = await depthRow(db, sourceId, depth);
return row !== null && (await ownedEventHashes(db, sourceId, row.id)).has(String(page.content_hash));
}
async function projectionRows(db: BrainEngine, pageIds: readonly number[]): Promise<Map<number, Projection[]>> {
const out = new Map<number, Projection[]>();
if (!pageIds.length) return out;
const rows = await db.executeRaw<{ event_page_id: number; date: string; summary: string; detail: string | null }>(
'SELECT event_page_id, date::text AS date, summary, detail FROM timeline_entries WHERE event_page_id = ANY($1::bigint[]) ORDER BY date', [[...pageIds]]);
for (const row of rows) out.set(Number(row.event_page_id), [...out.get(Number(row.event_page_id)) ?? [], { date: row.date, summary: row.summary, detail: row.detail ?? '' }]);
return out;
}
/**
* The event rows of `itemKeys` and every live event naming the depth page, classified: owned live events and verified
* retirements are items; an operator-edited or operator-deleted event (or any other page at a proposed slug) is left out.
*/
async function readEventItems(db: BrainEngine, key: GenerationKey, itemKeys: readonly string[], context?: ChronicleGenerationContext): Promise<Map<string, ItemRow>> {
const depth = depthOf(key);
const rows = await readPageRows(db, key.sourceId, `p.slug = ANY($2::text[]) OR (p.deleted_at IS NULL AND p.type='event' AND p.frontmatter->'event'->>'depth' = $3
AND p.frontmatter->>'captured_via' LIKE 'life-chronicle:%')`, [[...itemKeys], depth]);
if (!rows.length) return new Map();
const hashes = await db.executeRaw<{ slug: string; content_hash: string | null }>('SELECT slug, content_hash FROM pages WHERE source_id=$1 AND id = ANY($2::bigint[])',
[key.sourceId, rows.map(row => row.page_id)]);
const hashOf = new Map(hashes.map(row => [row.slug, row.content_hash]));
const events: EventRow[] = rows.filter(row => row.type === 'event').map(row => ({ ...row, content_hash: hashOf.get(row.slug) ?? null }));
const depthPage = await depthRow(db, key.sourceId, depth);
const owned = depthPage ? await ownedEventHashes(db, key.sourceId, depthPage.id) : new Set<string>();
const recorded = new Map((await db.executeRaw<{ item_key: string; identity_hash: string }>(
`SELECT i.item_key, i.identity_hash FROM derived_generation_items i JOIN derived_generations g ON g.id=i.generation_id
WHERE g.source_id=$1 AND g.kind=$2 AND g.owner_key=$3 AND g.state='live' AND i.action <> 'retired'`, [key.sourceId, CHRONICLE_EVENT_KIND, key.ownerKey]))
.map(row => [row.item_key, row.identity_hash]));
const retired = await ledgerRetired(db, key.sourceId, events.filter(row => row.deleted).map(row => row.slug));
const projections = await projectionRows(db, events.map(row => row.page_id));
const out = new Map<string, ItemRow>();
for (const row of events) {
const fm = row.frontmatter ?? {};
const origin = String(fm.captured_via ?? '').startsWith('life-chronicle:') && (fm.event as { depth?: unknown } | undefined)?.depth === depth;
if (!origin) continue;
if (row.deleted) {
const stamp = fm.retired_by;
const verified = retired.has(row.slug) || (stamp === CHRONICLE_RETIRED_BY && owned.has(String(row.content_hash ?? '')));
if (!verified || (stamp !== CHRONICLE_RETIRED_BY && stamp !== 'generation-restore')) continue;
} else if (!owned.has(String(row.content_hash ?? '')) && recorded.get(row.slug) !== pageIdentityHash(row) && context?.planned?.[row.slug] !== pageIdentityHash(row)) continue;
const rowProjections = projections.get(row.page_id) ?? [];
out.set(row.slug, { key: row.slug, identityHash: pageIdentityHash(row), live: !row.deleted, owned: true, segmented: row.segmented, preimage: () => {
const page = pagePreimage(row);
return page.json ? { json: { ...page.json, projection: rowProjections, content_hash: row.content_hash }, bytes: page.bytes } : page;
} });
}
return out;
}
async function recordProjectionFlag(tx: BrainEngine, assessment: WriteGateAssessment, eventPageId: number, date: string, sourceId: string): Promise<void> {
if (assessment.verdict !== 'flag') return;
const [entry] = await tx.executeRaw<{ id: number }>('SELECT id FROM timeline_entries WHERE event_page_id=$1 AND date=$2::date', [eventPageId, date]);
if (entry) await recordWriteGateReceipt(tx, { targetTable: 'timeline_entries', targetId: Number(entry.id), sourceId, assessment });
}
/**
* Writes one event page (versioned first when it replaces a live one) inside the caller's transaction; returns its id.
* `contentHash`: a restore keeps the hash the page had, which the chronicle ledger owns (jsonb reorders frontmatter keys,
* and the content hash is order-sensitive).
*/
async function writeEventPage(tx: BrainEngine, sourceId: string, slug: string, page: { title: string; compiledTruth: string; frontmatter: Record<string, unknown>; when: unknown; contentHash?: string | null }): Promise<number> {
const live = await tx.readPageSnapshot(slug, { sourceId });
if (live) await tx.createVersion(slug, { sourceId, preimage: live });
const written = await tx.putPage(slug, { type: 'event', title: page.title, compiled_truth: page.compiledTruth,
frontmatter: { type: 'event', ...page.frontmatter }, effective_date: safeDate(page.when), ...(page.contentHash ? { content_hash: page.contentHash } : {}) }, { sourceId });
return Number(written.id);
}
export const chronicleEventAdapter: GenerationAdapter<ChronicleGenerationContext> = {
kind: CHRONICLE_EVENT_KIND,
retiredBy: CHRONICLE_RETIRED_BY,
modelProduced: true,
databaseOnly: true,
lockKeys: (key, itemKeys) => [depthOf(key), ...itemKeys].map(slug => ({ sourceId: key.sourceId, slug })),
async readInput(engine, key, context) {
const snapshot = await engine.readPageSnapshot(depthOf(key), { sourceId: key.sourceId });
if (!snapshot) return null;
const pin = await pinDepth(engine, snapshot);
const size = pageBodyBytes(snapshot.page);
const revoked = context?.decisionRequestId ? !await grantHolds(engine, context.decisionRequestId) : false;
return { pin: revoked ? `${depthInputPin(pin)}:grant_revoked` : depthInputPin(pin), size };
},
readItems: (engine, key, itemKeys, context) => readEventItems(engine, key, itemKeys, context),
// An owned event already carries producer evidence (its content hash is on the chronicle ledger).
legacyEvidence: async (_engine, _key, rows) => new Set(rows.map(row => row.key)),
async publishItems(tx, key, items, context) {
const depth = depthOf(key);
const derivation = await deriveTrust(tx, [{ table: 'pages', sourceId: key.sourceId, slug: depth }], { channel: 'derive:chronicle' });
const gateCfg = await derivedGateConfig(tx);
const items0 = await readEventItems(tx, key, items.map(item => item.key), context);
await withWriteTrust(tx, derivation.trust, async () => {
for (const item of items) {
const event = JSON.parse(item.content) as ChronicleEventContent;
const existing = await tx.executeRaw('SELECT 1 FROM pages WHERE source_id=$1 AND slug=$2', [key.sourceId, item.key]);
if (existing.length && !items0.has(item.key)) {
const { opError } = await import('../../ops/contract.ts');
throw opError('revision_conflict', `chronicle_superseded: ${item.key} was edited or deleted by an operator; nothing from this generation is published.`,
'Nothing to do: the next chronicle cycle judges the depth page again and leaves that event as the operator left it.');
}
const pageId = await writeEventPage(tx, key.sourceId, item.key, { title: event.title, compiledTruth: event.compiledTruth, frontmatter: event.frontmatter, when: event.when });
await lowerDerivedPageIn(tx, derivation, key.sourceId, item.key);
// #5575 B3: the event's summary lands on the depth page's timeline; a quarantined or rejected one projects nothing.
const gate = assessTimelineForGate({ summary: event.summary, source: `life-chronicle:event:${item.key}` }, derivedGateInput(derivation.trust), gateCfg);
if (!timelineRowAllowed(gate)) continue;
await tx.upsertEventProjection({ depthSlug: depth, eventSlug: item.key, date: event.day, summary: event.summary, sourceId: key.sourceId });
await recordProjectionFlag(tx, gate, pageId, event.day, key.sourceId);
}
});
},
async retireItems(tx, key, itemKeys, retiredBy) {
if (!itemKeys.length) return;
await tx.executeRaw(`DELETE FROM timeline_entries t USING pages p WHERE p.id=t.event_page_id AND p.source_id=$1 AND p.slug=ANY($2::text[])`, [key.sourceId, [...itemKeys]]);
await retireDerivedPagesInTransaction(tx, key.sourceId, itemKeys, retiredBy);
},
async restoreItem(tx, key, itemKey, preimage) {
const frontmatter = { ...(preimage.frontmatter as Record<string, unknown>) };
for (const stamp of RESERVED_RETIREMENT_KEYS) delete frontmatter[stamp];
delete frontmatter.type;
const pageId = await writeEventPage(tx, key.sourceId, itemKey, { title: String(preimage.title), compiledTruth: String(preimage.compiled_truth ?? ''), frontmatter,
when: frontmatter.event_date, contentHash: typeof preimage.content_hash === 'string' ? preimage.content_hash : null });
const depth = await depthRow(tx, key.sourceId, depthOf(key));
if (!depth?.live) return;
for (const projection of (preimage.projection as Projection[] | undefined) ?? []) {
await tx.executeRaw(`INSERT INTO timeline_entries (page_id, date, source, summary, detail, event_page_id) VALUES ($1, $2::date, $3, $4, $5, $6)
ON CONFLICT (event_page_id, date) WHERE event_page_id IS NOT NULL DO UPDATE SET summary=EXCLUDED.summary, detail=EXCLUDED.detail, page_id=EXCLUDED.page_id, source=EXCLUDED.source`,
[depth.id, projection.date, `life-chronicle:event:${itemKey}`, projection.summary, projection.detail, pageId]);
}
},
preimageIdentity,
async proofHolds(engine, key, proof: EmptySourceProof) {
if (proof.kind !== 'originIneligible' || !(CHRONICLE_INELIGIBLE_REASONS as readonly string[]).includes(proof.reason)) return false;
const snapshot = await engine.readPageSnapshot(depthOf(key), { sourceId: key.sourceId });
if (!snapshot?.page.content_hash) return false;
const { CHRONICLE_EXTRACTOR_VERSION } = await import('../../chronicle/contract.ts');
const rows = await engine.executeRaw('SELECT 1 FROM chronicle_page_state WHERE source_id=$1 AND page_id=$2 AND content_hash=$3 AND extractor_version=$4 AND state=$5 AND reason=$6',
[key.sourceId, Number(snapshot.page.id), snapshot.page.content_hash, CHRONICLE_EXTRACTOR_VERSION, 'skipped', proof.reason]);
return rows.length > 0;
},
};
/** The live chronicle generations of `sourceId` whose depth page is gone and that still hold a live event (C-6): their owner keys, oldest first. */
export async function orphanedDepthKeys(db: BrainEngine, sourceId: string, limit: number): Promise<string[]> {
const rows = await db.executeRaw<{ owner_key: string }>(
`SELECT g.owner_key FROM derived_generations g
WHERE g.source_id=$1 AND g.kind=$2 AND g.state='live'
AND EXISTS (SELECT 1 FROM derived_generation_items i JOIN pages e ON e.source_id=g.source_id AND e.slug=i.item_key AND e.deleted_at IS NULL
WHERE i.generation_id=g.id AND i.action <> 'retired')
AND NOT EXISTS (SELECT 1 FROM pages p WHERE p.source_id=g.source_id AND p.slug=substr(g.owner_key, 7) AND p.deleted_at IS NULL)
ORDER BY g.updated_at, g.id LIMIT $3`, [sourceId, CHRONICLE_EVENT_KIND, limit]);
return rows.map(row => row.owner_key);
}
export type { InputState };