agentfootprint 10.3.0 → 10.3.1

package/dist/esm/semantics/toolOutcome.js

@@ -0,0 +1,32 @@
+/**
+ * toolOutcome — the normalized tool-outcome vocabulary, as a PURE leaf
+ * (9.34.0).
+ *
+ * WHY IT LIVES HERE. A skill-graph route edge can key on what a tool
+ * DECLARED happened (`onToolStatus`), so this vocabulary is part of the
+ * graph's own reading of a turn — `InjectionContext.toolResults[].status`
+ * is typed by it. It used to be declared inside `core/agent/toolEffects.ts`
+ * (today `semantics/toolEffects.ts`),
+ * which meant the graph's context type reached into the agent loop's
+ * tool-effects module for one string union: the loop's vocabulary embedded
+ * in the graph's contract, pointing the dependency the wrong way.
+ *
+ * So the words moved DOWN here — a module with zero imports that both
+ * sides read. `semantics/toolEffects.ts` re-exports them under the same
+ * names, so every existing import path is unchanged; that module remains
+ * the owner of the ENVELOPE grammar (the two effect kinds, the recognizer).
+ *
+ * Zone: a zero-import leaf the skill-graph PURE CORE may reach (`PURE_LEAVES`).
+ * Pinned by `test/injection-engine/skill-graph-fence.test.ts`.
+ */
+/** The closed set, as data — validators and docs read one list. */
+export const TOOL_RESULT_STATUSES = [
+    'success',
+    'failure',
+    'denied',
+    'invalid',
+    'partial',
+    'pending',
+    'absent',
+];
+//# sourceMappingURL=toolOutcome.js.map

package/dist/esm/semantics/toolOutcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolOutcome.js","sourceRoot":"","sources":["../../../src/semantics/toolOutcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0BH,mEAAmE;AACnE,MAAM,CAAC,MAAM,oBAAoB,GAAgC;IAC/D,SAAS;IACT,SAAS;IACT,QAAQ;IACR,SAAS;IACT,SAAS;IACT,SAAS;IACT,QAAQ;CACT,CAAC"}

package/dist/esm/semantics/types.d.ts

