Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.0 KB
Raw Blame
/**
 * #5575 write gate persistence: verdict receipts (`write_gate_receipts`) and
 * the holding table for quarantined facts and takes (`write_gate_holds`),
 * DDL in `write-gate-schema.ts`.
 *
 * Writers record inside their publication transaction (pass the `tx`), so a
 * rolled-back write leaves no orphan receipt. Only flag and quarantine
 * verdicts are recorded; `allow` and `reject` write nothing here. Owner
 * review (`gbrain trust release|drop`, `gbrain quarantine list`) reads and
 * decides holds through the list/release/drop functions; releasing a hold
 * returns its payload so the confirm path can publish it at `user_confirmed`
 * in the same transaction.
 */
import { createHash } from 'node:crypto';
import type { BrainEngine } from './engine.ts';
import { noteBelief } from './belief/ledger.ts';
import {
  assessFactForGate, assessTakeForGate, normalizeForGate,
  type GateFactRow, type GateTakeRow, type WriteGateAssessment, type WriteGateConfig, type WriteGateInput, type WriteGateOrigin, type WriteGateReasonFamily,
} from './write-gate.ts';

type Exec = Pick<BrainEngine, 'executeRaw'>;

export type WriteGateTargetTable = 'pages' | 'facts' | 'takes' | 'timeline_entries' | 'write_gate_holds';
export type WriteGateHoldKind = 'fact' | 'take';
export type WriteGateHoldStatus = 'held' | 'released' | 'dropped';

/** Receipts not seen again for this long are pruned. */
export const WRITE_GATE_RECEIPT_RETENTION_DAYS = 365;

const RECORDED: ReadonlySet<string> = new Set(['flag', 'quarantine']);
const recorded = (a: WriteGateAssessment): a is WriteGateAssessment & { contentHash: string } => RECORDED.has(a.verdict) && a.contentHash !== null;

function reasonList(a: WriteGateAssessment): string[] {
  return a.hits.map(h => `${h.field}:${h.pattern}`);
}

const RECEIPT_COLUMNS = 'target_table, target_id, source_id, content_hash, tier, detector_version, verdict, reason_families, reasons, detector_error, request_id';
const RECEIPT_UPSERT = `ON CONFLICT (target_table, target_id, content_hash, detector_version) DO UPDATE
  SET last_seen_at = now(), verdict = EXCLUDED.verdict, tier = EXCLUDED.tier, reason_families = EXCLUDED.reason_families,
      reasons = EXCLUDED.reasons, detector_error = EXCLUDED.detector_error, request_id = COALESCE(EXCLUDED.request_id, write_gate_receipts.request_id)
  RETURNING id::text AS id`;

function receiptParams(a: WriteGateAssessment, requestId: string | null | undefined): unknown[] {
  return [a.contentHash, a.tier, a.detectorVersion, a.verdict, a.families, reasonList(a), a.detectorError, requestId ?? null];
}

/** Record a flag or quarantine verdict on a persisted row; returns the receipt id (null for allow/reject). */
export async function recordWriteGateReceipt(tx: Exec, input: {
  targetTable: WriteGateTargetTable; targetId: string | number; sourceId?: string | null; assessment: WriteGateAssessment; requestId?: string | null;
}): Promise<number | null> {
  if (!recorded(input.assessment)) return null;
  const rows = await tx.executeRaw<{ id: string }>(
    `INSERT INTO write_gate_receipts (${RECEIPT_COLUMNS})
     VALUES ($9, $10, $11, $1, $2, $3, $4, $5::text[], $6::text[], $7, $8) ${RECEIPT_UPSERT}`,
    [...receiptParams(input.assessment, input.requestId), input.targetTable, String(input.targetId), input.sourceId ?? null]);
  return rows[0] ? Number(rows[0].id) : null;
}

