Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
32.6 KB
Raw Blame
/**
 * The crash robot's reference model: an independent temporal oracle. It
 * derives expectations from durable receipts (request id -> revision) plus a
 * small state model of page identities, revisions, markers, withdrawals and
 * supersession chains. Committed visibility is checked at the observation
 * point (right after the caller saw the receipt); afterwards only legal
 * transitions are allowed: a page's revision moves only when a committed op
 * touched that page, and a withdrawn fact never becomes visible again.
 *
 * Documented exceptions: `remember` without an entity page writes a DB-only
 * fact (src/core/persistence/memory-mutations.ts) and has no fence row; an
 * explicit `remember` of a withdrawn claim is a new assertion, not a resurrection.
 */
import type { EffectKind } from '../../src/core/persistence/effect-model.ts';
import { EFFECT_FAULT_POINTS, type FaultPoint } from '../../src/core/persistence/fault-points.ts';
import { operationsByName } from '../../src/core/operations.ts';
import { parseFactsFence } from '../../src/core/facts-fence.ts';
import { parseTakesFence } from '../../src/core/takes-fence.ts';
import { FACT_FENCE_KIND, TAKE_FENCE_KIND, fenceOwnerKey, readFenceBlocks } from '../../src/core/generations/fence.ts';
import { isRegistryCode } from '../../src/core/error-catalogue.ts';
import { unquoteTranscriptText } from '../../src/core/search/transcript-quote.ts';
import { CONNECTOR_SLUG, contextFor, retryingRead, type OpDescriptor, type OpKind, type OpObservation, type World } from './ops.ts';

/**
 * How the generator reaches each effect kind's mid-effect seam: the op that
 * queues it. A new effect kind without an entry fails typecheck.
 * facts-backstop is queued only when facts extraction is configured; keyless
 * robot brains never queue it, so its seam is exercised by the facts drain.
 * links is queued only for remote (untrusted) page writes; its seam is
 * exercised whenever the generator's put_page runs as a remote caller.
 * withdrawal-mirror is queued only by a pre-G4 database-first withdrawal an
 * older gbrain wrote; this binary's forget publishes through the git effect.
 */
export const EFFECT_SEAMS = {
  git: { op: 'put_page', point: EFFECT_FAULT_POINTS.git },
  embedding: { op: 'put_page', point: EFFECT_FAULT_POINTS.embedding },
  'withdrawal-mirror': { op: 'forget', point: EFFECT_FAULT_POINTS['withdrawal-mirror'] },
  'facts-backstop': { op: 'put_page', point: EFFECT_FAULT_POINTS['facts-backstop'] },
  links: { op: 'put_page', point: EFFECT_FAULT_POINTS.links },
} as const satisfies Record<EffectKind, { op: OpKind; point: FaultPoint }>;

/** Non-error outcomes a sync or connector run reports as its status (not error codes). */
const EXTERNAL_RESULT_CODES = new Set(['blocked_by_failures', 'dry_run']);

/**
 * Findings outside the safety classes, filed in TODOS.md with a skipped test,
 * stay visible in the manifest (`deferred`) without failing the gate.
 */
export const KNOWN_DEFERRALS: { class: ViolationClass; match: RegExp; todo: string }[] = [
  { class: 'untyped_error', match: /\(internal_error\)[\s\S]*(LockUnavailableError|SyncLockBusyError)/,
    todo: 'TODOS.md "A held sync lock reaches agents as internal_error"' },
];

export type ViolationClass = 'lost_write' | 'duplicate_apply' | 'untrue_receipt' | 'wedge' | 'withdrawal_permanence'
  | 'source_isolation' | 'authorization' | 'caller_bound_replay' | 'projection_drift' | 'missing_attribution' | 'orphan_rows' | 'effects_not_terminal'
  | 'untyped_error' | 'lock_order' | 'read_failure';
/** Violations that always block a ship (see the plan's bug-fix bound). */
export const SAFETY_CLASSES: ReadonlySet<ViolationClass> = new Set(['lost_write', 'duplicate_apply', 'untrue_receipt', 'wedge',
  'withdrawal_permanence', 'source_isolation', 'authorization', 'caller_bound_replay']);
export interface Violation { class: ViolationClass; op?: string; detail: string }

interface PageModel { live: boolean; revision: string | null; markers: Set<string>; lastMarker: string | null }
interface FactModel { id: string; source: string; text: string; entity: string; withdrawn: boolean; op: string }