@@ -0,0 +1,322 @@
+/**
+ * semantics/types — the semantic tool-result vocabulary, as a PURE leaf
+ * (9.53.0, the `toolOutcome.ts` precedent).
+ *
+ * WHY IT LIVES HERE. Two sides read these words and neither may own the
+ * other: the agent loop's dispatch boundary (core/agent/stages/toolCalls.ts)
+ * recognizes the envelope at run time, and the `check:semantics` build gate
+ * (semantics/check.ts) judges the same shapes with no agent anywhere in
+ * sight. Declaring the vocabulary in a leaf both sides import keeps the
+ * dependency pointing the right way — the loop and the gate depend on the
+ * words, never on each other.
+ *
+ * The one exception to "zero imports" is TYPE-ONLY and deliberate: the
+ * envelope's `coverage` field ABSORBS the existing coverage vocabulary
+ * (`CoverageItem` / `CoverageInput`, semantics/coverage/types.ts — itself a
+ * pure-data leaf) instead of duplicating it. Two spellings of "ground this
+ * result does not cover" would eventually disagree; type-only imports erase
+ * at runtime, so this module stays a runtime leaf.
+ *
+ * ## What the envelope is
+ *
+ * A tool that answers "how many IOPS did fc1/3 do last hour?" today returns
+ * prose or an ad-hoc object, and every caveat that makes the number honest —
+ * the collection interval, whether the values are counters that must not be
+ * summed, when the world was actually measured, which clusters were not
+ * collected — is re-implemented by hand inside every tool and held in place
+ * by review. Culture scales to one disciplined author; it does not scale to
+ * a hundred tools. The semantic envelope makes those caveats TYPED DATA that
+ * travel with the values, so honesty is inherited, not re-authored — and so
+ * a build gate can refuse a triage tool that forgot its own limits.
+ *
+ * It is a SIBLING recognizer beside the effects envelope and the coverage
+ * primitives — its own reserved marker (`af_semantics`, the
+ * `af_absent`/`af_coverage` family), never new keys on the effects envelope.
+ * The three compose on one result: `{ content: describedResult({…}), effects:
+ * […], status }` is a tool that returns typed data AND proposes a transition.
+ */
+import type { CoverageDeclaration, CoverageItem } from './coverage/types.js';
+import type { DeclaredPeriod, PeriodOnWire } from './coverage/period.js';
+/**
+ * The reserved key that makes a semantic envelope recognizable. Reserved
+ * vocabulary on the tool-result wire (the `af_absent` / `af_coverage`
+ * precedent): a plain object carrying `af_semantics: true` that validates
+ * cleanly is an envelope; every other value any tool has ever returned keeps
+ * its bytes.
+ */
+export declare const SEMANTICS_MARKER = "af_semantics";
+/**
+ * One measured point. `t` is the tool's own clock words (an ISO string or an
+ * epoch number — the library never reinterprets it), `entity` is what was
+ * measured, `metric` names the measurement, `value` is the reading.
+ */
+export interface SemanticSeriesPoint {
+    readonly t: string | number;
+    readonly entity: string;
+    readonly metric: string;
+    readonly value: number | string | boolean | null;
+}
+/**
+ * One row of typed facts about one entity. The columns are the tool's own —
+ * this library requires only that every row says WHAT it is about.
+ */
+export interface SemanticFact {
+    readonly entity: string;
+    readonly [field: string]: unknown;
+}
+/** One typed relationship — "this VM rides that datastore", "this zone
+ *  contains that WWPN". `kind` names the relationship in the tool's words. */
+export interface SemanticEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: string;
+    readonly [field: string]: unknown;
+}
+/**
+ * The grain — what one value MEANS, stated when it is not what a reader
+ * would assume. This is the field that stops a model from adding
+ * `jobs_local` to `jobs_replicated_in` and announcing a fleet size nobody
+ * has.
+ */
+export interface SemanticGrain {
+    /** The collection interval the values live on ('30m', '1h', 'daily'). */
+    readonly interval?: string;
+    /** How the values were folded ('avg', 'max', 'sum', 'count', …). */
+    readonly aggregation?: string;
+    /**
+     * Whether the values are counters. MUST be stated (true or false) whenever
+     * `aggregation` is counter-looking (see
+     * {@link COUNTER_AGGREGATION_WORDS}): summing two counters double-counts,
+     * and a reader cannot tell a counter from a gauge by looking at a number.
+     */
+    readonly is_counter?: boolean;
+    /** What was folded away ('per-port rows collapsed to per-switch'). */
+    readonly collapsed?: string;
+}
+/**
+ * Where the values came from and how old they are. `measured_at` is when the
+ * WORLD was measured — not when the tool ran; a tool that reads a nightly
+ * export and answers in 4ms is serving yesterday.
+ */
+export interface SemanticProvenance {
+    /** When the world was measured (the tool's own clock words). Required
+     *  whenever the envelope carries `series` or `facts`. */
+    readonly measured_at: string;
+    /** How stale the data was when the tool answered, in seconds. */
+    readonly age_seconds?: number;
+    /** The system of record the values were read from. Required with
+     *  `measured_at`. */
+    readonly source: string;
+    /** For file-fed collectors: the export the values rode in on. */
+    readonly source_export_date?: string;
+}
+/**
+ * The ask-vs-answer decision, as data. A tool that matched three volumes for
+ * one WWN should not pick one silently — it should hand the question and the
+ * candidates back, typed, so the loop (or a UI) can ask.
+ */
+export interface SemanticClarify {
+    readonly question: string;
+    /** The candidates the question is choosing between. May be empty — an open
+     *  question is still a question. */
+    readonly candidates: readonly unknown[];
+}
+/**
+ * Rendering HINTS — the tool never renders. A UI that understands them draws
+ * a better table; one that does not loses nothing, because everything load-
+ * bearing is in the data fields. Dropped from the model's view entirely.
+ */
+export interface SemanticRender {
+    /** The default presentation ('table', 'chart', 'prose', …). A hint. */
+    readonly default: string;
+    /** Column order for a tabular view. */
+    readonly columns?: readonly string[];
+    /** Sort hint ('avg_iops desc'). */
+    readonly sort?: string;
+    /** A note about what filtering already happened ('replicas excluded'). */
+    readonly filter_note?: string;
+    /** Chart-shape hint ('line per entity'). */
+    readonly chart_hint?: string;
+}
+/**
+ * The envelope's coverage, normalized — the SAME three-list vocabulary the
+ * `coverage()` / `absent()` primitives speak (checked / not checked / cannot
+ * cover), in the snake_case spelling every rendered tool shape uses because
+ * a model reads it more often than code does. Declared through
+ * {@link DescribedResultDeclaration.coverage} with the exact `CoverageDeclaration`
+ * input the `coverage()` primitive takes; the dispatch loop declares it
+ * through the same channel (`tools.coverage_declared`, tracked state, the
+ * final-answer limits block) — absorbed, never duplicated.
+ */
+export interface SemanticCoverage {
+    readonly checked?: readonly CoverageItem[];
+    readonly not_checked?: readonly CoverageItem[];
+    readonly cannot_cover?: readonly CoverageItem[];
+}
+/**
+ * {@link SemanticGrain}, spelled as code: `isCounter` is `is_counter` on the
+ * wire.
+ *
+ * @inline
+ */
+interface DescribedGrain {
+    /** The collection interval the values live on ('30m', '1h', 'daily'). */
+    readonly interval?: string;
+    /** How the values were folded ('avg', 'max', 'sum', 'count', …). */
+    readonly aggregation?: string;
+    /**
+     * Whether the values are counters — cumulative readings a reader must never
+     * add together. MUST be stated (true or false) whenever `aggregation` is
+     * counter-looking (see {@link COUNTER_AGGREGATION_WORDS}).
+     */
+    readonly isCounter?: boolean;
+    /** What was folded away ('per-port rows collapsed to per-switch'). */
+    readonly collapsed?: string;
+}
+/**
+ * {@link SemanticProvenance}, spelled as code: `measuredAt`, `ageSeconds` and
+ * `sourceExportDate` are `measured_at`, `age_seconds` and
+ * `source_export_date` on the wire.
+ *
+ * @inline
+ */
+interface DescribedProvenance {
+    /**
+     * When the WORLD was measured, in the tool's own clock words — never
+     * parsed. Take it from the data: the export's time for a file, the moment
+     * of the read for a live query, the newest sample for a series, and the END
+     * of the window for a value computed over one.
+     */
+    readonly measuredAt: string;
+    /** How stale the data was when the tool answered, in seconds. */
+    readonly ageSeconds?: number;
+    /** The system of record the values were read from. */
+    readonly source: string;
+    /** For file-fed collectors: the export the values rode in on. */
+    readonly sourceExportDate?: string;
+}
+/**
+ * {@link SemanticRender}, spelled as code: `filterNote` and `chartHint` are
+ * `filter_note` and `chart_hint` on the wire.
+ *
+ * @inline
+ */
+interface DescribedRender {
+    /** The default presentation ('table', 'chart', 'prose', …). A hint. */
+    readonly default: string;
+    /** Column order for a tabular view. */
+    readonly columns?: readonly string[];
+    /** Sort hint ('avg_iops desc'). */
+    readonly sort?: string;
+    /** A note about what filtering already happened ('replicas excluded'). */
+    readonly filterNote?: string;
+    /** Chart-shape hint ('line per entity'). */
+    readonly chartHint?: string;
+}
+/**
+ * What a tool author passes to `describedResult()` — the
+ * result fields in ONE spelling, camelCase, respelled to
+ * the unchanged snake_case wire ({@link ToolSemantics}).
+ *
+ * `provenance` is REQUIRED whenever `series` or `facts` is present, and the
+ * compiler says so: a number with no source and no age is refused at run time
+ * anyway, inside the tool, where the model reads the refusal. A declaration
+ * with only `edges` or only a `clarify` question needs none.
+ *
+ * At least one of `series`, `facts`, `edges` or a non-null `clarify` must be
+ * present — an envelope with no data and no question declares nothing. There
+ * is no `notCovered`: the prose list the model reads is derived from
+ * `coverage`, so the two can never disagree.
+ */
+export type DescribedResultDeclaration = {
+    /** Measured points — `{ t, entity, metric, value }`. Needs `grain`. */
+    readonly series?: readonly SemanticSeriesPoint[];
+    /** Typed rows about entities — every row names its `entity`. */
+    readonly facts?: readonly SemanticFact[];
+    /** Typed relationships — `{ from, to, kind }`. */
+    readonly edges?: readonly SemanticEdge[];
+    /** What one value MEANS. Required with `series`. */
+    readonly grain?: DescribedGrain;
+    /** Where the values came from and how old they are. Required with
+     *  `series` or `facts`. */
+    readonly provenance?: DescribedProvenance;
+    /**
+     * What the READ behind the data covered in time (honesty step 7b) — the
+     * instants it asked for (`queried`), what the store holds (`held`, or
+     * `'unknown'` said out loud) and when the read ran (`readAt`). Every value
+     * is an ISO 8601 instant with a zone; the model reads it as declared, and
+     * the results layer files its verdict.
+     */
+    readonly period?: DeclaredPeriod;
+    /** The coverage()-vocabulary declaration this result absorbs. */
+    readonly coverage?: CoverageDeclaration;
+    /** A question the result hands back instead of picking silently. `null`
+     *  states "ambiguity was considered; there is none". It does not pause the
+     *  run — the model reads it and decides what to ask. */
+    readonly clarify?: SemanticClarify | null;
+    /** Hints for a UI. The model never reads them. */
+    readonly render?: DescribedRender;
+} & ({
+    readonly provenance: DescribedProvenance;
+} | {
+    readonly series?: undefined;
+    readonly facts?: undefined;
+});
+/**
+ * The rendered semantic envelope — the exact object a tool hands back.
+ * Field names are snake_case and English on purpose (the `ToolAbsence`
+ * precedent): this value is read by a language model far more often than by
+ * code, and `af_semantics` is the only field that exists for the machine.
+ */
+export interface ToolSemantics {
+    readonly af_semantics: true;
+    readonly series?: readonly SemanticSeriesPoint[];
+    readonly facts?: readonly SemanticFact[];
+    readonly edges?: readonly SemanticEdge[];
+    readonly grain?: SemanticGrain;
+    readonly provenance?: SemanticProvenance;
+    /** What the read behind the data covered in time — honesty step 7b; minted
+     *  only by `describedResult()`. The model reads it as declared. */
+    readonly period?: PeriodOnWire;
+    readonly coverage?: SemanticCoverage;
+    /** DERIVED from `coverage` (not checked + cannot cover), one prose line
+     *  per item — never author-set, so the list and the lists cannot drift. */
+    readonly not_covered?: readonly string[];
+    readonly clarify?: SemanticClarify | null;
+    readonly render?: SemanticRender;
+    /** The static sentence. Never interpolated — see `envelope.ts`. */
+    readonly note: string;
+}
+/**
+ * The declared class of a tool's RESULTS — what kind of answer this tool
+ * gives, stated by whoever wrote it (`defineTool({ resultClass })`; the
+ * `capabilities` law: declared, never inferred). The `check:semantics` gate
+ * keys its per-class rules on it:
+ *
+ *   • `'triage'` — a verdict about health or fault. Every sample result must
+ *     declare coverage: a triage that cannot say what it did NOT check turns
+ *     "everything looks fine" into a claim about ground it never stood on.
+ *   • `'inventory'` — a population listing. Every sample result must declare
+ *     coverage ("4 of 5 clusters"), and one with `facts` but no `render`
+ *     hint is warned at.
+ *
+ * Two classes, deliberately closed: each carries a rule the gate can PROVE.
+ * A class with no rule would be dead vocabulary.
+ */
+export type ToolResultClass = 'triage' | 'inventory';
+/** The closed set, as data — validators and docs read one list. */
+export declare const RESULT_CLASSES: readonly ToolResultClass[];
+/**
+ * Aggregation words that suggest the values are counters — the words that
+ * make `grain.is_counter` REQUIRED (stated true or false). Matched as whole
+ * tokens, singular or plural, case-insensitive.
+ */
+export declare const COUNTER_AGGREGATION_WORDS: readonly string[];
+/**
+ * The static sentence every semantic envelope carries in the model's view.
+ * Never interpolated (the `ABSENCE_NOTE` law): everything else the model
+ * reads is the tool's own data, and a note that quoted any of it back would
+ * hand the evidence corpus a second copy of values it already indexes.
+ */
+export declare const SEMANTICS_NOTE: string;
+export {};

