nl2time 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nl2time contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# nl2time
+
+Bidirectional natural language ⇄ date/time. Parse expressions like *"last week"* into concrete, timezone- and locale-correct intervals — and describe instants back as *"9pm last night"*. Deterministic core; optional LLM assist that can only ever emit the same symbolic IR the rule parser emits.
+
+```ts
+import { TimeContext, parse, resolve, describe, Temporal } from 'nl2time';
+
+const ctx = TimeContext.make({
+  now: '2026-07-20T17:00:00Z',        // omit for system time; pass for reproducibility
+  timeZone: 'America/Los_Angeles',    // the user's zone, not the machine's
+  locale: 'en-US',                    // region matters: week start, date order, …
+});
+
+// NL → time -----------------------------------------------------------------
+const { matches } = parse('how many shoes did I sell last week', ctx);
+resolve(matches[0].expr, ctx).candidates[0];
+// { kind: 'interval', start: 2026-07-12T07:00:00Z, end: 2026-07-19T07:00:00Z, grain: 'week' }
+// …with locale 'en-GB' the same words give Jul 13 – Jul 20 (Monday week start).
+
+// time → NL -----------------------------------------------------------------
+describe(Temporal.Instant.from('2026-07-20T04:00:00Z'), ctx, { style: 'casual' }).text;
+// '9pm last night'   (4am UTC Jul 20 = 9pm Jul 19 in LA; today is Jul 20 there)
+describe(Temporal.Instant.from('2026-07-20T04:00:00Z'), ctx).text;
+// 'yesterday at 9:00 PM'
+```
+
+## Why another date library?
+
+Existing tools do one direction, half-way:
+
+- **Parsers** (chrono-node, Duckling, dateparser) collapse text straight to a concrete datetime, losing granularity ("July" is a month, not a millisecond), ambiguity (which "Friday"?), and the week-start question entirely.
+- **Formatters** (`Intl.RelativeTimeFormat`, Luxon, timeago) take a pre-computed `(value, unit)` — *you* decide the framing, the unit, and when "23 hours ago" should become "yesterday". Nobody owns that decision.
+- **LLMs** are demonstrably bad at raw date arithmetic (leap years, DST, large offsets) but good at language.
+
+nl2time puts a small symbolic IR in the middle of both directions:
+
+```
+   text ──parse──►┐                       ┌──◄─select── instant/interval
+                  │   TimeExpr (JSON IR)  │
+                  └──►─resolve──► value   └──render──► "9pm last night"
+```
+
+- **`TimeExpr`** — a JSON operator tree (`now`, `literal`, `offset`, `snap`, `span`, `seek`, `between`, `intersect`, `recur`) over timeline intervals. [Spec](docs/ir-spec.md), [JSON Schema](schema/timeexpr.schema.json).
+- **`resolve(expr, ctx)`** — deterministic evaluation against a `TimeContext` (reference instant, IANA timezone, locale, week start, ambiguity policies). Ambiguity is data: candidates come back ordered, never silently guessed.
+- **`describe(value, ctx)`** — chooses framing (calendar / elapsed / absolute), builds the IR expression that describes the value, renders it via `Intl`. Round-trip invariant: `resolve(describe(v).expr, ctx)` contains `v`.
+- **Everything language refers to is an interval with a grain.** "Last week" is seven days; "9pm" is an hour; "March" is a month.
+
+## The LLM boundary (optional)
+
+nl2time never makes network calls. Rules run first; you can supply a fallback for the long tail, and its output is schema-validated **IR, never concrete dates** — all arithmetic stays deterministic and testable:
+
+```ts
+import { parseWithFallback, buildPrompt, irJsonSchema } from 'nl2time/llm';
+
+const result = await parseWithFallback(text, ctx, async (text, ctxSummary) => {
+  // call your LLM with buildPrompt(text, ctx) + irJsonSchema() constrained output
+  return llmClient.structured(buildPrompt(text, ctx), irJsonSchema());
+});
+```
+
+See [docs/agents.md](docs/agents.md) for reference architectures (analytics agents, tool-calling, deferred resolution).
+
+## Policy, not guesses
+
+Cultural/ambiguous semantics are explicit `TimeContext` knobs with CLDR-derived defaults:
+
+| Question | Knob | Default |
+|---|---|---|
+| Does a week start Sunday or Monday? | `weekStart` | CLDR, by locale *region* (en-US: sun, en-GB: mon) |
+| Is 5/2 May 2nd or Feb 5th? | `dateOrder` | CLDR-style by region |
+| "Friday" — which one? | `bias: 'past' \| 'future' \| 'none'` | `none` (nearest) |
+| "Next Tuesday" on a Sunday? | `nextWeekday: 'nearest' \| 'week-after'` | `nearest` |
+| Does "last 3 days" include today? | `partialPeriod: 'include' \| 'exclude'` | `include` |
+| "At 4" — am or pm? | — | both candidates, plausibility-ordered |
+
+## Status
+
+v0.1 — English parsing, en-* describe, core engine with a DST/edge-case battery. Recurrence (`every Tuesday`) is representable in the IR but resolves in v2.
+
+**Corpus** ([corpus/](corpus/), runner exported as `nl2time/corpus`): a bidirectional golden set with per-case license provenance — 41 hand-authored NL→time cases (all passing), a 65-case datetime→NL golden set (all passing; to our knowledge the first published eval set for humanized time generation), and 693 cases imported from Microsoft Recognizers-Text (MIT) of which 12.6% currently pass — the honest coverage baseline the parser climbs against (`npm run eval`, `npm run baselines`). See [corpus/ATTRIBUTIONS.md](corpus/ATTRIBUTIONS.md) and [docs/porting.md](docs/porting.md).
+
+## Development
+
+```
+npm install
+npm test          # vitest: conformance fixtures + DST battery + round-trip invariant
+npm run typecheck
+npm run build
+```
+
+MIT.

