agentfootprint 9.128.1 → 9.131.0

package/dist/types/core/time/checkRecord.d.ts

@@ -0,0 +1,75 @@
+/**
+ * core/time/checkRecord — the record half of the result checks (time design
+ * § 9.2, § 9.6, step T8): the shapes a `period` row carries
+ * (`PeriodDiffers`, `ReadSource`), the checkpoint door's tests for them
+ * (`isPeriodDiffers`, `isShifted`), and the two reads over the turn's
+ * wall-clock sources (`distinctSources`, `clocksDiffer`).
+ *
+ * Pattern: pure shapes and guards; no conversion, no drift, no clock.
+ * Role:    split from `check.ts` BY FILE for the synchronous doors — the
+ *          checkpoint door's row test (`coverage/period.ts` ·
+ *          `periodRowIsWellFormed`) is on every agent's graph, and a bundler
+ *          places a whole file there — so this file imports only
+ *          `instant.ts` and the range and zone types (the optional-family
+ *          law, `test/lib/trace-toolpack/browserGraph.test.ts`). `check.ts`
+ *          re-exports every public name.
+ * Emits:   N/A.
+ *
+ * @example
+ * ```ts
+ * clocksDiffer([
+ *   { toolName: 'orders', zone: 'America/New_York' },
+ *   { toolName: 'tickets', zone: 'Europe/Berlin' },
+ * ]); // { tools: ['orders', 'tickets'], zones: ['America/New_York', 'Europe/Berlin'] }
+ * ```
+ */
+import type { TimeRange } from './range.js';
+import type { ZoneName } from './zone.js';
+/** Where a check's read range came from — see the module table. */
+export type ReadSource = 'declared' | 'sent' | 'shifted' | 'asked';
+/**
+ * `period-differs-from-asked` (§ 9.2): the range compared against, what was
+ * read, and the two lists — each piece half-open, in time order, spelled in
+ * UTC. At least one list is non-empty (an empty check is not filed).
+ */
+export interface PeriodDiffers {
+    /** `asked` — the call's asked range; `person` — the person's window, for a window the model chose. */
+    readonly against: 'asked' | 'person';
+    /** The range compared against. */
+    readonly asked: TimeRange;
+    /** What the call read — one range per declared period, else one. */
+    readonly read: readonly TimeRange[];
+    readonly source: ReadSource;
+    /** The step a declared inclusive end was read back with (§ 3.3) — `source: 'declared'` only. */
+    readonly stepMs?: number;
+    /** Asked but not read. */
+    readonly missing: readonly TimeRange[];
+    /** Read but not asked. */
+    readonly extra: readonly TimeRange[];
+}
+/** A dataset of one call whose declared time axis names a zone — a wall-clock source. */
+export interface SourceClock {
+    readonly toolName: string;
+    readonly zone: ZoneName;
+}
+/** `clocks-differ` (§ 9.6): the wall-clock sources of one answer, when they declare different zones. */
+export interface ClocksDiffer {
+    readonly tools: readonly string[];
+    readonly zones: readonly ZoneName[];
+}
+/**
+ * The wall-clock sources of one answer, one per tool and zone in the order
+ * met — the limits block names each. Fresh plain objects.
+ */
+export declare function distinctSources(sources: readonly SourceClock[]): SourceClock[];
+/**
+ * `clocks-differ` (§ 9.6) — the tools and zones when the wall-clock sources
+ * of one answer declare more than one zone; `undefined` otherwise. A label
+ * only: it changes no standing, and every comparison is made on instants.
+ */
+export declare function clocksDiffer(sources: readonly SourceClock[]): ClocksDiffer | undefined;
+/** The checkpoint door's test for a row's {@link PeriodDiffers}. */
+export declare function isPeriodDiffers(value: unknown): value is PeriodDiffers;
+/** The checkpoint door's test for a row's `shifted`. */
+export declare function isShifted(value: unknown): boolean;
+//# sourceMappingURL=checkRecord.d.ts.map

package/dist/types/core/time/checkRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkRecord.d.ts","sourceRoot":"","sources":["../../../../src/core/time/checkRecord.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAI1C,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,sGAAsG;IACtG,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAED,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,wGAAwG;AACxG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;CACrC;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAU9E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,YAAY,GAAG,SAAS,CAKtF;AAaD,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAiBtE;AAED,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMjD"}

