agentfootprint 10.2.0 → 10.3.1

package/dist/types/time/range.d.ts

@@ -0,0 +1,146 @@
+/**
+ * time/range — the library's one range, its two spellings, and one
+ * conversion per boundary a range crosses.
+ *
+ * Pattern: one internal shape, converted at every edge by a named function —
+ *          never inline. Inside the library a range is HALF-OPEN `[from, to)`;
+ *          the places a range crosses do not share that edge (the time design,
+ *          `docs/design/time/README.md` § 3.3), so each crossing is a function
+ *          here and its inverse.
+ * Role:    L0 leaf (the time layer's one owner). Imports `instant.ts` and
+ *          `duration.ts`. Asked by `tools/declare.ts` ·
+ *          `parsesUnderSpelling` (an `iso-range` argument is
+ *          {@link splitRange} under `'..'` and the strict profile). No other
+ *          file splits or joins a range.
+ * Emits:   N/A.
+ *
+ * ## The boundaries
+ *
+ * | Boundary | Its edge | Into it from `[from, to)` | Back |
+ * |----------|----------|---------------------------|------|
+ * | a result's `DeclaredPeriod.queried` / `held` | inclusive at both ends | not converted — the tool declares it | {@link fromInclusive} with the tool's step (`granularity`, else 1 ms) |
+ * | a tool argument bound | declared on every `bounds`/`object` end (TQ18); only the sugar defaults inclusive | {@link boundInto} | {@link boundFrom} |
+ * | a look-back argument | `[until − L, until]` | {@link lookbackRange} | {@link lookbackOf} |
+ * | an ask answer / an ISO 8601 interval | `from/to`, half-open | identity: {@link spellRange} | identity: {@link parseRange} |
+ * | an inclusive interval clause (SQL `BETWEEN`, a chart brush) | inclusive at both ends | {@link toInclusive} | {@link fromInclusive} |
+ *
+ * `coverage/period.ts` · `periodVerdict` stays inclusive and is NOT routed
+ * through here: it compares the two inclusive spans a result declared.
+ *
+ * A derived bound keeps the offset its source was written in, spelled in the
+ * strict profile; a bound that is not derived is kept as written.
+ *
+ * @example
+ * ```ts
+ * parseRange('2026-10-09T08:00:00-07:00/2026-10-09T08:41:00-07:00');
+ * // { from: '2026-10-09T08:00:00-07:00', to: '2026-10-09T08:41:00-07:00' }
+ * toInclusive({ from: '2026-10-09T08:00:00-07:00', to: '2026-10-09T08:41:00-07:00' }, 60_000);
+ * // { from: '2026-10-09T08:00:00-07:00', to: '2026-10-09T08:40:00-07:00' } — "through 08:40"
+ * ```
+ */
+import { type DurationText } from './duration.js';
+import { type InstantProfile, type InstantText, type ParsedInstant } from './instant.js';
+/**
+ * The library's INTERNAL range: half-open `[from, to)`, `from` before `to`.
+ * NOT the same reading as `DeclaredPeriod.queried`, whose bounds are
+ * inclusive — every boundary converts (the module table).
+ */
+export interface TimeRange {
+    readonly from: InstantText;
+    readonly to: InstantText;
+}
+/** Two instants with inclusive ends, `from` not after `to` — a declared period's span, an SQL `BETWEEN`. */
+export interface InclusiveSpan {
+    readonly from: InstantText;
+    readonly to: InstantText;
+}
+/** How two bounds are joined in one string: an ISO 8601 interval (`/`) or a tool's joined argument (`..`). */
+export type RangeJoiner = '/' | '..';
+/** Whether a tool's bound includes the instant it names. */
+export type Edge = 'inclusive' | 'exclusive';
+/**
+ * The two bounds of a joined range string — exactly one `joiner`, each half an
+ * instant under `profile` — or `undefined`. The ORDER is not checked: a format
+ * check, for a declaration that only promises a spelling.
+ */
+export declare function splitRange(value: unknown, joiner: RangeJoiner, profile: InstantProfile): readonly [ParsedInstant, ParsedInstant] | undefined;
+/**
+ * A joined string read as a {@link TimeRange} — strict instants, `from`
+ * before `to` — or `undefined`. The bounds are kept as written.
+ */
+export declare function parseRange(value: unknown, joiner?: RangeJoiner): TimeRange | undefined;
+/** Whether `value` is a well-formed {@link TimeRange}: strict instants, `from` before `to`, no other key. */
+export declare function isTimeRange(value: unknown): value is TimeRange;
+/** The range spelled as one string: `from<joiner>to`, bounds as written. Throws on a range that is not well formed. */
+export declare function spellRange(range: TimeRange, joiner?: RangeJoiner): string;
+/** The step a tool's `granularity` names (under `units`), else 1 ms — the § 3.3 rule. */
+export declare function stepMsOf(granularity: DurationText | undefined, units: string): number;
+/**
+ * An inclusive span read back as half-open: `[from, to + step)`. The step is
+ * the source's smallest step (a tool's `granularity`, else 1 ms). The span is
+ * read in the LENIENT profile — a result declares it.
+ */
+export declare function fromInclusive(span: InclusiveSpan, stepMs?: number): TimeRange;
+/**
+ * A half-open range written with inclusive ends: `[from, to − step]` — the
+ * last instant inside the range at the reader's precision. Refused when the
+ * range is narrower than one step (it holds no instant at that precision).
+ */
+export declare function toInclusive(range: TimeRange, stepMs?: number): InclusiveSpan;
+/**
+ * A half-open range's end as a tool's `to` bound: `exclusive` → as is;
+ * `inclusive` → the last instant inside at the argument's precision
+ * (`to − step`).
+ */
+export declare function boundInto(to: InstantText, edge: Edge, stepMs: number): InstantText;
+/** The inverse of {@link boundInto}: a tool's `to` bound as a half-open range's end. */
+export declare function boundFrom(to: InstantText, edge: Edge, stepMs: number): InstantText;
+/**
+ * A look-back `duration` evaluated at `until` — `[until − L, until]`, both
+ * ends inside — as a half-open range `[until − L, until + 1 ms)`.
+ */
+export declare function lookbackRange(until: InstantText, duration: DurationText, units: string): TimeRange;
+/**
+ * The inverse of {@link lookbackRange}: the `until` and the smallest exact
+ * look-back spelling a half-open range is, or `undefined` when its length is
+ * no whole duration in `units`.
+ */
+export declare function lookbackOf(range: TimeRange, units: string): {
+    readonly until: InstantText;
+    readonly duration: DurationText;
+} | undefined;
+/**
+ * How far a half-open range `[from, to)` REACHES, in milliseconds: from its
+ * first instant to its last (`to − 1 ms − from`) — the length a tool's
+ * `maxRange` is held against (an inclusive ceiling: a range is over it only
+ * when its last instant lies further than `maxRange` after its first). The one
+ * owner of that length, so a range is judged by the instants it holds, never by
+ * how it was spelled: the look-back row `[until − L, until]` ({@link lookbackRange},
+ * half-open `[until − L, until + 1 ms)`) reaches `L`, exactly as the same instants
+ * written as bounds do — a look-back exactly `maxRange` long is one the tool reads
+ * at once, and one more step (`L + 1 min`) is not.
+ *
+ * @example
+ * ```ts
+ * reachMs(Date.parse('2026-10-08T15:40:00Z'), Date.parse('2026-10-09T15:40:00.001Z')); // 86_400_000 — 'last 24h'
+ * reachMs(Date.parse('2026-10-08T00:00:00Z'), Date.parse('2026-10-09T00:00:00Z'));     // 86_399_999 — one day
+ * ```
+ */
+export declare function reachMs(fromMs: number, toMs: number): number;
+/** Whether `outer` holds every instant of `inner` (half-open). */
+export declare function covers(outer: TimeRange, inner: TimeRange): boolean;
+/** Whether two ranges hold the same instants (their spellings and offsets aside). */
+export declare function sameRange(a: TimeRange, b: TimeRange): boolean;
+/** Whether `a` and `b` share at least one instant (half-open: touching ends do not overlap). */
+export declare function overlaps(a: TimeRange, b: TimeRange): boolean;
+/**
+ * The range widened to whole steps — `from` down, `to` up, never inward —
+ * with `rounded` saying whether anything moved. Steps are counted from the
+ * epoch in UTC: right for seconds, minutes and hours; a calendar day or week
+ * in a zone is `zone.ts`'s question, not this one.
+ */
+export declare function roundOutward(range: TimeRange, stepMs: number): {
+    readonly range: TimeRange;
+    readonly rounded: boolean;
+};
+//# sourceMappingURL=range.d.ts.map