const MARKER = /mk-[a-z]+\d+/g;
const key = (source: string, slug: string) => `${source}\u0000${slug}`;
function memberMarkersOf(members: { d: OpDescriptor }[]): string[] { return members.flatMap(x => markersIn(JSON.stringify(x.d.args))); }
function markersIn(text: string | undefined | null): string[] { return text ? [...text.matchAll(MARKER)].map(m => m[0]) : []; }
/** The newest page-body marker: edits insert theirs right after "Marker: ". */
function bodyMarker(text: string | undefined | null): string | null { return /Marker: (mk-[a-z]+\d+)/.exec(text ?? '')?.[1] ?? null; }

export class ReferenceModel {
  pages = new Map<string, PageModel>();
  facts = new Map<string, FactModel>();
  /** Marker -> source of the committed op that introduced it. */
  committedMarkers = new Map<string, string>();
  /** Markers of ops that were refused: they must never become visible. */
  refusedMarkers = new Set<string>();
  /** Re-asserted withdrawn claims (an explicit remember after forget). */
  reasserted = new Set<string>();
  violations: Violation[] = [];
  /** Pages a committed op touched in the current step: their revision may move. */
  touched = new Set<string>();
  revoked = new Set<string>();
  /** Accepted but not yet terminal when the caller stopped waiting: settled by `settlePending`. */
  pending = new Map<string, OpDescriptor>();

  constructor(readonly world: World) {}
  violate(v: Violation) { this.violations.push(v); }

  /** Durable model state, so a worker started after a SIGKILL continues the same oracle. */
  toJSON(): Record<string, unknown> {
    return { pages: [...this.pages].map(([k, p]) => [k, { ...p, markers: [...p.markers] }]), facts: [...this.facts],
      committedMarkers: [...this.committedMarkers], refusedMarkers: [...this.refusedMarkers], reasserted: [...this.reasserted],
      revoked: [...this.revoked], violations: this.violations, pending: [...this.pending], projected: [...this.projected] };
  }
  static fromJSON(world: World, state: Record<string, any>): ReferenceModel {
    const m = new ReferenceModel(world);
    m.pages = new Map(state.pages.map(([k, p]: [string, any]) => [k, { ...p, markers: new Set(p.markers) }]));
    m.facts = new Map(state.facts); m.committedMarkers = new Map(state.committedMarkers);
    m.refusedMarkers = new Set(state.refusedMarkers); m.reasserted = new Set(state.reasserted);
    m.revoked = new Set(state.revoked); m.violations = state.violations; m.pending = new Map(state.pending ?? []); m.projected = new Map(state.projected ?? []);
    return m;
  }
  /** An interrupted op whose outcome is unknown: its marker may legally be visible, in its own source only. */
  uncertain(d: OpDescriptor): void {
    const marker = markersIn(JSON.stringify(d.args)).at(-1);
    if (!marker) return;
    this.refusedMarkers.delete(marker); this.committedMarkers.set(marker, d.source);
    const slug = d.kind === 'connector_publish' ? CONNECTOR_SLUG : d.args.slug;
    if (typeof slug === 'string') this.pages.delete(key(d.source, slug));
  }
  /** Pages an in-flight op names: a crash may or may not have committed it, so their revision may move. */
  allowInFlight(ops: OpDescriptor[]): void {
    for (const d of ops) {
      const slug = d.kind === 'connector_publish' ? CONNECTOR_SLUG : d.args.slug ?? d.args.entity;
      if (typeof slug === 'string') this.touched.add(key(d.source, slug));
      if (d.kind === 'forget') for (const f of this.facts.values()) if (f.source === d.source) this.touched.add(key(f.source, f.entity));
    }
  }
  /** Forget pending page-liveness expectations an in-flight delete/restore may have settled either way. */
  relaxInFlight(ops: OpDescriptor[]): void {
    for (const d of ops) if (['delete_page', 'restore_page', 'put_page', 'sync'].includes(d.kind) && typeof d.args.slug === 'string') {
      this.pages.delete(key(d.source, d.args.slug));
    }
  }

  page(source: string, slug: string): PageModel {
    let p = this.pages.get(key(source, slug));
    if (!p) { p = { live: false, revision: null, markers: new Set(), lastMarker: null }; this.pages.set(key(source, slug), p); }
    return p;
  }