package/dist/types/core/time/clock.d.ts

@@ -0,0 +1,184 @@
+/**
+ * core/time/clock — the run clock: a declared, recorded input, never a hidden read.
+ *
+ * Pattern: normalize-or-refuse at a boundary (`core/runInput.ts`'s shape): the
+ *          app's `.time({ zone })` and the run's `time: { now, zone, window }`
+ *          are read here into one {@link TimeClock}, or refused by name.
+ * Role:    core/ leaf (the time layer's one owner). Imports `instant.ts`,
+ *          `zone.ts`, `range.ts`, `reader.ts` (the reader's check) and
+ *          `resolve.ts` (the policy's) only. The Agent reads the two inputs
+ *          (`Agent.run`, `Agent.resume`); seed stamps the clock once per turn
+ *          (`rows.ts` · `ClockRow`); the ToolCalls resume door compares a
+ *          resume's `time` with the kept clock ({@link clockChange}).
+ * Emits:   N/A.
+ *
+ * ## The laws (time design § 4)
+ *
+ * - **The zone is per run; the builder's is a fallback.** The run's
+ *   `time.zone` wins, `.time({ zone })` is used when the run names none, and
+ *   with neither the run is REFUSED before the turn starts — never the
+ *   server's zone ({@link draftClock} answers `'no-zone'`).
+ * - **`now` is the app's, else the turn's start** — admitted as
+ *   `nowSource: 'default'`, like any default nobody chose.
+ * - **Frozen across a pause.** The clock is written once per turn. A resume
+ *   that passes a different `time` keeps the frozen clock and records what was
+ *   passed ({@link clockChange}); it is not refused, because an app that
+ *   passes the current time on every call is doing nothing wrong.
+ * - **A window set in a UI is a run input** (`time.window`), recorded with
+ *   `source: 'control'` — the person's own typed value, never filed as an
+ *   answer to an ask.
+ *
+ * @example
+ * ```ts
+ * const run = readRunTime({ now: '2026-10-09T15:40:00Z', zone: 'America/Los_Angeles' });
+ * const draft = draftClock(run.value, readTimeOptions({}).value!);
+ * // { now: '2026-10-09T15:40:00Z', zone: 'America/Los_Angeles', zoneSource: 'run' }
+ * completeClock(draft as ClockDraft, Date.parse('2026-10-09T15:40:02Z'));
+ * // { now: '2026-10-09T15:40:00Z', nowSource: 'app', zone: 'America/Los_Angeles', zoneSource: 'run' }
+ * ```
+ */
+import { type InstantText } from './instant.js';
+import { type TimeRange } from './range.js';
+import { type ZoneName } from './zone.js';
+import { type TimeReader } from './reader.js';
+import { type TimePolicy } from './resolveRecord.js';
+import { type TimeAskMessages } from './ask.js';
+/** The run's clock, stamped once per turn (time design § 4). */
+export interface TimeClock {
+    /** The anchor for this turn — the app's `now`, else the turn's start. */
+    readonly now: InstantText;
+    /** The app passed `now`, or the library took the turn's start. */
+    readonly nowSource: 'app' | 'default';
+    /** The person's zone for this run — an IANA name. */
+    readonly zone: ZoneName;
+    /** The run's `time.zone`, else the `.time({ zone })` fallback. */
+    readonly zoneSource: 'run' | 'builder';
+}
+/**
+ * The run's time input — `agent.run({ message, time })`, or the options bag of
+ * `run`, `followUp`, `resume` and `resumeOnError`. Every key is optional; a
+ * run with no zone here needs the builder's fallback.
+ *
+ * @example
+ * ```ts
+ * await agent.run({ message: 'errors since 8?', time: { now: sentAt, zone: 'America/Los_Angeles' } });
+ * ```
+ */
+export interface RunTime {
+    /**
+     * The turn's anchor — the MESSAGE's time, so a replay or a late resume
+     * reads "yesterday" the same way. An ISO 8601 instant with a zone (upper
+     * case `T` and `Z`, no leap second), or a `Date`. Omitted: the turn's start,
+     * recorded `nowSource: 'default'`.
+     */
+    readonly now?: string | Date;
+    /** The person's IANA zone for this run (`'America/Los_Angeles'`). Never an abbreviation. */
+    readonly zone?: string;
+    /**
+     * A window set in a UI — a brushed chart range, a range picker — as a
+     * half-open `{ from, to }` of instants. Recorded with `source: 'control'`.
+     */
+    readonly window?: TimeRange;
+}
+/** The builder's `.time(options)` — the fallback zone, the reader and its policy (time design § 11). */
+export interface TimeOptions {
+    /** The fallback zone for a run that names none. Omitted: every run must name its own. */
+    readonly zone?: string;
+    /**
+     * The strategy that reads the person's words into time parts (`TimeReader`).
+     * No default: without one, the person's words are not read — no
+     * `time-reading` row is filed.
+     */
+    readonly reader?: TimeReader;
+    /**
+     * How the library picks among a reading's candidates (needs `reader`).
+     * `dateOrder` (default `'ask'`): a numeric date's orders become choices,
+     * or the one order your people write (`'MDY'`, `'DMY'`, `'YMD'`), recorded
+     * as assumed. `year` (default `'ask'`): a date said without a year is
+     * asked, or `'current'` — the clock's year, recorded as assumed.
+     */
+    readonly policy?: {
+        readonly dateOrder?: TimePolicy['dateOrder'];
+        readonly year?: TimePolicy['year'];
+    };
+    /**
+     * Your words for the time ask (`defaultTimeAskMessages` keys → sentence):
+     * the reason a refused time answer is re-asked with, the ask's questions,
+     * the label on a reading to confirm. A key you leave out keeps the default.
+     */
+    readonly messages?: Partial<TimeAskMessages>;
+}
+/** {@link RunTime} as read: every value checked and kept as written, a `Date` spelled in UTC. */
+export interface ReadRunTime {
+    readonly now?: InstantText;
+    readonly zone?: ZoneName;
+    readonly window?: TimeRange;
+}
+/** {@link TimeOptions} as read — the policy's defaults filled in when a reader is armed. */
+export interface ReadTimeOptions {
+    readonly zone?: ZoneName;
+    readonly reader?: TimeReader;
+    readonly policy?: TimePolicy;
+    /** The app's catalog overrides — every key one the catalog has. */
+    readonly messages?: Partial<TimeAskMessages>;
+}
+/** What a turn's clock is before seed knows the turn's start. */
+export interface ClockDraft {
+    readonly now?: InstantText;
+    readonly zone: ZoneName;
+    readonly zoneSource: 'run' | 'builder';
+    readonly window?: TimeRange;
+}
+/** A read answer: the value, or a problem named in words. */
+export type Read<T> = {
+    readonly value: T;
+} | {
+    readonly problem: string;
+};
+/**
+ * The run's `time` input, checked. `undefined` reads as "nothing passed".
+ * Refused, by name: a non-object, an unknown key, a zone that is not an IANA
+ * name, a `now` that is not an instant with a zone, a `window` that is not two
+ * strict instants with `from` before `to`.
+ */
+export declare function readRunTime(value: unknown): Read<ReadRunTime | undefined>;
+/**
+ * The builder's `.time(options)`, checked. `undefined` reads as `{}` — the
+ * layer armed with no fallback zone, so every run names its own.
+ */
+export declare function readTimeOptions(value: unknown): Read<ReadTimeOptions>;
+/**
+ * The turn's clock as far as the run's inputs decide it — or `'no-zone'`
+ * when neither the run nor the builder names a zone (the run is then refused;
+ * never the server's zone).
+ */
+export declare function draftClock(run: ReadRunTime | undefined, options: ReadTimeOptions): ClockDraft | 'no-zone';
+/** The clock, once the turn's start is known: `now` is the app's, else that start. */
+export declare function completeClock(draft: ClockDraft, turnStartMs: number): TimeClock;
+/** What a resume passed that differs from the kept clock, and the kept values it would have replaced. */
+export interface ClockChange {
+    readonly passed: ReadRunTime;
+    readonly kept: {
+        readonly now: InstantText;
+        readonly zone: ZoneName;
+        readonly window?: TimeRange;
+    };
+}
+/**
+ * The difference between a resume's `time` and the turn's frozen clock, or
+ * `undefined` when every value passed equals the kept one (a key not passed
+ * is no difference). `now` compares as text: a resume passing the same
+ * instant in another spelling is recorded, because the record keeps spellings.
+ *
+ * @example
+ * ```ts
+ * clockChange({ now: '2026-10-09T16:10:00Z' }, { now: '2026-10-09T15:40:00Z', zone: 'UTC' });
+ * // { passed: { now: '2026-10-09T16:10:00Z' }, kept: { now: '2026-10-09T15:40:00Z', zone: 'UTC' } }
+ * ```
+ */
+export declare function clockChange(passed: ReadRunTime, kept: {
+    readonly now: InstantText;
+    readonly zone: ZoneName;
+    readonly window?: TimeRange;
+}): ClockChange | undefined;
+//# sourceMappingURL=clock.d.ts.map