package/dist/esm/semantics/types.js

@@ -0,0 +1,71 @@
+/**
+ * semantics/types — the semantic tool-result vocabulary, as a PURE leaf
+ * (9.53.0, the `toolOutcome.ts` precedent).
+ *
+ * WHY IT LIVES HERE. Two sides read these words and neither may own the
+ * other: the agent loop's dispatch boundary (core/agent/stages/toolCalls.ts)
+ * recognizes the envelope at run time, and the `check:semantics` build gate
+ * (semantics/check.ts) judges the same shapes with no agent anywhere in
+ * sight. Declaring the vocabulary in a leaf both sides import keeps the
+ * dependency pointing the right way — the loop and the gate depend on the
+ * words, never on each other.
+ *
+ * The one exception to "zero imports" is TYPE-ONLY and deliberate: the
+ * envelope's `coverage` field ABSORBS the existing coverage vocabulary
+ * (`CoverageItem` / `CoverageInput`, semantics/coverage/types.ts — itself a
+ * pure-data leaf) instead of duplicating it. Two spellings of "ground this
+ * result does not cover" would eventually disagree; type-only imports erase
+ * at runtime, so this module stays a runtime leaf.
+ *
+ * ## What the envelope is
+ *
+ * A tool that answers "how many IOPS did fc1/3 do last hour?" today returns
+ * prose or an ad-hoc object, and every caveat that makes the number honest —
+ * the collection interval, whether the values are counters that must not be
+ * summed, when the world was actually measured, which clusters were not
+ * collected — is re-implemented by hand inside every tool and held in place
+ * by review. Culture scales to one disciplined author; it does not scale to
+ * a hundred tools. The semantic envelope makes those caveats TYPED DATA that
+ * travel with the values, so honesty is inherited, not re-authored — and so
+ * a build gate can refuse a triage tool that forgot its own limits.
+ *
+ * It is a SIBLING recognizer beside the effects envelope and the coverage
+ * primitives — its own reserved marker (`af_semantics`, the
+ * `af_absent`/`af_coverage` family), never new keys on the effects envelope.
+ * The three compose on one result: `{ content: describedResult({…}), effects:
+ * […], status }` is a tool that returns typed data AND proposes a transition.
+ */
+/**
+ * The reserved key that makes a semantic envelope recognizable. Reserved
+ * vocabulary on the tool-result wire (the `af_absent` / `af_coverage`
+ * precedent): a plain object carrying `af_semantics: true` that validates
+ * cleanly is an envelope; every other value any tool has ever returned keeps
+ * its bytes.
+ */
+export const SEMANTICS_MARKER = 'af_semantics';
+/** The closed set, as data — validators and docs read one list. */
+export const RESULT_CLASSES = ['triage', 'inventory'];
+/**
+ * Aggregation words that suggest the values are counters — the words that
+ * make `grain.is_counter` REQUIRED (stated true or false). Matched as whole
+ * tokens, singular or plural, case-insensitive.
+ */
+export const COUNTER_AGGREGATION_WORDS = [
+    'sum',
+    'count',
+    'total',
+    'cumulative',
+    'counter',
+    'delta',
+];
+/**
+ * The static sentence every semantic envelope carries in the model's view.
+ * Never interpolated (the `ABSENCE_NOTE` law): everything else the model
+ * reads is the tool's own data, and a note that quoted any of it back would
+ * hand the evidence corpus a second copy of values it already indexes.
+ */
+export const SEMANTICS_NOTE = 'Typed data, not prose. `grain` and `provenance` are caveats that travel with the ' +
+    'numbers: check `is_counter` before summing values from a series, read `measured_at` ' +
+    '(and `age_seconds`) as how old the data is, and treat everything under `not_covered` ' +
+    'as ground this result does NOT cover — a clean look here says nothing about it.';
+//# sourceMappingURL=types.js.map