package/dist/clock/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The clock seam: every Temporal usage in nl2time flows through this module.
+ *
+ * Portability contract (see docs/porting.md): a Python port replaces this
+ * module with `whenever` (Temporal-inspired) — Temporal.Instant ↔
+ * whenever.Instant, Temporal.ZonedDateTime ↔ whenever.ZonedDateTime,
+ * Temporal.PlainDate ↔ whenever.Date. No other module may import Temporal
+ * directly.
+ */
+import { Temporal } from 'temporal-polyfill';
+import type { Grain, Unit, Weekday } from '../ir/types.js';
+export { Temporal };
+export type Instant = Temporal.Instant;
+export type Zoned = Temporal.ZonedDateTime;
+/** Half-open zoned interval [start, end) carrying its granularity. */
+export interface ZInterval {
+    start: Zoned;
+    end: Zoned;
+    grain: Grain;
+}
+export declare function systemNow(): Instant;
+export declare function systemTimeZone(): string;
+export declare function toZoned(instant: Instant, timeZone: string): Zoned;
+export declare function weekdayNumber(w: Weekday): number;
+/** Point interval at z (grain 'instant'). */
+export declare function pointInterval(z: Zoned): ZInterval;
+/**
+ * The containing unit interval of z: floor to the unit boundary, extend one
+ * unit. Weeks honor weekStart; quarters are calendar quarters.
+ */
+export declare function containingUnit(z: Zoned, unit: Unit, weekStart: Weekday): ZInterval;
+export declare function floorTo(z: Zoned, unit: Unit, weekStart: Weekday): Zoned;
+/**
+ * Calendar-aware unit addition: day/week/month/quarter/year offsets preserve
+ * wall-clock time across DST (Temporal semantics); hour/minute/second are
+ * exact.
+ */
+export declare function addUnits(z: Zoned, unit: Unit, n: number): Zoned;
+/** Whole calendar days between two zoned datetimes (calendar difference, not /86400s). */
+export declare function calendarDaysBetween(from: Zoned, to: Zoned): number;

package/dist/clock/index.js

