agentfootprint/dist/esm/semantics/coverage/search/gaps.d.ts

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

/**
 * search/gaps — the ground one call's search did NOT cover, typed.
 *
 * Pattern: one pure composer per list; this one is the gaps.
 * Role:    semantics/ layer, pure.
 * Emits:   N/A.
 *
 * Each gap names the facet it bears on, so a checker decides relevance by
 * facet and never by reading prose:
 *
 *   • `argument-unsent` — any classified argument of any role but `inert` the
 *     call did not send, with no `whenOmitted`, or sent as an empty list: its
 *     default may live inside `execute`, and an empty list names nothing (it is
 *     never "every value"). Bears on that argument's facet (cap and page:
 *     completeness).
 *   • `cap-reached` — rows at the cap in effect (an argument's, or the
 *     declared server cap), rows that cannot be counted under a cap, or a
 *     server cap of `'unknown'`. Bears on completeness.
 *   • `paged` — a page argument sent, a result whose `paging.next` is not
 *     null, or a tool with a `page` argument whose result declares no
 *     `paging`. Bears on completeness.
 *   • `partial` — the tool declared its outcome `partial` or `pending`.
 *   • `period` — the declared period's verdict is not `covered`.
 *   • `scope` — the declaration's own constants.
 *   • `prose` — a hand-written `notChecked` / `cannotCover` item; no facet.
 *
 * Every `what` the library writes here names an ARGUMENT or a verdict, never
 * a value the call sent.
 */
import type { CoverageGap } from '../composedCoverage.js';
import { type DeclaredPeriod } from '../period.js';
import type { CoverageItem } from '../types.js';
import type { ArgumentReading } from './inEffect.js';
import type { PagingDeclaration } from './resultFacts.js';
import type { SearchArgument, ToolSearch } from './types.js';
import type { ToolResultStatus } from '../../toolOutcome.js';
/** What the gap composer reads. */
export interface GapInput {
    readonly search: ToolSearch;
    readonly readings: ReadonlyArray<readonly [SearchArgument, ArgumentReading]>;
    /** How many rows the result carried; `undefined` when it cannot be counted. */
    readonly rows: number | undefined;
    readonly paging?: PagingDeclaration;
    readonly period?: DeclaredPeriod;
    readonly status?: ToolResultStatus;
    readonly handNotChecked: readonly CoverageItem[];
    readonly handCannotCover: readonly CoverageItem[];
}
/** The gaps, and the two plain lists every older reader prints. */
export interface ComposedGaps {
    readonly gaps: readonly CoverageGap[];
    readonly notChecked: readonly CoverageItem[];
    readonly cannotCover: readonly CoverageItem[];
}
/**
 * Every gap of one call, in a fixed order, with the plain lists: the
 * composed gaps (but `period`, which the period row carries) and the
 * hand-written `notChecked` under `notChecked`; the declared constants and the
 * hand-written `cannotCover` under `cannotCover`.
 */
export declare function composeGaps(input: GapInput): ComposedGaps;
/** The gap kinds that keep a row from being complete — and `prose`, which names no facet. */
export declare function blocksComplete(gap: CoverageGap): boolean;