Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.5 KB
Raw Blame
/**
 * Relationship state refresh (temporal typed edges): one SQL implementation
 * for both engines. Reads every piece of evidence for the given relationships
 * (`links` assertions + `link_transitions`), runs the pure
 * `buildRelationshipState`, and upserts one `link_relationships` row per read
 * scope:
 *
 *   all    evidence from every live origin page in the relationship's source
 *   world  the same minus evidence from private origins, so private notes
 *          never change what a remote caller sees
 *
 * Callers run this inside the transaction that changed the evidence (link
 * writes, derived-link replacement, transition replacement), so state and
 * evidence commit together. Evidence from soft-deleted origins, from origins in
 * another source, or attached to a soft-deleted endpoint does not count.
 * Relationships with no remaining evidence lose their state row (and then read
 * as live, the same as an unrefreshed relationship).
 */
import { createHash } from 'node:crypto';
import type { BrainEngine } from './engine.ts';
import { executeRawJsonb } from './sql-query.ts';
import { privatePagesFilterFragment } from './search/private-visibility.ts';
import {
  buildRelationshipState, relationSemantics, statusAt, stintsToMultirange, dateKey, temporalLinkTypes,
  type AssertionEvidence, type TransitionEvidence, type RelationshipScope, type TransitionProducer,
} from './link-validity.ts';

export interface RelationshipKey { from_page_id: number; to_page_id: number; link_type: string }

type RawExec = { executeRaw<R = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<R[]> };

const keyOf = (k: RelationshipKey) => `${k.from_page_id}\0${k.to_page_id}\0${k.link_type}`;

/** Dedupe keys and keep only temporal (state/event) relation types. */
export function temporalKeys(keys: Iterable<RelationshipKey>): RelationshipKey[] {
  const out = new Map<string, RelationshipKey>();
  for (const k of keys) {
    if (!k || relationSemantics(k.link_type) === 'reference') continue;
    const from = Number(k.from_page_id), to = Number(k.to_page_id);
    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to)) continue;
    out.set(keyOf(k), { from_page_id: from, to_page_id: to, link_type: k.link_type });
  }
  return [...out.values()];
}

interface AssertionRow { from_page_id: number; to_page_id: number; link_type: string; origin_id: number; tense: string; created_at: unknown; source_id: string; origin_public: boolean }
interface TransitionRow { from_page_id: number; to_page_id: number; link_type: string; origin_id: number | null; kind: string; occurred_on: unknown; producer: string; created_at: unknown; source_id: string; origin_public: boolean }
interface ExistingRow { from_page_id: number; to_page_id: number; link_type: string; scope: RelationshipScope; recorded_at: unknown; retired_at: unknown; evidence_hash: string }

