agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
121 lines • 7.04 kB
TypeScript
/**
* The value decision shared by claim-seam adapters. Evidence selection,
* scope/coverage eligibility, provenance and delivery policy belong to callers.
* This module owns the existing doubt and numeric-leniency rules; structural
* comparison stays in ContextFootprint's assertion algebra. It also owns the
* one declared normalization a claim that governs delivery is compared under
* (`compareClaimValues`, read by `delivered.ts`): the detector keeps exact
* equality, pinned; a verdict that can withhold an answer must not accuse it
* over a representational difference.
*
* Outcomes describe why a comparison did or did not find a conflict. None is
* a verification badge: in particular, no-conflict is not positive support.
*/
import type { Assertion } from '../assertion/types.js';
export type ClaimPairEvaluation = 'evidence-unavailable' | 'claim-nonparticipating' | 'doubt-against-value' | 'both-doubt' | 'numeric-leniency' | 'conflict' | 'no-conflict';
/**
* Evaluate an explicitly selected evidence/claim pair, without selecting or
* rewriting either assertion. Adapters must establish that the asserted pair
* concerns the same subject, predicate and epoch before interpreting a result.
* No rule here establishes scope, completeness, authorisation or truth.
*/
export declare function evaluateClaimPair(evidence: Assertion, claim: Assertion): ClaimPairEvaluation;
/**
* How a value an answer states compares with the value a tool settled, under
* ONE declared normalization (`compareClaimValues`). Only `contradicts`
* accuses; `agrees` verifies nothing.
*/
export type ClaimValueComparison = 'agrees' | 'contradicts' | 'incomparable';
/** What a value at the TOP of a claim is (`claimShapeOf`). */
export type ClaimShape =
/** A value: plain data, or a well-formed `known(…)` by its value (`declared`). */
{
readonly kind: 'value';
readonly face: unknown;
readonly declared: boolean;
}
/**
* Doubt: no value (`undefined`), `null` or the doubt word (`'unknown'` in
* any case or spacing), or — `declared` — a well-formed `unknown(…)` /
* `notApplicable(…)` Claim.
*/
| {
readonly kind: 'doubt';
readonly declared: boolean;
}
/** Claim-shaped, but not a well-formed Claim of its kind: never read. */
| {
readonly kind: 'malformed';
};
/**
* Read a value at the TOP of a claim — the one place the contract puts a
* Claim (a tool's `known(…)` fact, a claimed field) — by its shape. Doubt
* words are recognized after the same normalization the comparison uses, so
* `'Unknown'` and `' UNKNOWN '` are doubt like `'unknown'`. Inside a value
* nothing is read this way: a wrapper there is the value's data.
*/
export declare function claimShapeOf(value: unknown): ClaimShape;
/**
* Compare the value a tool settled with the value an answer states, after
* the declared normalization — the comparison a claim that GOVERNS DELIVERY
* is judged by (`delivered.ts`). The detector above keeps exact equality (its
* findings are pinned); this rule exists so a representational difference
* never withholds a correct answer as a contradiction:
*
* - text is Unicode NFC, trimmed and its white space collapsed. Case agrees
* only where two texts differ in case alone: every word that differs is a
* word of letters, more than three of them, cased all lower, all upper or
* with a capital first letter, with the same letters, letter for letter, in
* another case (`'Settled'` and `'settled '`, `'STRAẞE'` and `'Straße'` —
* `ẞ` is the capital of `ß`). The rule cannot know where case carries
* meaning, so it merges such words too (`'Polish'` and `'polish'`,
* `'AIDS'` and `'aids'`). Any other case difference is not compared — a
* short word or a unit (`'MW'`, `'Co'`), a mixed-case word, anything with a
* digit, `ß` against `ss` in any casing (`'Masse'`, `'maße'`, `'MASSE'`
* against `'Maße'`), a dotted against a dotless i (`'ılık'`). Texts that
* differ in no letter — in such a case difference, in marks (Greek
* capitals drop the accent: `'Αθήνα'`, `'ΑΘΗΝΑ'`), in compatibility forms
* (a full-width letter) — are never agreement, and never a contradiction;
* - a value written in a format — a currency symbol, digit separators, a
* dot-grouped number (`'1.250'`: 1.25 or 1250), a date or a time — agrees
* only as written and is otherwise not compared, and so is text that
* differs only in how a number inside it is spelled (`'USD 42.50'`);
* - a number and a string written as a plain decimal (`-?digits[.digits]`, no
* leading zero, sign or exponent) compare by value, both ways: two decimal
* strings digit for digit (`'42.50'` = `'42.5'`), a JS number at the double
* precision it has (`'42.50'` = `42.5`);
* - a plain decimal with a unit (`'1250 ms'`) compares only with the same
* unit, written exactly — case included (`MW` is not `mW`);
* - lists compare item by item in order, objects key by key, and a definite
* difference anywhere wins over a part that could not be compared; a hole
* in a list (`[, 1250]`, which `structuredClone` keeps) is no value and is
* never compared;
* - `null` against a value is a difference (a raw doubt is the caller's to
* classify first; only a DECLARED `known(null)` should reach here);
* - a Claim wrapper is read only at the TOP of either value, and only when it
* is a well-formed `known(…)` (`kind`, `value`, a text `evidence`). Inside a
* value a wrapper-shaped object is that value's data, compared as an
* object: an answer cannot have a nested object read as the value it wraps.
*
* Anything else — a list or an object against a scalar, a unit against a bare
* number or another unit, text against a number or `true`/`false`, a value
* that is not JSON, an unknown `Claim` or a malformed wrapper at the top,
* nesting past 64 levels — is `incomparable`: never "contradicts", never
* "agrees". Pure and total.
*/
export declare function compareClaimValues(settled: unknown, claimed: unknown): ClaimValueComparison;
/**
* One EXACT key per value under the same normalization, for a reader of
* several values at once (`delivered.ts` asks whether a run read one fact two
* ways). Equal keys always compare `agrees`: two values share a key only when
* they are the same value under the comparison's exact parts — text up to
* the case rule (a word keyed by its lower case never meets a word kept as
* written), a number by its digits — so `'9007199254740993'` and the double
* `9007199254740992`, which `compareClaimValues` cannot tell apart, have
* different keys. The converse does not hold: a key is stricter (`'SETTLED'`
* and `'settled'` agree under two keys), and key equality is transitive where
* agreement at double precision is not. `undefined` for a value that cannot
* be compared at all, a list with a hole included.
*/
export declare function claimValueKey(value: unknown): string | undefined;
//# sourceMappingURL=evaluate.d.ts.map