package/dist/types/time/range.d.ts.map

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

package/dist/types/time/reader.d.ts

@@ -0,0 +1,170 @@
+/**
+ * time/reader — the port a strategy reads a person's words through, and
+ * the checks every reading passes before anything resolves it.
+ *
+ * Pattern: port + adapter (Duckling's value/resolution split). A strategy
+ *          TOKENIZES: it returns the parts it sees and the verbatim quote,
+ *          never an instant, never a date order, never a zone. Everything
+ *          that turns parts into instants is `resolve.ts`'s, the same way for
+ *          every strategy (time design § 5.1).
+ * Role:    L0 leaf (the time layer). Imports nothing. The builder's
+ *          `.time({ reader })` checks a reader through {@link readerIssue};
+ *          seed checks what it returned through {@link checkReading}.
+ * Emits:   N/A.
+ *
+ * ## What is checked — shape, never meaning
+ *
+ * | Check | A failure |
+ * |-------|-----------|
+ * | the reader: `id`, `version`, `locale` non-empty strings, `kind` `'rule'` or `'model'`, `read` a function | refused at build |
+ * | the reading: `{ mentions: [] }`, at most {@link MAX_MENTIONS} | the reader broke its port — the run fails, naming it |
+ * | each mention's `quote`: a non-empty VERBATIM substring of the text read | the mention is refused (`quote-not-in-text`) and keeps no text |
+ * | each mention's parts: the {@link TimeParts} shape, every field in range, no unknown key, at most {@link MAX_PARSES} | the mention is refused (`malformed`) |
+ *
+ * None of these checks what a word MEANS: a model that reads "yesterday" as
+ * the wrong day passes every one of them. That is why NO reading is ever the
+ * person's words — a `rule` reading as much as a `model` one (the owner's
+ * decision "Always confirm", time design TQ29): a reading only PROPOSES a
+ * window, offered through the time ask with its zone, and only what the
+ * person picks or types in that form is theirs (`rowsBuild.ts` ·
+ * `timeReadingRows`).
+ *
+ * @example
+ * ```ts
+ * const fixture: TimeReader = {
+ *   id: 'fixture', version: '1.0.0', locale: 'en-US', kind: 'rule',
+ *   read: () => ({ mentions: [{ quote: '10/09/26', parses: [{ date: { kind: 'numeric', fields: [10, 9, 26] } }] }] }),
+ * };
+ * readerIssue(fixture); // undefined — a well-formed reader
+ * checkReading('errors on 10/09/26', fixture.read('', { locale: 'en-US' }), 'fixture');
+ * // [{ quote: '10/09/26', parses: [{ date: { kind: 'numeric', fields: [10, 9, 26] } }] }]
+ * ```
+ */
+/** What a reader is told besides the text: a hint for its tokenizer — no clock, no zone, no map. */
+export interface TimeReadContext {
+    readonly locale: string;
+}
+/**
+ * A strategy that reads a person's words into zone-less PARTS (time design
+ * § 5.1). Armed with `.time({ reader })`; there is no default. It runs once
+ * per turn, at the seed, on the message a person wrote, and never again for
+ * that message — a resume and a retry read the recorded reading.
+ *
+ * @example
+ * ```ts
+ * const reader: TimeReader = {
+ *   id: 'my-app/english', version: '1.2.0', locale: 'en-US', kind: 'rule',
+ *   read: (text) => ({ mentions: tokenize(text) }),
+ * };
+ * Agent.create({ provider, model }).time({ zone: 'UTC', reader }).build();
+ * ```
+ */
+export interface TimeReader {
+    /** Recorded on every reading with the version, e.g. `'agentfootprint/english'`. */
+    readonly id: string;
+    readonly version: string;
+    /** The language it reads, e.g. `'en-US'`. */
+    readonly locale: string;
+    /**
+     * `'rule'`: deterministic over the text. `'model'`: an LLM or other learned
+     * reader. Neither kind's reading is ever the person's words: a `rule`
+     * reading is offered through the time ask to confirm; a `model` reading
+     * fills as a reading (`derived-from-reading`) until the person confirms it.
+     */
+    readonly kind: 'rule' | 'model';
+    read(text: string, context: TimeReadContext): TimeReading | Promise<TimeReading>;
+}
+/** What a reader returns: every time mention it found, in the order the text wrote them. */
+export interface TimeReading {
+    readonly mentions: readonly TimeMention[];
+}
+/** One mention of a time in the text. */
+export interface TimeMention {
+    /** A VERBATIM substring of the text — the library checks it. */
+    readonly quote: string;
+    /** Usually one; more only when the TOKENS split two ways. Empty when `problem` is set. */
+    readonly parses: readonly TimeParts[];
+    /** The reader saw a time here and could not read it. */
+    readonly problem?: 'unreadable';
+}
+/** A date as the text wrote it. */
+export type TimeDate = 
+/** `'10/09/26'` → `fields: [10, 9, 26]` — the ORDER is not decided by the reader. Two or three fields. */
+{
+    readonly kind: 'numeric';
+    readonly fields: readonly number[];
+    readonly yearDigits?: 2 | 4;
+}
+/** ISO or a named month: the text fixes the order. */
+ | {
+    readonly kind: 'fixed';
+    readonly year?: number;
+    readonly month: number;
+    readonly day: number;
+};
+/** A wall-clock time as the text wrote it — no zone. */
+export interface TimeWall {
+    readonly h: number;
+    readonly m?: number;
+    readonly s?: number;
+    readonly meridiem?: 'am' | 'pm';
+    /**
+     * `'24h'`: the text's FORM is a 24-hour clock (an ISO instant's
+     * `T08:00`), so the hour is read as written — never also as pm. A form
+     * fact the reader sees and `resolve.ts` cannot; absent, an hour 1–12 with
+     * no meridiem is read both ways. Never with `meridiem`.
+     */
+    readonly clock?: '24h';
+}
+/** A time said relative to the message's moment. */
+export type TimeRelative = 
+/** `'yesterday'` = `{ unit: 'day', offset: -1 }`. */
+{
+    readonly unit: 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
+    readonly offset: number;
+}
+/** `'last 40 minutes'` = `{ unit: 'minute', count: 40 }` — a look-back. */
+ | {
+    readonly unit: 'second' | 'minute' | 'hour' | 'day' | 'week';
+    readonly count: number;
+};
+/** Zone-less parts, in the order the text wrote them. Every field present was said. */
+export interface TimeParts {
+    readonly date?: TimeDate;
+    readonly wall?: TimeWall;
+    /** As written: `'PST'`, `'-07:00'`, `'America/Los_Angeles'` — `resolve.ts` maps it. */
+    readonly zoneToken?: string;
+    readonly relative?: TimeRelative;
+    /** `'morning'` — a KEY into a table, never hours. */
+    readonly partOfDay?: string;
+    /** `'the hour before that'` — resolved from the recorded previous window only. */
+    readonly anchor?: 'previous';
+    /** `'8 AM to 8:40 AM'`. */
+    readonly rangeOf?: readonly [TimeParts, TimeParts];
+}
+/** The most mentions one reading may hold — a bound on the record, not a guess at language. */
+export declare const MAX_MENTIONS = 16;
+/** The most parses one mention may hold. */
+export declare const MAX_PARSES = 4;
+/** Why `value` is not a {@link TimeReader}, or `undefined` when it is one. */
+export declare function readerIssue(value: unknown): string | undefined;
+/** Why one mention was refused. A refused mention keeps no text: its quote is not the person's words. */
+export type MentionRefusal = 'quote-not-in-text' | 'malformed';
+/** One mention after the checks. */
+export type CheckedMention = {
+    readonly quote: string;
+    readonly parses: readonly TimeParts[];
+    readonly problem?: 'unreadable';
+} | {
+    readonly refused: MentionRefusal;
+};
+/** Whether `value` is a well-formed {@link TimeParts} — `nested` refuses a range inside a range side. */
+export declare function isTimeParts(value: unknown, nested?: boolean): value is TimeParts;
+/**
+ * A reader's answer for `text`, checked: one {@link CheckedMention} per
+ * mention, in order. Throws a `TypeError` naming the reader when the answer
+ * is not `{ mentions: [] }` (at most {@link MAX_MENTIONS}) — the reader
+ * broke its port, and a run is never read by a guess at what it meant.
+ */
+export declare function checkReading(text: string, value: unknown, readerId: string): CheckedMention[];
+//# sourceMappingURL=reader.d.ts.map