/** Record a page verdict, resolving the live page id by (source_id, slug) inside the caller's transaction. */
export async function recordPageGateReceipt(tx: Exec, input: {
  slug: string; sourceId: string; assessment: WriteGateAssessment; requestId?: string | null;
}): Promise<number | null> {
  if (!recorded(input.assessment)) return null;
  const rows = await tx.executeRaw<{ id: string }>(
    `INSERT INTO write_gate_receipts (${RECEIPT_COLUMNS})
     SELECT 'pages', p.id::text, p.source_id, $1, $2, $3, $4, $5::text[], $6::text[], $7, $8
       FROM pages p WHERE p.source_id = $9 AND p.slug = $10 AND p.deleted_at IS NULL
     ${RECEIPT_UPSERT}`,
    [...receiptParams(input.assessment, input.requestId), input.sourceId, input.slug]);
  return rows[0] ? Number(rows[0].id) : null;
}

/**
 * ENG-11 (L1b contract): a page rewrite the gate assessed again replaces the
 * verdict of the content it replaced, so receipts on the page for any other
 * content hash are removed (an allowed benign rewrite stops being suppressed).
 */
export async function clearStalePageGateReceipts(tx: Exec, input: { slug: string; sourceId: string; contentHash: string | null }): Promise<void> {
  await tx.executeRaw(`DELETE FROM write_gate_receipts r USING pages p
    WHERE r.target_table = 'pages' AND r.target_id = p.id::text AND p.source_id = $1 AND p.slug = $2 AND r.content_hash IS DISTINCT FROM $3`,
  [input.sourceId, input.slug, input.contentHash]);
}

/** Dedupe key for a held row: its kind plus the normalized text of every gated field. */
export function holdFingerprint(kind: WriteGateHoldKind, texts: ReadonlyArray<string | null | undefined>): string {
  return createHash('sha256').update(`${kind}\u0000${texts.map(t => normalizeForGate(t ?? '').toLowerCase().replace(/\s+/g, ' ').trim()).join('\u0001')}`).digest('hex');
}

export interface WriteGateHoldInput {
  kind: WriteGateHoldKind;
  sourceId: string;
  /** The page the row would have landed on ('' when not page-bound). */
  slug?: string | null;
  /** The row exactly as the writer would have inserted it. */
  payload: Record<string, unknown>;
  /** Gated text fields of the row, for the dedupe fingerprint. */
  texts: ReadonlyArray<string | null | undefined>;
  assessment: WriteGateAssessment;
  origin?: WriteGateOrigin | null;
  requestId?: string | null;
}

/**
 * Hold a quarantined fact or take instead of inserting it, plus its receipt.
 * The same content arriving again (same source, slug, fingerprint and
 * detector version) re-opens the existing hold rather than adding a row.
 */
export async function recordWriteGateHold(tx: Exec, input: WriteGateHoldInput): Promise<{ holdId: number; receiptId: number | null }> {
  const a = input.assessment;
  const rows = await tx.executeRaw<{ id: string }>(
    `INSERT INTO write_gate_holds (kind, source_id, slug, fingerprint, detector_version, tier, reason_families, reasons, detector_error, payload, write_origin, request_id)
     VALUES ($1, $2, $3, $4, $5, $6, $7::text[], $8::text[], $9, $10::text::jsonb, $11::text::jsonb, $12)
     ON CONFLICT (source_id, slug, fingerprint, detector_version) DO UPDATE
       SET status = 'held', decided_at = NULL, decided_by = NULL, last_seen_at = now(), seen_count = write_gate_holds.seen_count + 1,
           tier = EXCLUDED.tier, reason_families = EXCLUDED.reason_families, reasons = EXCLUDED.reasons, payload = EXCLUDED.payload,
           write_origin = EXCLUDED.write_origin, request_id = COALESCE(EXCLUDED.request_id, write_gate_holds.request_id)
     RETURNING id::text AS id`,
    [input.kind, input.sourceId, input.slug ?? '', holdFingerprint(input.kind, input.texts), a.detectorVersion, a.tier, a.families, reasonList(a),
      a.detectorError, JSON.stringify(input.payload), input.origin ? JSON.stringify(input.origin) : null, input.requestId ?? null]);
  const holdId = Number(rows[0]!.id);
  const fingerprint = holdFingerprint(input.kind, input.texts);
  noteBelief({ kind: 'held', holdKind: input.kind, fingerprint, holdId, slug: input.slug ?? '', tier: a.tier, valueHash: fingerprint });
  const receiptId = await recordWriteGateReceipt(tx, { targetTable: 'write_gate_holds', targetId: holdId, sourceId: input.sourceId, assessment: { ...a, verdict: 'quarantine' }, requestId: input.requestId });
  return { holdId, receiptId };
}

