Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.2 KB
Raw Blame
/**
 * I2 taint (#5575: ENG-3, CEO-1, ENG-7): the tier of a derived row is the
 * minimum over every input placed in the model's context for that
 * derivation, capped at agent_written, decided at prompt-build time. A
 * deriver collects the rows it put in the prompt (pages, facts, takes,
 * timeline entries), reads their stored tiers here, declares the result to
 * the attribution seam, and records the complete input edges
 * (`derivation_inputs`, facts/derivation-inputs.ts) right after it writes.
 *
 * Deterministic projections that restate an input without a model (a fence
 * or timeline parse) take the input's tier, capped at operator_curated,
 * instead of the agent_written cap.
 *
 * Text that is not a row (a transcript file, a caller's turn text) enters as
 * a lowering cap: `lowerTo`.
 */
import type { BrainEngine } from '../engine.ts';
import { recordDerivationInputs, type DerivationRef } from '../facts/derivation-inputs.ts';
import {
  OWNER_TIER_FLOOR, compareTrust, effectiveWriteTrust, isTrustTier, minTrust, storedTrustTier, trustRankSql,
  type TaintInput, type TaintTable, type TrustTier, type WriteOrigin, type WriteTrust,
} from './tier.ts';
import { frontmatterTrustCaps } from './channel.ts';
import { maintenanceTransaction } from '../persistence/attribution.ts';
import { propagateTierLowering } from './propagation.ts';

/** A row placed in a model's context: by id, or a page by its (source, slug) coordinate. */
/** `hidden`: the page exists but the caller may not read it, so it reads exactly as a missing page (GBRA-431). */
export type TaintRef = { table: TaintTable; id: number } | { table: 'pages'; sourceId: string; slug: string; hidden?: boolean };

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

/**
 * The stored tier of every referenced row, deduplicated. A row that no longer
 * exists reads as `unknown` (a page by slug keeps `source:slug` as its id), so
 * a vanished input can never raise the derived tier.
 */
export async function readTaintInputs(engine: Sql, refs: readonly TaintRef[]): Promise<TaintInput[]> {
  const ids = new Map<TaintTable, Set<number>>();
  const slugs = new Map<string, { source_id: string; slug: string; hidden?: boolean }>();
  for (const ref of refs) {
    if ('slug' in ref) slugs.set(`${ref.sourceId}:${ref.slug}`, { source_id: ref.sourceId, slug: ref.slug, ...(ref.hidden ? { hidden: true } : {}) });
    else if (Number.isSafeInteger(Number(ref.id))) (ids.get(ref.table) ?? ids.set(ref.table, new Set()).get(ref.table)!).add(Number(ref.id));
  }
  const found = new Map<string, TaintInput>();
  for (const [table, set] of ids) {
    const rows = await engine.executeRaw<{ id: number | string; trust_tier: string | null }>(
      `SELECT id,trust_tier FROM ${table} WHERE id=ANY($1::bigint[])`, [[...set]]);
    for (const row of rows) found.set(`${table}:${row.id}`, { table, id: Number(row.id), tier: storedTrustTier(row.trust_tier) });
    for (const id of set) if (!found.has(`${table}:${id}`)) found.set(`${table}:${id}`, { table, id, tier: 'unknown' });
  }
  if (slugs.size) {
    const rows = await engine.executeRaw<{ id: number | string; source_id: string; slug: string; trust_tier: string | null }>(
      `SELECT p.id,p.source_id,p.slug,p.trust_tier FROM pages p
        JOIN jsonb_to_recordset($1::text::jsonb) AS r(source_id text,slug text) ON p.source_id=r.source_id AND p.slug=r.slug`,
      [JSON.stringify([...slugs.values()].filter(s => !s.hidden).map(({ source_id, slug }) => ({ source_id, slug })))]);
    const bySlug = new Map(rows.map(row => [`${row.source_id}:${row.slug}`, row]));
    for (const [key] of slugs) {
      const row = bySlug.get(key);
      if (row) found.set(`pages:${row.id}`, { table: 'pages', id: Number(row.id), tier: storedTrustTier(row.trust_tier) });
      else found.set(`pages:${key}`, { table: 'pages', id: key, tier: 'unknown' });
    }
  }
  return [...found.values()];
}

/** The tier the frontmatter of a not-yet-imported page (a transcript file read from disk) names, or undefined. */
export function frontmatterTaint(frontmatter: Record<string, unknown> | null | undefined): TrustTier | undefined {
  const caps = frontmatterTrustCaps(frontmatter);
  return caps.length ? minTrust(caps[0], ...caps.slice(1)) : undefined;
}

