Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.7 KB
Raw Blame
/**
 * Life Chronicle event publication (#5876, E5/E8, C4b/C12; GBRA-161 PR 3).
 *
 * One extraction generation of a depth page (meeting, conversation, calendar
 * page) is published against the immutable snapshot the judge read, through the
 * generation primitive (generations/adapters/chronicle-events.ts):
 *
 *   - The activation re-validates that the depth page still has the judged
 *     revision, content hash, source incarnation and privacy, and that the
 *     writer whose revision was decided still holds the extraction grant. Any
 *     change → `superseded`; no model call or transaction spans the judge.
 *   - Events carry the depth page's effective visibility.
 *   - Ownership is content-addressed: an event is the extractor's while its
 *     live content_hash is one the ledger recorded for this depth page. An
 *     operator-edited event (hash changed) is never overwritten or retired;
 *     an operator-deleted event (deleted without a verified retirement) is
 *     never resurrected.
 *   - A complete generation (`replaces`) retires the previous generation's
 *     owned events it did not reproduce, with their timeline projection rows, in
 *     the activation: versioned, soft-deleted, `retired_by: life-chronicle`, and
 *     restorable with `gbrain repair generations --kind chronicle-event`. A result
 *     below the shrink floor is held and retires nothing; so does an empty or
 *     partial one (#7013). An empty generation retires only with a proof: the
 *     revision became ineligible (`originIneligible`) or the depth page is gone
 *     (`originGone`).
 *
 * Managed brains publish each new or changed event through the chronicle event
 * intent (database-only), then one `managed_generation_activate` request that
 * retires and flips the ledger; unmanaged brains do it all in one transaction.
 */
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import type { PageSnapshot } from '../page-state/types.ts';
import type { PreparedMutation } from '../persistence/coordinator.ts';
import type { WriteRequest } from '../persistence/model.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { computeContentHash } from '../ingestion/types.ts';
import { serializeMarkdown } from '../markdown.ts';
import { digest } from '../persistence/digest.ts';
import { maintenancePreflight, submitDatabaseMaintenanceIntent, type MaintenanceAuthority } from '../persistence/prepared-maintenance.ts';
import { preparePageMutation } from '../persistence/page-prepare.ts';
import { stampDerivedRetirement } from '../persistence/derived-retirement-hold.ts';
import type { Visibility } from '../search/private-visibility.ts';
import type { ChronicleEventProposal } from './extract-events.ts';
import { resolveChronicleEventSlugs } from './event-identity.ts';
import { declareDerivation, deriveTrust } from '../trust/taint.ts';
import { derivationWriteTrust } from '../trust/page-write.ts';
import { CHRONICLE_CAPTURED_VIA } from '../trust/channel.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 { InputState, ProposedItem } from '../generations/contract.ts';
import { originGone, type EmptySourceProof } from '../generations/proofs.ts';
import { publishGeneration, type PublishOutcome, type PublishRequest } from '../generations/publish.ts';
import { planManagedGeneration, recordActivation, type ActivationIntent } from '../generations/managed.ts';
import { CHRONICLE_EVENT_KIND, CHRONICLE_RETIRED_BY, chronicleEventAdapter, chronicleEventItem, chronicleOwnerKey, depthInputPin, depthPinBroken,
  orphanedDepthKeys, ownedEventHashes, pinDepth, verifiedChronicleRetirement, type ChronicleDepthPin, type ChronicleGenerationContext } from '../generations/adapters/chronicle-events.ts';

export { CHRONICLE_CAPTURED_VIA, CHRONICLE_RETIRED_BY, depthPinBroken, ownedEventHashes, pinDepth, type ChronicleDepthPin };
export const CHRONICLE_EVENT_INTENT = 'managed_maintenance_chronicle_event';
export const CHRONICLE_RETIRE_INTENT = 'managed_maintenance_chronicle_retire';

export interface BuiltChronicleEvent {
  slug: string;
  title: string;
  compiledTruth: string;
  frontmatter: Record<string, unknown>;
  when: string;
  day: string;
  summary: string;
}