  /** Ops of the current concurrent group: their observation-point checks wait for `settleGroup`. */
  private deferred = false;

  /** Fold one observed op into the model and check its observation-point promises. */
  async observe(d: OpDescriptor, o: OpObservation, original?: OpObservation): Promise<void> {
    const marker = markersIn(JSON.stringify(d.args)).at(-1) ?? null;
    if (d.replayOf && original) {
      await this.checkReplay(d, o, original);
      // A same-principal replay returns the original receipt; it is not a new write.
      if (d.actor === original.actor) return;
    }
    if (d.actor !== 'local' && this.revoked.has(d.actor) && o.status === 'committed') {
      this.violate({ class: 'authorization', op: d.id, detail: `${d.kind} by revoked ${d.actor} committed` });
    }
    if (o.status === 'pending') { this.pending.set(d.id, d); return; }
    this.pending.delete(d.id);
    if (o.status !== 'committed') {
      if (marker && !this.committedMarkers.has(marker)) this.refusedMarkers.add(marker);
      // The agent sees the MCP envelope: its code must be a registered one, and not the unknown-failure fallback.
      const agentCode = o.agentCode ?? o.code;
      if (o.status === 'refused' && agentCode !== 'http:401' && (!agentCode || !isRegistryCode(agentCode) || agentCode === 'internal_error') && !EXTERNAL_RESULT_CODES.has(o.code ?? '')) {
        this.violate({ class: 'untyped_error', op: d.id, detail: `${d.kind} failed without a registered agent error code (${agentCode}): ${JSON.stringify(o.raw).slice(0, 300)}` });
      }
      return;
    }
    if (marker) { this.committedMarkers.set(marker, d.source); this.refusedMarkers.delete(marker); }
    await MODEL[d.kind](this, d, o);
  }

  /** Start of a step: pages a committed op touches during this step (or a pending op names) may move their revision. */
  beginStep(concurrent: boolean): void {
    this.touched.clear(); this.deferred = concurrent;
    this.allowInFlight([...this.pending.values()]);
  }
  get deferringVisibility(): boolean { return this.deferred; }

  /**
   * After a concurrent group: each touched page's revision must be one a
   * committed group member returned, or the write of a committed sync or
   * connector publish (which returns no revision) whose marker the page
   * carries; every committed edit's marker is visible, and every superseded
   * member revision is in the page's history.
   */
  async settleGroup(batch: OpDescriptor[], observed: OpObservation[]): Promise<void> {
    const committed = batch.map((d, i) => ({ d, o: observed[i] })).filter(x => x.o.status === 'committed');
    const bySlug = new Map<string, typeof committed>();
    for (const x of committed) {
      const slug = x.d.kind === 'connector_publish' ? CONNECTOR_SLUG : String(x.d.args.slug ?? x.d.args.entity ?? '');
      if (slug) bySlug.set(key(x.d.source, slug), [...(bySlug.get(key(x.d.source, slug)) ?? []), x]);
    }
    for (const [k, members] of bySlug) {
      const [source, slug] = k.split('\u0000');
      const read = await this.readPage('local', source, slug);
      const revisions = members.map(x => x.o.values.revision).filter(Boolean) as string[];
      // Whole-page writers (put, sync, connector) may legally replace each other; edits and fact writes compose.
      const replacing = members.some(x => ['put_page', 'sync', 'connector_publish'].includes(x.d.kind));
      const memberMarkers = members.map(x => ['edit_page', 'put_page', 'sync', 'connector_publish'].includes(x.d.kind) ? markersIn(JSON.stringify(x.d.args)).at(-1) : null);
      const visible = markersIn(String(read?.content));
      // A sync or connector publish returns no revision: the page may end at its write when it ran after a
      // receipted member, and then carries its marker.
      const unreceiptedFinal = members.some((x, i) => ['sync', 'connector_publish'].includes(x.d.kind) && !x.o.values.revision
        && !!memberMarkers[i] && visible.includes(memberMarkers[i]!));
      if (revisions.length && !revisions.includes(String(read?.revision)) && !unreceiptedFinal) {
        this.violate({ class: 'lost_write', op: members.map(x => x.d.id).join('+'), detail: `concurrent group left ${source}/${slug} at ${String(read?.revision)}, none of the committed revisions ${revisions.join(',')}` });
      }
      if (replacing && memberMarkers.some(Boolean) && !memberMarkers.some(mk => mk && visible.includes(mk))) {
        this.violate({ class: 'lost_write', op: members.map(x => x.d.id).join('+'), detail: `no committed whole-page write of the group is visible in ${source}/${slug}` });
      }
      for (const [i, x] of members.entries()) {
        const marker = memberMarkers[i];
        if (!replacing && marker && !markersIn(String(read?.content)).includes(marker)) this.violate({ class: 'lost_write', op: x.d.id, detail: `committed concurrent ${x.d.kind} marker ${marker} is not visible` });
        if (x.o.values.revision && x.o.values.revision !== read?.revision) {
          const [kept] = await this.q<{ n: number }>(`SELECT count(*)::int AS n FROM page_versions v JOIN pages p ON p.id=v.page_id
            WHERE p.source_id=$1 AND p.slug=$2 AND v.knowledge_revision::text=$3`, [source, slug, x.o.values.revision]);
          if (!kept.n) this.violate({ class: 'untrue_receipt', op: x.d.id, detail: `committed revision ${x.o.values.revision} of ${source}/${slug} never existed` });
        }
      }
      const page = this.page(source, slug);
      page.revision = read?.revision ? String(read.revision) : null;
      if (members.some(x => ['edit_page', 'put_page', 'sync', 'connector_publish'].includes(x.d.kind))) page.lastMarker = bodyMarker(String(read?.content)) ?? markersIn(String(read?.content)).find(mk => memberMarkersOf(members).includes(mk)) ?? page.lastMarker;
    }
    this.deferred = false;
  }