@@ -0,0 +1,99 @@
+/**
+ * The clock seam: every Temporal usage in nl2time flows through this module.
+ *
+ * Portability contract (see docs/porting.md): a Python port replaces this
+ * module with `whenever` (Temporal-inspired) — Temporal.Instant ↔
+ * whenever.Instant, Temporal.ZonedDateTime ↔ whenever.ZonedDateTime,
+ * Temporal.PlainDate ↔ whenever.Date. No other module may import Temporal
+ * directly.
+ */
+import { Temporal } from 'temporal-polyfill';
+export { Temporal };
+export function systemNow() {
+    return Temporal.Now.instant();
+}
+export function systemTimeZone() {
+    return Temporal.Now.timeZoneId();
+}
+export function toZoned(instant, timeZone) {
+    return instant.toZonedDateTimeISO(timeZone);
+}
+const WEEKDAY_NUM = {
+    mon: 1,
+    tue: 2,
+    wed: 3,
+    thu: 4,
+    fri: 5,
+    sat: 6,
+    sun: 7,
+};
+export function weekdayNumber(w) {
+    return WEEKDAY_NUM[w];
+}
+/** Point interval at z (grain 'instant'). */
+export function pointInterval(z) {
+    return { start: z, end: z, grain: 'instant' };
+}
+/**
+ * The containing unit interval of z: floor to the unit boundary, extend one
+ * unit. Weeks honor weekStart; quarters are calendar quarters.
+ */
+export function containingUnit(z, unit, weekStart) {
+    const start = floorTo(z, unit, weekStart);
+    return { start, end: addUnits(start, unit, 1), grain: unit };
+}
+export function floorTo(z, unit, weekStart) {
+    switch (unit) {
+        case 'second':
+            return z.round({ smallestUnit: 'second', roundingMode: 'floor' });
+        case 'minute':
+            return z.round({ smallestUnit: 'minute', roundingMode: 'floor' });
+        case 'hour':
+            return z.round({ smallestUnit: 'hour', roundingMode: 'floor' });
+        case 'day':
+            return z.startOfDay();
+        case 'week': {
+            const target = WEEKDAY_NUM[weekStart];
+            // dayOfWeek is ISO (mon=1..sun=7); step back to the week-start day.
+            const delta = (z.dayOfWeek - target + 7) % 7;
+            return z.startOfDay().subtract({ days: delta });
+        }
+        case 'month':
+            return z.with({ day: 1 }).startOfDay();
+        case 'quarter': {
+            const qStartMonth = Math.floor((z.month - 1) / 3) * 3 + 1;
+            return z.with({ month: qStartMonth, day: 1 }).startOfDay();
+        }
+        case 'year':
+            return z.with({ month: 1, day: 1 }).startOfDay();
+    }
+}
+/**
+ * Calendar-aware unit addition: day/week/month/quarter/year offsets preserve
+ * wall-clock time across DST (Temporal semantics); hour/minute/second are
+ * exact.
+ */
+export function addUnits(z, unit, n) {
+    switch (unit) {
+        case 'second':
+            return z.add({ seconds: n });
+        case 'minute':
+            return z.add({ minutes: n });
+        case 'hour':
+            return z.add({ hours: n });
+        case 'day':
+            return z.add({ days: n });
+        case 'week':
+            return z.add({ weeks: n });
+        case 'month':
+            return z.add({ months: n });
+        case 'quarter':
+            return z.add({ months: 3 * n });
+        case 'year':
+            return z.add({ years: n });
+    }
+}
+/** Whole calendar days between two zoned datetimes (calendar difference, not /86400s). */
+export function calendarDaysBetween(from, to) {
+    return to.startOfDay().since(from.startOfDay(), { largestUnit: 'day' }).days;
+}

package/dist/context.d.ts