/** Event identity is content-addressed on (who, what, depth): a re-run upserts the same page. Same-day collisions are resolved at publication (event-identity.ts). */
export function buildChronicleEvent(ev: ChronicleEventProposal, ctx: {
  depthSlug: string; attendees: string[]; effectiveDate: string | null; tz: string; visibility: Visibility; depthHash: string;
  isoDay: (when: string, tz: string) => string; normalizeKind: (kind: string) => string;
}): BuiltChronicleEvent {
  const who = ev.who.length ? ev.who : ctx.attendees;
  const when = ev.when || ctx.effectiveDate || ctx.isoDay(new Date(0).toISOString(), ctx.tz);
  const day = ctx.isoDay(when, ctx.tz);
  const hash = computeContentHash(`${who.join(',')}|${ev.what}|${ctx.depthSlug}`).slice(0, 8);
  const event = { when, who, what: ev.what, where: ev.where ?? null, kind: ctx.normalizeKind(ev.kind), depth: ctx.depthSlug };
  return {
    slug: `life/events/${day}-${hash}`,
    title: ev.what.slice(0, 120),
    compiledTruth: `${ev.what} — see [[${ctx.depthSlug}]].`,
    frontmatter: { event, event_date: when, captured_via: CHRONICLE_CAPTURED_VIA, visibility: ctx.visibility, chronicle_depth_hash: ctx.depthHash },
    when, day, summary: ev.what,
  };
}

type TargetVerdict = { write: true; restore: boolean; expectedRevision: string | null } | { write: false; reason: 'operator_deleted' | 'operator_edited' };

/** Whether an event slug may be written: absent, owned and live, or retired by a verified chronicle retirement (restored). */
async function judgeTarget(db: BrainEngine, sourceId: string, existing: PageSnapshot | null, owned: Set<string>): Promise<TargetVerdict> {
  if (!existing) return { write: true, restore: false, expectedRevision: null };
  if (existing.page.deleted_at) {
    return await verifiedChronicleRetirement(db, sourceId, existing.page)
      ? { write: true, restore: true, expectedRevision: existing.revision }
      : { write: false, reason: 'operator_deleted' };
  }
  return owned.has(String(existing.page.content_hash ?? ''))
    ? { write: true, restore: false, expectedRevision: existing.revision }
    : { write: false, reason: 'operator_edited' };
}

function requestIdFor(value: unknown): string {
  const key = digest(value);
  return `${key.slice(0, 8)}-${key.slice(8, 12)}-4${key.slice(13, 16)}-a${key.slice(17, 20)}-${key.slice(20, 32)}`;
}

function supersededError(reason: string): OperationError {
  return opError('revision_conflict', `chronicle_superseded: ${reason}. The depth page, its privacy or its writer grant changed after it was judged; nothing from this generation is published.`,
    'Nothing to do: the newer revision carries its own extraction decision, and the next chronicle cycle judges it.');
}

/** A publication failure that means the judged generation no longer applies. */
export function isSupersession(error: unknown): boolean {
  return error instanceof OperationError
    && ['revision_conflict', 'page_identity_changed', 'source_changed', 'permission_denied', 'page_not_found', 'generation_fenced', 'generation_live_conflict'].includes(error.code);
}

export interface ChronicleGenerationResult {
  written: Array<{ slug: string; hash: string }>;
  retired: string[];
  protected: Array<{ slug: string; reason: 'operator_deleted' | 'operator_edited' }>;
  superseded?: string;
  /** The result was held (`generation_held`): nothing was published or retired. */
  held?: string;
}

/**
 * Publish one generation (possibly empty) for a pinned depth page. `replaces`: a complete judged generation, which may
 * retire the previous generation's owned events it did not reproduce (within the shrink floor and valve); without it
 * (an empty or partial judged generation, #7013) it adds and retires nothing. `proof` makes an empty `replaces`
 * generation retire every owned event: `originIneligible` (the revision no longer qualifies) or `originGone` (the
 * depth page is gone; `pin` is then null).
 */