/** Refresh the state of `keys`. Returns the number of state rows written or removed. */
export async function refreshRelationships(exec: RawExec, keys: Iterable<RelationshipKey>): Promise<number> {
  const rows = temporalKeys(keys);
  if (rows.length === 0) return 0;
  const payload = { rows };
  const assertions = await executeRawJsonb<AssertionRow>(exec,
    `SELECT v.from_page_id, v.to_page_id, v.link_type,
            COALESCE(l.origin_page_id, l.from_page_id) AS origin_id,
            COALESCE(l.assertion_tense, 'present') AS tense, l.created_at, f.source_id,
            (${privatePagesFilterFragment('o')}) AS origin_public
       FROM jsonb_to_recordset(($1::jsonb)->'rows') AS v(from_page_id int, to_page_id int, link_type text)
       JOIN links l ON l.from_page_id = v.from_page_id AND l.to_page_id = v.to_page_id AND l.link_type = v.link_type
       JOIN pages f ON f.id = l.from_page_id AND f.deleted_at IS NULL
       JOIN pages t ON t.id = l.to_page_id AND t.deleted_at IS NULL
       JOIN pages o ON o.id = COALESCE(l.origin_page_id, l.from_page_id) AND o.deleted_at IS NULL AND o.source_id = f.source_id`,
    [], [payload]);
  const transitions = await executeRawJsonb<TransitionRow>(exec,
    `SELECT v.from_page_id, v.to_page_id, v.link_type, lt.origin_page_id AS origin_id, lt.kind,
            lt.occurred_on::text AS occurred_on, lt.producer, lt.created_at, f.source_id,
            (o.id IS NULL OR ${privatePagesFilterFragment('o')}) AS origin_public
       FROM jsonb_to_recordset(($1::jsonb)->'rows') AS v(from_page_id int, to_page_id int, link_type text)
       JOIN link_transitions lt ON lt.from_page_id = v.from_page_id AND lt.to_page_id = v.to_page_id AND lt.link_type = v.link_type
       JOIN pages f ON f.id = lt.from_page_id AND f.deleted_at IS NULL
       JOIN pages t ON t.id = lt.to_page_id AND t.deleted_at IS NULL
       LEFT JOIN pages o ON o.id = lt.origin_page_id
      WHERE lt.origin_page_id IS NULL OR (o.deleted_at IS NULL AND o.source_id = f.source_id)`,
    [], [payload]);
  const existing = await executeRawJsonb<ExistingRow>(exec,
    `SELECT lr.from_page_id, lr.to_page_id, lr.link_type, lr.scope, lr.recorded_at, lr.retired_at, lr.evidence_hash
       FROM jsonb_to_recordset(($1::jsonb)->'rows') AS v(from_page_id int, to_page_id int, link_type text)
       JOIN link_relationships lr ON lr.from_page_id = v.from_page_id AND lr.to_page_id = v.to_page_id AND lr.link_type = v.link_type`,
    [], [payload]);

  const byKey = new Map<string, { a: AssertionRow[]; t: TransitionRow[] }>();
  const bucket = (k: RelationshipKey) => {
    const id = keyOf(k);
    let b = byKey.get(id);
    if (!b) { b = { a: [], t: [] }; byKey.set(id, b); }
    return b;
  };
  for (const a of assertions) bucket(a).a.push(a);
  for (const t of transitions) bucket(t).t.push(t);
  const prior = new Map(existing.map(e => [`${keyOf(e)}\0${e.scope}`, e]));

  let changed = 0;
  const upserts: Array<Record<string, unknown>> = [];
  const removals: Array<{ from_page_id: number; to_page_id: number; link_type: string; scope: RelationshipScope }> = [];
  const now = new Date();
  for (const key of rows) {
    const evidence = byKey.get(keyOf(key));
    const semantics = relationSemantics(key.link_type) as 'state' | 'event';
    for (const scope of ['all', 'world'] as const) {
      const a = (evidence?.a ?? []).filter(r => scope === 'all' || r.origin_public);
      const t = (evidence?.t ?? []).filter(r => scope === 'all' || r.origin_public);
      const before = prior.get(`${keyOf(key)}\0${scope}`);
      if (a.length === 0 && t.length === 0) {
        if (before) removals.push({ ...key, scope });
        continue;
      }
      const state = buildRelationshipState(semantics,
        a.map((r): AssertionEvidence => ({ tense: r.tense === 'past' ? 'past' : 'present', originPageId: Number(r.origin_id) })),
        t.map((r): TransitionEvidence => ({ kind: r.kind === 'end' ? 'end' : 'start', occurredOn: String(dateKey(r.occurred_on)), producer: r.producer as TransitionProducer, originPageId: r.origin_id == null ? null : Number(r.origin_id) })));
      const status = statusAt(state);
      const hash = evidenceHash(a, t);
      const earliest = [...a.map(r => r.created_at), ...t.map(r => r.created_at), before?.recorded_at]
        .map(v => (v instanceof Date ? v : v == null ? null : new Date(String(v))))
        .filter((d): d is Date => !!d && Number.isFinite(d.getTime()))
        .sort((x, y) => x.getTime() - y.getTime())[0] ?? now;
      const ended = status === 'ended' || status === 'ended_unknown_date';
      const priorRetired = before?.retired_at == null ? null : before.retired_at instanceof Date ? before.retired_at : new Date(String(before.retired_at));
      const retiredAt = ended ? (priorRetired ?? now) : null;
      upserts.push({
        ...key, scope, source_id: (a[0] ?? t[0]).source_id, semantics,
        valid_ranges: stintsToMultirange(state.stints), status_now: status,
        first_start: state.firstStart, last_start: state.lastStart, last_end: state.lastEnd,
        undated_present: state.undatedPresent, undated_past: state.undatedPast, disputed: state.disputed,
        recorded_at: earliest.toISOString(), retired_at: retiredAt ? retiredAt.toISOString() : null,
        evidence_hash: hash,
      });
      if (!before || before.evidence_hash !== hash || (before.retired_at == null) !== (retiredAt == null)) changed++;
    }
  }

  if (upserts.length) {
    const written = await executeRawJsonb(exec,
      `INSERT INTO link_relationships (from_page_id, to_page_id, link_type, scope, source_id, semantics, valid_ranges,
         status_now, first_start, last_start, last_end, undated_present, undated_past, disputed, recorded_at, retired_at,
         evidence_hash, refreshed_at)
       SELECT v.from_page_id, v.to_page_id, v.link_type, v.scope, v.source_id, v.semantics, v.valid_ranges::datemultirange,
              v.status_now, v.first_start, v.last_start, v.last_end, v.undated_present, v.undated_past, v.disputed,
              v.recorded_at, v.retired_at, v.evidence_hash, now()
         FROM jsonb_to_recordset(($1::jsonb)->'rows') AS v(from_page_id int, to_page_id int, link_type text, scope text,
           source_id text, semantics text, valid_ranges text, status_now text, first_start date, last_start date,
           last_end date, undated_present int, undated_past int, disputed boolean, recorded_at timestamptz,
           retired_at timestamptz, evidence_hash text)
       ON CONFLICT (from_page_id, to_page_id, link_type, scope) DO UPDATE SET
         source_id = EXCLUDED.source_id, semantics = EXCLUDED.semantics, valid_ranges = EXCLUDED.valid_ranges,
         status_now = EXCLUDED.status_now, first_start = EXCLUDED.first_start, last_start = EXCLUDED.last_start,
         last_end = EXCLUDED.last_end, undated_present = EXCLUDED.undated_present, undated_past = EXCLUDED.undated_past,
         disputed = EXCLUDED.disputed, recorded_at = LEAST(link_relationships.recorded_at, EXCLUDED.recorded_at),
         retired_at = EXCLUDED.retired_at, evidence_hash = EXCLUDED.evidence_hash, refreshed_at = now()
       RETURNING 1`,
      [], [{ rows: upserts }]);
    if (written.length !== upserts.length) throw new Error('link_relationships refresh did not persist every state row');
  }
  if (removals.length) {
    const removed = await executeRawJsonb(exec,
      `DELETE FROM link_relationships lr
        USING jsonb_to_recordset(($1::jsonb)->'rows') AS v(from_page_id int, to_page_id int, link_type text, scope text)
        WHERE lr.from_page_id = v.from_page_id AND lr.to_page_id = v.to_page_id AND lr.link_type = v.link_type AND lr.scope = v.scope
        RETURNING 1`,
      [], [{ rows: removals }]);
    changed += removed.length;
  }
  if (changed) await exec.executeRaw(`SELECT nextval('graph_generation_seq')`);
  return changed;
}