@@ -0,0 +1,48 @@
+import { type Instant, type Zoned } from './clock/index.js';
+import type { DayPeriodRule } from './data/dayPeriods.js';
+import type { Weekday } from './ir/types.js';
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export type DateOrder = 'MDY' | 'DMY' | 'YMD';
+export type Bias = 'past' | 'future' | 'none';
+/** The dialectal "next Tuesday" question: nearest upcoming vs Tuesday of next week. */
+export type NextWeekdayPolicy = 'nearest' | 'week-after';
+/** Does "the last 3 days" include the partial current day? */
+export type PartialPeriodPolicy = 'include' | 'exclude';
+export interface TimeContextOptions {
+    /**
+     * Reference instant. Defaults to the system clock; pass an explicit value
+     * (Temporal.Instant or ISO string) for reproducible resolution and tests.
+     */
+    now?: Instant | string;
+    /** IANA timezone of the *user/utterance*, not the machine. Defaults to system. */
+    timeZone?: string;
+    /** BCP-47 language-REGION tag. Region drives week-start & date-order defaults. */
+    locale?: string;
+    weekStart?: Weekday;
+    dateOrder?: DateOrder;
+    /** Direction preference for underspecified expressions ("Friday", "May 29"). */
+    bias?: Bias;
+    nextWeekday?: NextWeekdayPolicy;
+    partialPeriod?: PartialPeriodPolicy;
+    /** Override the locale's day-period boundaries (e.g. to match another system's conventions). */
+    dayPeriods?: DayPeriodRule[];
+}
+export declare class TimeContext {
+    readonly now: Instant;
+    readonly timeZone: string;
+    readonly locale: string;
+    readonly language: string;
+    readonly region: string | undefined;
+    readonly weekStart: Weekday;
+    readonly dateOrder: DateOrder;
+    readonly bias: Bias;
+    readonly nextWeekday: NextWeekdayPolicy;
+    readonly partialPeriod: PartialPeriodPolicy;
+    readonly dayPeriods: DayPeriodRule[] | undefined;
+    private constructor();
+    static make(opts?: TimeContextOptions): TimeContext;
+    /** The reference instant projected into the context timezone. */
+    get zonedNow(): Zoned;
+}

package/dist/context.js

@@ -0,0 +1,75 @@
+import { Temporal, systemNow, systemTimeZone, toZoned, } from './clock/index.js';
+import { firstDayForRegion } from './data/weekData.js';
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+const MDY_REGIONS = ['US', 'PH', 'UM', 'VI', 'GU', 'AS', 'PR'];
+const YMD_REGIONS = ['CN', 'JP', 'KR', 'TW', 'HU', 'MN', 'LT'];
+export class TimeContext {
+    now;
+    timeZone;
+    locale;
+    language;
+    region;
+    weekStart;
+    dateOrder;
+    bias;
+    nextWeekday;
+    partialPeriod;
+    dayPeriods;
+    constructor(opts) {
+        const rawNow = opts.now ?? systemNow();
+        try {
+            this.now = typeof rawNow === 'string' ? parseInstant(rawNow) : rawNow;
+        }
+        catch (e) {
+            throw new ConfigError(`invalid now: ${String(e)}`);
+        }
+        this.timeZone = opts.timeZone ?? systemTimeZone();
+        this.locale = opts.locale ?? 'en-US';
+        let language;
+        let region;
+        try {
+            const tag = new Intl.Locale(this.locale);
+            language = tag.language;
+            region = tag.region;
+        }
+        catch {
+            throw new ConfigError(`invalid locale: ${this.locale}`);
+        }
+        this.language = language;
+        this.region = region;
+        this.weekStart = opts.weekStart ?? firstDayForRegion(region);
+        this.dateOrder =
+            opts.dateOrder ??
+                (region && MDY_REGIONS.includes(region)
+                    ? 'MDY'
+                    : region && YMD_REGIONS.includes(region)
+                        ? 'YMD'
+                        : 'DMY');
+        this.bias = opts.bias ?? 'none';
+        this.nextWeekday = opts.nextWeekday ?? 'nearest';
+        this.partialPeriod = opts.partialPeriod ?? 'include';
+        this.dayPeriods = opts.dayPeriods;
+        // Validate the timezone eagerly so failures surface at construction.
+        try {
+            toZoned(this.now, this.timeZone);
+        }
+        catch {
+            throw new ConfigError(`invalid timeZone: ${this.timeZone}`);
+        }
+    }
+    static make(opts = {}) {
+        return new TimeContext(opts);
+    }
+    /** The reference instant projected into the context timezone. */
+    get zonedNow() {
+        return toZoned(this.now, this.timeZone);
+    }
+}
+function parseInstant(s) {
+    return Temporal.Instant.from(s);
+}