  /**
   * Requests whose receipts the caller sees late (a pending write settled after
   * the drain, or an interrupted request resubmitted after a crash) were
   * committed in queue order with writes observed since. Their receipt must
   * name a revision the page really had (current or archived in page_versions);
   * the page's current state is then adopted as the model's.
   */
  async settleLate(batch: OpDescriptor[], observed: OpObservation[]): Promise<void> {
    for (const [i, d] of batch.entries()) {
      const o = observed[i];
      if (o.status !== 'committed' || !o.values.revision) continue;
      const slug = d.kind === 'connector_publish' ? CONNECTOR_SLUG
        : d.kind === 'forget' ? this.facts.get(String((o.raw as { id?: unknown } | undefined)?.id ?? ''))?.entity ?? ''
        : String(d.args.slug ?? d.args.entity ?? '');
      const [seen] = await this.q<{ n: number }>(`SELECT
        (SELECT count(*)::int FROM pages p WHERE p.source_id=$1 AND p.slug=$2 AND p.knowledge_revision::text=$3)
        + (SELECT count(*)::int FROM page_versions v JOIN pages p ON p.id=v.page_id WHERE p.source_id=$1 AND p.slug=$2 AND v.knowledge_revision::text=$3) AS n`,
      [d.source, slug, o.values.revision]);
      if (!seen.n) this.violate({ class: 'untrue_receipt', op: d.id, detail: `late receipt names revision ${o.values.revision} that ${d.source}/${slug} never had` });
    }
    for (const d of batch) {
      const slug = d.kind === 'connector_publish' ? CONNECTOR_SLUG : d.args.slug ?? d.args.entity;
      if (typeof slug !== 'string') continue;
      const page = this.page(d.source, slug); const read = await this.readPage('local', d.source, slug);
      this.touched.add(key(d.source, slug));
      page.live = read !== null; page.revision = read?.revision ? String(read.revision) : null;
      page.lastMarker = read ? bodyMarker(String(read.content)) : null;
    }
    this.deferred = false;
  }

  private async checkReplay(d: OpDescriptor, o: OpObservation, original: OpObservation): Promise<void> {
    const sameActor = d.actor === original.actor;
    const sameIntent = JSON.stringify(d.args) === JSON.stringify(this.world.descriptors?.get(original.id)?.args);
    if (!sameActor) {
      if (o.receipt && original.receipt && o.receipt.revision && o.receipt.revision === original.receipt.revision) {
        this.violate({ class: 'caller_bound_replay', op: d.id, detail: `${d.actor} replaying ${original.actor}'s request id received the original receipt` });
      }
      return;
    }
    if (sameIntent) {
      if (original.status === 'committed' && o.status !== 'committed') this.violate({ class: 'untrue_receipt', op: d.id, detail: `same-intent replay of a committed request returned ${o.status}/${o.code}` });
      if (original.status === 'committed' && o.receipt?.revision && original.receipt?.revision && o.receipt.revision !== original.receipt.revision) {
        this.violate({ class: 'duplicate_apply', op: d.id, detail: 'same-intent replay produced a new revision' });
      }
    } else if (original.status !== 'refused' && o.status === 'committed') {
      this.violate({ class: 'caller_bound_replay', op: d.id, detail: 'changed intent under one request id committed instead of idempotency_conflict' });
    }
  }