function evidenceHash(a: readonly AssertionRow[], t: readonly TransitionRow[]): string {
  const parts = [
    ...a.map(r => `a:${r.origin_id}:${r.tense}`),
    ...t.map(r => `t:${r.origin_id ?? 'manual'}:${r.kind}:${dateKey(r.occurred_on)}:${r.producer}`),
  ].sort();
  return createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 32);
}

/** Relationship keys with any evidence touching these pages (as endpoint or origin). */
export async function relationshipKeysForPages(exec: RawExec, pageIds: readonly number[]): Promise<RelationshipKey[]> {
  const ids = [...new Set(pageIds.map(Number).filter(Number.isSafeInteger))];
  if (!ids.length) return [];
  const rows = await exec.executeRaw<RelationshipKey>(
    `SELECT DISTINCT from_page_id, to_page_id, link_type FROM links
      WHERE (from_page_id = ANY($1::int[]) OR to_page_id = ANY($1::int[]) OR origin_page_id = ANY($1::int[]))
        AND link_type = ANY($2::text[])
     UNION
     SELECT DISTINCT from_page_id, to_page_id, link_type FROM link_transitions
      WHERE from_page_id = ANY($1::int[]) OR to_page_id = ANY($1::int[]) OR origin_page_id = ANY($1::int[])
     UNION
     SELECT from_page_id, to_page_id, link_type FROM link_relationships
      WHERE from_page_id = ANY($1::int[]) OR to_page_id = ANY($1::int[])`,
    [ids, temporalLinkTypes()]);
  return rows.map(r => ({ from_page_id: Number(r.from_page_id), to_page_id: Number(r.to_page_id), link_type: r.link_type }));
}

