nl2time 0.3.3 → 0.4.0

package/README.md

@@ -45,7 +45,7 @@ nl2time puts a small symbolic IR in the middle of both directions:
 - **`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.
+- **Everything language refers to is an interval with a grain.** "Last week" is seven days; "9pm" is an hour; "March" is a month. Intervals are half-open `[start, end)`; a range with no lower bound ("orders placed before March 2022") has `start: null`.
 
 ## The LLM boundary (optional)
 
@@ -120,7 +120,7 @@ Every imported conformance case carries machine-readable provenance (upstream pr
 pip install nl2time
 ```
 
-The Python engine port lives in [`python/`](python/) (`whenever`-based time model): IR validation, `TimeContext`, and the full deterministic resolver at **100% bit-exact parity** with the JS reference across all 2,790 engine-parity fixtures (`corpus/ir/`), enforced in CI on every push. Parsers and `describe()` are JS-only so far — [docs/porting.md](docs/porting.md) has the strategy and the divergence gates.
+The Python engine port lives in [`python/`](python/) (`whenever`-based time model): IR validation, `TimeContext`, and the full deterministic resolver at **100% bit-exact parity** with the JS reference across all 2,827 engine-parity fixtures (`corpus/ir/`), enforced in CI on every push. Parsers and `describe()` are JS-only so far — [docs/porting.md](docs/porting.md) has the strategy and the divergence gates.
 
 ## Release history
 

package/dist/corpus/runner.d.ts