export interface WriteGateHold {
  id: number;
  ref: string;
  kind: WriteGateHoldKind;
  source_id: string;
  slug: string;
  tier: string;
  detector_version: number;
  detector_error: boolean;
  reason_families: WriteGateReasonFamily[];
  reasons: string[];
  payload: Record<string, unknown>;
  write_origin: WriteGateOrigin | null;
  request_id: string | null;
  status: WriteGateHoldStatus;
  seen_count: number;
  created_at: string;
  last_seen_at: string;
  decided_at: string | null;
  decided_by: string | null;
}

const ISO = (col: string) => `to_char(${col} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')`;
const HOLD_SELECT = `SELECT id::text AS id, kind, source_id, slug, tier, detector_version, detector_error, reason_families, reasons, payload, write_origin,
  request_id, status, seen_count, ${ISO('created_at')} AS created_at, ${ISO('last_seen_at')} AS last_seen_at, ${ISO('decided_at')} AS decided_at, decided_by
  FROM write_gate_holds`;

type HoldRow = Omit<WriteGateHold, 'id' | 'ref' | 'payload' | 'write_origin'> & { id: string; payload: unknown; write_origin: unknown };

function jsonObject(value: unknown): Record<string, unknown> | null {
  const parsed = typeof value === 'string' ? JSON.parse(value) as unknown : value;
  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
}

function toHold(row: HoldRow): WriteGateHold {
  const id = Number(row.id);
  return {
    ...row, id, ref: `h${id}`, detector_version: Number(row.detector_version), seen_count: Number(row.seen_count),
    payload: jsonObject(row.payload) ?? {}, write_origin: jsonObject(row.write_origin) as WriteGateOrigin | null,
  };
}

/** `h12` (or `12`) -> 12; null when the ref is not a hold ref. */
export function parseHoldRef(ref: string): number | null {
  const m = /^h?(\d{1,18})$/.exec(ref.trim());
  return m ? Number(m[1]) : null;
}

export interface ListWriteGateHoldsOpts {
  status?: WriteGateHoldStatus | 'all';
  kind?: WriteGateHoldKind;
  sourceId?: string;
  sourceIds?: string[];
  /** Keyset: only holds with id below this (newest first). */
  beforeId?: number;
  limit?: number;
}

/** Holds, newest first; default status `held`, limit 200. */
export async function listWriteGateHolds(engine: Exec, opts: ListWriteGateHoldsOpts = {}): Promise<WriteGateHold[]> {
  const where: string[] = [];
  const params: unknown[] = [];
  const bind = (v: unknown) => { params.push(v); return `$${params.length}`; };
  const status = opts.status ?? 'held';
  if (status !== 'all') where.push(`status = ${bind(status)}`);
  if (opts.kind) where.push(`kind = ${bind(opts.kind)}`);
  if (opts.sourceIds?.length) where.push(`source_id = ANY(${bind(opts.sourceIds)}::text[])`);
  else if (opts.sourceId) where.push(`source_id = ${bind(opts.sourceId)}`);
  if (opts.beforeId !== undefined) where.push(`id < ${bind(opts.beforeId)}`);
  const limit = Math.max(1, Math.min(opts.limit ?? 200, 1000));
  const rows = await engine.executeRaw<HoldRow>(
    `${HOLD_SELECT} ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY id DESC LIMIT ${bind(limit)}`, params);
  return rows.map(toHold);
}

export async function getWriteGateHold(engine: Exec, id: number): Promise<WriteGateHold | null> {
  const rows = await engine.executeRaw<HoldRow>(`${HOLD_SELECT} WHERE id = $1`, [id]);
  return rows[0] ? toHold(rows[0]) : null;
}

async function decideHold(tx: Exec, id: number, status: Exclude<WriteGateHoldStatus, 'held'>, decidedBy: string): Promise<WriteGateHold | null> {
  const rows = await tx.executeRaw<{ id: string }>(
    `UPDATE write_gate_holds SET status = $2, decided_at = now(), decided_by = $3 WHERE id = $1 AND status = 'held' RETURNING id::text AS id`,
    [id, status, decidedBy]);
  return rows[0] ? getWriteGateHold(tx, id) : null;
}

