agentfootprint 9.128.1 → 9.131.0

package/dist/esm/core/time/rows.d.ts

@@ -0,0 +1,297 @@
+/**
+ * core/time/rows — the time layer's rows on the one honesty ledger
+ * (`AgentState.findingsLedger`), and the checkpoint door's test for each.
+ *
+ * Pattern: one owner of each row's shape (the `coverage/period.ts` ·
+ *          `periodRowIsWellFormed` precedent): the module that defines a row
+ *          also answers "is this a row I would have filed?", so the
+ *          checkpoint door (`core/runCheckpoint.ts` · `ledgerRowIsWellFormed`)
+ *          refuses exactly what the library never files.
+ * Role:    core/ leaf (the time layer). Imports `instant.ts`, `zone.ts`,
+ *          `range.ts`, `reader.ts` (the parts check), `resolveRecord.ts` (the
+ *          candidate and choice checks), `convert.ts` (the refusal codes) and
+ *          `clock.ts`' and `bind.ts`' types only — the rows are plain records
+ *          the agent loop files (`agent/stages/timeLayer.ts`, the inputs
+ *          layer). Their BUILDERS live in `rowsBuild.ts` — never re-exported
+ *          here: they reach the resolver, which only an armed agent loads,
+ *          while this module is on the checkpoint door's synchronous path.
+ * Emits:   N/A — the rows fire no event of their own (the `conflict` row's
+ *          precedent: no event field ships without a reader in the same
+ *          release). The lens reads the rows.
+ *
+ * Eight kinds, each filed only while `.time()` is armed:
+ *
+ * | Kind | Filed | Carries |
+ * |------|-------|---------|
+ * | `clock` | once per turn, by seed | the turn's {@link TimeClock} and, when the run passed one, the `control` window |
+ * | `clock-on-resume` | first thing in the resumed leg's ToolCalls stage — either pause shape: the pausable resume door, or the stage re-run an `interrupt()` pause makes — when a resume passed a `time` that differs from the kept clock | what was passed and what was kept — the kept clock still rules |
+ * | `call` | once per dispatched call, just before the tool runs | `dispatchedAt`: the wall clock at dispatch (a look-back is evaluated by the TOOL at dispatch, which after a pause is later than `now`); `drift` when a look-back was sent more than the tool's step after `now` — `redrawn` into an absolute form, or `shifted` (§ 7.4, `drift.ts`) |
+ * | `call-window` | by the inputs layer, once per call to a tool that declares period forms, before it dispatches | which window the call carries: filled from the turn's one window (exactly, or wider — with what the read adds), bound to one (by quote or value), the model's own (beside the person's when it differs), unread, not filled and why, or refused before dispatch and why |
+ * | `time-reading` | by seed, once per MENTION the armed reader (`.time({ reader })`) found in the person's message — or ONE row with `mentions: 0` when it found none, so a retry knows the message was read | the quote, the parts, every candidate `resolve.ts` made of them, how the reading settled (`choice` — never settled by the library: every reading is a PROPOSAL, `open` with `confirm`, its candidates `said: []`), the reader's id, version, kind and locale, and the tz database version; a refused mention keeps only why |
+ * | `time-answer` | by the batch ask, once per mention the person settled in the time ask — the only door by which a window of words becomes the person's | the mention, the window and its zone, and `how`: `confirmed` (they picked a reading the library offered — the click) or `edited` (they wrote their own) |
+ * | `time-derived` | by the Route decider, once per judged answer that stands, when the evidence gate found values no tool result carried that the library itself spelled from this turn's time readings (§ 9.5, step T7 — `forms.ts` · `timeFormsOf`'s `derived` list) | the values, normalized and clipped as the gate reports them — the lineage `derived-from-reading`: never invented, never the person's |
+ * | `source-clock` | by ToolCalls, once per call and zone, when the call minted a dataset whose declared time axis names a `zone` (§ 9.6, step T8) | the tool, the call and the zone its rows' wall times are in — read by the limits block's `Clocks` lines and `check.ts` · `clocksDiffer` |
+ *
+ * Readers that switch over every row kind must skip one they do not know.
+ */
+import { type InstantText } from './instant.js';
+import { type TimeRange } from './range.js';
+import { type ZoneName } from './zone.js';
+import type { ClockChange, TimeClock } from './clock.js';
+import { type MentionRefusal, type TimeParts } from './reader.js';
+import type { CallWindow, WindowSource } from './bind.js';
+import { type TimeRefusal } from './periodForm.js';
+import { type ReadingChoice, type TimeCandidate } from './resolveRecord.js';
+/** A window set in a UI, as the clock row records it. */
+export interface ControlWindow extends TimeRange {
+    readonly source: 'control';
+}
+/** The turn's clock stamp — one per turn (time design § 4). */
+export interface ClockRow extends TimeClock {
+    readonly kind: 'clock';
+    /** `AgentState.turnNumber` when the row was filed — the conversation turn. */
+    readonly turn: number;
+    /** The iteration seed filed it at (1). */
+    readonly iteration: number;
+    /** The run's `time.window`, when it passed one. */
+    readonly window?: ControlWindow;
+}
+/** A resume passed a `time` that differs from the frozen clock: recorded, not applied (TQ21). */
+export interface ClockOnResumeRow {
+    readonly kind: 'clock-on-resume';
+    readonly turn: number;
+    /** The iteration the paused batch ran in. */
+    readonly iteration: number;
+    /** What the resume passed, as read (values as written, a `Date` spelled in UTC). */
+    readonly passed: ClockChange['passed'];
+    /** The frozen clock's values the passed ones would have replaced. */
+    readonly kept: ClockChange['kept'];
+}
+/** One dispatched call's wall-clock moment (time design § 4, § 7.4). */
+export interface CallRow {
+    readonly kind: 'call';
+    readonly turn: number;
+    readonly iteration: number;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    /** The wall clock when the library handed the call to the tool — UTC, millisecond precision. */
+    readonly dispatchedAt: InstantText;
+    /**
+     * The clock at dispatch (§ 7.4, step T5b) — present only when the call sent
+     * a LOOK-BACK and `dispatchedAt − now` (`byMs`, signed) is more than the
+     * tool's step. `redrawn`: the library's own look-back fill was re-sent as
+     * the asked range in absolute form `form`; `shifted`: the look-back ran as
+     * sent (the model's value, or no absolute form), so the tool read a window
+     * shifted by `byMs` — `period-shifted`.
+     */
+    readonly drift?: CallDrift;
+}
+/** A look-back call's dispatch drift (§ 7.4) — see {@link CallRow.drift}. */
+export type CallDrift = {
+    readonly byMs: number;
+    readonly outcome: 'redrawn';
+    readonly form: number;
+} | {
+    readonly byMs: number;
+    readonly outcome: 'shifted';
+};
+/** The reader a reading came from, as recorded. */
+export interface TimeReaderStamp {
+    readonly id: string;
+    readonly version: string;
+    readonly kind: 'rule' | 'model';
+    readonly locale: string;
+}
+/**
+ * One mention the armed reader found in the person's message (time design
+ * § 5.2) — or, with `mentions: 0` and no mention fields, the record that the
+ * message was read and held none. Read back, never re-read: a resume and a
+ * retry of the same turn find these rows and do not call the reader.
+ */
+export interface TimeReadingRow {
+    readonly kind: 'time-reading';
+    readonly turn: number;
+    readonly iteration: number;
+    readonly reader: TimeReaderStamp;
+    /** The tz database the candidates were resolved with (`process.versions.tz`), else `'unknown'`. */
+    readonly tzdata: string;
+    /** How many mentions the reading held. */
+    readonly mentions: number;
+    /** This row's mention, 0-based — absent on the `mentions: 0` row. */
+    readonly mention?: number;
+    /** A verbatim substring of the person's message. */
+    readonly quote?: string;
+    readonly parses?: readonly TimeParts[];
+    readonly problem?: 'unreadable';
+    /** Why the mention was refused — its quote was not in the message, or its parts were malformed. It keeps no text. */
+    readonly refused?: MentionRefusal;
+    /** Every window `resolve.ts` made of the parts. */
+    readonly candidates?: readonly TimeCandidate[];
+    /** How the reading settled under the policy — `open` waits for the person. */
+    readonly choice?: ReadingChoice;
+}
+/**
+ * The window the person settled for one mention in the time ask — the ONLY
+ * door by which a window of words becomes the person's (the owner's decision
+ * "Always confirm", time design TQ29). Filed by the batch ask when a window
+ * answer binds (`arguments/ask.ts` · `bindAnswer`); read back by
+ * `bind.ts` · `turnWindowsOf`, so the rest of the turn uses it as an
+ * `answered` window and the served sentence names it with its source.
+ */
+export interface TimeAnswerRow extends TimeRange {
+    readonly kind: 'time-answer';
+    readonly turn: number;
+    readonly iteration: number;
+    /** The `time-reading` row's mention the answer settles. */
+    readonly mention: number;
+    /** The zone the window was answered in — the reading's, or the turn's clock for free entry. */
+    readonly zone: ZoneName;
+    /**
+     * `confirmed`: the person picked a reading the library offered (the
+     * pre-filled choice — their click); `edited`: they wrote a window of their
+     * own. Both are the person's answer.
+     */
+    readonly how: 'confirmed' | 'edited';
+}
+/** The person's window a `call-window` row names — its range, who gave it, and its mention. */
+export interface PersonWindow extends TimeRange {
+    readonly source: WindowSource;
+    /** The `time-reading` row's mention index — absent on a `control` window. */
+    readonly mention?: number;
+}
+/**
+ * Which window one call to a tool that declares period forms carries (time
+ * design § 7.3) — one row per such call, filed by the inputs layer beside the
+ * call's `argument` rows, before the call dispatches.
+ *
+ * | `how` | Means |
+ * |-------|-------|
+ * | `filled` | the model left the period out; the turn's one window (`person`) went into form `form` exactly (`rounded`: an epoch-seconds bound or a look-back's length moved outward) |
+ * | `bound` | the sent window IS the person's window `person` — named by the model's quote (`by: 'quote'`) or equal in value (`by: 'value'`) |
+ * | `model-chosen` | the sent window (`asked`) differs from the person's (`person`, when one window is theirs): it ran as sent (the v1 law) |
+ * | `model` | the sent window, and no window of the person's this turn |
+ * | `unread` | a period argument was sent and no form reads the call back as a range |
+ * | `not-filled` | the period was left out and nothing was filled (`why`) — the tool's own rule applied |
+ * | `refused` | refused before dispatch (`refused`: a fact the window breaks, `multi-day`, `dst-gap` with its `argument`) — the call did not run |
+ *
+ * `asked` is the half-open range the call asks for: the person's on a fill,
+ * the sent value read back otherwise — what `ctx.time.asked` hands the tool.
+ * A WIDENED fill (no form holds the window exactly — § 7.2) carries `sent`,
+ * the range the tool reads, and either `differs.extra` (the parts read but
+ * not asked — `period-differs-from-asked`) or `trimmedByTool` (the tool
+ * declares `filtersToAsked`). `partlyBeyondRetention` marks a window that
+ * starts before the source's oldest data and ends after it: it dispatched.
+ */
+export interface CallWindowRow {
+    readonly kind: 'call-window';
+    readonly turn: number;
+    readonly iteration: number;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly how: CallWindow['how'];
+    /** The index of the tool's form the call used (filled into, or read back from). */
+    readonly form?: number;
+    readonly asked?: TimeRange;
+    readonly person?: PersonWindow;
+    readonly by?: 'quote' | 'value';
+    readonly rounded?: true;
+    readonly why?: 'no-window' | 'several-mentions' | 'open-reading' | 'no-exact-form';
+    /** A widened fill: the range the tool reads with the sent values. */
+    readonly sent?: TimeRange;
+    /** A widened fill the tool does not trim: the parts read but not asked. */
+    readonly differs?: {
+        readonly extra: readonly TimeRange[];
+    };
+    /** A widened fill to a tool that declares `filtersToAsked`. */
+    readonly trimmedByTool?: true;
+    readonly partlyBeyondRetention?: true;
+    /** Why the call was refused before dispatch. */
+    readonly refused?: TimeRefusal;
+    /** On a `dst-gap` refusal: the argument whose wall time the zone skips. */
+    readonly argument?: string;
+}
+/**
+ * The answer's values the library itself spelled from a time reading of this
+ * turn (§ 9.5, step T7) — an implied year, an offset, the end-of-grain
+ * minute, a value of the served time line. The lineage `derived-from-reading`:
+ * the answer's standing reads it as "not sure" at most, never "known", and the
+ * gate never calls these invented.
+ */
+export interface TimeDerivedRow {
+    readonly kind: 'time-derived';
+    readonly turn: number;
+    readonly iteration: number;
+    /** The values as the gate reports them — normalized, clipped, at most `MAX_DERIVED_VALUES`. */
+    readonly values: readonly string[];
+}
+/** The most values one `time-derived` row carries (the gate's report bound). */
+export declare const MAX_DERIVED_VALUES = 12;
+/** The longest value a `time-derived` row carries (the gate's clip). */
+export declare const MAX_DERIVED_VALUE_CHARS = 64;
+/**
+ * A wall-clock source (§ 9.6, step T8): the call minted a dataset whose
+ * declared time axis (`axis.ts` · `DatasetTimeAxis`, its `zone`) says its rows are
+ * wall times in `zone`. One row per call and zone. A period's offset is never
+ * read as a clock — only a declared axis zone files this row.
+ */
+export interface SourceClockRow {
+    readonly kind: 'source-clock';
+    readonly turn: number;
+    readonly iteration: number;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly zone: ZoneName;
+}
+/** Every time-layer row kind. */
+export type TimeRow = ClockRow | ClockOnResumeRow | CallRow | TimeReadingRow | CallWindowRow | TimeAnswerRow | TimeDerivedRow | SourceClockRow;
+/** This turn's `call-window` row for one call, if the inputs layer filed one — `ctx.time` reads it. */
+export declare function callWindowOfCall(ledger: readonly unknown[] | undefined, toolCallId: string, turn: number): CallWindowRow | undefined;
+/** The `time-reading` rows filed for `turn` — read back on a resume or a retry, never re-read. */
+export declare function readingsOf(ledger: readonly unknown[] | undefined, turn: number): readonly TimeReadingRow[];
+/** The `time-answer` row for one window the person settled in the time ask. */
+export declare function timeAnswerRow(answer: {
+    readonly mention: number;
+    readonly range: TimeRange;
+    readonly zone: ZoneName;
+    readonly how: 'confirmed' | 'edited';
+}, at: {
+    readonly turn: number;
+    readonly iteration: number;
+}): TimeAnswerRow;
+/** The `time-derived` row for one judged answer — `values` cut to {@link MAX_DERIVED_VALUES}. */
+export declare function timeDerivedRow(values: readonly string[], at: {
+    readonly turn: number;
+    readonly iteration: number;
+}): TimeDerivedRow;
+/** The `source-clock` row for one call's dataset whose declared axis names `zone`. */
+export declare function sourceClockRow(call: {
+    readonly toolCallId: string;
+    readonly toolName: string;
+}, at: {
+    readonly turn: number;
+    readonly iteration: number;
+}, zone: ZoneName): SourceClockRow;
+/** This turn's `call` row for one call — the last filed (a resumed leg files its own). */
+export declare function callRowOfCall(ledger: readonly unknown[] | undefined, toolCallId: string, turn: number): CallRow | undefined;
+/** The `source-clock` rows filed for `turn`, in the order filed. */
+export declare function sourceClocksOf(ledger: readonly unknown[] | undefined, turn: number | undefined): readonly SourceClockRow[];
+/** The `time-answer` rows filed for `turn`, in the order filed. */
+export declare function answersOf(ledger: readonly unknown[] | undefined, turn: number): readonly TimeAnswerRow[];
+/**
+ * The clock of the LATEST turn on the ledger — the last `clock` row — or
+ * `undefined` when none was filed (an agent without `.time()`, or a turn
+ * paused by a runtime that had none). A continued conversation carries one
+ * row per turn; the last one is this turn's, because each turn's seed files
+ * exactly one (last in seed, before any stage of the turn can read it).
+ */
+export declare function clockOf(ledger: readonly unknown[] | undefined): ClockRow | undefined;
+/**
+ * The checkpoint door's test for a time-layer row — `true` only for a row of
+ * one of the eight kinds with every field this module files, well formed.
+ * Any other kind answers `false` (the caller routes by kind first).
+ */
+export declare function timeRowIsWellFormed(row: Readonly<Record<string, unknown>>): boolean;
+/** Whether a ledger row is one of the time layer's kinds (the router's question). */
+export declare function isTimeRowKind(kind: unknown): kind is TimeRow['kind'];
+/** The zone the answer's lines are rendered in — the clock's (no reader is armed yet, so the run's). */
+export declare function presentationZoneOf(ledger: readonly unknown[] | undefined): ZoneName | undefined;