/**
 * Relationships whose state is missing or older than their newest evidence,
 * oldest first. The extract cycle phase refreshes these so writers that bypass
 * the engine (or ran before an upgrade) converge.
 */
export async function staleRelationshipKeys(exec: RawExec, limit = 500): Promise<RelationshipKey[]> {
  const rows = await exec.executeRaw<RelationshipKey>(
    `SELECT from_page_id, to_page_id, link_type FROM (
       SELECT l.from_page_id, l.to_page_id, l.link_type, max(l.created_at) AS newest
         FROM links l WHERE l.link_type = ANY($1::text[]) GROUP BY 1, 2, 3
       UNION ALL
       SELECT lt.from_page_id, lt.to_page_id, lt.link_type, max(lt.created_at)
         FROM link_transitions lt GROUP BY 1, 2, 3
     ) e
     WHERE NOT EXISTS (SELECT 1 FROM link_relationships lr WHERE lr.from_page_id = e.from_page_id
         AND lr.to_page_id = e.to_page_id AND lr.link_type = e.link_type AND lr.scope = 'all' AND lr.refreshed_at >= e.newest)
     GROUP BY from_page_id, to_page_id, link_type
     ORDER BY min(newest) LIMIT $2`,
    [temporalLinkTypes(), limit]);
  // Relationships whose evidence-owning page was deleted, restored or edited
  // after the last refresh (soft deletes change no evidence row).
  const originChanged = rows.length >= limit ? [] : await exec.executeRaw<RelationshipKey>(
    `SELECT DISTINCT lr.from_page_id, lr.to_page_id, lr.link_type FROM link_relationships lr
       JOIN links l ON l.from_page_id = lr.from_page_id AND l.to_page_id = lr.to_page_id AND l.link_type = lr.link_type
       JOIN pages o ON o.id = COALESCE(l.origin_page_id, l.from_page_id)
      WHERE lr.scope = 'all' AND GREATEST(o.updated_at, COALESCE(o.deleted_at, o.updated_at)) > lr.refreshed_at
      LIMIT $1`, [limit - rows.length]);
  rows.push(...originChanged.filter(k => !rows.some(r => r.from_page_id === k.from_page_id && r.to_page_id === k.to_page_id && r.link_type === k.link_type)));
  // State rows whose evidence is gone entirely (raw deletes) are refreshed away too.
  const orphans = rows.length >= limit ? [] : await exec.executeRaw<RelationshipKey>(
    `SELECT lr.from_page_id, lr.to_page_id, lr.link_type FROM link_relationships lr
      WHERE lr.scope = 'all'
        AND NOT EXISTS (SELECT 1 FROM links l WHERE l.from_page_id = lr.from_page_id AND l.to_page_id = lr.to_page_id AND l.link_type = lr.link_type)
        AND NOT EXISTS (SELECT 1 FROM link_transitions t WHERE t.from_page_id = lr.from_page_id AND t.to_page_id = lr.to_page_id AND t.link_type = lr.link_type)
      LIMIT $1`, [limit - rows.length]);
  return [...rows, ...orphans].map(r => ({ from_page_id: Number(r.from_page_id), to_page_id: Number(r.to_page_id), link_type: r.link_type }));
}


/**
 * Extract-phase sweep: relationships whose state is missing, older than their
 * newest evidence, or orphaned converge here, bounded per cycle. Zero LLM.
 * Returns details for the phase result; never throws.
 */
export async function sweepStaleRelationships(engine: BrainEngine, limit = 2000): Promise<Record<string, unknown>> {
  try {
    const { primeRelationSemantics } = await import('./link-semantics-pack.ts');
    await primeRelationSemantics(engine);
    const keys = await staleRelationshipKeys(engine, limit);
    if (!keys.length) return {};
    const { maintenanceTransaction } = await import('./persistence/attribution.ts');
    const changed = await maintenanceTransaction(engine, tx => refreshRelationships(tx, keys));
    return { relationships_swept: keys.length, relationships_changed: changed };
  } catch (e) {
    return { relationship_sweep_error: e instanceof Error ? e.message : String(e) };
  }
}