/**
 * Mark a held row released and return it (payload included) so the caller's
 * confirm path publishes it at `user_confirmed` in the same transaction. Null
 * when the hold does not exist or was already decided. Authorization (TTY
 * confirmation or `memory_confirm`, CEO-9) is the caller's job.
 */
export function releaseWriteGateHold(tx: Exec, id: number, decidedBy: string): Promise<WriteGateHold | null> {
  return decideHold(tx, id, 'released', decidedBy);
}

/** Mark a held row dropped (kept as a decided record, payload included). Null when not held. */
export function dropWriteGateHold(tx: Exec, id: number, decidedBy: string): Promise<WriteGateHold | null> {
  return decideHold(tx, id, 'dropped', decidedBy);
}

/** Delete receipts not seen for `olderThanDays` (default 365). Holds keep their receipts while held. */
export async function pruneWriteGateReceipts(engine: Exec, olderThanDays = WRITE_GATE_RECEIPT_RETENTION_DAYS): Promise<number> {
  const rows = await engine.executeRaw<{ id: string }>(
    `DELETE FROM write_gate_receipts r
      WHERE r.last_seen_at < now() - make_interval(days => $1)
        AND NOT (r.target_table = 'write_gate_holds' AND EXISTS (SELECT 1 FROM write_gate_holds h WHERE h.id::text = r.target_id AND h.status = 'held'))
      RETURNING r.id::text AS id`, [olderThanDays]);
  return rows.length;
}

/**
 * What a fact or take writer does with one row (B3/B4):
 *   - `insert`: write the row; when `assessment.verdict` is `flag`, call
 *     `recordFlaggedRow` with the inserted id in the same transaction.
 *   - `hold`: do not insert; call `recordWriteGateHold(tx, hold)` and return
 *     the verb error `write_held` (`writeHeldError`).
 *   - `reject`: do not insert; refuse with `writeGateRejectedError`.
 */
export interface GatedRowDecision {
  assessment: WriteGateAssessment;
  action: 'insert' | 'hold' | 'reject';
  hold: WriteGateHoldInput | null;
  requestId: string | null;
}

export interface GatedRowContext {
  sourceId: string;
  slug?: string | null;
  /** The row exactly as the writer would insert it (kept in the hold). */
  payload: Record<string, unknown>;
  input: WriteGateInput;
  cfg: WriteGateConfig;
}

function decide(kind: WriteGateHoldKind, assessment: WriteGateAssessment, texts: ReadonlyArray<string | null | undefined>, ctx: GatedRowContext): GatedRowDecision {
  const requestId = ctx.input.requestId ?? null;
  if (assessment.verdict === 'reject') return { assessment, action: 'reject', hold: null, requestId };
  if (assessment.verdict !== 'quarantine') return { assessment, action: 'insert', hold: null, requestId };
  return {
    assessment, action: 'hold', requestId,
    hold: { kind, sourceId: ctx.sourceId, slug: ctx.slug ?? '', payload: ctx.payload, texts, assessment, origin: ctx.input.origin ?? null, requestId: ctx.input.requestId ?? null },
  };
}

export function decideFactWrite(row: GateFactRow, ctx: GatedRowContext): GatedRowDecision {
  return decide('fact', assessFactForGate(row, ctx.input, ctx.cfg), [row.fact, row.context, row.value], ctx);
}

export function decideTakeWrite(row: GateTakeRow, ctx: GatedRowContext): GatedRowDecision {
  return decide('take', assessTakeForGate(row, ctx.input, ctx.cfg), [row.claim, row.source, row.evidence], ctx);
}

/** Record a flagged row's receipt after insert (no-op unless the verdict is `flag`). */
export function recordFlaggedRow(tx: Exec, decision: GatedRowDecision, target: { table: 'facts' | 'takes' | 'timeline_entries'; id: string | number; sourceId: string }): Promise<number | null> {
  if (decision.assessment.verdict !== 'flag') return Promise.resolve(null);
  return recordWriteGateReceipt(tx, { targetTable: target.table, targetId: target.id, sourceId: target.sourceId, assessment: decision.assessment, requestId: decision.requestId });
}