package/dist/esm/semantics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/semantics/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AA4R/C,mEAAmE;AACnE,MAAM,CAAC,MAAM,cAAc,GAA+B,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAElF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsB;IAC1D,KAAK;IACL,OAAO;IACP,OAAO;IACP,YAAY;IACZ,SAAS;IACT,OAAO;CACR,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,mFAAmF;IACnF,sFAAsF;IACtF,uFAAuF;IACvF,iFAAiF,CAAC"}

package/dist/esm/thinking/dispatch.d.ts

@@ -1,5 +1,5 @@
 /** One raw-thinking envelope for a provider choice, shared by both routing paths. */
-import type { LLMProvider, LLMResponse } from '../adapters/types.js';
+import type { LLMProvider, LLMResponse } from '../provider-contract/types.js';
 import type { ThinkingHandler } from './types.js';
 /** Plain data only; handler functions stay in the chart's build-time closure. */
 export declare function tagThinkingResponse(response: LLMResponse, answeredBy: string): LLMResponse;

package/dist/esm/thinking/replay.d.ts

@@ -3,7 +3,7 @@
  * text, tool arguments, signatures or credentials. The concrete wire owns
  * capture and comparison; the run owns persistence and observation.
  */
-import type { LLMRequest } from '../adapters/types.js';
+import type { LLMRequest } from '../provider-contract/types.js';
 /** The order of already-stored content and its supported inert wire metadata. */
 export type ReplayPart = {
     readonly type: 'text';

package/dist/esm/thinking/replayHistory.d.ts

@@ -1,5 +1,5 @@
 /** Pure message matching for durable omissions; no second conversation store. */
-import type { LLMMessage } from '../adapters/types.js';
+import type { LLMMessage } from '../provider-contract/types.js';
 import type { ReplayPreparation } from './replay.js';
 /** Only an approved thinking edit, never a replacement conversation or tool result. */
 export interface ReplayRetirement {

package/dist/esm/thinking/replayHistory.js

@@ -1,5 +1,5 @@
 import { canonicalJson } from '../lib/canonicalJson.js';
-import { sha256Hex } from '../lib/time-travel/sha256.js';
+import { sha256Hex } from '../lib/sha256.js';
 /** Narrow a transport report before a checkpoint owner retains it. */
 export function replayRetirements(preparation) {
     const seen = new Set();

package/dist/esm/thinking/replayHistory.js.map

@@ -1 +1 @@
-{"version":3,"file":"replayHistory.js","sourceRoot":"","sources":["../../../src/thinking/replayHistory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAUzD,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,WAA8B;IAC9D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE;QAChD,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,EAAE,CAAC;QAC/C,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QAChC,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QACxE,IAAI,WAAW,KAAK,SAAS;YAC3B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,OAAO;YACL;gBACE,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC;gBACvE,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB;gBAC/C,cAAc,EAAE,WAAW,CAAC,cAAc;gBAC1C,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC;aACxE;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,wBAAwB,CAAC,OAAmB;IAC1D,OAAO,SAAS,CACd,aAAa,CAAC;QACZ,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CACjC,OAA8B,EAC9B,WAA8B;IAE9B,OAAO,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB,CACpC,OAA8B,EAC9B,WAAwC;IAExC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC7C,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACnC,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CACzC,IAAI,CAAC,QAAQ,KAAK,SAAS;YACzB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,KAAK,IAAI,CAAC,QAAQ;YACtC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,IAAI,wBAAwB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,kBAAkB,CACzF,CAAC;QACF,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,MAAM;YAAE,OAAO,OAAO,CAAC;QAC9E,OAAO,GAAG,IAAI,CAAC;QACf,OAAO;YACL,GAAG,OAAO;YACV,cAAc,EAAE,QAAQ,CAAC,cAAc;YACvC,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;SAClE,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;AAClC,CAAC"}
+{"version":3,"file":"replayHistory.js","sourceRoot":"","sources":["../../../src/thinking/replayHistory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAU7C,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,WAA8B;IAC9D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE;QAChD,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,EAAE,CAAC;QAC/C,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QAChC,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QACxE,IAAI,WAAW,KAAK,SAAS;YAC3B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,OAAO;YACL;gBACE,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC;gBACvE,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB;gBAC/C,cAAc,EAAE,WAAW,CAAC,cAAc;gBAC1C,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC;aACxE;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,wBAAwB,CAAC,OAAmB;IAC1D,OAAO,SAAS,CACd,aAAa,CAAC;QACZ,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CACjC,OAA8B,EAC9B,WAA8B;IAE9B,OAAO,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB,CACpC,OAA8B,EAC9B,WAAwC;IAExC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC7C,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACnC,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CACzC,IAAI,CAAC,QAAQ,KAAK,SAAS;YACzB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,KAAK,IAAI,CAAC,QAAQ;YACtC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,IAAI,wBAAwB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,kBAAkB,CACzF,CAAC;QACF,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,MAAM;YAAE,OAAO,OAAO,CAAC;QAC9E,OAAO,GAAG,IAAI,CAAC;QACf,OAAO;YACL,GAAG,OAAO;YACV,cAAc,EAAE,QAAQ,CAAC,cAAc;YACvC,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;SAClE,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;AAClC,CAAC"}

package/dist/esm/thinking/thinkingHandlerFor.d.ts

@@ -9,7 +9,7 @@
  * Role:    the ONE place `Agent` and `LLMCall` resolve their handler when the
  *          builder did not set one.
  */
-import type { LLMProvider } from '../adapters/types.js';
+import type { LLMProvider } from '../provider-contract/types.js';
 import type { ThinkingHandler } from './types.js';
 /**
  * The thinking handler `provider` declares, or `undefined` when it declares

package/dist/esm/thinking/thinkingModeFor.d.ts

@@ -9,7 +9,7 @@
  * Role:    the ONE place the agent reads that declaration, so a malformed one
  *          is refused at build, by provider name, instead of meaning "no claim".
  */
-import type { LLMProvider } from '../adapters/types.js';
+import type { LLMProvider } from '../provider-contract/types.js';
 import type { ThinkingMode } from './types.js';
 /**
  * The mode `provider` declares for `model`, or `undefined` when it declares

package/dist/esm/time/ask.d.ts

@@ -0,0 +1,126 @@
+/**
+ * time/ask — the one time ask (time design § 6): what a time field's
+ * answer must be, why one is refused, and the choices a reading offers.
+ *
+ * Pattern: one judge per boundary (the `range.ts` precedent). A typed ask's
+ *          `InputField.format` (`tools/inputRequest.ts`) names what the answer
+ *          is; {@link checkTimeAnswer} is the ONE judge of it — at definition
+ *          (a choice, a supplied value) and at the resume door (the person's
+ *          answer). A refusal is a CODE with its facts; the sentence is a
+ *          catalog entry (`src/locales/timeAsk.ts` · `defaultTimeAskMessages`)
+ *          the app may override (`.time({ messages })`), filled here
+ *          ({@link refusalReason}) — the library writes a reason only for a
+ *          check the app armed by declaring the field (TQ7).
+ * Role:    L0 leaf (the time layer). Imports `instant.ts`, `zone.ts`,
+ *          `range.ts`, `present.ts` and the row / candidate TYPES only.
+ * Emits:   N/A.
+ *
+ * ## What an answer must be (§ 6.1, § 6.2)
+ *
+ * | `format` | The answer | Refused as |
+ * |----------|------------|------------|
+ * | `instant` | an ISO 8601 date-time WITH its offset, strict profile (`2026-10-09T08:00-07:00`) | `not-an-instant`; `no-offset` (a date-time with no zone); `dst-gap` |
+ * | `time-range` | an ISO 8601 interval `from/to` of two such instants, `from` before `to` | `not-a-range`; either end's refusal; `out-of-order` |
+ * | `zone` | an IANA zone name (`America/Los_Angeles`) — never an abbreviation or a bare offset | `not-a-zone` |
+ * | `time-range`, for a tool's period | the same, inside the tool's declared facts | `time-future`; `time-past`; `beyond-retention`; `over-max-range` |
+ *
+ * A `time-range` answer given for a tool's period is also judged against the
+ * tool's declared FACTS (§ 6.2, step T5a — `convert.ts` ·
+ * `periodFactProblem`), when the caller hands them with the turn's clock:
+ * `time-future` (a `past` source asked for a window after now), `time-past`
+ * (a `future` source asked for one that ended), `beyond-retention` (the WHOLE
+ * window older than the source keeps — a partial overlap is taken) and
+ * `over-max-range` (wider than the source reads at once).
+ *
+ * `dst-gap` is asked only when the ask knows the person's zone (the run
+ * clock's, under `.time()`): a wall time that zone's clocks skip, written with
+ * one of the two offsets around the change (`2026-03-08T02:30-08:00` in Los
+ * Angeles) names an instant nobody's clock showed. An instant written in some
+ * other offset is that instant, and is taken.
+ *
+ * ## The choices a reading offers (§ 6.1, § 6.3)
+ *
+ * `readingAsk.ts` · `timeAskOf` (split out: it renders labels through
+ * `present.ts`, which only an armed agent loads) turns a `time-reading` row whose choice is `open` into one
+ * field: a `format: 'zone'` field when the person named a zone the layer
+ * cannot read (`PST`), else a `format: 'time-range'` field whose `enum` is
+ * the candidates left (each an ISO interval) and whose `labels` render each in
+ * the reader's locale, the zone named, with the end the person said. A
+ * `kind: 'model'` reader's window is offered as the LIBRARY'S reading to
+ * confirm ("I read “yesterday” as … — is that right?"), never as the person's
+ * words (§ 5.5). So is EVERY `rule` reading (the owner's decision "Always
+ * confirm", time design TQ29 — `rowsBuild.ts` · `timeReadingRows`): the choice is
+ * the reading pre-filled WITH ITS ZONE ("I read “yesterday” as Thu, Oct 8,
+ * 2026, PDT in America/Los_Angeles — is that right?"), so a person who meant
+ * another zone's day corrects it in one answer. Free entry stays open: a
+ * field is `strict` only when the app says so.
+ *
+ * @example
+ * ```ts
+ * checkTimeAnswer('time-range', '2026-10-09T08:40-07:00/2026-10-09T08:00-07:00');
+ * // { problem: 'out-of-order', facts: { from: '2026-10-09T08:40-07:00', to: '2026-10-09T08:00-07:00' } }
+ * checkTimeAnswer('instant', '2026-10-09T08:00'); // { problem: 'no-offset', facts: { value: '2026-10-09T08:00' } }
+ * checkTimeAnswer('instant', '2026-03-08T02:30-08:00', 'America/Los_Angeles'); // { problem: 'dst-gap', … }
+ * checkTimeAnswer('zone', 'PST'); // { problem: 'not-a-zone', facts: { value: 'PST' } }
+ * refusalReason([checkTimeAnswer('zone', 'PST')!], defaultTimeAskMessages);
+ * // '“PST” is not a time zone name. Name one such as America/Los_Angeles.'
+ * ```
+ */
+import { type PeriodFacts } from './periodForm.js';
+import { type InstantText } from './instant.js';
+import { type ZoneName } from './zone.js';
+/** What a time field's answer is (time design § 6.1). The value stays a string on the wire. */
+export type TimeFormat = 'instant' | 'time-range' | 'zone';
+export declare const TIME_FORMATS: readonly TimeFormat[];
+/** Whether `value` names a {@link TimeFormat}. */
+export declare function isTimeFormat(value: unknown): value is TimeFormat;
+/** Why a time answer was refused — a code; the sentence is the catalog's. */
+export type TimeAnswerProblem = 'not-an-instant' | 'no-offset' | 'not-a-range' | 'out-of-order' | 'dst-gap' | 'not-a-zone' | 'time-future' | 'time-past' | 'beyond-retention' | 'over-max-range';
+/** One refused answer: the code and the facts its sentence names (the value as given, capped). */
+export interface TimeAnswerRefusal {
+    readonly problem: TimeAnswerProblem;
+    readonly facts: Readonly<Record<string, string>>;
+}
+export declare const quoted: (value: string) => string;
+/** A tool's declared facts and the turn's clock — what a `time-range` answer for that tool's period is judged against. */
+export interface ToolTimeFacts {
+    readonly facts: PeriodFacts;
+    readonly now: InstantText;
+}
+/**
+ * Why `value` is not a well-formed answer of `format`, or `undefined` when it
+ * is one. `zone` — the person's zone, when the ask knows it (the run clock's)
+ * — arms the DST-gap check; without it the answer is judged for shape, order
+ * and offset only. `tool` — a tool's declared facts and the clock — judges a
+ * well-formed `time-range` against them too.
+ */
+export declare function checkTimeAnswer(format: TimeFormat, value: string, zone?: ZoneName, tool?: ToolTimeFacts): TimeAnswerRefusal | undefined;
+/**
+ * Every sentence the time ask can put before a person — the keys of the
+ * catalog (`src/locales/timeAsk.ts`). `answer.*` is a refusal's reason, one
+ * per {@link TimeAnswerProblem}; `ask.*` a question; `choice.confirm` the
+ * label on a reading to confirm — every reading the armed reader made.
+ * Placeholders are `{{name}}`; the label also takes `zone`.
+ */
+export declare const TIME_ASK_MESSAGE_KEYS: readonly ["answer.not-an-instant", "answer.no-offset", "answer.not-a-range", "answer.out-of-order", "answer.dst-gap", "answer.not-a-zone", "answer.time-future", "answer.time-past", "answer.beyond-retention", "answer.over-max-range", "ask.which", "ask.confirm", "ask.zone", "ask.zone-unknown", "choice.confirm"];
+export type TimeAskMessageKey = (typeof TIME_ASK_MESSAGE_KEYS)[number];
+/** A whole catalog: one sentence per key. */
+export type TimeAskMessages = Readonly<Record<TimeAskMessageKey, string>>;
+/**
+ * The app's overrides (`.time({ messages })`) read — every key one the
+ * catalog has, every value a non-blank sentence of at most 4096 characters —
+ * or a problem in words.
+ */
+export declare function readTimeAskMessages(value: unknown): {
+    readonly value: Partial<TimeAskMessages>;
+} | {
+    readonly problem: string;
+};
+/** A catalog sentence with its `{{name}}` placeholders filled; a placeholder with no fact is left as written. */
+export declare function fillMessage(template: string, facts: Readonly<Record<string, string>>): string;
+/**
+ * The reason a re-ask carries (`InputRefusal.reason`): one catalog sentence
+ * per refused field, in field order, joined by a space — at most 4096
+ * characters, the refusal's own bound.
+ */
+export declare function refusalReason(refusals: readonly TimeAnswerRefusal[], messages: TimeAskMessages): string;