agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
73 lines (72 loc) • 4.13 kB
TypeScript
/**
* delivered — one declared claim of an answer about to be DELIVERED, judged
* for answer validation (`answer-validation/agentChecks.ts` turns the verdict
* into a report row).
*
* Pattern: pure function over one `check.ts` · `compareClaim` result.
* Role: the claim seam's verdict when it can WITHHOLD an answer. It reads
* the detector's own selection (`compareClaim`: every row this run
* settled for the declared `(entity, field)`) and adds the rules a
* verdict that governs delivery needs, because that contract is
* unscoped: rows from ANY tool result, with no scope or age check,
* and any result carrying the semantics marker settles a fact — so
* any row may be forged, foreign or stale.
*
* THE LAW — a reading can only withhold. With no reading the claim is not
* checked (`uncollected`, `not-applicable`), and ONE more reading of the fact,
* wherever it lands, never makes the verdict more permissive: a forged or
* stale row can at most withhold an answer, never deliver one or make it
* read "known". Pinned by the monotonicity property in
* `test/answer-validation/agentChecks.test.ts`. That is why:
* - AGREEMENT IS NEVER SUPPORT. It is `agrees` — `not-applicable`, exactly as
* silent as no reading at all — and only the app's own checks can pass a
* report. A contradiction still withholds.
* - EVERY READING COUNTS, never the latest alone. A reading that settled
* nothing (an `unknown(…)` Claim, a bare `null` or doubt word) beside the
* answer's value, readings that disagree, and a reading that is not a
* well-formed Claim each withhold, whatever else the run read.
* - A CONTRADICTION FOUND IS REPORTED AS ONE. If the answer contradicts ANY
* value the run read, the verdict is a contradiction — `contradicts` when
* it contradicts every value read, `contradicts-a-reading` when the
* readings themselves differ — never relabelled "could not tell" by
* whatever else was read (a forged `null` beside a real reading included).
* Withheld either way; only the label is at stake, and the label is honest.
* - DOUBT IS NEVER AGREEMENT. Doubt on both sides (`null` or `'unknown'` —
* in any case or spacing — or an unknown Claim) withholds; only an absence
* a tool DECLARED (`known(null)`) agrees with the answer's doubt.
* - VALUES COMPARE UNDER THE DECLARED NORMALIZATION (`evaluate.ts` ·
* `compareClaimValues`), never by exact JSON: `'Settled '` agrees with
* `'settled'`, `42.5` with `'42.50'`. Kinds that cannot be compared safely
* are `incomparable`, never `contradicts`.
*/
import type { ClaimComparison } from './check.js';
/** One delivered claim's verdict. Only `contradicts` accuses; nothing here verifies. */
export type DeliveredClaim =
/** The answer does not state the field. */
'omitted'
/** The answer declines it (doubt) where the run's readings are values. */
| 'declined'
/** No reading of this run settled the fact: the claim is not checked. */
| 'uncollected'
/** This run's readings of the fact are not all the same value. */
| 'disputed'
/** A reading settled the fact as an unknown `Claim`, and the answer states a value. */
| 'settled-unknown'
/** A reading settled only a bare `null` / doubt word, and the answer states a value. */
| 'settled-doubt'
/** Doubt on both sides. */
| 'doubt-on-both-sides'
/** The answer's value agrees with every reading — agreement, not support. */
| 'agrees'
/** The answer's value contradicts every value the run read. */
| 'contradicts'
/** The answer's value contradicts one value the run read, and the values read differ. */
| 'contradicts-a-reading'
/** A reading or the answer is not well formed, or the values cannot be compared safely. */
| 'incomparable';
/**
* Judge one compared claim for delivery, over EVERY reading of the fact this
* run made. Pure and monotone: a reading added anywhere never turns a
* withholding verdict into `agrees`, `declined` or `uncollected`.
*/
export declare function judgeDeliveredClaim(comparison: ClaimComparison): DeliveredClaim;