package/dist/corpus/runner.d.ts

@@ -0,0 +1,81 @@
+import { type TimeContextOptions } from '../context.js';
+import { type DescribeOptions } from '../describe/index.js';
+import type { CalendarAmount, Grain } from '../ir/types.js';
+export interface SourceInfo {
+    name: string;
+    license: string;
+    url?: string;
+    path?: string;
+    commit?: string;
+    index?: number;
+}
+export interface IntervalExpect {
+    /** Instant expectations (ISO with offset/Z). */
+    start?: string;
+    end?: string;
+    /** Civil expectations, compared in the case's timeZone ("YYYY-MM-DDTHH:MM:SS"). */
+    startLocal?: string;
+    endLocal?: string;
+    /** Civil point: candidate interval start must equal it. */
+    pointLocal?: string;
+    /** Omit or null to skip the grain check (imported cases). */
+    grain?: Grain | null;
+}
+export interface ForwardExpect {
+    noMatch?: boolean;
+    amount?: CalendarAmount;
+    durationSeconds?: number;
+    /** Ordered: candidate i must match spec i (hand-authored cases). */
+    first?: IntervalExpect;
+    candidates?: IntervalExpect[];
+    /** Unordered: every value must appear among resolved candidates (imported). */
+    values?: IntervalExpect[];
+}
+export interface ForwardCase {
+    id: string;
+    text: string;
+    ctx: TimeContextOptions;
+    expect: ForwardExpect;
+    /** Default: 'core'. */
+    level?: 'core' | 'aspirational';
+    source?: SourceInfo;
+    tags?: string[];
+    note?: string;
+}
+export interface ReverseCase {
+    id: string;
+    value: {
+        instant?: string;
+        interval?: {
+            start: string;
+            end: string;
+            grain: Grain;
+        };
+    };
+    ctx: TimeContextOptions;
+    opts?: DescribeOptions;
+    /** Expected nl2time output (normalized). Graded exactly for level 'core'. */
+    primary: string;
+    /** Additional acceptable renderings, for grading other systems/LLM output. */
+    accept?: string[];
+    framing?: string;
+    /** Default: 'core'. */
+    level?: 'core' | 'aspirational';
+    source?: SourceInfo;
+    tags?: string[];
+    note?: string;
+}
+export interface CaseOutcome {
+    id: string;
+    pass: boolean;
+    detail?: string;
+}
+/** Lowercase, unify NBSP/NNBSP, collapse whitespace, strip trailing period. */
+export declare function normalizeText(s: string): string;
+export declare function runForwardCase(c: ForwardCase): CaseOutcome;
+export declare function runReverseCase(c: ReverseCase): CaseOutcome;
+/**
+ * Grade arbitrary text (another system, an LLM) against a reverse case:
+ * primary and every accept entry are acceptable.
+ */
+export declare function gradeReverseText(c: ReverseCase, text: string): boolean;

package/dist/corpus/runner.js

