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

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

/**
 * coverage/timeLimitFacts — WHAT the time layer's limits lines of one turn
 * say (step T8), read from the record and not yet rendered: the clock's zone,
 * the turn's `period` rows whose result checks hold, and the wall-clock
 * sources.
 *
 * Pattern: Walker over the committed ledger; pure, no rendering.
 * Role:    the record half of `timeLimits.ts`, split out BY FILE for the one
 *          synchronous door that needs it — the Tools mount's `inputMapper`
 *          (`agent/buildAgentChart.ts` · `timeLimitsArg`), which runs before
 *          any `import()` can: it hands these facts across, and the slot's
 *          served line renders them (`arguments/serve.ts` · `timeLimitsLine`,
 *          loaded under the arm). The renderer (`time/present.ts`) never
 *          reaches the graph `import { Agent }` loads (the optional-family
 *          law, `test/trace-toolpack/browserGraph.test.ts`).
 * Emits:   N/A.
 *
 * `undefined` exactly when `timeLimits.ts` · `renderTimeLimits` would say
 * nothing for the same audience — so the mount arg stays value-conditional:
 * a turn whose reads match what was asked crosses no key.
 *
 * @example
 * ```ts
 * timeLimitFactsOf(ledger, 1, 'model');
 * // { zone: 'America/Los_Angeles', period: [{ kind: 'period', differs: { … }, … }], sources: [] }
 * ```
 */
import type { PeriodRow } from './period.js';
import { type ClocksDiffer, type SourceClock } from '../../time/checkRecord.js';
import type { ZoneName } from '../../time/zone.js';
/** Who reads the lines: the person (the limits block) or the model (the served time line). */
export type TimeLimitsAudience = 'person' | 'model';
/** The unrendered limits of one turn — see the file header. */
export interface TimeLimitFacts {
    /** The clock's zone — every range is rendered in it. */
    readonly zone: ZoneName;
    /** The turn's `period` rows that carry a check line, in the order filed. */
    readonly period: readonly PeriodRow[];
    /** The wall-clock sources, one per tool and zone (`checkRecord.ts` · `distinctSources`). */
    readonly sources: readonly SourceClock[];
    /** The label that two sources declare different zones (`checkRecord.ts` · `clocksDiffer`). */
    readonly differ?: ClocksDiffer;
    /** The clock's zone is unknown (G15): `zone` is only the UTC spelling, and the lines say so. */
    readonly zoneUnknown?: true;
}
/**
 * Whether a `period` row carries a limits line for `audience`: a read that
 * differs, a shifted look-back, or a window beyond retention (`period.ts` ·
 * `periodCheckLine` returns one exactly then) — and, for the MODEL only, a
 * source that holds none or only part of the asked time (`held`, rendered by
 * `timeLimits.ts` · `heldLine`). The person's limits block already prints that
 * span on the call's `Period:` line (`period.ts` · `periodLine`), in their
 * zone, so it gets no second line.
 */
export declare function carriesCheckLine(row: PeriodRow, audience?: TimeLimitsAudience): boolean;
/**
 * The turn's limits facts from the ledger. `turn` undefined reads every row
 * (a ledger that carries one turn). `undefined` when there is no clock or,
 * for this `audience`, nothing to say: the person reads every wall-clock
 * source, the model only the label that two differ.
 */
export declare function timeLimitFactsOf(ledger: readonly unknown[] | undefined, turn: number | undefined, audience?: TimeLimitsAudience): TimeLimitFacts | undefined;