package/dist/types/core/time/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../../../src/core/time/clock.ts"],"names":[],"mappings":"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"}

package/dist/types/core/time/convert.d.ts

@@ -0,0 +1,179 @@
+/**
+ * core/time/convert — a tool's period FORMS (time design § 7.1) and the EXACT
+ * conversions of one range into them (§ 7.2), with the inverse a binding reads.
+ *
+ * Pattern: one table per direction. A tool declares every SHAPE its period
+ *          takes (`PeriodForm` — two arguments, one joined string, an object,
+ *          a day, a look-back); the library converts a resolved range into the
+ *          first form that holds it EXACTLY ({@link convertExact}) and reads a
+ *          sent value back into a range ({@link readBack}). Both cross the
+ *          argument boundary of § 3.3 through `range.ts` (`boundInto` /
+ *          `boundFrom` for a `to` bound; `lookbackRange` for a look-back) —
+ *          never inline.
+ * Role:    core/ leaf (the time layer). Imports `instant.ts`, `duration.ts`,
+ *          `range.ts`, `zone.ts` and `periodForm.ts` — the declaration half
+ *          (the shapes, the sugar, each form's own rules, a declared value's
+ *          spelling, the tool's facts), split out for the synchronous doors
+ *          (`arguments/declare.ts`, `ask.ts`, `rows.ts`) and re-exported
+ *          here. Asked by `bind.ts` (the fill and the binding) and `drift.ts`,
+ *          which only an armed agent loads.
+ * Emits:   N/A.
+ *
+ * ## The sugar (§ 7.1)
+ *
+ * | Sugar | Means |
+ * |-------|-------|
+ * | `{ argument, spelling: 'lookback' }` | `{ kind: 'lookback', argument, signed: false }` |
+ * | `spelling: 'signed-lookback'` | the same with `signed: true` |
+ * | `spelling: 'iso-range'` | `{ kind: 'joined', argument, as: 'iso', joiner: '..', edge: 'inclusive' }` |
+ * | `'wall-range'` + `zoneArgument` | `{ kind: 'joined', argument, as: 'wall', joiner: '..', edge: 'inclusive', zone: { argument } }` |
+ * | `accepts: [a, b]` | `[sugar(a), sugar(b)]` |
+ *
+ * ## The exact rows (§ 7.2) — what {@link convertExact} sends
+ *
+ * | Asked | Form | Sent | Note |
+ * |-------|------|------|------|
+ * | a look-back | `lookback` | the same length, the sign added or removed, respelled in the form's `units` | none when no unit of `units` spells it |
+ * | a look-back | `bounds` / `joined` / `object` | `[now − L, now)` in that `as` | |
+ * | a range | `bounds` / `joined` / `object`, `as` `iso` · `epoch-ms` · `epoch-s` | the range; a `to` bound per its `edge` | `epoch-s` rounds outward to whole seconds: `rounded` |
+ * | a range | `as: 'wall'` / `'date'` + a zone | the wall times (dates) in the zone | exact only when the tool reads back the same instants (no doubled hour; a date only at midnights) |
+ * | a whole day | `day` | that day | any other range is not exact — see the inexact rows |
+ * | a range ending at now (within `granularity`) | `lookback` | the smallest spelling in `units` that covers `from` | `rounded` when it is longer |
+ *
+ * Every other row of § 7.2 is not exact, and {@link convertExact} answers
+ * `undefined` for it.
+ *
+ * ## The inexact rows (§ 7.2, step T5b) — what {@link convertWidened} sends
+ *
+ * | Asked | Form | Sent | Reads |
+ * |-------|------|------|-------|
+ * | a range inside one calendar day (in the form's zone) | `day` | that day | the whole day — the rest of it is `extra` |
+ * | a range ending before now (past the tool's step) | `lookback` | the covering look-back from now, in the form's units | `[now − L, now]` — the gap after the range (and any rounding before it) is `extra` |
+ *
+ * A form whose read would be wider than the tool's `maxRange` is skipped.
+ * The refusals are tests the binding asks: a range across days when every
+ * form is a `day` ({@link spansDaysForDayOnly}), a sent wall time the zone
+ * skips ({@link wallGapArgument}), and the facts ({@link periodFactProblem};
+ * a range only partly older than `retention` runs —
+ * {@link partlyBeyondRetention}).
+ *
+ * ## Precision and the inclusive edge
+ *
+ * An ISO or wall bound is written to the second when the instant is a whole
+ * second, else to the millisecond; an inclusive `to` is "the last instant
+ * inside at that precision" (`to − 1 s`, or `to − 1 ms`). Read back, a bound's
+ * precision is how it was written: minutes (`to + 1 min`), seconds, or a
+ * fraction (`+ 1 ms`). An epoch bound's precision is its unit; a date's is
+ * the calendar day in the zone.
+ *
+ * @example
+ * ```ts
+ * const forms = sugarForms({ argument: 'window', spelling: 'iso-range' });
+ * convertExact(
+ *   { range: { from: '2026-10-09T08:00:00-07:00', to: '2026-10-09T08:41:00-07:00' } },
+ *   forms,
+ *   { now: '2026-10-09T15:40:00Z', zone: 'America/Los_Angeles', granularityMs: 60_000 },
+ * );
+ * // { form: 0, values: { window: '2026-10-09T08:00:00-07:00..2026-10-09T08:40:59-07:00' } }
+ * ```
+ */
+import { type DurationText } from './duration.js';
+import { type InstantText } from './instant.js';
+import { sameRange, type TimeRange } from './range.js';
+export { sameRange };
+import { type ZoneName } from './zone.js';
+import { type PeriodFacts, type PeriodForm } from './periodForm.js';
+export { BOUND_AS, DEFAULT_GRANULARITY_MS, FACT_UNITS, FORM_KINDS, formArguments, formIssue, isBoundValue, needsZone, parsesUnderForm, PERIOD_SPELLINGS, periodFactProblem, primaryArgument, sugarForm, sugarForms, TIME_REFUSALS, } from './periodForm.js';
+export type { Bound, BoundAs, FormArgument, PeriodDirection, PeriodFactProblem, PeriodFacts, PeriodForm, PeriodShapes, PeriodSpelling, TimeRefusal, ToBound, ZoneArgument, } from './periodForm.js';
+/** What a conversion knows beyond the window: the turn's clock, the zones, the tool's step. */
+export interface ConvertContext {
+    /** The turn's clock (§ 4) — a look-back ends here. */
+    readonly now: InstantText;
+    /** The zone a wall or date form is written in and its zone argument is sent: the window's. */
+    readonly zone: ZoneName;
+    /** The app's `.time({ zone })` — the zone of a form that declares `wallZone: 'app'` and no zone argument. */
+    readonly appZone?: ZoneName;
+    /** The tool's `granularity` in milliseconds, else {@link DEFAULT_GRANULARITY_MS}. */
+    readonly granularityMs: number;
+}
+/** The window to convert: its half-open range and, when it was said as one, its look-back. */
+export interface WindowToConvert {
+    readonly range: TimeRange;
+    /** The look-back length the window was said as (`smhdw`), ending at the clock's `now`. */
+    readonly lookback?: DurationText;
+}
+/** One exact conversion: the form used (its index), the argument values, and whether it rounded outward. */
+export interface Conversion {
+    readonly form: number;
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly rounded?: true;
+}
+/**
+ * The first form (in declared order) that holds `window` EXACTLY — the exact
+ * rows of § 7.2 — as the argument values to send, or `undefined` when no form
+ * does. A form that would widen, shift or drop part of the window is never
+ * chosen here.
+ */
+export declare function convertExact(window: WindowToConvert, forms: readonly PeriodForm[], ctx: ConvertContext): Conversion | undefined;
+/**
+ * One conversion that holds MORE than the window: the form, the values, the
+ * range the tool reads with them (`sent`, half-open) and the parts of it the
+ * window did not ask for (`extra` — one or two ranges, in time order).
+ */
+export interface WidenedConversion extends Conversion {
+    readonly sent: TimeRange;
+    readonly extra: readonly TimeRange[];
+}
+/**
+ * The first form (in declared order) that holds `window` by READING MORE than
+ * it — the inexact rows of § 7.2: a range inside one calendar day → that day
+ * (`day`); a range ending before now → the covering look-back from now
+ * (`lookback`). `widestMs` (the tool's `maxRange`) skips a form whose read
+ * would be wider than the tool reads at once. Asked only after
+ * {@link convertExact} found no exact form.
+ */
+export declare function convertWidened(window: WindowToConvert, forms: readonly PeriodForm[], ctx: ConvertContext, widestMs?: number): WidenedConversion | undefined;
+/**
+ * Whether every form is a `day` and the window spans more than one calendar
+ * day in the form's zone — the row § 7.2 refuses before dispatch: one call per
+ * day is the model's choice, not the library's.
+ */
+export declare function spansDaysForDayOnly(window: WindowToConvert, forms: readonly PeriodForm[], ctx: ConvertContext): boolean;
+/**
+ * The first argument of `form` whose sent value is a wall time the zone
+ * SKIPS (a spring-forward gap) — the tool would read a time that never
+ * happened; refused before dispatch (§ 7.2). `undefined` when the form reads
+ * no wall bound, the zone is unknown, or every wall value exists.
+ */
+export declare function wallGapArgument(args: Readonly<Record<string, unknown>>, form: PeriodForm, ctx: {
+    readonly appZone?: ZoneName;
+}): string | undefined;
+/**
+ * The half-open range the arguments of `form` name — the § 3.3 conversion back
+ * from each bound — or `undefined` when they do not name one (missing,
+ * misspelled, a wall time the zone doubles or skips, `from` not before `to`).
+ * A look-back is read at the turn's clock (`lookbackRange`). The range is
+ * spelled in UTC: compare it as instants ({@link sameRange}).
+ */
+export declare function readBack(args: Readonly<Record<string, unknown>>, form: PeriodForm, ctx: {
+    readonly now: InstantText;
+    readonly appZone?: ZoneName;
+}): TimeRange | undefined;
+/**
+ * The absolute range a look-back window was sent as to a bounds form —
+ * `[now − L, now)`, which reads back one millisecond shorter than the
+ * look-back's own `[now − L, now]` — so a binding recognises either.
+ */
+export declare function lookbackAsBounds(now: InstantText, lookback: DurationText): TimeRange | undefined;
+/** The tool's step in milliseconds — its `granularity`, else one minute (§ 7.4). */
+export declare function granularityMsOf(facts: PeriodFacts | undefined): number;
+/**
+ * Whether a half-open range is PARTLY older than what the source keeps — it
+ * starts before `now − retention` and ends after it. It dispatches as asked
+ * (§ 7.2); the result's `held` decides `partly-held`. `false` when the tool
+ * declares no `retention`.
+ */
+export declare function partlyBeyondRetention(range: TimeRange, facts: PeriodFacts, now: InstantText): boolean;
+/** The widest window the tool reads at once (`maxRange`) in milliseconds, when it declares one. */
+export declare function widestMsOf(facts: PeriodFacts | undefined): number | undefined;
+//# sourceMappingURL=convert.d.ts.map

