Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.0 KB
Raw Blame
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 } : {}) };
  } };
}