export interface DerivedTrustInput {
  /** The write path, e.g. `derive:synthesize`, `derive:facts_backstop`. */
  channel: string;
  /** Every row placed in the model's context (ENG-3). */
  inputs: readonly TaintInput[];
  /** Tiers of context text that is not a row (caller turn text, a transcript file). */
  lowerTo?: readonly TrustTier[];
  requestId?: string | null;
  sourceUri?: string | null;
  /** A deterministic restatement of its inputs (no model): capped at operator_curated, not agent_written. */
  projection?: boolean;
}

/** The WriteTrust of one derivation, computed once (trust/tier.ts effectiveWriteTrust). */
export function derivedWriteTrust(input: DerivedTrustInput): WriteTrust {
  const lowerTo = [...input.lowerTo ?? []];
  if (input.projection && !input.inputs.length && !lowerTo.length) lowerTo.push('unknown');
  return effectiveWriteTrust({
    channel: input.projection ? OWNER_TIER_FLOOR : 'agent_written',
    derived: !input.projection,
    inputs: input.inputs,
    lowerTo,
    origin: { channel: input.channel, ...(input.requestId ? { request_id: input.requestId } : {}),
      ...(input.sourceUri ? { source_uri: input.sourceUri } : {}) },
  });
}

/** Reads the inputs' tiers and builds the derivation's WriteTrust in one call. */
export async function deriveTrust(engine: Sql, refs: readonly TaintRef[], input: Omit<DerivedTrustInput, 'inputs'>):
  Promise<{ trust: WriteTrust; inputs: TaintInput[] }> {
  const inputs = await readTaintInputs(engine, refs);
  return { trust: derivedWriteTrust({ ...input, inputs }), inputs };
}

/**
 * ENG-7: the complete input edges of one derived row, written in the same
 * transaction right after the row. Inputs read as `unknown` because they
 * vanished keep their recorded reference.
 */
export async function recordTaintEdges(tx: BrainEngine, derived: { table: TaintTable; id: number; sourceId?: string | null },
  inputs: readonly Pick<TaintInput, 'table' | 'id'>[]): Promise<void> {
  if (!inputs.length) return;
  await recordDerivationInputs(tx, derived, inputs.map(({ table, id }): DerivationRef => ({ table, id })));
}

/**
 * Lowers rows to a derivation's tier, never raising. A derived write that
 * changes no content column (a re-promotion that only refreshes `source`, a
 * provenance republish with identical content) keeps the stored tier under
 * the trigger rule, so the deriver lowers explicitly; the trigger allows any
 * lowering. Returns the ids lowered.
 */
export async function lowerToDerivedTier(tx: Sql, table: TaintTable, ids: readonly number[], trust: WriteTrust): Promise<number[]> {
  if (!ids.length) return [];
  const rows = await tx.executeRaw<{ id: number | string }>(
    `UPDATE ${table} SET trust_tier=$2,write_origin=$3::text::jsonb
      WHERE id=ANY($1::bigint[]) AND ${trustRankSql('trust_tier')}>${trustRankSql('$2::text')} RETURNING id`,
    [[...ids], trust.tier, trust.origin ? JSON.stringify(trust.origin) : null]);
  const lowered = rows.map(row => Number(row.id));
  // W1 #6783 §12 (b): what was derived from a lowered row follows it down.
  if (lowered.length) await propagateTierLowering(tx as BrainEngine, lowered.map(id => ({ table, id })));
  return lowered;
}

/**
 * A row a derivation wrote, for the lowering and edge pass. `prior` (#7917): an existing page's slug and the tier and
 * revision read before the write, so a page the derivation lowered files a `lower_page` proposal for the owner.
 */
export interface DerivedRowRef { table: TaintTable; id: number; sourceId?: string | null; prior?: { slug: string; tier: TrustTier; revision: string | null } }

/**
 * An unmanaged deriver's write: one attributed maintenance transaction at the
 * derivation's tier; every row `fn` reports is lowered to that tier (when its
 * content did not change) and gets its complete input edges.
 */
export async function derivedMaintenanceTransaction<T>(engine: BrainEngine, derivation: { trust: WriteTrust; inputs: readonly TaintInput[] },
  fn: (tx: BrainEngine) => Promise<{ result: T; rows: readonly DerivedRowRef[] }>): Promise<T> {
  return maintenanceTransaction(engine, async tx => {
    const { result, rows } = await fn(tx);
    for (const row of rows) {
      await lowerToDerivedTier(tx, row.table, [row.id], derivation.trust);
      await recordTaintEdges(tx, row, derivation.inputs);
      if (row.table !== 'pages' || !row.prior || !row.sourceId) continue;
      const { recordAgentPageLowering } = await import('./page-write.ts');
      await recordAgentPageLowering(tx, { operation: 'derived_maintenance', source_id: row.sourceId, slug: row.prior.slug }, row.prior,
        `derived_page:${String(derivation.trust.origin?.channel ?? 'maintenance')}`);
    }
    return result;
  }, derivation.trust);
}