package/dist/types/time/reader.d.ts.map

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

package/dist/types/time/readers/english.d.ts

@@ -0,0 +1,147 @@
+/**
+ * time/readers/english — the library's careful English reader (time
+ * design § 5.3): a tokenizer over a small, closed set of phrases, and
+ * "unreadable" for every other time phrase it recognises.
+ *
+ * Pattern: Strategy behind the `TimeReader` port (`../reader.ts`). It
+ *          TOKENIZES only: it returns the parts it sees and the verbatim
+ *          quote. It never resolves an instant, never applies a date order,
+ *          never maps a zone token (an abbreviation, a place) to a zone and
+ *          never refuses a future date —
+ *          all of that is `resolve.ts`'s, the policy's or the ask's.
+ * Role:    L0 leaf (the time layer). Imports only the port's types. Armed
+ *          by the app: `.time({ reader: englishTimeReader() })` — there is no
+ *          default reader.
+ * Emits:   N/A.
+ *
+ * ## What it reads (the v1 rows of § 5.3)
+ *
+ * | Phrase | Example | Parts |
+ * |--------|---------|-------|
+ * | an ISO date or instant | `2026-10-09`, `2026-10-09T08:00-07:00` | `date: fixed`, `wall` (marked `clock: '24h'` — never also pm), `zoneToken` |
+ * | a numeric date | `10/09/26`, `10/9` | `date: numeric` — the ORDER is not decided here |
+ * | a clock time | `8 AM`, `8:40`, `20:40`, `8:40 p.m.` | `wall` (a bare `8` is a time only as a range's first side: `8 to 9 AM`) |
+ * | a range between two of the above | `8 AM to 8:40 AM`, `08:00–08:40`, `between 8 and 9 AM`, `today between 1 pm and 2 pm` | `rangeOf` (a day or zone said once for both sides is the whole mention's) |
+ * | a zone after a time, a date or a day word | `America/Los_Angeles`, `UTC-07:00`, `London time`, `PST` | `zoneToken`, as written — `resolve.ts` maps it (a place the tz database names once; an abbreviation only through the app's map; else ASKED) |
+ * | a named-month date | `11 September`, `Sept 29`, `September 29, 2026`, `the 29th of Sep` | `date: fixed` — no `year` unless written (the policy's or the person's, as for `10/9`) |
+ * | a day word | today, yesterday, tomorrow | `relative: { unit: 'day', offset }` |
+ * | a relative span from now | last 40 minutes, past 2 hours, last 24h, past 6h, the last hour, the past week | `relative: { unit, count }` — a look-back in minutes, hours, days or weeks, spelled out or compact (`m`, `h`, `d`, `w`) |
+ *
+ * ## What it says "unreadable" for — never a partial reading
+ *
+ * Parts of the day (`yesterday morning`, `tonight`, `noon` — a greeting, `Good morning`, is
+ * no time and reads no mention), calendar spans
+ * (`last week`, `this month`), week days and a month named alone (`Friday`,
+ * `in September`), `N hours ago`, spans in words (`last two hours`), in a unit it
+ * does not read (`last 30 seconds`, `last 30s`, `last 3 months`) or said with `previous`
+ * (`previous 7 days` — often relative to another window), a look-ahead (`next 2 hours`), an
+ * ordinal day (`the 9th`), `8 o'clock`, and any v1 phrase a modifier changes
+ * (`since 8 AM`, `before yesterday`, `around 8:40`, `earlier today`,
+ * `8 AM to now`, `past 8 PM`, `8 AM-ish`, `from 3 PM yesterday` with no `to`), a
+ * bare first side whose far side says no meridiem (`8 to 9:30` — `9:30` alone
+ * would drop the start) and a meridiem the number contradicts (`13:00 PM`). Such a phrase is ONE mention
+ * with `problem: 'unreadable'`, quoting the whole phrase: reading `yesterday`
+ * out of `yesterday morning` would silently widen what the person said.
+ *
+ * ## It only PROPOSES — the person confirms (the owner's decision "Always confirm")
+ *
+ * Nothing this reader reads is ever filed as the person's words. Seven review
+ * rounds each found the next English spelling a word list, an allow-list or a
+ * position rule missed (a zone named in words, a look-back tied to an event,
+ * an open end, a half-read range), so the owner decided (2026-09-30, time
+ * design TQ29): every reading of a chat message is a PROPOSAL, offered
+ * through the time ask pre-filled and editable, with its window AND its zone
+ * ("I read “last 2 hours” as … in America/Los_Angeles — is that right?").
+ * Only what the person picks or types in that form is theirs. The library
+ * owns the law (`../rowsBuild.ts` · `timeReadingRows`), so this reader returns
+ * parts and quotes only — no confirm flag, no leftover list, no allow-list.
+ * A form may later skip the click only when a registered benchmark shows it
+ * is always read right (TQ29's growth rule).
+ *
+ * A numeric date the tokens could split two ways stays ONE parse — `10/09/26`
+ * is three numbers; which is the month is the policy's or the person's.
+ *
+ * @example
+ * ```ts
+ * const reader = englishTimeReader();
+ * reader.read('errors on 10/09/26 8 AM to 8:40 AM PST', { locale: 'en-US' });
+ * // { mentions: [{ quote: '10/09/26 8 AM to 8:40 AM PST', parses: [{
+ * //   date: { kind: 'numeric', fields: [10, 9, 26], yearDigits: 2 }, zoneToken: 'PST',
+ * //   rangeOf: [{ wall: { h: 8, meridiem: 'am' } }, { wall: { h: 8, m: 40, meridiem: 'am' } }] }] }] }
+ * reader.read('errors in the last 2 hours', { locale: 'en-US' });
+ * // { mentions: [{ quote: 'last 2 hours', parses: [{ relative: { unit: 'hour', count: 2 } }] }] }
+ * reader.read('what failed yesterday morning?', { locale: 'en-US' });
+ * // { mentions: [{ quote: 'yesterday morning', parses: [], problem: 'unreadable' }] }
+ * ```
+ */
+import { type TimeReader } from '../reader.js';
+/** The reader's recorded identity — on every `time-reading` row with its version. */
+export declare const ENGLISH_TIME_READER_ID = "agentfootprint/english";
+/** Raised whenever what the reader returns for some text changes. */
+export declare const ENGLISH_TIME_READER_VERSION = "1.2.0";
+/** A word right before a phrase that changes what it means: the phrase is not read. */
+export declare const MODIFIER_BEFORE: RegExp;
+/** `from` with no `to`: a time after it is where a window STARTS (`from 3 PM yesterday`), not an hour. */
+export declare const FROM_BEFORE: RegExp;
+/**
+ * A bare number joined to a clock time as a range's first side the grammar
+ * does not read (`8 to 9:30`, `from 8 to 9:30`, `between 8 and 9:30` — the
+ * far side says no meridiem, so `8` is no time): the whole phrase is not
+ * read. Reading `9:30` alone would drop the start the person said.
+ */
+export declare const BARE_SIDE_BEFORE: RegExp;
+/**
+ * Whether some span of `covering` holds `span` whole — `covering.some((a) =>
+ * a.start <= span.start && span.end <= a.end)` — answered by binary search:
+ * among the spans starting at or before `span.start`, the farthest end. Asking
+ * `some` once per match cost matches × phrases, and a long message has many of
+ * both.
+ */
+export declare function coverage(covering: readonly {
+    readonly start: number;
+    readonly end: number;
+}[]): (span: {
+    readonly start: number;
+    readonly end: number;
+}) => boolean;
+/**
+ * `/\bbetween\s+$/i.test(text.slice(0, end))` — `between`, then blanks right
+ * up to `end` — walked back from `end`. The regex read the whole text before
+ * each phrase it was asked about, so a message of many short phrases cost its
+ * length times their number.
+ */
+export declare function saysBetweenBefore(text: string, end: number): boolean;
+/**
+ * Where the text before `end` that those three patterns can reach starts: back
+ * over the blanks before `end`, then over `WORDS_BEFORE` words and the blanks
+ * before each. Each pattern ends at `end` (`\s*$`), spans fewer words, and
+ * takes its leading boundary from the character just before its first word —
+ * all inside this window, which starts at a blank or at 0, so the window's
+ * `^` adds no match. The leftmost match in the window is therefore the leftmost
+ * match in all the text before `end`; matching that text instead re-read the
+ * whole message once per group.
+ */
+export declare function windowBefore(text: string, end: number): number;
+/** Options for {@link englishTimeReader}. */
+export interface EnglishTimeReaderOptions {
+    /**
+     * The language tag the time ask's labels are rendered in (`present.ts`),
+     * e.g. `'en-GB'`. Default `'en-US'`. It never decides a date order — that is
+     * the policy's (`dateOrder`) or the person's.
+     */
+    readonly locale?: string;
+}
+/**
+ * The library's careful English reader: a `kind: 'rule'` tokenizer over the
+ * v1 phrases of the time design's § 5.3, "unreadable" for every other time
+ * phrase it recognises. No dependency; deterministic over the text.
+ *
+ * @example
+ * ```ts
+ * Agent.create({ provider, model })
+ *   .time({ zone: 'America/Los_Angeles', reader: englishTimeReader() })
+ *   .build();
+ * ```
+ */
+export declare function englishTimeReader(options?: EnglishTimeReaderOptions): TimeReader;
+//# sourceMappingURL=english.d.ts.map