  /** Read surfaces an agent uses, under a given actor. */
  /**
   * The oracle's own reads retry a session drop the robot injected (the
   * pooler_disconnect fault); only the system under test is judged on such
   * errors, and any other close fails the run.
   */
  private retrying<T>(read: () => Promise<T>): Promise<T> { return retryingRead(this.world, read); }
  q<R = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<R[]> {
    return this.retrying(() => this.world.engine.executeRaw<R>(sql, params));
  }

  /** The last read error, quoted in a violation so a failed read is never mistaken for a missing page. */
  lastReadError: string | null = null;
  async readPage(actor: string, source: string, slug: string): Promise<Record<string, unknown> | null> {
    this.lastReadError = null;
    try {
      return await this.retrying(() => operationsByName.get_page.handler(contextFor(this.world, actor, source),
        { slug, include_content: true, ...(actor === 'local' ? { source_id: source } : {}) })) as Record<string, unknown>;
    } catch (error) {
      const e = error as { code?: string; message?: string };
      this.lastReadError = `${e.code ?? 'error'}: ${String(e.message).slice(0, 160)}`;
      return null;
    }
  }
  async recall(actor: string, source: string, entity: string): Promise<string[]> {
    try {
      const r = await this.retrying(() => operationsByName.recall.handler(contextFor(this.world, actor, source),
        { entity, limit: 100, ...(actor === 'local' ? { source_id: source } : {}) })) as { facts?: { id?: number; fact?: string; quoted?: string }[] };
      // GST-687: a remote reader gets an agent-written fact quoted; the stored text is what the receipt promised.
      return (r.facts ?? []).map(f => f.quoted ? unquoteTranscriptText(String(f.fact ?? ''), `fact ${f.id}`) : String(f.fact ?? ''));
    } catch { return []; }
  }

  /** Invariants over the whole brain; run after every step and after recovery. */
  async checkGlobal(stage: string): Promise<void> {
    const rows = await this.q<{ source_id: string; slug: string; compiled_truth: string; timeline: string; revision: string | null; deleted: boolean; id: number }>(
      'SELECT id,source_id,slug,compiled_truth,timeline,knowledge_revision::text AS revision,deleted_at IS NOT NULL AS deleted FROM pages');
    const seen = new Set<string>();
    for (const row of rows) {
      const k = key(row.source_id, row.slug); seen.add(k);
      for (const m of markersIn(`${row.compiled_truth}\n${row.timeline}`)) {
        const owner = this.committedMarkers.get(m);
        if (owner && owner !== row.source_id) this.violate({ class: 'source_isolation', detail: `${stage}: ${m} written to ${owner} is visible in ${row.source_id}/${row.slug}` });
        if (!owner && this.refusedMarkers.has(m)) this.violate({ class: 'untrue_receipt', detail: `${stage}: refused write ${m} is visible in ${row.source_id}/${row.slug}` });
      }
      const model = this.pages.get(k);
      if (!model) continue;
      if (model.live === row.deleted) this.violate({ class: model.live ? 'lost_write' : 'untrue_receipt', detail: `${stage}: ${row.source_id}/${row.slug} live=${!row.deleted}, model expects ${model.live}` });
      if (this.touched.has(k)) model.revision = row.revision;
      else if (model.revision && row.revision !== model.revision) {
        this.violate({ class: 'lost_write', detail: `${stage}: ${row.source_id}/${row.slug} revision ${row.revision} != last committed ${model.revision}` });
      }
      if (model.live && model.lastMarker && !markersIn(row.compiled_truth).includes(model.lastMarker)) {
        this.violate({ class: 'lost_write', detail: `${stage}: ${row.source_id}/${row.slug} lost committed marker ${model.lastMarker}` });
      }
    }
    for (const [k, model] of this.pages) if (model.live && !seen.has(k)) this.violate({ class: 'lost_write', detail: `${stage}: committed page ${k.replace('\u0000', '/')} is missing` });
    await this.checkWithdrawals(stage);
    await this.checkProjection(stage, rows.filter(r => !r.deleted));
    await this.checkAttribution(stage);
  }

