agentfootprint/dist/esm/time/drift.d.ts

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

/**
 * time/drift — the clock at dispatch (time design § 7.4, step T5b).
 *
 * Pattern: one pure decision per dispatched call. The turn's clock is frozen
 *          at the message (§ 4); a LOOK-BACK is evaluated by the tool, against
 *          its own clock, when it is handed the call. After a pause (or with
 *          an app `now` far from the wall clock) the two differ by
 *          `drift = dispatchedAt − now`. Within the tool's step nothing
 *          changes; past it, the library re-sends its OWN look-back fill as
 *          the asked range in the tool's first absolute form that holds it
 *          exactly, and records a look-back it cannot re-send — the model's
 *          own (never written over, § 7.3), or a tool with no absolute form —
 *          as shifted.
 * Role:    L0 leaf (the time layer). Imports `convert.ts` and `range.ts`
 *          types only. Asked by ToolCalls (`stages/toolCalls.ts` ·
 *          `timeAtDispatch`) at both execute sites, just before the tool
 *          runs; the answer rides the `call` row (`rows.ts` · `CallDrift`).
 * Emits:   N/A.
 *
 * | Drift | The call sent | Tool has an absolute form | Sent | Recorded |
 * |-------|---------------|---------------------------|------|----------|
 * | ≤ the tool's step (one minute when none) | — | — | as it was | nothing |
 * | larger | the library's look-back fill | yes | the asked range in that form | `drift: { outcome: 'redrawn', form }` |
 * | larger | the library's look-back fill | no | the look-back | `drift: { outcome: 'shifted' }` |
 * | larger | the model's look-back | — | the look-back, as sent | `drift: { outcome: 'shifted' }` |
 *
 * @example
 * ```ts
 * driftAtDispatch(
 *   { how: 'filled', form: 0, asked: { from: '2026-10-09T14:40:00Z', to: '2026-10-09T15:40:00.001Z' } },
 *   [{ kind: 'lookback', argument: 'window', signed: false },
 *    { kind: 'bounds', from: { argument: 'start', as: 'epoch-ms' },
 *      to: { argument: 'end', as: 'epoch-ms', edge: 'exclusive' } }],
 *   { now: '2026-10-09T15:40:00Z', dispatchedAt: '2026-10-09T16:10:00.000Z', granularityMs: 60_000 },
 * );
 * // { byMs: 1_800_000, outcome: 'redrawn', form: 1,
 * //   values: { start: 1791556800000, end: 1791560400001 } }
 * ```
 */
import { type PeriodForm } from './convert.js';
import { type InstantText } from './instant.js';
import type { TimeRange } from './range.js';
import type { ZoneName } from './zone.js';
/** What a call's `call-window` row says about its window — the fields the decision reads. */
export interface DispatchedWindow {
    readonly how: string;
    readonly form?: number;
    readonly asked?: TimeRange;
}
/** The clocks and the tool's step. */
export interface DispatchClock {
    /** The turn's frozen clock. */
    readonly now: InstantText;
    /** The wall clock at dispatch — the `call` row's. */
    readonly dispatchedAt: InstantText;
    /** The tool's `granularity` in milliseconds, else one minute. */
    readonly granularityMs: number;
    /** The clock's zone — a wall or date form's zone argument is sent in it. */
    readonly zone?: ZoneName;
    /** The app's `.time({ zone })`, for a form that declares `wallZone: 'app'`. */
    readonly appZone?: ZoneName;
}
/** The decision: nothing, a redraw (with the values to send), or a shift. */
export type DispatchDrift = {
    readonly byMs: number;
    readonly outcome: 'redrawn';
    readonly form: number;
    readonly values: Readonly<Record<string, unknown>>;
} | {
    readonly byMs: number;
    readonly outcome: 'shifted';
};
/**
 * Whether the call SENT a look-back: its `call-window` row names a form, that
 * form is a `lookback`, and the call dispatched with a window in it (filled,
 * bound, or the model's). The one reading of it — the drift decision here and
 * the result checks' step allowance (`check.ts` · `differsOf`) both ask it.
 */
export declare function sentLookback(window: Pick<DispatchedWindow, 'how' | 'form'>, forms: readonly PeriodForm[]): boolean;
/**
 * The drift decision for one dispatched call (the module table), or
 * `undefined` when the call sent no look-back or the drift is within the
 * tool's step. Pure.
 */
export declare function driftAtDispatch(window: DispatchedWindow | undefined, forms: readonly PeriodForm[], clock: DispatchClock): DispatchDrift | undefined;