export async function publishChronicleGeneration(engine: BrainEngine, opts: {
  sourceId: string; pin: ChronicleDepthPin | null; depthSlug?: string; events: BuiltChronicleEvent[]; decisionRequestId: string | null;
  replaces: boolean; proof?: EmptySourceProof; maintenance?: MaintenanceAuthority | null; signal?: AbortSignal;
}): Promise<ChronicleGenerationResult> {
  const { sourceId, pin } = opts;
  const depthSlug = pin?.slug ?? opts.depthSlug!;
  const maintenance = opts.maintenance === undefined ? await maintenancePreflight(engine, sourceId) : opts.maintenance;
  const result: ChronicleGenerationResult = { written: [], retired: [], protected: [] };
  if (opts.signal?.aborted) { const e = new Error('aborted'); e.name = 'AbortError'; throw e; }
  const key = { kind: CHRONICLE_EVENT_KIND, sourceId, ownerKey: chronicleOwnerKey(depthSlug) };
  const context: ChronicleGenerationContext = { decisionRequestId: opts.decisionRequestId };
  let input: InputState | null = null;
  const items: ProposedItem[] = [];
  const members = new Map<string, { event: BuiltChronicleEvent; verdict: Extract<TargetVerdict, { write: true }>; markdown: string }>();
  if (pin) {
    const broken = await depthPinBroken(engine, sourceId, pin, opts.decisionRequestId);
    if (broken) return { ...result, superseded: broken };
    input = await chronicleEventAdapter.readInput(engine, key, context);
    if (input?.pin !== depthInputPin(pin)) return { ...result, superseded: 'superseded' };
    const owned = await ownedEventHashes(engine, sourceId, pin.pageId);
    for (const event of await resolveChronicleEventSlugs(engine, sourceId, opts.events)) {
      const verdict = await judgeTarget(engine, sourceId, await engine.readPageSnapshot(event.slug, { sourceId, includeDeleted: true }), owned);
      if (!verdict.write) { result.protected.push({ slug: event.slug, reason: verdict.reason }); continue; }
      const markdown = serializeMarkdown(event.frontmatter, event.compiledTruth, '', { type: 'event', title: event.title, tags: [] });
      items.push(chronicleEventItem(event.slug, { markdown, title: event.title, compiledTruth: event.compiledTruth, frontmatter: event.frontmatter,
        when: event.when, day: event.day, summary: event.summary }));
      members.set(event.slug, { event, verdict, markdown });
    }
  }
  if (!opts.replaces && !items.length) return result;
  context.planned = Object.fromEntries(items.map(item => [item.key, item.identityHash]));
  const request = { key, items, input, partial: !opts.replaces, ...(opts.proof ? { proof: opts.proof } : {}), context };
  let outcome: PublishOutcome | null;
  try {
    outcome = maintenance ? await publishManagedChronicle(engine, maintenance, request, pin, members, opts.decisionRequestId)
      : await publishGeneration(engine, chronicleEventAdapter, request);
  } catch (error) {
    if (!isSupersession(error)) throw error;
    return { ...result, written: await writtenEvents(engine, sourceId, items), superseded: 'superseded' };
  }
  if (outcome?.state === 'held') return { ...result, held: outcome.reason };
  return { ...result, written: await writtenEvents(engine, sourceId, items), retired: outcome?.state === 'published' ? outcome.retired : [] };
}

/** The live content hash of each proposed event (what the chronicle ledger records as the extractor's). */
async function writtenEvents(engine: BrainEngine, sourceId: string, items: readonly ProposedItem[]): Promise<Array<{ slug: string; hash: string }>> {
  if (!items.length) return [];
  const rows = await engine.executeRaw<{ slug: string; content_hash: string | null }>(
    'SELECT slug, content_hash FROM pages WHERE source_id=$1 AND slug=ANY($2::text[]) AND deleted_at IS NULL', [sourceId, items.map(item => item.key)]);
  const hashes = new Map(rows.map(row => [row.slug, row.content_hash]));
  return items.flatMap(item => hashes.get(item.key) ? [{ slug: item.key, hash: String(hashes.get(item.key)) }] : []);
}