  private async checkWithdrawals(stage: string): Promise<void> {
    const withdrawn = [...this.facts.values()].filter(f => f.withdrawn && !this.reasserted.has(`${f.source}\u0000${f.text}`));
    for (const fact of withdrawn) {
      const actors = ['local', ...this.world.remotes.filter(r => r.sourceId === fact.source && !this.revoked.has(r.name)).map(r => r.name)];
      for (const actor of actors) {
        if ((await this.recall(actor, fact.source, fact.entity)).includes(fact.text)) {
          this.violate({ class: 'withdrawal_permanence', op: fact.op, detail: `${stage}: withdrawn fact "${fact.text}" returned by recall for ${actor}` });
        }
      }
      const page = await this.readPage('local', fact.source, fact.entity);
      const live = parseFactsFence(String(page?.content ?? '')).facts.filter(f => !f.forgotten && f.validUntil === undefined && f.claim === fact.text);
      if (live.length) this.violate({ class: 'withdrawal_permanence', op: fact.op, detail: `${stage}: withdrawn fact "${fact.text}" is a live row in ${fact.source}/${fact.entity}'s fence` });
      const [db] = await this.q<{ n: number }>(
        'SELECT count(*)::int AS n FROM facts WHERE source_id=$1 AND fact=$2 AND expired_at IS NULL', [fact.source, fact.text]);
      if (db.n > 0) this.violate({ class: 'withdrawal_permanence', op: fact.op, detail: `${stage}: withdrawn fact "${fact.text}" has ${db.n} active row(s)` });
    }
  }

  /** Each page fence's rows the last time they matched the fence, by page key and fence name. */
  private projected = new Map<string, string>();

  /**
   * A fence must list exactly its page's rows, with one exception (GBRA-161 PR 2, B-5): a write that drops the whole
   * section holds the fence `fence_absent` and keeps the rows. That page passes only while it has no fence block, the
   * hold is recorded, and its rows are still the ones it had when they last matched the fence. A parsed fence with the
   * hold still recorded fails, so a hold never outlives the fence that answers it.
   */
  private async checkFence(stage: string, row: { source_id: string; slug: string }, content: string, fence: 'facts' | 'takes', listed: string[], rows: string[]): Promise<void> {
    const k = `${key(row.source_id, row.slug)}\u0000${fence}`;
    const [hold] = await this.q<{ n: number }>(`SELECT count(*)::int AS n FROM derived_generations WHERE source_id=$1 AND kind=$2 AND owner_key=$3
      AND state='held' AND held_reason='fence_absent'`, [row.source_id, fence === 'facts' ? FACT_FENCE_KIND : TAKE_FENCE_KIND, fenceOwnerKey(row.slug)]);
    const held = hold.n > 0;
    const absent = readFenceBlocks({ compiled_truth: content }, fence).state === 'absent';
    if (JSON.stringify(listed) === JSON.stringify(rows)) {
      this.projected.set(k, JSON.stringify(rows));
      if (held && !absent) this.violate({ class: 'projection_drift', detail: `${stage}: ${row.source_id}/${row.slug} ${fence} fence parses but its fence_absent hold is still recorded` });
      return;
    }
    if (absent && held && this.projected.get(k) === JSON.stringify(rows)) return;
    this.violate({ class: 'projection_drift', detail: `${stage}: ${row.source_id}/${row.slug} ${fence} fence ${JSON.stringify(listed)} != rows ${JSON.stringify(rows)}${held ? ' (held fence_absent)' : ''}` });
  }

