Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* S9 `conflict` (hot-memory contradiction): the question, the evidence items
* and the ONE pair reducer shared by the sweep, calibration and evals.
*
* Each swept fact is the request state; each eligible neighbour gets one
* `choice` question (duplicate | supersede | independent). Per pair,
* independently: `duplicate` chosen at or above threshold -> duplicate
* (receipt only); else P(supersede) at or above decide.slots.conflict.
* proposal_floor -> proposal (a pending supersede in `on` mode only; v1 never
* supersedes automatically); else independent. Pure: no I/O.
*/
import type { ChoiceAnswer, DecideQuestion, EvidenceItem } from './types.ts';
import { thresholdValue } from './types.ts';
export const CONFLICT_OPTIONS: Readonly<Record<'duplicate' | 'supersede' | 'independent', string>> = {
duplicate: '`fact` and `candidate` state the same claim',
supersede: '`fact` is a newer or corrected version of the same claim, so `candidate` is no longer true',
independent: '`fact` and `candidate` can both be true',
};
export const CONFLICT_INSTRUCTIONS = 'How does `fact` relate to `candidate`, an earlier stored fact about the same entity?';
/** Neighbours judged per swept fact, and the cosine floor they must clear. */
export const CONFLICT_NEIGHBOURS = 5;
export const CONFLICT_MIN_COSINE = 0.8;
/** The watermark only advances past facts created at least this long ago (commit-order lag). */
export const CONFLICT_WATERMARK_LAG_MS = 60_000;
export const DEFAULT_PROPOSAL_FLOOR = 0.5;
export type ConflictOutcome = 'duplicate' | 'proposal' | 'independent';
export interface ConflictFact {
id: number;
source_id: string;
fact: string;
visibility: 'private' | 'world';
}
export function factEvidence(f: ConflictFact): EvidenceItem {
return { text: f.fact, class: 'facts', fact_id: f.id, source_id: f.source_id, visibility: f.visibility };
}
/** A fact with the timestamps the sweep orders a pair by. */
export interface DatedConflictFact extends ConflictFact {
valid_from: Date | string;
created_at: Date | string;
}
const iso = (v: Date | string) => new Date(v).toISOString();
/** The fact's timestamps as evidence with the fact's own provenance (egress judges it exactly like the fact). */
function timeEvidence(f: DatedConflictFact): EvidenceItem {
return { ...factEvidence(f), text: `valid from ${iso(f.valid_from)}; recorded ${iso(f.created_at)}` };
}
/**
* True when `a` is older than `b`: valid_from, then created_at, then id. The sweep presents the newer fact of a pair
* as `fact`, so a proposal always retires the older one, even when the older fact is the one being swept (a fact
* that just gained an entity through `gbrain facts relink`).
*/
export function isOlderFact(a: DatedConflictFact, b: DatedConflictFact): boolean {
const ms = (v: Date | string) => new Date(v).getTime();
return (ms(a.valid_from) - ms(b.valid_from) || ms(a.created_at) - ms(b.created_at) || a.id - b.id) < 0;
}
export function conflictState(f: ConflictFact): Record<string, EvidenceItem> {
return { fact: factEvidence(f) };
}
export function conflictQuestion(id: string, rank: number, candidate: ConflictFact): DecideQuestion {
return { id, kind: 'choice', rank, instructions: CONFLICT_INSTRUCTIONS, options: { ...CONFLICT_OPTIONS }, inputs: { candidate: factEvidence(candidate) } };
}
/** The state of a pair the sweep reordered by chronology: the newer fact plus its timestamps (`fact_time`). */
export function datedConflictState(f: DatedConflictFact): Record<string, EvidenceItem> {
return { ...conflictState(f), fact_time: timeEvidence(f) };
}
/** The question of a reordered pair: the older (swept) fact as `candidate` plus its timestamps (`candidate_time`). */
export function datedConflictQuestion(id: string, rank: number, candidate: DatedConflictFact): DecideQuestion {
const q = conflictQuestion(id, rank, candidate);
return { ...q, inputs: { ...q.inputs, candidate_time: timeEvidence(candidate) } };
}
/** P(supersede) for the proposal floor: the reported probability, else the confidence when supersede was chosen. */
export function supersedeProbability(answer: ChoiceAnswer): number {
return answer.probabilities.supersede ?? (answer.choice === 'supersede' ? answer.confidence : 0);
}
/**
* The pair reducer. `threshold` is the calibrated (or override) duplicate
* threshold; without one (shadow diagnostics) the chosen label decides.
*/
export function reduceConflict(answer: ChoiceAnswer, policy: { threshold?: number; proposalFloor: number }): ConflictOutcome {
if (answer.choice === 'duplicate' && thresholdValue(answer) >= (policy.threshold ?? 0)) return 'duplicate';
if (supersedeProbability(answer) >= policy.proposalFloor) return 'proposal';
return 'independent';
}
/** Unordered pair identity (pair dedup across and within sweeps). */
export function pairKey(sourceId: string, a: number, b: number): string {
return `conflict:${sourceId}:${Math.min(a, b)}:${Math.max(a, b)}`;
}
/** Which way a proposal points: the superseding fact is newer (larger id) or older than the one it would expire. */
export function proposalDirection(supersedingId: number, expiredId: number): 'new_supersedes_old' | 'old_supersedes_new' {
return supersedingId > expiredId ? 'new_supersedes_old' : 'old_supersedes_new';
}
/**
* The prefix of `facts` (ascending id, all above the watermark) a sweep may
* process: it stops at the first fact created less than `lagMs` ago, so a
* lower id that commits late is never skipped by an advanced watermark.
*/
export function sweepWindow<T extends { id: number; created_at: Date | string }>(facts: readonly T[], nowMs: number, lagMs = CONFLICT_WATERMARK_LAG_MS): T[] {
const out: T[] = [];
for (const f of facts) {
if (nowMs - new Date(f.created_at).getTime() < lagMs) break;
out.push(f);
}
return out;
}
/** Eligibility beyond the SQL prefilter: the guards decideSingleFact applies, re-checked on the returned rows. */
export function eligibleCandidate(
fact: { id: number; source_id: string; entity_slug: string | null; visibility: string },
c: { id: number; source_id: string; entity_slug: string | null; visibility: string; expired_at: Date | string | null; valid_until: Date | string | null; source_markdown_slug: string | null; similarity: number },
nowMs: number,
): boolean {
return c.id !== fact.id && c.source_id === fact.source_id && c.entity_slug === fact.entity_slug && c.visibility === fact.visibility
&& c.expired_at === null && (c.valid_until === null || new Date(c.valid_until).getTime() > nowMs)
&& (!c.source_markdown_slug || c.source_markdown_slug === fact.entity_slug)
&& c.similarity >= CONFLICT_MIN_COSINE;
}