@@ -17,6 +17,8 @@ export interface IntervalExpect {
     /** Civil expectations, compared in the case's timeZone ("YYYY-MM-DDTHH:MM:SS"). */
     startLocal?: string;
     endLocal?: string;
+    /** Unbounded start ("before March 2022"): the candidate's start must be null (#32). */
+    openStart?: boolean;
     /** Civil point: candidate interval start must equal it. */
     pointLocal?: string;
     /** Omit or null to skip the grain check (imported cases). */

package/dist/corpus/runner.js

@@ -80,6 +80,15 @@ function matchesInterval(v, spec, timeZone) {
         return false;
     if (spec.grain !== undefined && spec.grain !== null && v.grain !== spec.grain)
         return false;
+    if ((spec.openStart === true) !== (v.start === null))
+        return false;
+    if (v.start === null) {
+        if (spec.end !== undefined && v.end.toString() !== spec.end)
+            return false;
+        if (spec.endLocal !== undefined && !localEq(localString(v.end, timeZone), normLocal(spec.endLocal)))
+            return false;
+        return spec.start === undefined && spec.startLocal === undefined && spec.pointLocal === undefined;
+    }
     if (spec.start !== undefined && v.start.toString() !== spec.start)
         return false;
     if (spec.end !== undefined && v.end.toString() !== spec.end)
@@ -177,7 +186,7 @@ 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}`
+        ? `[${v.start === null ? '-inf' : localString(v.start, tz)}, ${localString(v.end, tz)}) ${v.grain}`
         : JSON.stringify(v))
         .join(' | ');
     return `got: ${shown || '(none)'}`;

package/dist/describe/index.js

@@ -17,6 +17,11 @@ export function describe(value, ctx, opts = {}) {
         if (value.kind === 'duration' || value.kind === 'amount') {
             return describeAmount(value, ctx);
         }
+        if (value.start === null) {
+            // Open start ("before March 2022", #32): describe the boundary.
+            const bound = describeInterval(toZoned(value.end, ctx.timeZone), value.grain, ctx, 'absolute', style);
+            return { ...bound, text: `before ${bound.text}`, expr: { op: 'until', end: bound.expr, exclusive: true } };
+        }
         const start = toZoned(value.start, ctx.timeZone);
         return describeInterval(start, value.grain, ctx, framing, style);
     }

package/dist/engine/resolve.d.ts

@@ -8,9 +8,11 @@ export declare class AmbiguityError extends Error {
     constructor(message: string);
 }
 /** A resolved value. Intervals are half-open [start, end). */
-export type TimeValue = {
+export type TimeValue = 
+/** `start` is null for an unbounded start ("before March 2022", #32). */
+{
     kind: 'interval';
-    start: Instant;
+    start: Instant | null;
     end: Instant;
     grain: Grain;
 } | {

package/dist/engine/resolve.js

@@ -1,4 +1,4 @@
-import { addUnits, calendarDaysBetween, containingUnit, floorTo, pointInterval, weekdayNumber, } from '../clock/index.js';
+import { Temporal, addUnits, calendarDaysBetween, containingUnit, floorTo, pointInterval, weekdayNumber, } from '../clock/index.js';
 import { dayPeriodRules } from '../data/dayPeriods.js';
 export class NotResolvableError extends Error {
     constructor(message) {
@@ -27,6 +27,106 @@ function finerGrain(a, b) {
     return GRAIN_ORDER.indexOf(a) <= GRAIN_ORDER.indexOf(b) ? a : b;
 }
 const MAX_CANDIDATES = 8;
+const isPointZi = (zi) => Temporal_compare(zi.start, zi.end) === 0;
+/**
+ * Grain of a `between` result (#37). A range that starts on a calendar period
+ * and ends on a point ("since 2020" = 2020 → now) keeps the start's grain;
+ * a range between two points takes its grain from how the edges align ("the
+ * second half of 2024" = Jul 1 → Jan 1 is month-grained, while a deadline
+ * "by end of month" = now → Sep 1 stays 'instant'). Otherwise the finer
+ * operand grain, as before.
+ */
+function rangeGrain(s, e, start, end, touchesNow) {
+    const sp = isPointZi(s);
+    const ep = isPointZi(e);
+    // `now` is an arbitrary instant even when a fixture pins it to midnight.
+    if (sp && ep && !touchesNow)
+        return alignedGrain(start, end);
+    if (!sp && ep)
+        return s.grain;
+    return finerGrain(s.grain, e.grain);
+}
+/**
+ * Clock-time semantics need a fine grain AND a sub-day extent: a multi-day
+ * interval whose edges are snap points ("end of year" = Jul 1 → Jan 1) is a
+ * calendar period, not a time of day.
+ */
+function isTimeGrained(e) {
+    return (GRAIN_ORDER.indexOf(e.grain) < GRAIN_ORDER.indexOf('day') &&
+        (isPointZi(e) || Temporal_compare(e.start.add({ days: 1 }), e.end) > 0));
+}
+/** Candidates for one (start, end) operand pair of `between`. */
+function betweenPair(s, e, touchesNow) {
+    const out = [];
+    const isPoint = isPointZi(e);
+    const timeGrained = isTimeGrained(e);
+    // Day-grain-or-coarser ends are conversationally inclusive: "between July
+    // 4th and July 10th" covers the 10th. Emit the inclusive reading (end
+    // operand contributes its END) first, with the strict exclusive-at-start
+    // reading as an alternative — the Recognizers-derived corpus pins the
+    // exclusive value, so both must remain candidates (#17).
+    if (!isPoint && !timeGrained) {
+        if (Temporal_compare(s.start, e.end) < 0) {
+            const grain = rangeGrain(s, e, s.start, e.end, touchesNow);
+            out.push({ type: 'interval', zi: { start: s.start, end: e.end, grain } });
+        }
+        if (Temporal_compare(s.start, e.start) < 0) {
+            const grain = rangeGrain(s, e, s.start, e.start, touchesNow);
+            out.push({ type: 'interval', zi: { start: s.start, end: e.start, grain } });
+        }
+        return out;
+    }
+    // Non-point time ends are exclusive at their *start* ("9 to 5pm" ends at
+    // 17:00); point ends are used directly.
+    let endPoint = isPoint ? e.end : e.start;
+    if (Temporal_compare(s.start, endPoint) >= 0) {
+        // A clock-time range wrapping midnight ("9:30pm to 7:30am") rolls the
+        // end into the next day; date ranges just drop.
+        if (!timeGrained)
+            return out;
+        endPoint = endPoint.add({ days: 1 });
+        if (Temporal_compare(s.start, endPoint) >= 0)
+            return out;
+    }
+    out.push({
+        type: 'interval',
+        zi: { start: s.start, end: endPoint, grain: rangeGrain(s, e, s.start, endPoint, touchesNow) },
+    });
+    return out;
+}
+/**
+ * Internal stand-in for an unbounded start; `toValue` turns it into
+ * `start: null`. Far enough back that no calendar arithmetic reaches it.
+ */
+const OPEN_START = Temporal.Instant.from('0100-01-01T00:00:00Z');
+/** (−∞, end) readings for an `until` whose end is not after now (#32). */
+function openStartPair(e, ctx) {
+    const open = OPEN_START.toZonedDateTimeISO(ctx.timeZone);
+    if (isPointZi(e))
+        return [{ type: 'interval', zi: { start: open, end: e.end, grain: edgeGrain(e.end) } }];
+    return [
+        { type: 'interval', zi: { start: open, end: e.end, grain: e.grain } },
+        { type: 'interval', zi: { start: open, end: e.start, grain: e.grain } },
+    ];
+}
+/** Coarsest calendar boundary a single point sits on ("end of 2024" → year). */
+function edgeGrain(z) {
+    if (Temporal_compare(z, z.startOfDay()) !== 0)
+        return 'instant';
+    if (z.day !== 1)
+        return 'day';
+    return z.month === 1 ? 'year' : 'month';
+}
+function alignedGrain(start, end) {
+    if (Temporal_compare(start, end) === 0)
+        return 'instant';
+    const atDayStart = (z) => Temporal_compare(z, z.startOfDay()) === 0;
+    if (!atDayStart(start) || !atDayStart(end))
+        return 'instant';
+    if (start.day !== 1 || end.day !== 1)
+        return 'day';
+    return start.month === 1 && end.month === 1 ? 'year' : 'month';
+}
 export function resolve(expr, ctx) {
     const cands = evalExpr(expr, ctx, undefined).slice(0, MAX_CANDIDATES);
     return { candidates: cands.map((c) => toValue(c)) };
@@ -44,7 +144,7 @@ function toValue(c) {
         case 'interval':
             return {
                 kind: 'interval',
-                start: c.zi.start.toInstant(),
+                start: c.zi.start.epochMilliseconds === OPEN_START.epochMilliseconds ? null : c.zi.start.toInstant(),
                 end: c.zi.end.toInstant(),
                 grain: c.zi.grain,
             };
@@ -168,63 +268,38 @@ function evalExprInner(expr, ctx, anchor) {
         case 'span':
             return intervalMap(evalExpr(expr.anchor, ctx, anchor), (zi) => expr.business ? evalBusinessSpan(zi, expr.amount, ctx) : evalSpan(zi, expr.amount, ctx));
         case 'between': {
-            const starts = evalExpr(expr.start, ctx, anchor);
+            const touchesNow = expr.start.op === 'now' || expr.end.op === 'now';
             const out = [];
-            for (const s of starts) {
-                if (s.type !== 'interval')
+            for (const st of evalExpr(expr.start, ctx, anchor)) {
+                if (st.type !== 'interval')
                     continue;
                 // The end operand resolves anchored to the start (shared context:
                 // "between 3 and 12 of Sept" — the 3 anchors to September).
-                for (const e of evalExpr(expr.end, ctx, s.zi)) {
+                for (const e of evalExpr(expr.end, ctx, st.zi)) {
                     if (e.type !== 'interval')
                         continue;
-                    const isPoint = Temporal_compare(e.zi.start, e.zi.end) === 0;
-                    // Clock-time semantics need a fine grain AND a sub-day extent: a
-                    // multi-day interval whose edges are snap points ("end of year" =
-                    // Jul 1 → Jan 1) carries grain 'instant' but is a calendar period,
-                    // not a time of day.
-                    const timeGrained = GRAIN_ORDER.indexOf(e.zi.grain) < GRAIN_ORDER.indexOf('day') &&
-                        (isPoint || Temporal_compare(e.zi.start.add({ days: 1 }), e.zi.end) > 0);
-                    // Day-grain-or-coarser ends are conversationally inclusive:
-                    // "between July 4th and July 10th" covers the 10th. Emit the
-                    // inclusive reading (end operand contributes its END) first, with
-                    // the strict exclusive-at-start reading as an alternative — the
-                    // Recognizers-derived corpus pins the exclusive value, so both
-                    // must remain candidates (#17).
-                    if (!isPoint && !timeGrained) {
-                        const grain = finerGrain(s.zi.grain, e.zi.grain);
-                        if (Temporal_compare(s.zi.start, e.zi.end) < 0) {
-                            out.push({ type: 'interval', zi: { start: s.zi.start, end: e.zi.end, grain } });
-                        }
-                        if (Temporal_compare(s.zi.start, e.zi.start) < 0) {
-                            out.push({ type: 'interval', zi: { start: s.zi.start, end: e.zi.start, grain } });
-                        }
-                        continue;
-                    }
-                    // Non-point time ends are exclusive at their *start* ("9 to 5pm"
-                    // ends at 17:00); point ends are used directly.
-                    let endPoint = isPoint ? e.zi.end : e.zi.start;
-                    if (Temporal_compare(s.zi.start, endPoint) >= 0) {
-                        // A clock-time range wrapping midnight ("9:30pm to 7:30am") rolls
-                        // the end into the next day; date ranges just drop.
-                        if (!timeGrained)
-                            continue;
-                        endPoint = endPoint.add({ days: 1 });
-                        if (Temporal_compare(s.zi.start, endPoint) >= 0)
-                            continue;
-                    }
-                    out.push({
-                        type: 'interval',
-                        zi: {
-                            start: s.zi.start,
-                            end: endPoint,
-                            grain: finerGrain(s.zi.grain, e.zi.grain),
-                        },
-                    });
+                    out.push(...betweenPair(st.zi, e.zi, touchesNow));
                 }
             }
             return out;
         }
+        case 'until': {
+            // "by Friday", "until 2025-06-30", "before March 2022" (#32): a
+            // deadline [now, end) for the end candidates still ahead of now. Only
+            // when none is ahead does it read as the stretch of history up to the
+            // end, with an unbounded start. Clock-time ends always keep the
+            // deadline reading (they roll to the next day like any time range).
+            const now = pointInterval(ctx.zonedNow);
+            const ends = evalExpr(expr.end, ctx, anchor).flatMap((e) => (e.type === 'interval' ? [e.zi] : []));
+            const ahead = ends.filter((e) => Temporal_compare(e.end, ctx.zonedNow) > 0 || (!isPointZi(e) && isTimeGrained(e)));
+            const out = [];
+            for (const e of ahead.length > 0 ? ahead : ends) {
+                const pair = ahead.length > 0 ? betweenPair(now, e, true) : openStartPair(e, ctx);
+                // "before X" excludes X: its exclusive reading leads.
+                out.push(...(expr.exclusive && pair.length === 2 ? [pair[1], pair[0]] : pair));
+            }
+            return out;
+        }
         case 'seek':
             return evalSeek(expr, ctx, anchor);
         case 'intersect': {
@@ -398,7 +473,25 @@ function evalSeek(expr, ctx, anchor) {
                     out.push({ type: 'interval', zi });
             continue;
         }
-        const zi = seekFrom(b.zi, expr, ctx);
+        // Deictic "this Friday" / "this weekend" (#23): the occurrence on or
+        // after the base day leads, whatever the bias; the previous one follows.
+        // It leads instead when it is the weekend still in progress (Sunday)
+        // or, under bias 'past', when it was at most 3 days ago ("this weekend"
+        // said on Monday or Tuesday).
+        if (expr.dir === 'this' && expr.target.kind === 'weekday' && (b.zi.grain === 'instant' || b.zi.grain === 'day')) {
+            const today = floorTo(b.zi.start, 'day', ctx.weekStart);
+            const target = weekdayNumber(expr.target.weekday);
+            const upDelta = (target - today.dayOfWeek + 7) % 7;
+            const backDelta = ((today.dayOfWeek - target + 6) % 7) + 1;
+            const up = today.add({ days: upDelta });
+            const prev = today.subtract({ days: backDelta });
+            const prevLeads = (target === 6 && backDelta === 1) || (ctx.bias === 'past' && backDelta <= 3);
+            for (const d of prevLeads ? [prev, up] : [up, prev]) {
+                out.push({ type: 'interval', zi: { start: d, end: d.add({ days: 1 }), grain: 'day' } });
+            }
+            continue;
+        }
+        const zi = seekFrom(b.zi, expr.dir === 'this' ? { ...expr, dir: 'nearest' } : expr, ctx);
         if (zi)
             out.push({ type: 'interval', zi });
     }
@@ -623,9 +716,12 @@ function resolveDate(date, ctx, anchor) {
     if (date.month !== undefined && date.day !== undefined) {
         // "May 29" with no year → the most recent occurrence starting on-or-
         // before today, then the following one ("past + future" pairing).
-        const mk = (yearDelta) => {
+        // Occurrence k walks over years where the date exists, so "Feb 29"
+        // lands on leap years instead of clamping to Feb 28 (#14).
+        const valid = (d) => ref.add({ years: d }).with({ month: date.month, day: 1 }).daysInMonth >= date.day;
+        const mk = (k) => {
             const day = ref
-                .add({ years: yearDelta })
+                .add({ years: nthValidDelta(k, valid) })
                 .with({ month: date.month, day: date.day })
                 .startOfDay();
             return { start: day, end: day.add({ days: 1 }), grain: 'day' };
@@ -646,8 +742,13 @@ function resolveDate(date, ctx, anchor) {
     }
     if (date.day !== undefined) {
         // "the 3rd" → most recent occurrence on-or-before today, then the next.
-        const mk = (monthDelta) => {
-            const day = ref.add({ months: monthDelta }).with({ day: date.day }).startOfDay();
+        // Skip months too short for the day ("the 31st" never means the 30th).
+        const valid = (d) => ref.add({ months: d }).with({ day: 1 }).daysInMonth >= date.day;
+        const mk = (k) => {
+            const day = ref
+                .add({ months: nthValidDelta(k, valid) })
+                .with({ day: date.day })
+                .startOfDay();
             return { start: day, end: day.add({ days: 1 }), grain: 'day' };
         };
         if (ctx.bias === 'none') {
@@ -660,6 +761,24 @@ function resolveDate(date, ctx, anchor) {
     const day = floorTo(ref, 'day', ctx.weekStart);
     return [{ start: day, end: day.add({ days: 1 }), grain: 'day' }];
 }
+/**
+ * Map occurrence index k to a calendar delta, counting only deltas where
+ * `valid` holds: index 0 is the first valid delta >= 0, k > 0 steps forward
+ * and k < 0 steps back from it. With every delta valid this is the identity.
+ */
+function nthValidDelta(k, valid) {
+    const LIMIT = 16; // leap years skip at most 8 years; month lengths at most 2
+    let d = 0;
+    for (let g = 0; !valid(d) && g < LIMIT; g++)
+        d++;
+    const step = k > 0 ? 1 : -1;
+    for (let i = 0; i < Math.abs(k); i++) {
+        d += step;
+        for (let g = 0; !valid(d) && g < LIMIT; g++)
+            d += step;
+    }
+    return d;
+}
 /**
  * Order the this-period occurrence and its neighbor under the context bias:
  * 'future' → soonest occurrence not in the past first; 'past' → most recent

package/dist/ir/types.d.ts

@@ -108,6 +108,17 @@ export type TimeExprBody =
     start: TimeExpr;
     end: TimeExpr;
 }
+/**
+ * The stretch up to `end` ("by Friday", "until 2025-06-30", "before March
+ * 2022"): [now, end) while `end` is ahead of now, else (−∞, end) with an
+ * unbounded start. `exclusive` ("before") ranks the reading that stops at
+ * the start of `end` first.
+ */
+ | {
+    op: 'until';
+    end: TimeExpr;
+    exclusive?: boolean;
+}
 /**
  * Directed calendar navigation: seek(now, 'next', weekday tue) is "next
  * Tuesday" (semantics of 'next' controlled by context nextWeekday policy);
@@ -116,7 +127,7 @@ export type TimeExprBody =
  | {
     op: 'seek';
     base: TimeExpr;
-    dir: 'next' | 'prev' | 'nearest';
+    dir: 'next' | 'prev' | 'nearest' | 'this';
     target: Target;
     n?: number;
 }

package/dist/ir/validate.js

@@ -8,7 +8,7 @@ export class IRValidationError extends Error {
     }
 }
 const MODS = ['approx', 'start', 'mid', 'end'];
-const DIRS = ['next', 'prev', 'nearest'];
+const DIRS = ['next', 'prev', 'nearest', 'this'];
 /**
  * Structural validation of untrusted input (LLM output, stored IR, network)
  * into a typed TimeExpr. Mirrors schema/timeexpr.schema.json; the JSON Schema
@@ -66,10 +66,17 @@ export function validateExpr(input, path = '$') {
             validateExpr(obj.end, `${path}.end`);
             return obj;
         }
+        case 'until': {
+            validateExpr(obj.end, `${path}.end`);
+            if (obj.exclusive !== undefined && typeof obj.exclusive !== 'boolean') {
+                throw new IRValidationError('exclusive must be boolean', `${path}.exclusive`);
+            }
+            return obj;
+        }
         case 'seek': {
             validateExpr(obj.base, `${path}.base`);
             if (!DIRS.includes(obj.dir)) {
-                throw new IRValidationError('dir must be next|prev|nearest', `${path}.dir`);
+                throw new IRValidationError('dir must be next|prev|nearest|this', `${path}.dir`);
             }
             validateTarget(obj.target, `${path}.target`);
             if (obj.n !== undefined)

package/dist/parse/en.js

@@ -156,8 +156,23 @@ const TIME_PREPOSITIONS = new Set([
 ]);
 // --- rules -----------------------------------------------------------------
 /** today / yesterday / tomorrow / tonight / day before yesterday / day after tomorrow */
-const ruleDeicticDay = (tokens, i) => {
+const ruleDeicticDay = (tokens, i, ctx) => {
     const w = word(tokens[i]);
+    // "overnight" (#23): the night just ended, or tonight once it is afternoon
+    // and the context looks forward (bias 'future', or 'none' after noon). A
+    // night still in progress is "last night" (the night period wraps midnight).
+    if (w === 'overnight') {
+        const tonight = ctx.bias === 'future' || (ctx.bias === 'none' && ctx.zonedNow.hour >= 12);
+        return {
+            expr: {
+                op: 'intersect',
+                parts: [tonight ? snapNow('day') : snapOffset(-1, 'day'), { op: 'literal', dayPeriod: 'night' }],
+            },
+            consumed: 1,
+            confidence: 0.85,
+            role: 'datetime',
+        };
+    }
     if (w === 'today' || w === 'tdy')
         return { expr: snapNow('day'), consumed: 1, confidence: 1, role: 'date' };
     if (w === 'yesterday')
@@ -416,30 +431,33 @@ const ruleRange = (tokens, i, ctx) => {
     }
     return { expr, consumed: end - i, confidence: 0.95, role: rangeRole(a, b) };
 };
+/** "end of 2024" / "beginning of the year 2024" → the year's boundary point. */
+function readYearEdge(tokens, i) {
+    const w0 = word(tokens[i]);
+    if ((w0 !== 'end' && w0 !== 'beginning' && w0 !== 'start') || word(tokens[i + 1]) !== 'of')
+        return undefined;
+    let yAt = i + 2;
+    if (word(tokens[yAt]) === 'the')
+        yAt += 1;
+    const year = yearAt(tokens, yAt);
+    if (year === undefined)
+        return undefined;
+    return {
+        expr: { op: 'snap', base: { op: 'literal', date: { year } }, unit: 'year', edge: w0 === 'end' ? 'end' : 'start' },
+        consumed: yAt + 1 - i,
+    };
+}
 function readOperand(tokens, i, ctx) {
     // "between the end of 2007 and the end of 2008" — inside a range, "end of
     // YEAR" means the year's end boundary (a point), not its final third.
-    const w0 = word(tokens[i]);
-    if ((w0 === 'end' || w0 === 'beginning' || w0 === 'start') && word(tokens[i + 1]) === 'of') {
-        let yAt = i + 2;
-        if (word(tokens[yAt]) === 'the')
-            yAt += 1;
-        const year = yearAt(tokens, yAt);
-        if (year !== undefined) {
-            return {
-                operand: {
-                    kind: 'date',
-                    expr: {
-                        op: 'snap',
-                        base: { op: 'literal', date: { year } },
-                        unit: 'year',
-                        edge: w0 === 'end' ? 'end' : 'start',
-                    },
-                },
-                consumed: yAt + 1 - i,
-            };
-        }
-    }
+    // "through the end of 2024" (#32): an article before the boundary word.
+    const lead = word(tokens[i]) === 'the' ? 1 : 0;
+    const edge = readYearEdge(tokens, i + lead);
+    if (edge)
+        return { operand: { kind: 'date', expr: edge.expr }, consumed: lead + edge.consumed };
+    const wdd = readWeekdayDate(tokens, i, ctx);
+    if (wdd)
+        return { operand: { kind: 'date', expr: wdd.expr }, consumed: wdd.consumed };
     const rel = ruleLastThisNext(tokens, i, ctx);
     if (rel && rel.role === 'date') {
         // "this friday 5/12": an explicit date after the weekday supersedes it.
@@ -638,6 +656,18 @@ const ruleOpenRange = (tokens, i, ctx) => {
         (ruleCalendarDate(tokens, at + 1, ctx) || ruleEndOf(tokens, at + 1, ctx))) {
         at += 1;
     }
+    // "through the end of 2024" (#32): a year's end is its boundary point here,
+    // as in range operands, not the year's late part.
+    const yearEdge = readYearEdge(tokens, word(tokens[at]) === 'the' ? at + 1 : at);
+    if (yearEdge && mode === 'until') {
+        const consumed = (word(tokens[at]) === 'the' ? 1 : 0) + yearEdge.consumed;
+        return {
+            expr: { op: 'until', end: yearEdge.expr, ...(w === 'before' ? { exclusive: true } : {}) },
+            consumed: at + consumed - i,
+            confidence: 0.9,
+            role: 'datetime',
+        };
+    }
     const inner = ruleDeicticDay(tokens, at, ctx) ??
         ruleLastThisNext(tokens, at, ctx) ??
         ruleHoliday(tokens, at, ctx) ??
@@ -669,19 +699,97 @@ const ruleOpenRange = (tokens, i, ctx) => {
             target = target.start;
         }
     }
+    // Deadlines become `until`: [now, X) while X is ahead, else the history
+    // up to X with an unbounded start ("orders before March 2022", #32).
     const expr = mode === 'since'
         ? { op: 'between', start: target, end: NOW }
-        : { op: 'between', start: NOW, end: target };
+        : { op: 'until', end: target, ...(w === 'before' ? { exclusive: true } : {}) };
     return { expr, consumed: at + inner.consumed - i, confidence: 0.9, role: 'datetime' };
 };
 /** "week of April 10th", "the first/last week of July", "the week starting on Feb 4". */
+/**
+ * A weekday written next to an explicit month-day ("Thursday 2026-08-20",
+ * "Monday, March 3, 2025") checks the date rather than naming a second,
+ * relative weekday: the date wins (#34). A weekday that contradicts a full
+ * date keeps the date at lowered confidence.
+ */
+function readWeekdayDate(tokens, i, ctx) {
+    const w = word(tokens[i]);
+    const weekday = w !== undefined ? WEEKDAY_WORDS[w] : undefined;
+    if (!weekday)
+        return undefined;
+    const d = ruleCalendarDate(tokens, i + 1, ctx);
+    if (!d || d.role !== 'date' || d.expr.op !== 'literal')
+        return undefined;
+    const date = d.expr.date;
+    if (!date || date.month === undefined || date.day === undefined)
+        return undefined;
+    let confidence = Math.max(d.confidence, 0.9);
+    if (date.year !== undefined && isoWeekday(date.year, date.month, date.day) !== weekday)
+        confidence = 0.6;
+    return { expr: d.expr, consumed: 1 + d.consumed, confidence };
+}
+const WEEKDAY_BY_ISO = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+/** Weekday of a proleptic Gregorian date (Sakamoto), without Temporal. */
+function isoWeekday(year, month, day) {
+    const t = [0, 3, 2, 5, 0, 3, 5, 1, 4, 6, 2, 4];
+    const y = month < 3 ? year - 1 : year;
+    const sun0 = (y + Math.floor(y / 4) - Math.floor(y / 100) + Math.floor(y / 400) + t[month - 1] + day) % 7;
+    return WEEKDAY_BY_ISO[(sun0 + 6) % 7];
+}
+/** "Thursday 2026-08-20" → the date (#34). */
+const ruleWeekdayDate = (tokens, i, ctx) => {
+    const r = readWeekdayDate(tokens, i, ctx);
+    return r ? { expr: r.expr, consumed: r.consumed, confidence: r.confidence, role: 'date' } : undefined;
+};
+/**
+ * "twelve months ended June", "the 12 months ending June 30, 2026", "the
+ * three years ended 2025" (#36): the N units up to and including the date's
+ * period — span(date, -N units), i.e. [end(date) − N units, end(date)).
+ */
+const ruleNUnitsEnded = (tokens, i, ctx) => {
+    let at = i;
+    if (word(tokens[at]) === 'the')
+        at += 1;
+    const n = readNumber(tokens, at);
+    if (!n || !Number.isInteger(n.value) || n.value < 1)
+        return undefined;
+    at += n.consumed;
+    const unit = UNIT_WORDS[word(tokens[at]) ?? ''];
+    if (unit !== 'day' && unit !== 'week' && unit !== 'month' && unit !== 'quarter' && unit !== 'year')
+        return undefined;
+    at += 1;
+    const conn = word(tokens[at]);
+    if (conn !== 'ended' && conn !== 'ending')
+        return undefined;
+    at += 1;
+    if (word(tokens[at]) === 'on' || word(tokens[at]) === 'in')
+        at += 1;
+    if (word(tokens[at]) === 'the')
+        at += 1;
+    const year = yearAt(tokens, at);
+    const inner = ruleCalendarDate(tokens, at, ctx) ??
+        ruleLastThisNext(tokens, at, ctx) ??
+        (year !== undefined
+            ? { expr: { op: 'literal', date: { year } }, consumed: 1, confidence: 0.85, role: 'date' }
+            : undefined);
+    if (!inner || inner.role !== 'date')
+        return undefined;
+    const amount = unit === 'quarter' ? { months: -3 * n.value } : { [`${unit}s`]: -n.value };
+    return {
+        expr: { op: 'span', anchor: inner.expr, amount },
+        consumed: at + inner.consumed - i,
+        confidence: 0.95,
+        role: 'date',
+    };
+};
 const ruleWeekOf = (tokens, i, ctx) => {
     let at = i;
     if (word(tokens[at]) === 'the')
         at += 1;
     // "w/c Feb 4" (week commencing)
     if (word(tokens[at]) === 'w/c' || word(tokens[at]) === 'wc') {
-        const date = ruleCalendarDate(tokens, at + 1, ctx);
+        const date = ruleWeekdayDate(tokens, at + 1, ctx) ?? ruleCalendarDate(tokens, at + 1, ctx);
         if (date && date.role === 'date') {
             return {
                 expr: { op: 'snap', base: date.expr, unit: 'week' },
@@ -696,7 +804,7 @@ const ruleWeekOf = (tokens, i, ctx) => {
         let dAt = at + 2;
         if (word(tokens[dAt]) === 'on' || word(tokens[dAt]) === 'from')
             dAt += 1;
-        const date = ruleCalendarDate(tokens, dAt, ctx) ?? ruleDeicticDay(tokens, dAt, ctx);
+        const date = ruleWeekdayDate(tokens, dAt, ctx) ?? ruleCalendarDate(tokens, dAt, ctx) ?? ruleDeicticDay(tokens, dAt, ctx);
         if (date && date.role === 'date') {
             return {
                 expr: { op: 'snap', base: date.expr, unit: 'week' },
@@ -739,7 +847,7 @@ const ruleWeekOf = (tokens, i, ctx) => {
     let scope;
     let consumed = 0;
     const year = yearAt(tokens, at);
-    const date = ruleCalendarDate(tokens, at, ctx);
+    const date = ruleWeekdayDate(tokens, at, ctx) ?? ruleCalendarDate(tokens, at, ctx);
     if (date) {
         scope = date.expr;
         consumed = date.consumed;
@@ -1013,11 +1121,20 @@ const ruleHalfOf = (tokens, i, ctx) => {
     }
     if (which === undefined)
         return undefined;
-    if (word(tokens[at + 1]) !== 'half' || word(tokens[at + 2]) !== 'of')
+    if (word(tokens[at + 1]) !== 'half')
         return undefined;
-    at += 3;
-    if (word(tokens[at]) === 'the')
-        at += 1;
+    if (word(tokens[at + 2]) === 'of') {
+        at += 3;
+        if (word(tokens[at]) === 'the')
+            at += 1;
+    }
+    else if (yearAt(tokens, at + 2) !== undefined) {
+        // "first half 2025" (#36): no "of" before a bare year.
+        at += 2;
+    }
+    else {
+        return undefined;
+    }
     // Scope: a bare unit ("the year"), a relative period ("next month"), a
     // month name, a quarter, or a year.
     let scope;
@@ -1030,9 +1147,13 @@ const ruleHalfOf = (tokens, i, ctx) => {
         consumed = 1;
     }
     else {
+        const bareYear = yearAt(tokens, at);
         const inner = ruleLastThisNext(tokens, at, ctx) ??
             ruleBareYear(tokens, at, ctx) ??
-            ruleCalendarDate(tokens, at, ctx);
+            ruleCalendarDate(tokens, at, ctx) ??
+            (bareYear !== undefined
+                ? { expr: { op: 'literal', date: { year: bareYear } }, consumed: 1, confidence: 0.85, role: 'date' }
+                : undefined);
         if (inner && inner.role === 'date') {
             unit = halfScopeUnit(inner.expr);
             if (unit) {
@@ -1063,7 +1184,8 @@ const ruleHalfOf = (tokens, i, ctx) => {
 };
 const REL_SYNONYMS = {
     last: 'last', previous: 'last', prior: 'last',
-    this: 'this', current: 'this', present: 'this', that: 'this',
+    // Not "that": "that year" points back into the conversation, not at now (#35).
+    this: 'this', current: 'this', present: 'this',
     next: 'next', coming: 'next', upcoming: 'next', following: 'next',
 };
 function weekendExpr(dir) {
@@ -1103,7 +1225,8 @@ const ruleLastThisNext = (tokens, i, ctx) => {
         return undefined;
     }
     if (nextWord === 'weekend') {
-        const dir = w === 'last' ? 'prev' : w === 'next' ? 'next' : 'nearest';
+        // "this weekend" is deictic: the current/upcoming one leads (#23).
+        const dir = w === 'last' ? 'prev' : w === 'next' ? 'next' : 'this';
         return { expr: weekendExpr(dir), consumed: 2, confidence: 1, role: 'date' };
     }
     if (nextWord === 'workweek' || ((nextWord === 'work' || nextWord === 'working') && word(tokens[i + 2]) === 'week')) {
@@ -1140,11 +1263,12 @@ const ruleLastThisNext = (tokens, i, ctx) => {
     }
     const weekday = WEEKDAY_WORDS[nextWord];
     if (weekday) {
-        const dir = w === 'last' ? 'prev' : w === 'next' ? 'next' : 'nearest';
+        // "this Friday" is deictic: today-or-next leads, whatever the bias (#23).
+        const dir = w === 'last' ? 'prev' : w === 'next' ? 'next' : 'this';
         // Only the literal words "next"/"last" carry the dialect ambiguity;
         // "upcoming Friday" is strictly the adjacent occurrence (n: 1).
         const literalWord = word(tokens[i]);
-        const strict = (literalWord === 'upcoming' || literalWord === 'coming') && dir !== 'nearest';
+        const strict = (literalWord === 'upcoming' || literalWord === 'coming') && dir !== 'this';
         return {
             expr: {
                 op: 'seek',
@@ -1411,6 +1535,101 @@ const ruleNextN = (tokens, i) => {
     };
 };
 /** "the year [2008]", "the week [31]", "the month", "the day" — with ISO week numbers. */
+/** Words that open a relative clause after "the <unit>" ("the year we …"). */
+const RELATIVE_CLAUSE_STARTS = new Set([
+    'the', 'a', 'an', 'we', 'i', 'you', 'they', 'he', 'she', 'it', 'that', 'which', 'when', 'where', 'our',
+    'my', 'your', 'their', 'his', 'her', 'its', 'this', 'these', 'those', 'in', 'during', 'after', 'before',
+]);
+/**
+ * "year to date", "YTD", "so far this month", "this quarter so far" (#36):
+ * from the start of the current period up to now — the period itself as the
+ * start operand keeps the period's grain. Ends at now, not at the start of
+ * today, whatever `partialPeriod` says (owner decision D3).
+ */
+function toDate(unit) {
+    return { op: 'between', start: snapNow(unit), end: NOW };
+}
+const TO_DATE_ABBREV = { ytd: 'year', qtd: 'quarter', mtd: 'month', wtd: 'week' };
+const ruleToDate = (tokens, i) => {
+    const w = word(tokens[i]);
+    if (w !== undefined && TO_DATE_ABBREV[w]) {
+        return { expr: toDate(TO_DATE_ABBREV[w]), consumed: 1, confidence: 0.95, role: 'date' };
+    }
+    const periodUnit = (u) => {
+        const unit = UNIT_WORDS[u ?? ''];
+        return unit === 'year' || unit === 'quarter' || unit === 'month' || unit === 'week' || unit === 'day'
+            ? unit
+            : undefined;
+    };
+    // "year to date" / "year-to-date" (the article form is in ruleTheUnit).
+    const u0 = periodUnit(w);
+    if (u0) {
+        let at = i + 1;
+        if (word(tokens[at]) === '-')
+            at += 1;
+        if (word(tokens[at]) === 'to') {
+            at += 1;
+            if (word(tokens[at]) === '-')
+                at += 1;
+            if (word(tokens[at]) === 'date')
+                return { expr: toDate(u0), consumed: at + 1 - i, confidence: 0.95, role: 'date' };
+        }
+    }
+    // "so far this year" / "so far in the month"
+    if (w === 'so' && word(tokens[i + 1]) === 'far') {
+        let at = i + 2;
+        if (word(tokens[at]) === 'in' || word(tokens[at]) === 'during')
+            at += 1;
+        if (word(tokens[at]) === 'this' || word(tokens[at]) === 'the') {
+            const u = periodUnit(word(tokens[at + 1]));
+            if (u)
+                return { expr: toDate(u), consumed: at + 2 - i, confidence: 0.95, role: 'date' };
+        }
+    }
+    // "this year so far" / "this month to date"
+    if (w === 'this') {
+        const u = periodUnit(word(tokens[i + 1]));
+        const tail = word(tokens[i + 2]);
+        if (u && ((tail === 'so' && word(tokens[i + 3]) === 'far') || (tail === 'to' && word(tokens[i + 3]) === 'date'))) {
+            return { expr: toDate(u), consumed: 4, confidence: 0.95, role: 'date' };
+        }
+    }
+    return undefined;
+};
+/**
+ * "trailing twelve months", "TTM", "LTM", "the trailing 4 quarters" (#36):
+ * the N most recent COMPLETE units before the current one — [start of the
+ * current unit − N, start of the current unit). The finance/BI convention
+ * (complete periods compare like with like); "the past 12 months" stays the
+ * rolling window.
+ */
+const ruleTrailing = (tokens, i) => {
+    const w = word(tokens[i]);
+    const trailing = (unit, n, consumed) => ({
+        expr: {
+            op: 'span',
+            anchor: { op: 'snap', base: NOW, unit, edge: 'start' },
+            amount: unit === 'quarter' ? { months: -3 * n } : { [`${unit}s`]: -n },
+        },
+        consumed,
+        confidence: 0.95,
+        role: 'date',
+    });
+    if (w === 'ttm' || w === 'ltm')
+        return trailing('month', 12, 1);
+    let at = i;
+    if (w === 'the')
+        at += 1;
+    if (word(tokens[at]) !== 'trailing')
+        return undefined;
+    const n = readNumber(tokens, at + 1);
+    if (!n || !Number.isInteger(n.value) || n.value < 1)
+        return undefined;
+    const unit = UNIT_WORDS[word(tokens[at + 1 + n.consumed]) ?? ''];
+    if (unit !== 'day' && unit !== 'week' && unit !== 'month' && unit !== 'quarter' && unit !== 'year')
+        return undefined;
+    return trailing(unit, n.value, at + 2 + n.consumed - i);
+};
 const ruleTheUnit = (tokens, i) => {
     if (word(tokens[i]) !== 'the')
         return undefined;
@@ -1446,14 +1665,17 @@ const ruleTheUnit = (tokens, i) => {
     const unit = UNIT_WORDS[uw];
     if (!unit || unit === 'second' || unit === 'minute' || unit === 'hour')
         return undefined;
+    // "over the years" is generic, and "the year the invoice was posted" /
+    // "the month we launched" name a period by a clause, not the current one:
+    // no match rather than a confident "this year" (#35).
+    if (uw.endsWith('s') && UNIT_WORDS[uw.slice(0, -1)] === unit)
+        return undefined;
+    if (RELATIVE_CLAUSE_STARTS.has(word(tokens[i + 2]) ?? ''))
+        return undefined;
     // "the year to date", "the month to date"
     if (word(tokens[i + 2]) === 'to' && word(tokens[i + 3]) === 'date') {
         return {
-            expr: {
-                op: 'between',
-                start: { op: 'snap', base: NOW, unit, edge: 'start' },
-                end: { op: 'snap', base: NOW, unit: 'day', edge: 'start' },
-            },
+            expr: toDate(unit),
             consumed: 4,
             confidence: 1,
             role: 'date',
@@ -1926,11 +2148,28 @@ const ruleBareYear = (tokens, i) => {
     if (!y || y.value < 1500 || y.value > 2199)
         return undefined;
     const prev = word(tokens[i - 1]);
-    if (prev !== undefined && !['in', 'since', 'by', 'until', 'during', 'year', 'of', 'from'].includes(prev)) {
-        return undefined;
+    // "2024 or 2025", "in 2024 and 2025" (#35): the second year of a
+    // coordination is its own match instead of being dropped.
+    const coordinated = prev !== undefined && ['or', 'and', '&', 'vs', 'versus'].includes(prev) && yearAt(tokens, i - 2) !== undefined;
+    if (prev !== undefined &&
+        !coordinated &&
+        !['in', 'since', 'by', 'until', 'during', 'year', 'of', 'from', 'for', 'calendar', 'cy', 'throughout'].includes(prev)) {
+        return undefined;
+    }
+    // "for 2024" / "revenue for 2024" (#36) — but not "for 2000 people": after
+    // "for", the year must end the phrase or be followed by a function word.
+    if (prev === 'for') {
+        const next = tokens[i + y.consumed];
+        const nw = word(next);
+        if (next !== undefined && (nw === undefined || !YEAR_FOLLOWERS.has(nw)))
+            return undefined;
     }
     return { expr: { op: 'literal', date: { year: y.value } }, consumed: y.consumed, confidence: 0.85, role: 'date' };
 };
+const YEAR_FOLLOWERS = new Set([
+    'and', 'or', 'vs', 'versus', 'compared', 'to', 'through', 'thru', 'by', 'in', 'on', 'at', 'from', 'with',
+    'was', 'were', 'is', 'are', 'only', 'alone', 'so', 'than', 'but', '-', '?', '.', ';', ':', ')',
+]);
 /** Decades ("1990s", "the 90s") and centuries ("21st century"). */
 const ruleDecadeCentury = (tokens, i) => {
     const t = tokens[i];
@@ -2963,6 +3202,10 @@ export const EN_RULE_ENTRIES = [
     { name: 'bare-year', rule: ruleBareYear },
     { name: 'calendar-date', rule: ruleCalendarDate },
     { name: 'clock-time', rule: ruleClockTime },
+    { name: 'weekday-date', rule: ruleWeekdayDate },
+    { name: 'n-units-ended', rule: ruleNUnitsEnded },
+    { name: 'to-date', rule: ruleToDate },
+    { name: 'trailing', rule: ruleTrailing },
     { name: 'weekday-day', rule: ruleWeekdayDay },
     { name: 'weekday-alone', rule: ruleWeekdayAlone },
     { name: 'period-alone', rule: rulePeriodAlone },

package/dist/parse/index.js

@@ -71,7 +71,7 @@ function parseWithRules(text, ctx, rules) {
             text: text.slice(startTok.start, endTok.end),
             start: startTok.start,
             end: endTok.end,
-            expr: m.expr,
+            expr: wholeAmounts(m.expr),
             confidence: m.confidence,
             source: 'rules',
         };
@@ -156,8 +156,14 @@ function mergeAdjacent(matches, tokens, connectors) {
                         dateExpr = stripDayPeriod(dateExpr) ?? dateExpr;
                 }
             }
+            // "end of day yesterday" / "yesterday at start of day": a bare day
+            // edge (built against today) moves onto the date it modifies instead
+            // of intersecting today's edge with that date, which is empty (#33).
+            const dayEdge = todayDayEdge(timeExpr);
             out.push({
-                expr: { op: 'intersect', parts: [dateExpr, timeExpr] },
+                expr: dayEdge
+                    ? { op: 'snap', base: dateExpr, unit: 'day', edge: dayEdge }
+                    : { op: 'intersect', parts: [dateExpr, timeExpr] },
                 consumed: next.tokenEnd - cur.tokenStart,
                 confidence: Math.max(cur.confidence, next.confidence),
                 role: 'datetime',
@@ -238,6 +244,38 @@ function forceMeridiem(expr, period) {
     const meridiem = period === 'morning' ? 'am' : (period === 'night' || period === 'evening') && hour <= 5 ? 'am' : 'pm';
     return { ...expr, time: { ...expr.time, meridiem } };
 }
+const AMOUNT_SECONDS = {
+    seconds: 1,
+    minutes: 60,
+    hours: 3600,
+    days: 86400,
+    weeks: 604800,
+    months: 2592000,
+    years: 31536000,
+};
+/**
+ * Calendar amounts are integers in the IR. A fractional one ("3,5 años",
+ * "半年", "123,45 secondes") becomes an exact duration, using the same
+ * nominal unit lengths as the English duration rules (#16).
+ */
+function wholeAmounts(expr) {
+    if (expr.op !== 'amount')
+        return expr;
+    const entries = Object.entries(expr.amount);
+    if (entries.every(([, v]) => Number.isInteger(v)))
+        return expr;
+    let secs = 0;
+    for (const [k, v] of entries)
+        secs += v * (AMOUNT_SECONDS[k] ?? 0);
+    return { op: 'duration', iso: `PT${Math.round(secs * 100) / 100}S` };
+}
+/** The edge of a bare "start/end of day" point anchored to today, if `expr` is one. */
+function todayDayEdge(expr) {
+    if (expr.op !== 'snap' || expr.unit !== 'day' || !expr.edge)
+        return undefined;
+    const b = expr.base;
+    return b.op === 'snap' && b.unit === 'day' && !b.edge && b.base.op === 'now' ? expr.edge : undefined;
+}
 /** Remove day-period literals from an intersect; undefined if nothing remains. */
 function stripDayPeriod(expr) {
     if (expr.op === 'literal' && expr.dayPeriod && !expr.date && !expr.time)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nl2time",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Bidirectional natural language ⇄ date/time: parse expressions like 'last week' into concrete intervals, and describe instants as '9pm last night' — deterministic core, optional LLM assist.",
   "license": "MIT",
   "type": "module",
@@ -48,12 +48,12 @@
     "locale"
   ],
   "dependencies": {
-    "temporal-polyfill": "^0.3.0"
+    "temporal-polyfill": "^1.0.6"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
-    "typescript": "^5.6.0",
-    "vitest": "^3.0.0"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22"

package/schema/timeexpr.schema.json

@@ -13,6 +13,7 @@
         { "$ref": "#/$defs/Snap" },
         { "$ref": "#/$defs/Span" },
         { "$ref": "#/$defs/Between" },
+        { "$ref": "#/$defs/Until" },
         { "$ref": "#/$defs/Seek" },
         { "$ref": "#/$defs/Intersect" },
         { "$ref": "#/$defs/Duration" },
@@ -157,13 +158,25 @@
       "required": ["op", "start", "end"],
       "additionalProperties": false
     },
+    "Until": {
+      "type": "object",
+      "description": "The stretch up to end ('by Friday', 'until 2025-06-30', 'before March 2022'): [now, end) while end is ahead of now, otherwise an open-start range ending at end (resolved values carry start: null). exclusive ('before') ranks the reading that stops at the start of end first.",
+      "properties": {
+        "op": { "const": "until" },
+        "end": { "$ref": "#/$defs/TimeExpr" },
+        "exclusive": { "type": "boolean" },
+        "mod": { "$ref": "#/$defs/Mod" }
+      },
+      "required": ["op", "end"],
+      "additionalProperties": false
+    },
     "Seek": {
       "type": "object",
       "description": "Directed calendar navigation: seek(now, next, weekday tue) is 'next Tuesday' (exact semantics owned by the context nextWeekday policy); with n, the nth occurrence within the base interval ('the 2nd Monday of March').",
       "properties": {
         "op": { "const": "seek" },
         "base": { "$ref": "#/$defs/TimeExpr" },
-        "dir": { "enum": ["next", "prev", "nearest"] },
+        "dir": { "enum": ["next", "prev", "nearest", "this"] },
         "target": { "$ref": "#/$defs/Target" },
         "n": { "type": "integer", "minimum": 1 },
         "mod": { "$ref": "#/$defs/Mod" }