  private async checkProjection(stage: string, live: { id: number; source_id: string; slug: string }[]): Promise<void> {
    for (const row of live) {
      const page = await this.readPage('local', row.source_id, row.slug);
      if (!page) {
        this.violate({ class: 'read_failure', detail: `${stage}: get_page of live page ${row.source_id}/${row.slug} failed (${this.lastReadError ?? 'no page returned'}); its fences were not compared with the rows` });
        continue;
      }
      const content = String(page.content ?? '');
      const takes = parseTakesFence(content).takes;
      const dbTakes = await this.q<{ row_num: number; claim: string; active: boolean }>(
        'SELECT row_num,claim,active FROM takes WHERE page_id=$1 ORDER BY row_num', [row.id]);
      const fence = takes.map(t => `${t.rowNum}:${t.claim}:${t.active}`).sort();
      const db = dbTakes.map(t => `${t.row_num}:${t.claim}:${t.active}`).sort();
      await this.checkFence(stage, row, content, 'takes', fence, db);
      const liveFacts = parseFactsFence(content).facts.filter(f => !f.forgotten && f.validUntil === undefined).map(f => f.claim).sort();
      const dbFacts = (await this.q<{ fact: string }>(`SELECT fact FROM facts WHERE source_id=$1 AND source_markdown_slug=$2
        AND expired_at IS NULL AND superseded_by IS NULL AND (valid_until IS NULL OR valid_until > now())`, [row.source_id, row.slug])).map(f => f.fact).sort();
      await this.checkFence(stage, row, content, 'facts', liveFacts, dbFacts);
    }
    const [orphans] = await this.q<{ takes: number; timeline: number }>(`SELECT
      (SELECT count(*)::int FROM takes t WHERE NOT EXISTS (SELECT 1 FROM pages p WHERE p.id=t.page_id)) AS takes,
      (SELECT count(*)::int FROM timeline_entries e WHERE NOT EXISTS (SELECT 1 FROM pages p WHERE p.id=e.page_id)) AS timeline`);
    if (orphans.takes || orphans.timeline) this.violate({ class: 'orphan_rows', detail: `${stage}: orphan takes=${orphans.takes} timeline=${orphans.timeline}` });
  }

  private async checkAttribution(stage: string): Promise<void> {
    const [missing] = await this.q<{ facts: number; takes: number; timeline: number; pages: number }>(`SELECT
      (SELECT count(*)::int FROM facts WHERE write_principal_kind IS NULL) AS facts,
      (SELECT count(*)::int FROM takes WHERE write_principal_kind IS NULL) AS takes,
      (SELECT count(*)::int FROM timeline_entries WHERE write_principal_kind IS NULL) AS timeline,
      (SELECT count(*)::int FROM pages WHERE deleted_at IS NULL AND revision_principal_kind IS NULL) AS pages`);
    for (const [table, n] of Object.entries(missing)) if (n) this.violate({ class: 'missing_attribution', detail: `${stage}: ${n} ${table} row(s) without write attribution` });
  }

  /** After a drain: nothing pending, every effect terminal, and a fresh write still admits (no wedge). */
  async checkDrained(stage: string): Promise<void> {
    const [pending] = await this.q<{ requests: number; effects: number }>(`SELECT
      (SELECT count(*)::int FROM persistence_requests WHERE state IN ('queued','running','recovering')) AS requests,
      (SELECT count(*)::int FROM persistence_effects WHERE state IN ('queued','running') OR recovery IS NOT NULL) AS effects`);
    if (pending.requests) this.violate({ class: 'wedge', detail: `${stage}: ${pending.requests} request(s) still pending after the drain` });
    if (pending.effects) this.violate({ class: 'effects_not_terminal', detail: `${stage}: ${pending.effects} effect(s) not terminal after the drain` });
  }
}

type Fold = (m: ReferenceModel, d: OpDescriptor, o: OpObservation) => Promise<void>;
const pageWrite = (kind: 'put' | 'edit'): Fold => async (m, d, o) => {
  const slug = String(d.args.slug); const page = m.page(d.source, slug); const k = key(d.source, slug);
  const marker = d.args.content === '$stale_content' ? bodyMarker(o.pageContent)
    : markersIn(String(d.args.content ?? JSON.stringify(d.args.edits ?? ''))).at(-1) ?? null;
  page.live = true; page.revision = o.values.revision ?? null; m.touched.add(k);
  if (kind === 'put') page.markers = new Set(markersIn(o.pageContent));
  if (marker) page.markers.add(marker);
  page.lastMarker = marker;
  if (m.deferringVisibility) return;
  const read = await m.readPage(d.actor === 'local' || m.revoked.has(d.actor) ? 'local' : d.actor, d.source, slug);
  if (!read || read.revision !== o.values.revision) {
    const [row] = await m.q<Record<string, unknown>>(`SELECT knowledge_revision::text AS revision,deleted_at IS NOT NULL AS deleted,
      source_path FROM pages WHERE source_id=$1 AND slug=$2`, [d.source, slug]);
    m.violate({ class: 'untrue_receipt', op: d.id, detail: `committed ${d.kind} revision ${o.values.revision} not visible (read ${String(read?.revision)}${m.lastReadError ? `; ${m.lastReadError}` : ''}; row ${JSON.stringify(row ?? null)})` });
  }
  else if (page.lastMarker && !markersIn(String(read.content)).includes(page.lastMarker)) m.violate({ class: 'untrue_receipt', op: d.id, detail: `committed ${d.kind} marker ${page.lastMarker} not visible` });
};
/** A write that moves a page's revision. A page the model has not seen committed (its put may still be pending) stays untracked. */
const touch = (slugOf: (d: OpDescriptor) => string): Fold => async (m, d, o) => {
  const k = key(d.source, slugOf(d)); m.touched.add(k);
  const page = m.pages.get(k);
  if (page) page.revision = o.values.revision ?? null;
};