/**
 * A derived page written through a path that stamps by its own channel (an
 * unmanaged importFromContent): lowers the live page to the derivation's
 * taint and records its edges, in one attributed transaction.
 */
export async function lowerDerivedPage(engine: BrainEngine, derivation: { trust: WriteTrust; inputs: readonly TaintInput[] },
  sourceId: string, slug: string): Promise<void> {
  await maintenanceTransaction(engine, tx => lowerDerivedPageIn(tx, derivation, sourceId, slug), derivation.trust);
}

/** lowerDerivedPage inside a caller's transaction (a managed brain's coordinated write). */
export async function lowerDerivedPageIn(tx: BrainEngine, derivation: { trust: WriteTrust; inputs: readonly TaintInput[] },
  sourceId: string, slug: string): Promise<void> {
  for (const row of await tx.executeRaw<{ id: number }>('SELECT id FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [sourceId, slug])) {
    await lowerToDerivedTier(tx, 'pages', [Number(row.id)], derivation.trust);
    await recordTaintEdges(tx, { table: 'pages', id: Number(row.id), sourceId }, derivation.inputs);
  }
}

// ---------------------------------------------------------------------------
// Declarations carried in a journaled maintenance intent
// ---------------------------------------------------------------------------

/**
 * A derivation declared by the deriver at prompt-build time and carried in its
 * maintenance or facts request intent, so the preparer stamps the same tier
 * and records the same edges when the coordinator publishes it.
 */
export interface DerivationDeclaration { tier: TrustTier; origin: WriteOrigin; inputs: Array<Pick<TaintInput, 'table' | 'id'>> }

export function declareDerivation(trust: WriteTrust, inputs: readonly TaintInput[]): DerivationDeclaration {
  return { tier: trust.tier, origin: trust.origin ?? { channel: 'derive:unnamed' }, inputs: inputs.map(({ table, id }) => ({ table, id })) };
}

const TAINT_TABLES: readonly string[] = ['facts', 'takes', 'pages', 'timeline_entries'];

/** A declaration read back from a stored intent, or null when absent or malformed. */
export function readDerivationDeclaration(value: unknown): DerivationDeclaration | null {
  const v = value as Partial<DerivationDeclaration> | null | undefined;
  if (!v || typeof v !== 'object' || !isTrustTier(v.tier) || !v.origin || typeof v.origin.channel !== 'string' || !Array.isArray(v.inputs)) return null;
  if (v.inputs.some(i => !i || !TAINT_TABLES.includes(i.table as string) || (typeof i.id !== 'number' && typeof i.id !== 'string'))) return null;
  return v as DerivationDeclaration;
}

/**
 * The WriteTrust a preparer declares for a stored derivation: never above
 * `ceiling` (agent_written for model output) and never above any input in its
 * sample. A missing declaration (an intent queued before tiers) is `unknown`.
 */
export function declaredWriteTrust(declaration: DerivationDeclaration | null, ceiling: TrustTier = 'agent_written'): WriteTrust {
  if (!declaration) return { tier: minTrust('unknown', ceiling), origin: null };
  const sample = (declaration.origin.taint_inputs ?? []).map(i => storedTrustTier(i.tier));
  const tier = minTrust(declaration.tier, ceiling, ...sample);
  return { tier, origin: declaration.origin };
}

/** Whether `tier` is external_untrusted (or lower): the partition rule's test (ENG-3). */
export function isExternalTier(tier: TrustTier): boolean {
  return compareTrust(tier, 'external_untrusted') <= 0;
}

/**
 * CEO-24 diagnostic (never gated): how many derived rows (those whose
 * `write_origin` carries `taint_inputs`) are stamped external_untrusted, across
 * facts, takes, timeline entries and pages. One scan per table, like the tier
 * counts beside it in doctor.
 */
export async function readDerivedTaintShare(engine: Sql): Promise<{ rows: number; external_untrusted: number; external_pct: number }> {
  let rows = 0, external = 0;
  for (const table of ['facts', 'takes', 'timeline_entries', 'pages'] as const) {
    const [row] = await engine.executeRaw<{ derived: number | string; external: number | string }>(
      `SELECT count(*) FILTER (WHERE write_origin ? 'taint_inputs') AS derived,
              count(*) FILTER (WHERE write_origin ? 'taint_inputs' AND trust_tier = 'external_untrusted') AS external FROM ${table}`);
    rows += Number(row?.derived ?? 0);
    external += Number(row?.external ?? 0);
  }
  return { rows, external_untrusted: external, external_pct: rows === 0 ? 0 : Math.round((external / rows) * 10_000) / 100 };
}