/**
 * The managed publication (database-only): the plan's new and changed events go through the chronicle event intent,
 * one request each, then one `managed_generation_activate` request, journaled on the depth page and bound to its
 * revision, rechecks the pin and every member, retires the dropped events with their projection rows and flips the
 * ledger in one transaction. null: nothing to publish.
 */
async function publishManagedChronicle(engine: BrainEngine, maintenance: MaintenanceAuthority, request: PublishRequest<ChronicleGenerationContext>,
  pin: ChronicleDepthPin | null, members: Map<string, { event: BuiltChronicleEvent; verdict: Extract<TargetVerdict, { write: true }>; markdown: string }>,
  decisionRequestId: string | null): Promise<PublishOutcome | null> {
  const plan = await planManagedGeneration(engine, chronicleEventAdapter, request, { scope: decisionRequestId });
  if (plan.kind === 'held') return plan.outcome;
  if (plan.kind === 'unchanged') return { state: 'unchanged', generation: null, retired: [], protected: [] };
  await engine.transaction(tx => recordActivation(tx, plan.intent));
  const owned = pin ? await ownedEventHashes(engine, request.key.sourceId, pin.pageId) : new Set<string>();
  const derivation = pin ? await deriveTrust(engine, [{ table: 'pages', id: pin.pageId }], { channel: 'derive:chronicle' }) : null;
  const gateCfg = pin ? await derivedGateConfig(engine) : null;
  for (const member of plan.members) {
    if (member.action === 'retire' || !pin || !derivation || !gateCfg) continue;
    const { event, verdict, markdown } = members.get(member.slug)!;
    if (member.action === 'overwrite' && member.identity === member.before) continue;
    // #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:${event.slug}` }, derivedGateInput(derivation.trust), gateCfg);
    const projection = timelineRowAllowed(gate) ? { depth_slug: pin.slug, date: event.day, summary: event.summary } : undefined;
    const intent = { kind: CHRONICLE_EVENT_INTENT, content: markdown, expected_revision: verdict.expectedRevision,
      restore_retired: verdict.restore, depth: pin, decision_request_id: decisionRequestId, activation_id: plan.intent.activationId,
      owned_hashes: [...owned], ...(projection ? { event_projection: projection } : {}), derivation: declareDerivation(derivation.trust, derivation.inputs) };
    await submitDatabaseMaintenanceIntent(engine, maintenance, event.slug, intent, requestIdFor({ writer: maintenance.writer.principal, slug: event.slug, intent }));
  }
  const depth = await engine.readPageSnapshot(request.key.ownerKey.slice('depth:'.length), { sourceId: request.key.sourceId, includeDeleted: true });
  const activation: ActivationIntent & { expected_revision: string | null } = { ...plan.intent, runKey: plan.intent.activationId,
    expected_revision: depth?.revision ?? null, ...(depth?.page.deleted_at ? { deleted_page: true } : {}) };
  await submitDatabaseMaintenanceIntent(engine, maintenance, request.key.ownerKey.slice('depth:'.length), activation, plan.intent.activationId);
  const retired = plan.members.filter(member => member.action === 'retire').map(member => member.slug);
  return { state: 'published', generationId: 0, generation: plan.intent.expectedGeneration + 1, puts: [], kept: [], adopted: [], retired, protected: [] };
}

/** C-6: retires the events of up to `limit` depth pages of `sourceId` that are gone, each through `originGone`; returns the count. */
export async function retireOrphanedChronicleEvents(engine: BrainEngine, sourceId: string, maintenance?: MaintenanceAuthority | null, limit = 50): Promise<number> {
  let retired = 0;
  const keys = await orphanedDepthKeys(engine, sourceId, limit);
  if (keys.length && maintenance === undefined) maintenance = await maintenancePreflight(engine, sourceId);
  for (const ownerKey of keys) {
    const generation = await publishChronicleGeneration(engine, { sourceId, pin: null, depthSlug: ownerKey.slice('depth:'.length), events: [],
      decisionRequestId: null, replaces: true, proof: originGone(), maintenance });
    retired += generation.retired.length;
  }
  return retired;
}