package/dist/types/core/time/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../../src/core/time/convert.ts"],"names":[],"mappings":"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"}

package/dist/types/core/time/drift.d.ts

@@ -0,0 +1,86 @@
+/**
+ * core/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:    core/ 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;
+//# sourceMappingURL=drift.d.ts.map

package/dist/types/core/time/drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.d.ts","sourceRoot":"","sources":["../../../../src/core/time/drift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,6FAA6F;AAC7F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;IACnC,iEAAiE;IACjE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;CAC7B;AAED,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,MAAM,CAAC,EAC9C,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,OAAO,CAQT;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,GAAG,SAAS,EACpC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,KAAK,EAAE,aAAa,GACnB,aAAa,GAAG,SAAS,CA8B3B"}

package/dist/types/core/time/duration.d.ts

@@ -0,0 +1,72 @@
+/**
+ * core/time/duration — the ONE duration grammar, with a unit set per use.
+ *
+ * Pattern: one grammar, units narrowed per use (never a second regex). A
+ *          duration is a MACHINE spelling an author declared — a tool's
+ *          `-40m` argument, a `retention: '30d'`, a dataset's `interval:
+ *          '5m'` — never a person's words ("the last 40 minutes" is read only
+ *          by an armed reader). This is the T-spellings law of the time
+ *          design (`docs/design/time/README.md`, § 5.4).
+ * Role:    core/ leaf (the time layer's one owner). Imports nothing. Asked by
+ *          `arguments/declare.ts` · `parsesUnderSpelling` for a look-back.
+ * Emits:   N/A.
+ *
+ * ## The grammar
+ *
+ * `^[1-9][0-9]*[smhdw]$` — a positive integer with no leading zero, then one
+ * unit. NO digit cap: `1000000m` is a look-back today and stays one. The UNIT
+ * SET is named by every caller, because widening it is a behaviour change:
+ *
+ * | Use | Units | Why |
+ * |-----|-------|-----|
+ * | a look-back argument ({@link LOOKBACK_UNITS}) | `mhdw` | today's spelling; a backend that never took seconds is never sent `30s` unless its tool declares `units: 'smhdw'` |
+ * | a dataset's interval ({@link AXIS_UNITS}) | `smhdw` | a series can be bucketed by the second |
+ *
+ * `d` is 24 hours and `w` is 7 days: a machine duration, not a calendar day
+ * (a calendar day in a zone with DST is `zone.ts`'s question).
+ *
+ * @example
+ * ```ts
+ * isDuration('30m', LOOKBACK_UNITS);        // true
+ * isDuration('30s', LOOKBACK_UNITS);        // false — seconds are opt-in
+ * isDuration('30s', AXIS_UNITS);            // true
+ * durationMs('2h', LOOKBACK_UNITS);         // 7200000
+ * spellDuration(7_200_000, LOOKBACK_UNITS); // '2h' — the smallest exact spelling
+ * ```
+ */
+/** The one duration grammar's text: `^[1-9][0-9]*[smhdw]$`, units narrowed per use. */
+export type DurationText = string;
+/** One unit: second, minute, hour, day (24 h), week (7 d). */
+export type DurationUnit = 's' | 'm' | 'h' | 'd' | 'w';
+/** Every unit, smallest first. */
+export declare const DURATION_UNITS: readonly DurationUnit[];
+/** A look-back's units — today's `mhdw`; `s` only by the tool's own opt-in. */
+export declare const LOOKBACK_UNITS = "mhdw";
+/** A dataset interval's units. */
+export declare const AXIS_UNITS = "smhdw";
+/**
+ * Whether `units` is a unit set: a non-empty string of distinct letters from
+ * `smhdw`, in any order.
+ */
+export declare function isUnitSet(units: unknown): units is string;
+/** The count (as written, digits) and unit of a duration, or `undefined` when it is not one under `units`. */
+export declare function durationParts(value: unknown, units: string): {
+    readonly digits: string;
+    readonly unit: DurationUnit;
+} | undefined;
+/** Whether `value` is a duration under `units`. A format check: any number of digits. */
+export declare function isDuration(value: unknown, units: string): value is DurationText;
+/**
+ * The milliseconds a duration names, or `undefined` when it is not a duration
+ * under `units` — or names more milliseconds than a double holds exactly (the
+ * spelling is still a duration; it just cannot be measured).
+ */
+export declare function durationMs(value: unknown, units: string): number | undefined;
+/**
+ * The smallest exact spelling of `ms` in `units` — the largest unit that
+ * divides it — or `undefined` when no unit in the set divides it (or `ms` is
+ * not a positive whole number of milliseconds). `durationMs(spellDuration(x))`
+ * is `x` whenever it is defined.
+ */
+export declare function spellDuration(ms: number, units: string): DurationText | undefined;
+//# sourceMappingURL=duration.d.ts.map

package/dist/types/core/time/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../../../src/core/time/duration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,uFAAuF;AACvF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEvD,kCAAkC;AAClC,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAA6C,CAAC;AAEhG,+EAA+E;AAC/E,eAAO,MAAM,cAAc,SAAS,CAAC;AAErC,kCAAkC;AAClC,eAAO,MAAM,UAAU,UAAU,CAAC;AAYlC;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAUzD;AAUD,8GAA8G;AAC9G,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAAG,SAAS,CAMtE;AAED,yFAAyF;AACzF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK5E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CASjF"}