Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { requestChannelTrust } from '../trust/channel.ts';
import { gateField, gateInput, loadWriteGateConfig } from '../trust/gate-outcomes.ts';
import { recordWriteGateReceipt } from '../write-gate-store.ts';
import { assessTimelineForGate, writeGateRejectedError } from '../write-gate.ts';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { serializePageToMarkdown } from '../markdown.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { wholeBodySnapshot } from './segmented-apply.ts';
import { pageIdentityError } from './page-identity.ts';
import { renderTimelineEntry, spliceTimelineBlock } from '../timeline-write-through.ts';
import { extractTimelineFromContent } from '../timeline-extract.ts';
import { preparePageMutation, prepareSegmentedTagMutation } from './page-prepare.ts';
import type { PreparedMutation } from './coordinator.ts';
import type { WriteRequest } from './model.ts';
import { assertPageRevision } from '../page-state/types.ts';
import { engineMutationPrecondition, parseMutationPrecondition } from './preconditions.ts';
import { materializedMarker } from '../timeline-marker.ts';
import { isConnectorSourceKind } from './connector-identity.ts';
function hasExactBlock(text: string, block: string): boolean {
const wanted = block.trimEnd().split('\n');
const lines = text.split('\n');
return lines.some((_, index) => wanted.every((line, offset) => lines[index + offset] === line));
}
/**
* Fix wave 4 audit of the page-regenerating writers: pages a writer re-renders
* from its own inputs through a preserving publication, where an unmarked
* user-added bullet the new body drops would be read as removed.
* - connector pages (Google, GitHub), re-rendered from the provider (#5567);
* - dream-owned pages (`dream_generated: true`: synthesis summaries, concepts,
* patterns), republished by the dream cycle;
* - Life Chronicle event pages (`captured_via: life-chronicle:auto`);
* - drift reports (`reports/drift-<date>`), rewritten by same-day re-runs.
* Ordinary pages keep unmarked bullets: their writers edit with the page's
* current body, so a bullet they drop is a deliberate removal.
*/
export function regeneratedByWriter(sourceKind: string | null | undefined, page: { slug: string; frontmatter?: Record<string, unknown> | null }): boolean {
if (isConnectorSourceKind(sourceKind)) return true;
const fm = page.frontmatter ?? {};
if (fm.dream_generated === true || fm.dream_generated === 'true') return true;
if (typeof fm.captured_via === 'string' && fm.captured_via.startsWith('life-chronicle:')) return true;
return /^reports\/drift-/.test(page.slug);
}
export async function prepareSemanticPageMutation(engine: BrainEngine, row: WriteRequest, config: GBrainConfig): Promise<PreparedMutation> {
const stored = await engine.readPageSnapshot(row.slug, { sourceId: row.source_id });
if (!stored || stored.page.id !== row.page_id) throw pageIdentityError(stored != null, 'The accepted page was replaced by another page.');
const p = row.intent!;
if (p.expected_revision !== undefined) assertPageRevision(stored,engineMutationPrecondition(parseMutationPrecondition(p)));
if (row.operation === 'add_tag' || row.operation === 'remove_tag') {
if (typeof p.tag !== 'string' || !p.tag.trim()) {
throw opError('invalid_params', 'A tag must be nonempty.', `Request ${row.request_id} for ${row.slug} in source ${row.source_id} named an empty tag, so nothing changed. Submit the tag change again with a nonempty tag.`);
}
const tag = p.tag.trim();
const tags = row.operation === 'add_tag' ? [...new Set([...stored.tags, tag])].sort() : stored.tags.filter(value => value !== tag);
// Wave B (spec 6.4): a tag change on a segmented page is a metadata flip over the live manifest, at any size;
// only a write whose gate scans the whole body (an external_untrusted writer) takes the put path, up to 24 MiB.
const flipped = isSegmentedPage(stored.page) ? await prepareSegmentedTagMutation(engine, row, stored, tags) : null;
const snapshot = flipped ? stored : (await wholeBodySnapshot(engine, stored, `${row.operation} (the write gate scans the whole body of an external_untrusted write)`))!;
const prepared = flipped ?? await preparePageMutation(engine, row, config, {
expectedRevision: snapshot.revision, tags, content: serializePageToMarkdown(snapshot.page, tags),
}, undefined, { boundedChunkWrites: true });
// #5251: a tag change leaves every chunk's text as it was, so the republication queues no
// embedding effect; the stale sweep still picks up any chunk the publish left without a vector.
return { ...prepared, deferEmbedding: true, apply: async tx => ({ ...await prepared.apply(tx), status: 'ok', tag }) };
}
if (row.operation !== 'add_timeline_entry') {
throw opError('writer_coordinator_required', 'This semantic writer has no registered preparation handler.',
`Request ${row.request_id} (${row.operation}) in source ${row.source_id} has no preparation handler in this gbrain version, so nothing changed. This is an internal or version-skew fault: report it to the user.`);
}
// Wave B: a segmented page within 24 MiB is read back whole and written as a normal put; a larger one refuses.
const snapshot = (await wholeBodySnapshot(engine, stored, row.operation))!;
const entry = { date: String(p.date), summary: String(p.summary), source: String(p.source ?? ''), detail: String(p.detail ?? '') };
const rendered = renderTimelineEntry(entry, row.slug);
if (!rendered) {
throw opError('invalid_params', 'The timeline entry cannot be represented losslessly in Markdown.',
`Request ${row.request_id}'s timeline entry for ${row.slug} would not read back as the same entry, so nothing changed. Submit it again with a YYYY-MM-DD date and a nonempty single-line summary that has no Markdown list or heading syntax.`);
}
// #5567: a writer that regenerates the page from its own inputs never holds this entry. The materialized
// marker makes its preserving render carry the bullet forward instead of deleting it (fix wave 4 audit).
const [source] = await engine.executeRaw<{ kind: string | null }>("SELECT config->>'kind' AS kind FROM sources WHERE id=$1", [row.source_id]);
const block = regeneratedByWriter(source?.kind, snapshot.page) ? `${materializedMarker(rendered.canonical)}\n${rendered.block}` : rendered.block;
// An identical entry written before the page's writer marked user bullets is still a duplicate.
const exact = hasExactBlock(snapshot.page.timeline, block) || (block !== rendered.block && hasExactBlock(snapshot.page.timeline, rendered.block));
const tuples = extractTimelineFromContent(`${snapshot.page.compiled_truth}\n<!-- timeline -->\n${snapshot.page.timeline}`, row.slug);
if (!exact && tuples.some(tuple => tuple.date === rendered.canonical.date && tuple.source === rendered.canonical.source && tuple.summary === rendered.canonical.summary)) {
throw new OperationError('invalid_params', 'This timeline identity already exists with different detail.', 'Read and conditionally edit the existing page to change that entry.');
}
// #5575 CEO-27: the timeline row is gated at the request's tier; it keeps its own tier, the page keeps its own.
const gate = assessTimelineForGate(entry, gateInput(requestChannelTrust(row) ?? { tier: 'unknown', origin: null }, row.id), await loadWriteGateConfig(engine));
if (gate.verdict === 'reject' || gate.verdict === 'quarantine') throw writeGateRejectedError(gate);
const page = { ...snapshot.page, timeline: exact ? snapshot.page.timeline : spliceTimelineBlock(snapshot.page.timeline, entry.date, block) };
const prepared = await preparePageMutation(engine, row, config, {
expectedRevision: snapshot.revision, content: serializePageToMarkdown(page, snapshot.tags),
}, undefined, { boundedChunkWrites: true });
return { ...prepared, apply: async tx => {
const outcome = await prepared.apply(tx);
const inserted = await tx.addTimelineEntry(row.slug, { ...rendered.canonical, detail: rendered.detail }, { sourceId: row.source_id });
const [stored] = gate.verdict === 'flag' ? await tx.executeRaw<{ id: number }>(`SELECT t.id FROM timeline_entries t JOIN pages p ON p.id = t.page_id
WHERE p.source_id = $1 AND p.slug = $2 AND t.date = $3::date AND t.summary = $4 ORDER BY t.id DESC LIMIT 1`, [row.source_id, row.slug, rendered.canonical.date, rendered.canonical.summary]) : [];
const flagged = stored ? gateField(gate, `p:${row.source_id}/${row.slug}`, await recordWriteGateReceipt(tx, { targetTable: 'timeline_entries', targetId: Number(stored.id), sourceId: row.source_id, assessment: gate, requestId: row.id })) : undefined;
// #5970: the rendered bullet is the exact line to edit (edit_page) when the entry needs a correction.
return { ...outcome, status: exact && !inserted ? 'skipped' : 'ok', ...(exact && !inserted ? { reason: 'duplicate' } : {}), entry: rendered.canonical, bullet: rendered.block, ...(flagged ? { gate: flagged } : {}) };
} };
}