Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.2 KB
Raw Blame
/**
 * v0.35.4 (R1 + R8 — D-CDX-4 + D-CDX-7) — IRON-RULE: the contradiction
 * probe NEVER writes `valid_until` on the facts table.
 *
 * The temporal trajectory wave (v0.35.4) gives `consolidate` the
 * authority to write `valid_until` on chronologically-superseded facts.
 * That authority is exclusive: the contradiction probe surfaces
 * `temporal_supersession` verdicts via paste-ready commands, but it
 * must NEVER auto-mutate. This preserves the
 * `src/core/eval-contradictions/auto-supersession.ts:4` invariant.
 *
 * Two layered guards:
 *   R1 — grep guard over the entire `src/core/eval-contradictions/`
 *        subtree and the `src/commands/eval-suspected-contradictions*.ts`
 *        files: no code path may UPDATE facts.valid_until.
 *   R8 — broader guard over all of `src/`: only reviewed writers may
 *        change valid_until. Any new
 *        write site fails this guard; the human adding it must explicitly
 *        amend the allow-list AND document the deliberate design change.
 */

import { test, expect, describe } from 'bun:test';
import { readdirSync, readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';

// Allow-listed files that legitimately write `valid_until`. Adding a new
// file here means you've thought carefully about the
// auto-supersession.ts:4 invariant and decided the new write site
// preserves it.
//
//   - consolidate.ts (v0.35.4 — chronological writeback)
//   - facts/forget.ts (v0.32.2 — user-initiated `gbrain forget`; user is
//     the supersession authority, not the probe)
//   - facts/withdrawal.ts — durable user-initiated forget closes every
//     matching active claim in the same source and visibility lane. It
//     records the user's withdrawal before filesystem work; this is an
//     explicit retraction, never a contradiction-probe inference.
//   - facts/withdrawal-schema.ts — its insert/update trigger reapplies an
//     already-recorded user withdrawal when derived facts are rebuilt; it
//     cannot invent a withdrawal or infer one from a contradiction.
//   - facts/insert-guard-schema.ts — the statement-level form of that same
//     insert trigger (#7105): it clamps valid_until only on rows the current
//     INSERT wrote that match an already-recorded fact_withdrawals row, the
//     same rule; it never reads contradiction findings.
//   - persistence/canonical-projections.ts — restores explicit valid_until
//     from the accepted canonical Markdown fence, including version reverts,
//     in the guarded page publication transaction. This copies user-authored
//     state; it never applies contradiction-probe inference.
//   - cycle/extract-facts.ts — the unmanaged fence reconcile updates a
//     matched row in place with the fence's explicit valid_until cell (the
//     same user-authored copy canonical-projections.ts makes); it never
//     applies contradiction-probe inference.
//   - postgres-engine.ts + pglite-engine.ts (v0.42.56.0, #2390 — Life
//     Chronicle ontology: `mergeOntologyFact` forward-supersession closes
//     the prior OPEN row's valid_until when a NEW value arrives for the
//     same (entity, dimension). Engine-layer, caller-requested, scoped to
//     `dimension IS NOT NULL` ontology rows only — plain facts untouched,
//     and the contradiction probe still never mutates, so the
//     auto-supersession.ts:4 invariant is preserved. Deliberate design
//     change per the #2390 eng review (G1: ontology extends facts).
//   - facts/proposal-supersede.ts (System One S9) — applies or undoes a
//     contradiction PROPOSAL only when the user runs `gbrain decide proposals
//     accept|undo <id>` (local CLI); the sweep and the inline fact write path
//     never call it, so a probe still never mutates (auto-supersession.ts:4).
//   - persistence/loop-fact-retirement.ts (#5869) — retires a commitment fact
//     only when its loop is closed through `loops_close` or `gbrain repair
//     loop-facts` (expired_at + valid_until with the struck fence row); the
//     contradiction sweep and probes never call it.
//   - repair/consolidate-ties.ts (#6023) — `gbrain repair consolidate-ties`
//     reopens (valid_until back to NULL) only the preview-approved facts the
//     pre-#6023 consolidate writeback closed at their own instant; local CLI,
//     explicit-only, and the contradiction probe never calls it.
//   - generations/adapters/fact-rows.ts (GBRA-161 PR 2) — `restoreFactRow`
//     writes back a fact's recorded before-state (valid_until included) only in
//     a preview-approved `gbrain repair generations --mode restore` of a
//     consolidation chain or a fence generation; local CLI, and the
//     contradiction probe never calls it.
//   - repair/unwithdrawn-facts.ts (#8819) — `gbrain repair unwithdrawn-facts`
//     writes back the ledger preimage (valid_until included) of a fact the
//     first managed fence generation retired though no fence held it; local
//     CLI, explicit-only, preview-bound, and the contradiction probe never
//     calls it.
const VALID_UNTIL_WRITE_ALLOWLIST: ReadonlySet<string> = new Set([
  'src/core/cycle/extract-facts.ts',
  'src/core/cycle/phases/consolidate.ts',
  'src/core/engine-sql/facts.ts', // #7214: insertFact's supersede closes the retired interval at the replacement's valid_from
  'src/core/facts/forget.ts',
  'src/core/facts/insert-guard-schema.ts',
  'src/core/facts/proposal-supersede.ts',
  'src/core/facts/withdrawal.ts',
  'src/core/facts/withdrawal-schema.ts',
  'src/core/generations/adapters/fact-rows.ts',
  'src/core/persistence/canonical-projections.ts',
  'src/core/persistence/facts-prepare.ts', // #7214: a published supersession closes the retired interval (supersededValidUntil)
  'src/core/persistence/loop-fact-retirement.ts',
  'src/core/persistence/memory-prepare.ts', // #7214: remember (replaces or cosine) closes the retired interval (supersededValidUntil)
  'src/core/persistence/prepared-maintenance.ts',
  'src/core/postgres-engine.ts',
  'src/core/pglite-engine.ts',
  'src/core/repair/consolidate-ties.ts',
  'src/core/repair/unwithdrawn-facts.ts',
]);

function walkTs(dir: string, acc: string[] = []): string[] {
  for (const name of readdirSync(dir)) {
    const full = join(dir, name);
    const st = statSync(full);
    if (st.isDirectory()) {
      // Skip generated / vendored / test directories.
      if (name === 'node_modules' || name === '.git' || name === 'dist') continue;
      walkTs(full, acc);
    } else if (name.endsWith('.ts') && !name.endsWith('.test.ts')) {
      acc.push(full);
    }
  }
  return acc;
}

/**
 * Detect lines that look like they are UPDATEing facts.valid_until.
 * Permissive on SQL formatting (the same UPDATE can be split across lines,
 * use template strings, or use parameterized SQL via postgres.js's
 * tagged-template syntax). We look for the pair of substrings near
 * each other in the same file: `UPDATE facts` and `valid_until`.
 *
 * Tolerated: a reference to `valid_until` in a SELECT projection list
 * (which is fine — reading the column is not writing it) is filtered out
 * by also requiring a write verb (SET) nearby OR an INSERT INTO facts
 * with valid_until in the column list (INSERT path is OK from
 * src/core/postgres-engine.ts + src/core/pglite-engine.ts because those
 * are the engine layer, intentionally writing on caller request via
 * insertFact/insertFacts; the issue is whether the contradiction probe
 * path triggers those writes).
 */
function findValidUntilWrites(source: string): string[] {
  // Quick-fail: no mention of valid_until at all.
  if (!source.includes('valid_until')) return [];
  const lines = source.split('\n');
  const hits: string[] = [];
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (/\bNEW\.valid_until\s*:=/i.test(line)) hits.push(`${i + 1}: ${line.trim()}`);
    // Detect actual SQL writes. The narrow pattern `UPDATE facts SET ...
    // valid_until` is unambiguous — UPDATE is a SQL verb, not text
    // anyone writes in a description string. Tolerates same-line and
    // multi-line UPDATEs (look at the next 4 lines after `UPDATE facts`
    // for `valid_until`).
    if (/\bUPDATE\s+facts\b/i.test(line)) {
      const window = lines.slice(i, i + 5).join('\n');
      if (/\bSET\b[\s\S]*\bvalid_until\b/i.test(window)) {
        hits.push(`${i + 1}: ${line.trim()}`);
      }
    }
  }
  return hits;
}