package/dist/types/time/readers/english.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"english.d.ts","sourceRoot":"","sources":["../../../../src/time/readers/english.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH,OAAO,EAML,KAAK,UAAU,EAIhB,MAAM,cAAc,CAAC;AAItB,qFAAqF;AACrF,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,qEAAqE;AACrE,eAAO,MAAM,2BAA2B,UAAU,CAAC;AAuFnD,uFAAuF;AACvF,eAAO,MAAM,eAAe,QAK3B,CAAC;AACF,0GAA0G;AAC1G,eAAO,MAAM,WAAW,QAA2B,CAAC;AACpD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAG5B,CAAC;AAiTF;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,GACpE,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAgBrE;AAKD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CASpE;AASD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ9D;AAgQD,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,UAAU,CAQpF"}

package/dist/types/time/readingAsk.d.ts

@@ -0,0 +1,50 @@
+/**
+ * time/readingAsk — the choices an OPEN reading offers (time design
+ * § 6.1, § 6.3): the one field a `time-reading` row whose choice is `open`
+ * needs.
+ *
+ * Pattern: a pure builder over the row — the candidates as labelled choices,
+ *          a zone asked as `format: 'zone'`, a `model` reading offered to
+ *          confirm. The judge of the answer stays `ask.ts` ·
+ *          `checkTimeAnswer`.
+ * Role:    L0 leaf (the time layer). Split from `ask.ts` because its
+ *          labels render through `present.ts` (`presentRange`), and `ask.ts`
+ *          is on the resume door's SYNCHRONOUS path (`tools/inputRequest.ts`)
+ *          while the renderer loads only under `.time()` — the
+ *          optional-family law of docs-next's site budget.
+ * Emits:   N/A.
+ *
+ * @example
+ * ```ts
+ * const ask = timeAskOf(row, defaultTimeAskMessages);
+ * ask?.field.format; // 'time-range' — its `enum` the candidates left
+ * ```
+ */
+import { type TimeAskMessages, type TimeFormat } from './ask.js';
+import type { TimeReadingRow } from './rows.js';
+/** A time field built from a reading — the fields of `tools/inputRequest.ts` · `InputField` it sets. */
+export interface TimeAskField {
+    readonly id: string;
+    readonly type: 'string';
+    readonly required: true;
+    readonly format: TimeFormat;
+    readonly enum?: readonly string[];
+    readonly labels?: readonly string[];
+}
+/** One question about one mention: the question and its field. */
+export interface TimeAsk {
+    readonly question: string;
+    readonly field: TimeAskField;
+}
+/**
+ * The ask a `time-reading` row needs, or `undefined` when its reading is
+ * settled (`only`, `policy`) or is no person's words (a refused mention).
+ * Words the library holds NO reading of (`none`: unreadable, no candidate)
+ * are asked too — which time the person meant, free entry, nothing
+ * pre-filled (`ask.which`, `format: 'time-range'`): the person wrote a time,
+ * and a tool's default never stands in for it. `messages` is the whole
+ * catalog (the caller composes the app's overrides over
+ * `defaultTimeAskMessages`); `id` names the field.
+ */
+export declare function timeAskOf(row: TimeReadingRow, messages: TimeAskMessages, id?: string): TimeAsk | undefined;
+//# sourceMappingURL=readingAsk.d.ts.map

package/dist/types/time/readingAsk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readingAsk.d.ts","sourceRoot":"","sources":["../../../src/time/readingAsk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAuB,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMhD,wGAAwG;AACxG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,kEAAkE;AAClE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;CAC9B;AAWD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,eAAe,EACzB,EAAE,SAAS,GACV,OAAO,GAAG,SAAS,CA6DrB"}