Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.3 KB
Raw Blame
/**
 * The row-level write gate for derivers (#5575 B3, ENG-18): the gate input
 * is exactly the tier the deriver declared (trust/taint.ts). Each writer
 * calls decideFactWrite / decideTakeWrite / assessTimelineForGate itself
 * (write-gate-store.ts, write-gate.ts); these helpers read the gate config
 * once per run and apply one decision inside the writer's transaction.
 * A deriver never throws for one row: a held row goes to write_gate_holds, a
 * rejected row is skipped and counted.
 */
import type { BrainEngine } from '../engine.ts';
import { loadImportSanityConfig } from '../import-screen.ts';
import { DEFAULT_WRITE_GATE_CONFIG, type WriteGateConfig, type WriteGateInput } from '../write-gate.ts';
import { recordFlaggedRow, recordWriteGateHold, recordWriteGateReceipt, type GatedRowDecision } from '../write-gate-store.ts';
import type { WriteGateAssessment } from '../write-gate.ts';
import type { WriteTrust } from './tier.ts';

/** `write_gate.*` as the import path reads it; unreadable values fall back to the defaults, never `off`. */
export async function derivedGateConfig(engine: BrainEngine): Promise<WriteGateConfig> {
  return (await loadImportSanityConfig(engine)).writeGate ?? DEFAULT_WRITE_GATE_CONFIG;
}

/** The gate input for a declared derivation. */
export function derivedGateInput(trust: WriteTrust, requestId?: string | null): WriteGateInput {
  return { tier: trust.tier, origin: trust.origin, requestId: requestId ?? trust.origin?.request_id ?? null };
}

/** What one run's gate did, for the run result. */
export interface GateTally { flagged: number; held: number; rejected: number }
export const emptyGateTally = (): GateTally => ({ flagged: 0, held: 0, rejected: 0 });
/** Sums two tallies; undefined while nothing was flagged, held or rejected (a run result shows the field only when the gate acted). */
export function mergeGateTally(into: GateTally | undefined, from: GateTally | undefined): GateTally | undefined {
  const sum = { flagged: (into?.flagged ?? 0) + (from?.flagged ?? 0), held: (into?.held ?? 0) + (from?.held ?? 0), rejected: (into?.rejected ?? 0) + (from?.rejected ?? 0) };
  return sum.flagged || sum.held || sum.rejected ? sum : undefined;
}

/**
 * Applies one decision inside the writer's transaction: `insert` runs the
 * insert and records the flag receipt on the new row; `hold` records the hold
 * instead of inserting; `reject` writes nothing. Returns the inserted id.
 */
export async function applyGateDecision(tx: BrainEngine, decision: GatedRowDecision, target: { table: 'facts' | 'takes'; sourceId: string },
  insert: () => Promise<number | null>, tally?: GateTally): Promise<number | null> {
  if (decision.action === 'reject') { if (tally) tally.rejected++; return null; }
  if (decision.action === 'hold') { await recordWriteGateHold(tx, decision.hold!); if (tally) tally.held++; return null; }
  const id = await insert();
  if (id !== null && await recordFlaggedRow(tx, decision, { table: target.table, id, sourceId: target.sourceId }) !== null && tally) tally.flagged++;
  return id;
}

/** Whether a timeline row's assessment lets it be written: timeline rows have no hold store, so quarantine and reject skip the row. */
export function timelineRowAllowed(assessment: WriteGateAssessment): boolean {
  return assessment.verdict === 'allow' || assessment.verdict === 'flag';
}

/**
 * Records a flagged timeline row's receipt after its insert, in the same
 * transaction. Batch inserts return no ids, so the row is found by its
 * natural key (page, date, summary, source).
 */
export async function recordTimelineFlag(tx: BrainEngine, assessment: WriteGateAssessment,
  row: { slug: string; source_id?: string; date: string; summary: string; source?: string | null }, requestId?: string | null): Promise<void> {
  if (assessment.verdict !== 'flag') return;
  const sourceId = row.source_id ?? 'default';
  const [entry] = await tx.executeRaw<{ id: number }>(`SELECT te.id FROM timeline_entries te JOIN pages p ON p.id=te.page_id
    WHERE p.source_id=$1 AND p.slug=$2 AND te.date=$3::date AND te.summary=$4 AND COALESCE(te.source,'')=COALESCE($5,'') ORDER BY te.id DESC LIMIT 1`,
  [sourceId, row.slug, row.date, row.summary, row.source ?? null]);
  if (entry) await recordWriteGateReceipt(tx, { targetTable: 'timeline_entries', targetId: Number(entry.id), sourceId, assessment, requestId });
}