interface ChronicleIntent extends Record<string, unknown> {
  kind: string;
  depth: ChronicleDepthPin;
  decision_request_id: string | null;
  owned_hashes: string[];
  restore_retired?: boolean;
  event_projection?: { depth_slug: string; date: string; summary: string };
}

/** Preparer for the two chronicle maintenance intents; validation re-runs under the publication's page locks. */
export async function prepareChronicleMutation(engine: BrainEngine, row: WriteRequest, config: GBrainConfig): Promise<PreparedMutation> {
  const p = row.intent as ChronicleIntent | null;
  if (!p || !p.depth || !Array.isArray(p.owned_hashes) || row.authority.remote) {
    throw opError('invalid_params', 'Unsupported Life Chronicle maintenance intent.',
      'Life Chronicle maintenance is submitted only by the chronicle phase on the brain host; let `gbrain dream --phase chronicle` resubmit it rather than replaying this request.');
  }
  const owned = new Set(p.owned_hashes);
  const retire = p.kind === CHRONICLE_RETIRE_INTENT;
  const check = async (tx: BrainEngine) => {
    const reason = await depthPinBroken(tx, row.source_id, p.depth, p.decision_request_id);
    if (reason) throw supersededError(reason);
    const target = await tx.readPageSnapshot(row.slug, { sourceId: row.source_id, includeDeleted: true });
    if (retire) {
      if (!target || target.page.deleted_at || !owned.has(String(target.page.content_hash ?? ''))) throw supersededError('event_changed');
      return;
    }
    const verdict = await judgeTarget(tx, row.source_id, target, owned);
    if (!verdict.write) throw supersededError(verdict.reason);
  };
  await check(engine);
  const operation = retire ? 'delete_page' : 'put_page';
  const intent = row.intent!.expected_revision === null ? { ...row.intent, expected_revision: undefined } : row.intent;
  const prepared = await preparePageMutation(engine, { ...row, operation, intent }, config, undefined, undefined, { allowMissingFile: true });
  return { ...prepared, additionalPageKeys: [...prepared.additionalPageKeys ?? [], { sourceId: row.source_id, slug: p.depth.slug }],
    validate: async (tx) => { await prepared.validate?.(tx); await check(tx); },
    apply: async (tx) => {
      const outcome = await prepared.apply(tx);
      if (retire) {
        if (!prepared.noop) await stampRetired(tx, row.source_id, row.slug);
        return { ...outcome, retired_by: CHRONICLE_RETIRED_BY };
      }
      const projection = p.event_projection;
      if (!projection) return outcome;
      const { projected } = await tx.upsertEventProjection({ depthSlug: projection.depth_slug, eventSlug: row.slug,
        date: projection.date, summary: projection.summary, sourceId: row.source_id });
      const trust = derivationWriteTrust({ derivation: p.derivation } as never);
      if (projected && trust) {
        const assessment = assessTimelineForGate({ summary: projection.summary, source: `life-chronicle:event:${row.slug}` },
          derivedGateInput(trust, row.id), await derivedGateConfig(tx));
        const [event] = await tx.executeRaw<{ id: number }>('SELECT id FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [row.source_id, row.slug]);
        if (event) await recordProjectionFlag(tx, assessment, Number(event.id), projection.date, row.source_id, row.id);
      }
      return { ...outcome, event_projected: projected };
    } };
}

/** A retirement journaled by an earlier release (`managed_maintenance_chronicle_retire`): the stamp, and its projection row goes with it (C-3). */
async function stampRetired(tx: BrainEngine, sourceId: string, slug: string): Promise<void> {
  await stampDerivedRetirement(tx, sourceId, [slug], CHRONICLE_RETIRED_BY);
  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=$2', [sourceId, slug]);
}

/** A flagged event projection's receipt on its timeline row (found by its event page and date). */
async function recordProjectionFlag(tx: BrainEngine, assessment: WriteGateAssessment, eventPageId: number, date: string, sourceId: string, requestId?: 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, requestId });
}