@@ -0,0 +1,220 @@
+/**
+ * Corpus runner: executes golden-set cases (corpus/) against this
+ * implementation. Exported as `nl2time/corpus` so evals, ports, and consumers
+ * can grade their own pipelines against the same cases.
+ *
+ * Case format: see corpus/README.md. All comparisons here are pure functions
+ * of (case, implementation output) — no I/O.
+ */
+import { Temporal, toZoned } from '../clock/index.js';
+import { TimeContext } from '../context.js';
+import { describe } from '../describe/index.js';
+import { resolve } from '../engine/resolve.js';
+import { parse } from '../parse/index.js';
+/** Lowercase, unify NBSP/NNBSP, collapse whitespace, strip trailing period. */
+export function normalizeText(s) {
+    return s
+        .toLowerCase()
+        .replace(/[  ]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .replace(/\.$/, '')
+        .trim();
+}
+function localString(instant, timeZone) {
+    const pdt = toZoned(instant, timeZone).toPlainDateTime();
+    // Normalize to second precision: "YYYY-MM-DDTHH:MM:SS".
+    return pdt.toString({ smallestUnit: 'second' });
+}
+function normLocal(s) {
+    // Pad "2016-11-07T16:12" → "2016-11-07T16:12:00".
+    return s.length === 16 ? `${s}:00` : s;
+}
+/**
+ * Equality with inclusive-end tolerance: some upstream corpora express
+ * interval ends as the last included second ("23:59:59"); our half-open
+ * convention lands one second later ("00:00:00" next day). Accept both.
+ */
+function localEq(actual, expected) {
+    if (actual === expected)
+        return true;
+    if (!expected.endsWith(':59:59') && !expected.endsWith(':59'))
+        return false;
+    const bumped = Temporal.PlainDateTime.from(expected).add({ seconds: 1 }).toString({
+        smallestUnit: 'second',
+    });
+    return actual === bumped;
+}
+const AMOUNT_SECONDS = {
+    years: 31536000,
+    months: 2592000,
+    weeks: 604800,
+    days: 86400,
+    hours: 3600,
+    minutes: 60,
+    seconds: 1,
+};
+function amountToSeconds(amount) {
+    let total = 0;
+    for (const [k, v] of Object.entries(amount)) {
+        if (typeof v === 'number')
+            total += v * (AMOUNT_SECONDS[k] ?? 0);
+    }
+    return total;
+}
+function isoDurationToSeconds(iso) {
+    const m = iso.match(/^(-)?P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/);
+    if (!m)
+        return undefined;
+    const [, neg, y, mo, w, d, h, mi, s] = m;
+    const total = (Number(y ?? 0) * 31536000) +
+        (Number(mo ?? 0) * 2592000) +
+        (Number(w ?? 0) * 604800) +
+        (Number(d ?? 0) * 86400) +
+        (Number(h ?? 0) * 3600) +
+        (Number(mi ?? 0) * 60) +
+        Number(s ?? 0);
+    return neg ? -total : total;
+}
+function matchesInterval(v, spec, timeZone) {
+    if (v.kind !== 'interval')
+        return false;
+    if (spec.grain !== undefined && spec.grain !== null && v.grain !== spec.grain)
+        return false;
+    if (spec.start !== undefined && v.start.toString() !== spec.start)
+        return false;
+    if (spec.end !== undefined && v.end.toString() !== spec.end)
+        return false;
+    if (spec.startLocal !== undefined && !localEq(localString(v.start, timeZone), normLocal(spec.startLocal)))
+        return false;
+    if (spec.endLocal !== undefined) {
+        const actualEnd = localString(v.end, timeZone);
+        let expectedEnd = normLocal(spec.endLocal);
+        // Some upstream time ranges emit a cross-midnight end without the date
+        // roll (end textually before start) — accept the next-day equivalent.
+        if (spec.startLocal !== undefined && expectedEnd < normLocal(spec.startLocal)) {
+            const rolled = Temporal.PlainDateTime.from(expectedEnd).add({ days: 1 }).toString({ smallestUnit: 'second' });
+            if (!localEq(actualEnd, expectedEnd) && !localEq(actualEnd, rolled))
+                return false;
+        }
+        else if (!localEq(actualEnd, expectedEnd)) {
+            return false;
+        }
+    }
+    if (spec.pointLocal !== undefined && !localEq(localString(v.start, timeZone), normLocal(spec.pointLocal)))
+        return false;
+    return true;
+}
+function matchesAmountish(v, seconds) {
+    if (v.kind === 'amount')
+        return amountToSeconds(v.amount) === seconds;
+    if (v.kind === 'duration')
+        return isoDurationToSeconds(v.iso) === seconds;
+    return false;
+}
+export function runForwardCase(c) {
+    let ctx;
+    try {
+        ctx = TimeContext.make(c.ctx);
+    }
+    catch (e) {
+        return { id: c.id, pass: false, detail: `context: ${String(e)}` };
+    }
+    const { matches } = parse(c.text, ctx);
+    if (c.expect.noMatch) {
+        return matches.length === 0
+            ? { id: c.id, pass: true }
+            : { id: c.id, pass: false, detail: `unexpected match "${matches[0].text}"` };
+    }
+    if (matches.length === 0)
+        return { id: c.id, pass: false, detail: 'no match' };
+    const tz = ctx.timeZone;
+    // Hand-authored expectations grade the first match; imported `values`
+    // expectations accept any match (multi-span utterances).
+    for (const [mi, m] of matches.entries()) {
+        let candidates;
+        try {
+            candidates = resolve(m.expr, ctx).candidates;
+        }
+        catch {
+            continue;
+        }
+        let ok = true;
+        if (c.expect.amount) {
+            ok = candidates.some((v) => v.kind === 'amount' && JSON.stringify(v.amount) === JSON.stringify(c.expect.amount));
+        }
+        if (ok && c.expect.durationSeconds !== undefined) {
+            ok = candidates.some((v) => matchesAmountish(v, c.expect.durationSeconds));
+        }
+        if (ok && c.expect.first) {
+            ok = candidates.length > 0 && matchesInterval(candidates[0], c.expect.first, tz);
+        }
+        if (ok && c.expect.candidates) {
+            ok =
+                candidates.length >= c.expect.candidates.length &&
+                    c.expect.candidates.every((spec, i) => matchesInterval(candidates[i], spec, tz));
+        }
+        if (ok && c.expect.values) {
+            ok = c.expect.values.every((spec) => candidates.some((v) => matchesInterval(v, spec, tz)));
+        }
+        if (ok)
+            return { id: c.id, pass: true };
+        if (mi === 0 && (c.expect.first || c.expect.candidates)) {
+            // Ordered expectations are strict about the first match.
+            return { id: c.id, pass: false, detail: describeMismatch(candidates, tz) };
+        }
+    }
+    return { id: c.id, pass: false, detail: describeMismatch(resolveSafe(matches[0].expr, ctx), tz) };
+}
+function resolveSafe(expr, ctx) {
+    try {
+        return resolve(expr, ctx).candidates;
+    }
+    catch {
+        return [];
+    }
+}
+function describeMismatch(candidates, tz) {
+    const shown = candidates
+        .slice(0, 3)
+        .map((v) => v.kind === 'interval'
+        ? `[${localString(v.start, tz)}, ${localString(v.end, tz)}) ${v.grain}`
+        : JSON.stringify(v))
+        .join(' | ');
+    return `got: ${shown || '(none)'}`;
+}
+export function runReverseCase(c) {
+    let ctx;
+    try {
+        ctx = TimeContext.make(c.ctx);
+    }
+    catch (e) {
+        return { id: c.id, pass: false, detail: `context: ${String(e)}` };
+    }
+    const value = c.value.instant
+        ? Temporal.Instant.from(c.value.instant)
+        : {
+            kind: 'interval',
+            start: Temporal.Instant.from(c.value.interval.start),
+            end: Temporal.Instant.from(c.value.interval.end),
+            grain: c.value.interval.grain,
+        };
+    const d = describe(value, ctx, c.opts);
+    const got = normalizeText(d.text);
+    if (got === normalizeText(c.primary)) {
+        if (c.framing && d.framing !== c.framing) {
+            return { id: c.id, pass: false, detail: `framing ${d.framing} ≠ ${c.framing}` };
+        }
+        return { id: c.id, pass: true };
+    }
+    return { id: c.id, pass: false, detail: `got "${d.text}"` };
+}
+/**
+ * Grade arbitrary text (another system, an LLM) against a reverse case:
+ * primary and every accept entry are acceptable.
+ */
+export function gradeReverseText(c, text) {
+    const got = normalizeText(text);
+    if (got === normalizeText(c.primary))
+        return true;
+    return (c.accept ?? []).some((a) => normalizeText(a) === got);
+}