Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The keyless claim-conflict lane (GBRA-216 PR B). Finds two active facts that
* state different values of one typed claim for the same entity and as-of
* bucket, and files each pair as a pending supersede proposal in the existing
* decide_proposals queue (accept, reject and undo are facts/proposal-supersede.ts).
*
* A pair is two active, non-audit facts in one source with the same
* visibility, the same non-null entity_slug, the same claim_metric, the same
* claim_unit and claim_period (null-safe), the same as-of bucket
* (typed-claim.ts claimBucket) and different claim_value. Points in different
* buckets are history and are never proposed. A fact on a member page pairs
* only with another fact on that same page (access/member-facts.ts onOwnedMemoryPageSql).
* The newer fact (valid_from, then id) is proposed to supersede the older one.
*
* Bounded: at most max_pairs pairs per source per run, and a pair that already
* has a proposal (any lane, any status) or a pending trust supersede_fact
* proposal is excluded inside the bounded query, so old pairs never starve new
* ones. Idempotent across concurrent runs: a partial unique index over this
* lane's sweep ids (migration v288) keeps one proposal per unordered pair.
* Writes only proposal rows; it never changes a fact. Keyless, both engines,
* and every source runs whether or not it has a local path.
*/
import { randomUUID } from 'node:crypto';
import type { BrainEngine } from '../engine.ts';
import type { PhaseResult } from '../cycle.ts';
import { AUDIT_ROW_SOURCES } from './audit-sources.ts';
import { insertProposal } from '../ai/decide/proposals-store.ts';
import { claimBucketSql } from './typed-claim.ts';
import { onOwnedMemoryPageSql } from '../access/member-facts.ts';
import { CLAIM_CONFLICTS_MAX_PAIRS_KEY, readPhaseConfigNumber } from '../cycle/phase-config-values.ts';
export const CLAIM_CONFLICTS_MODE_KEY = 'dream.claim_conflicts.mode';
export const CLAIM_CONFLICTS_MODES = ['propose', 'off'] as const;
export const CLAIM_CONFLICTS_DEFAULT_MAX_PAIRS = 500;
export const CLAIM_CONFLICTS_SWEEP_PREFIX = 'claim_conflicts:';
export interface ClaimConflictPair {
new_fact_id: number; old_fact_id: number; entity_slug: string; visibility: string;
claim_metric: string; claim_unit: string | null; claim_period: string | null; bucket: string;
new_value: number; old_value: number;
}
export interface ClaimConflictSourceResult {
source_id: string;
status: 'complete' | 'partial' | 'failed';
pairs: ClaimConflictPair[];
proposals_written: number;
/** Pairs another run proposed between this run's read and its insert. */
already_proposed: number;
/** Pairs past max_pairs, left for the next run. */
deferred: number;
error?: string;
}
export interface ClaimConflictRun {
status: 'complete' | 'partial' | 'failed' | 'skipped';
detail: string;
sweep_id: string;
dry_run: boolean;
max_pairs: number;
pairs_found: number;
proposals_written: number;
deferred: number;
sources: ClaimConflictSourceResult[];
warnings: string[];
}
/** dream.claim_conflicts.mode: propose files proposals each cycle; off (the default, and any other stored value) skips the phase. */
export async function claimConflictsMode(engine: Pick<BrainEngine, 'getConfig'>): Promise<'propose' | 'off'> {
const raw = (await engine.getConfig(CLAIM_CONFLICTS_MODE_KEY).catch(() => null))?.trim().toLowerCase();
return raw === 'propose' ? 'propose' : 'off';
}
/** Why value is not a valid dream.claim_conflicts.mode, or null when it is. */
export function claimConflictsModeRefusal(value: string): string | null {
return (CLAIM_CONFLICTS_MODES as readonly string[]).includes(value.trim().toLowerCase()) ? null
: CLAIM_CONFLICTS_MODE_KEY + ' must be propose or off; got ' + JSON.stringify(value) + '. Nothing was written.';
}
const ACTIVE_CLAIMS = 'WITH f AS (\n'
+ ' SELECT id, entity_slug, visibility, claim_metric, claim_value, claim_unit, claim_period, valid_from, source_markdown_slug, ' + claimBucketSql('facts') + ' AS bucket\n'
+ ' FROM facts\n'
+ ' WHERE source_id = $1 AND expired_at IS NULL AND (valid_until IS NULL OR valid_until > now())\n'
+ ' AND entity_slug IS NOT NULL AND claim_metric IS NOT NULL AND claim_value IS NOT NULL AND source <> ALL($2::text[]))';
const PAIR_JOIN = 'FROM f n JOIN f o\n'
+ ' ON o.entity_slug = n.entity_slug AND o.visibility = n.visibility AND o.claim_metric = n.claim_metric\n'
+ ' AND o.claim_unit IS NOT DISTINCT FROM n.claim_unit AND o.claim_period IS NOT DISTINCT FROM n.claim_period\n'
+ ' AND o.bucket = n.bucket AND o.claim_value <> n.claim_value\n'
+ ' AND (NOT (' + onOwnedMemoryPageSql('n') + ' OR ' + onOwnedMemoryPageSql('o') + ') OR o.source_markdown_slug = n.source_markdown_slug)\n'
+ ' AND (o.valid_from < n.valid_from OR (o.valid_from = n.valid_from AND o.id < n.id))\n'
+ ' WHERE NOT EXISTS (SELECT 1 FROM decide_proposals p WHERE p.source_id = $1\n'
+ ' AND LEAST(p.new_fact_id, p.old_fact_id) = LEAST(n.id, o.id) AND GREATEST(p.new_fact_id, p.old_fact_id) = GREATEST(n.id, o.id))\n'
+ ' AND NOT EXISTS (SELECT 1 FROM trust_proposals tp WHERE tp.status = \'pending\' AND tp.action = \'supersede_fact\'\n'
+ ' AND tp.target_table = \'facts\' AND tp.related_table = \'facts\'\n'
+ ' AND ((tp.target_id = o.id AND tp.related_id = n.id) OR (tp.target_id = n.id AND tp.related_id = o.id)))';
function pairsSql(select: string, tail = ''): string {
return ACTIVE_CLAIMS + '\nSELECT ' + select + '\n' + PAIR_JOIN + tail;
}
/** Unproposed same-bucket claim conflicts in one source, at most limit, oldest new fact first; deferred counts the rest. */
export async function findClaimConflicts(engine: BrainEngine, sourceId: string, limit: number): Promise<{ pairs: ClaimConflictPair[]; deferred: number }> {
const rows = await engine.executeRaw<Record<string, unknown>>(pairsSql(
'n.id AS new_fact_id, o.id AS old_fact_id, n.entity_slug, n.visibility, n.claim_metric, n.claim_unit, n.claim_period, n.bucket, n.claim_value AS new_value, o.claim_value AS old_value',
'\n ORDER BY n.id, o.id\n LIMIT $3'), [sourceId, [...AUDIT_ROW_SOURCES], limit + 1]);
const pairs = rows.slice(0, limit).map(r => ({
new_fact_id: Number(r.new_fact_id), old_fact_id: Number(r.old_fact_id), entity_slug: String(r.entity_slug), visibility: String(r.visibility),
claim_metric: String(r.claim_metric), claim_unit: (r.claim_unit as string | null) ?? null, claim_period: (r.claim_period as string | null) ?? null,
bucket: String(r.bucket), new_value: Number(r.new_value), old_value: Number(r.old_value),
}));
if (rows.length <= limit) return { pairs, deferred: 0 };
const [count] = await engine.executeRaw<{ n: number | string }>(pairsSql('COUNT(*) AS n'), [sourceId, [...AUDIT_ROW_SOURCES]]);
return { pairs, deferred: Math.max(0, Number(count?.n ?? 0) - limit) };
}
/**
* One run over sourceIds (default: every source that is not archived, with or
* without a local path). dryRun finds pairs and writes nothing.
*/
export async function runClaimConflicts(engine: BrainEngine, opts: { sourceIds?: string[]; dryRun?: boolean } = {}): Promise<ClaimConflictRun> {
const sweepId = CLAIM_CONFLICTS_SWEEP_PREFIX + randomUUID();
const knob = await readPhaseConfigNumber(engine, CLAIM_CONFLICTS_MAX_PAIRS_KEY);
const maxPairs = knob.value ?? CLAIM_CONFLICTS_DEFAULT_MAX_PAIRS;
const dryRun = opts.dryRun === true;
const sourceIds = opts.sourceIds ?? (await engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE NOT archived ORDER BY id')).map(r => r.id);
const sources: ClaimConflictSourceResult[] = [];
let pairIndex = 0;
for (const sourceId of sourceIds) {
try {
const { pairs, deferred } = await findClaimConflicts(engine, sourceId, maxPairs);
let written = 0;
if (!dryRun) {
for (const pair of pairs) {
const id = await insertProposal(engine, { source_id: sourceId, sweep_id: sweepId, pair_index: pairIndex++, new_fact_id: pair.new_fact_id, old_fact_id: pair.old_fact_id,
direction: 'new_supersedes_old', p_supersede: 1, threshold: null, proposal_floor: 1, model_resolved: null });
if (id !== null) written++;
}
}
sources.push({ source_id: sourceId, status: deferred > 0 ? 'partial' : 'complete', pairs, proposals_written: written,
already_proposed: dryRun ? 0 : pairs.length - written, deferred });
} catch (error) {
sources.push({ source_id: sourceId, status: 'failed', pairs: [], proposals_written: 0, already_proposed: 0, deferred: 0, error: error instanceof Error ? error.message : String(error) });
}
}
const pairsFound = sources.reduce((n, s) => n + s.pairs.length, 0);
const written = sources.reduce((n, s) => n + s.proposals_written, 0);
const deferred = sources.reduce((n, s) => n + s.deferred, 0);
const failed = sources.filter(s => s.status === 'failed');
const status: ClaimConflictRun['status'] = sources.length === 0 ? 'skipped' : failed.length === sources.length ? 'failed'
: failed.length || sources.some(s => s.status === 'partial') ? 'partial' : 'complete';
const detail = sources.length === 0 ? 'no active sources'
: pairsFound + ' pair(s) found, ' + (dryRun ? 'none written (dry run)' : written + ' proposal(s) written') + ', ' + deferred + ' deferred by the cap (max_pairs ' + maxPairs + '), '
+ sources.length + ' source(s)' + (failed.length ? '; failed: ' + failed.map(s => s.source_id + ' (' + s.error + ')').join(', ') : '');
return { status, detail, sweep_id: sweepId, dry_run: dryRun, max_pairs: maxPairs, pairs_found: pairsFound, proposals_written: written, deferred, sources,
warnings: knob.warning ? [knob.warning] : [] };
}
/** Cycle adapter: off by default (dream.claim_conflicts.mode); maps the run onto the cycle's PhaseResult (duration filled by the caller). */
export async function claimConflictsCyclePhase(engine: BrainEngine | null, dryRun: boolean): Promise<PhaseResult> {
if (!engine) return { phase: 'claim_conflicts', status: 'skipped', duration_ms: 0, summary: 'no database connected', details: { reason: 'no_database' } };
if (await claimConflictsMode(engine) === 'off') {
return { phase: 'claim_conflicts', status: 'skipped', duration_ms: 0, summary: 'mode off (' + CLAIM_CONFLICTS_MODE_KEY + ', default off)', details: { reason: 'mode_off' } };
}
const r = await runClaimConflicts(engine, { dryRun });
const status: PhaseResult['status'] = r.status === 'complete' ? 'ok' : r.status === 'partial' ? 'warn' : r.status === 'failed' ? 'fail' : 'skipped';
return { phase: 'claim_conflicts', status, duration_ms: 0, summary: r.detail,
details: { pairs_found: r.pairs_found, proposals_written: r.proposals_written, deferred: r.deferred, sources: r.sources.length, sweep_id: r.sweep_id,
...(r.warnings.length ? { warnings: r.warnings } : {}) } };
}