agentfootprint/dist/esm/semantics/coverage/items.d.ts

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

/**
 * coverage/items — normalizing and refusing coverage lists.
 *
 * Pattern: one validator, two doors (`absent()` and `coverage()`), so the two
 *          primitives cannot disagree about what a well-formed piece of
 *          ground looks like.
 * Role:    core/ layer, pure. Throws at the CALL SITE (the
 *          `resolveEvidenceGate` precedent): a malformed declaration is a
 *          mistake in the line the author just wrote, and the stack should
 *          say so — not fail on the first absence of the first incident.
 * Emits:   N/A.
 */
import type { CoverageInput, CoverageItem } from './types.js';
/** Section names, as the author spells them — used verbatim in refusals. */
export type CoverageSection = 'checked' | 'notChecked' | 'cannotCover';
/** The closed kind vocabulary — `CoverageItem.kind`, named for this file. */
export type CoverageKind = NonNullable<CoverageItem['kind']>;
/** The longest `short` a report prints on one line. */
export declare const MAX_SHORT_CHARS = 80;
/** The item keys that are RECORD-ONLY — never served to the model, never
 *  evidence. `read.ts` · `servedToModel` and `evidence.ts` remove these. */
export declare const RECORD_ONLY_ITEM_KEYS: readonly string[];
/** What is wrong with a `short`, or `undefined` when it is fine. `what` is the
 *  item's own (trimmed) `what`. */
export declare function shortProblem(short: unknown, what: string): string | undefined;
/** The record-only extras a well-formed item may carry. */
export interface CoverageItemExtras {
    readonly short?: string;
    readonly kind?: CoverageKind;
}
/**
 * The item's `short` / `kind`, when each is valid — the NON-throwing reader
 * every dispatch door uses (`../../core/agent/stages/toolCalls.ts` · `declareCoverage`'s
 * copy), so the event and the tracked row carry the same fields.
 *
 * An invalid value is DROPPED, never repaired, and named once per tool in dev
 * mode: an envelope minted elsewhere (a Python sidecar, a hand-built value)
 * is read as found, and the absence it carries is still an absence either
 * way. `{}` when the item declares neither — so a spread of it adds no key.
 */
export declare function readItemExtras(item: unknown, section: CoverageSection, toolName?: string): CoverageItemExtras;
/**
 * One coverage list with the record-only keys removed from every item that
 * has one — the SAME reference when no item has one (the zero-cost law: a
 * run whose tools declare neither serves exactly the value it always did).
 * Anything that is not an array, and any item that is not an object, is left
 * as found.
 */
export declare function listWithoutRecordOnly(list: unknown): unknown;
/**
 * The keys a {@link CoverageDeclaration} has — the three lists, as the author
 * spells them — tied to the type in BOTH directions: a key the interface
 * gains, or one listed here that it does not have, fails to compile.
 * `coverage()` and a `describedResult()` declaration's
 * `coverage` refuse any other
 * key (`refusal.ts` · `refuseUnknownKeys`), so `not_checked` is refused,
 * naming `notChecked`, instead of vanishing.
 */
export declare const COVERAGE_DECLARATION_KEYS: readonly string[];
/**
 * Normalize one author list into {@link CoverageItem}s, refusing anything a
 * reader could not act on. Every refusal starts with `refusal.ts` ·
 * `REFUSED_PREFIX` and names the list and index, never the helper.
 *
 * `requireWhy` is true only for `cannotCover`. The asymmetry is deliberate:
 * "we checked the fcns database" and "we did not check the archive" are
 * complete statements on their own, but "this tool can never see host-side
 * multipathing" is a claim about capability — and a permanent blind spot with
 * no reason attached cannot be acted on, escalated, or disproved. It is also
 * the one an operator is most likely to want to fix, so the reason is the
 * useful half.
 */
export declare function normalizeCoverageList(section: CoverageSection, list: readonly CoverageInput[] | undefined, requireWhy: boolean): readonly CoverageItem[];
/** Two entries are the same ground when they say the same two things. Used to
 *  fold the run's declarations into ONE answer-level block: five tools that
 *  all name the same missing collector should say it once. */
export declare function sameItem(a: CoverageItem, b: CoverageItem): boolean;
/** Merge lists in declaration order, dropping repeats. Order is the run's own
 *  order on purpose — it is the only ordering that means anything here. */
export declare function mergeItems(lists: ReadonlyArray<readonly CoverageItem[]>): readonly CoverageItem[];
/**
 * `holder` (an envelope or a ledger marker) with each wire list stripped of
 * the record-only keys — the SAME reference when none of its lists carried
 * one. The one helper `read.ts` · `servedToModel` (what the model is served)
 * and `evidence.ts` (what may ground) both use, so the two cannot disagree
 * about which keys are record-only.
 */
export declare function listsWithoutRecordOnly<T extends object>(holder: T): T;