agentfootprint/dist/esm/core/agent/evidence/resultCarries.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * resultCarries — does ONE tool result carry ONE value? The evidence index's
 * own reading of a result, asked per value.
 *
 * Pattern: a pure reader over the index's one reading of a result
 *          (`evidenceIndex.ts` · `readResult`: parsed JSON with an absence's
 *          `looked_for` projected away, walked leaf by leaf, keys included —
 *          the leading JSON of a result a framework note follows, and the
 *          note as text; the text when it is not JSON) and the one normaliser
 *          (`lib/normalize.ts`) — never a second haystack.
 * Role:    core/ layer, `evidence/`. Asked by the inputs layer's declared-
 *          sources check (`core/agent/arguments/checks.ts` · `checkSource`),
 *          which loads with the layer — so this module is never on a plain
 *          agent's graph.
 * Emits:   N/A.
 */
/**
 * What `resultCarries` answers: the value is in the result (`found`), it is
 * not (`not-found`), or the question has no answer — the value has no token
 * after normalisation, or the result reached the index's token ceiling before
 * a match (`uncheckable`, never "not found").
 */
export type ResultCarriage = 'found' | 'not-found' | 'uncheckable';
/** A value's canonical token sequence — the evidence module's "same value". */
export declare function canonicalTokens(text: string): string[];
/** Whether `needle` occurs contiguously in `hay` — whole tokens, never substrings. */
export declare function occursIn(needle: readonly string[], hay: readonly string[]): boolean;
/**
 * A result read once, asked many times — `(value) => ResultCarriage`, the
 * same answers `resultCarries` gives, without re-reading the result for every
 * value. The declared-sources checks ask one result about several values per
 * batch (`core/agent/arguments/checks.ts`).
 */
export declare function resultReader(content: string): (value: string | number | boolean) => ResultCarriage;
/**
 * Whether ONE tool result carries a value — read the way the evidence index
 * reads a result (`readResult`: parsed JSON with an absence's `looked_for`
 * projected away, walked leaf by leaf, keys included; the text when it is not
 * JSON), so a number or a boolean in compact JSON is found (`{"limit":50,
 * "ok":true}` carries `50` and `true`) where a tokenizer over the raw string
 * would see `:50` and `:true` — also when a framework note follows the JSON
 * (a step banner, the repeated-call note), when it is several JSON blocks (an
 * MCP text result) and in a capped result's `head`. A one-token value is found when it equals a
 * leaf or one of a leaf's tokens; a longer value must occur contiguously
 * inside one string leaf (or in the text). Whole tokens only, never
 * substrings; one normaliser (`lib/normalize.ts`), so `41,200` is `41200` here as
 * at the gate.
 *
 * `content` is the TOOL's own bytes — the caller cuts a library note off first
 * (`lib/toolBytes.ts` · `toolBytesOf`). `uncheckable` when the value has no
 * token after normalisation, or the result reached the index's token ceiling
 * (`MAX_INDEX_TOKENS`) before a match: never a pass, never "not found".
 * `resultReader` answers the same question for many values over one read.
 *
 * @example
 * ```ts
 * resultCarries('{"host":"srv-4417","limit":50,"ok":true}', 50);    // 'found'
 * resultCarries('{"host":"srv-4417"}', 'srv-44');                   // 'not-found'
 * resultCarries('{"host":"srv-4417"}', '２４ｈ');                    // 'uncheckable'
 * ```
 */
export declare function resultCarries(content: string, value: string | number | boolean): ResultCarriage;