/** A file edit picked up by sync, or a connector item: the page now carries its marker. */
function externalWrite(target: (d: OpDescriptor) => [string, string, string]): Fold {
  return async (m, d) => {
    const [source, slug, text] = target(d);
    const marker = markersIn(text).at(-1) ?? null;
    const page = m.page(source, slug); m.touched.add(key(source, slug));
    page.live = true; page.revision = null; page.lastMarker = marker;
    if (marker) { page.markers.add(marker); m.committedMarkers.set(marker, source); }
    if (m.deferringVisibility) return;
    const read = await m.readPage('local', source, slug);
    if (marker && !markersIn(String(read?.content)).includes(marker)) m.violate({ class: 'untrue_receipt', op: d.id, detail: `${d.kind} reported success but ${source}/${slug} lacks ${marker}` });
  };
}

/** One fold per op kind: how a committed observation moves the model, plus its observation-point check. */
export const MODEL: Record<OpKind, Fold> = {
  put_page: pageWrite('put'),
  edit_page: pageWrite('edit'),
  remember: async (m, d, o) => {
    const text = String(d.args.fact); const entity = String(d.args.entity ?? '');
    if (o.values.fact_id) m.facts.set(o.values.fact_id, { id: o.values.fact_id, source: d.source, text, entity, withdrawn: false, op: d.id });
    if ([...m.facts.values()].some(f => f.withdrawn && f.source === d.source && f.text === text)) m.reasserted.add(`${d.source}\u0000${text}`);
    await touch(() => entity)(m, d, o);
    const status = (o.raw as { status?: string } | undefined)?.status;
    if (!m.deferringVisibility && status !== 'duplicate' && !(await m.recall(m.revoked.has(d.actor) ? 'local' : d.actor, d.source, entity)).includes(text)) {
      m.violate({ class: 'untrue_receipt', op: d.id, detail: `committed remember "${text}" not returned by recall` });
    }
  },
  forget: async (m, d, o) => {
    const id = String((o.raw as { id?: unknown } | undefined)?.id ?? '');
    const fact = m.facts.get(id);
    if (fact) {
      if (fact.source !== d.source) m.violate({ class: 'source_isolation', op: d.id, detail: `forget in ${d.source} expired fact ${id} of ${fact.source}` });
      fact.withdrawn = true; m.reasserted.delete(`${fact.source}\u0000${fact.text}`);
      const k = key(fact.source, fact.entity); m.touched.add(k);
      const page = m.pages.get(k); if (page) page.revision = null;
    }
  },
  takes_add: touch(d => String(d.args.slug)),
  takes_supersede: touch(d => String(d.args.slug)),
  add_timeline_entry: touch(d => String(d.args.slug)),
  delete_page: async (m, d, o) => { await touch(d => String(d.args.slug))(m, d, o); m.page(d.source, String(d.args.slug)).live = false; },
  restore_page: async (m, d, o) => { await touch(d => String(d.args.slug))(m, d, o); m.page(d.source, String(d.args.slug)).live = true; },
  revoke_access: async (m, d) => { m.revoked.add(String(d.args.actor)); },
  sync: externalWrite(d => [d.source, String(d.args.slug), String(d.args.content)]),
  connector_publish: externalWrite(d => [d.source, CONNECTOR_SLUG, String(d.args.body)]),
};