describe('R1 — contradiction probe never writes valid_until', () => {
  test('no file under src/core/eval-contradictions/ writes facts.valid_until', () => {
    const dir = 'src/core/eval-contradictions';
    const files = walkTs(dir);
    expect(files.length).toBeGreaterThan(0);
    for (const f of files) {
      const src = readFileSync(f, 'utf-8');
      const hits = findValidUntilWrites(src);
      expect(hits, `${f} contains valid_until write: ${hits.join(' | ')}`).toEqual([]);
    }
  });

  test('no src/commands/eval-suspected-contradictions* file writes facts.valid_until', () => {
    const dir = 'src/commands';
    const files = readdirSync(dir)
      .filter(n => n.startsWith('eval-suspected-contradictions') && n.endsWith('.ts'))
      .map(n => join(dir, n));
    expect(files.length).toBeGreaterThanOrEqual(1);
    for (const f of files) {
      const src = readFileSync(f, 'utf-8');
      const hits = findValidUntilWrites(src);
      expect(hits, `${f} contains valid_until write: ${hits.join(' | ')}`).toEqual([]);
    }
  });
});

describe('R8 — only reviewed temporal and user-retraction writers may write valid_until', () => {
  test('every src/ TypeScript file that writes valid_until is on the allow-list', () => {
    const files = walkTs('src');
    const offenders: Array<{ file: string; hits: string[] }> = [];

    for (const f of files) {
      // Normalize path separator for cross-platform matching of the
      // allow-list keys.
      const relForCheck = f.replace(/\\/g, '/');
      if (VALID_UNTIL_WRITE_ALLOWLIST.has(relForCheck)) continue;

      // Engine implementation files (postgres-engine.ts, pglite-engine.ts)
      // legitimately write valid_until inside insertFact/insertFacts —
      // those are caller-driven INSERTs. Pattern is `INSERT INTO facts (
      // ... valid_until ...) VALUES`. Detect and exempt that pattern.
      // The R8 guard is about UPDATE; INSERT carrying valid_until as a
      // column value is not the failure mode auto-supersession.ts:4 cares
      // about.
      const src = readFileSync(f, 'utf-8');
      const hits = findValidUntilWrites(src);
      if (hits.length > 0) offenders.push({ file: relForCheck, hits });
    }

    expect(
      offenders,
      `Unexpected valid_until UPDATE sites:\n` +
      offenders.map(o => `  ${o.file}:\n    ${o.hits.join('\n    ')}`).join('\n') +
      `\n\nIf you added a deliberate write, append the path to ` +
      `VALID_UNTIL_WRITE_ALLOWLIST in this test AND review the ` +
      `\`auto-supersession.ts:4\` invariant first.`,
    ).toEqual([]);
  });

  test('VALID_UNTIL_WRITE_ALLOWLIST is non-empty (consolidate is on it)', () => {
    // Self-check: if the test file ever ships with an empty allow-list,
    // the R8 guard collapses to "no code writes valid_until anywhere" and
    // becomes a tautology. Keep the consolidate phase on the list as the
    // explicit positive control.
    expect(VALID_UNTIL_WRITE_ALLOWLIST.has('src/core/cycle/phases/consolidate.ts')).toBe(true);
  });
});