fix(objectql): a placeholder resolved past the four-digit years on a time column takes the door's time class

Claude-Session: https://claude.ai/code/session_01Ujdtvqs7ree7WyQmEDwEnG
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/20844-resolved-token-year-range.md

@@ -11,14 +11,15 @@ Clause-②: no (narrowing)
 
 **BREAKING**: this narrows what the engine answers for a filter carrying a relative-date placeholder. A date macro is resolved after the temporal-comparand door, which steps around a placeholder, so the year range that door asks of a literal never saw the value one resolved to. It does now, through the same function, core's `isOutsideTemporalYearRange`, by the column's kind: a `date` takes the years 0001 to 9999 and a `datetime` 1000 to 9999. It ships as `minor` under the launch-window convention for accept-set narrowings. No export or published type changes.
 
-**What is refused now.** A date macro whose resolved value falls outside its column's years, on a declared `date` or `datetime` field, at `where` (on `find`, `findOne`, `count`, `aggregate`, a multi-row `update` and `delete`), at a per-aggregation `filter`, at `having` (by the aggregated column's kind), and through `judgeFilter`. On REST that is `POST /api/v1/data/:object/query` and every other door that reads through the engine. Measured before this on InMemoryDriver and SqlDriver on SQLite, over a `datetime` field with a row in 2026 and a row in 1500:
+**What is refused now.** A date macro whose resolved value falls outside its column's years, on a declared `date` or `datetime` field (or, on a `time` field, one that resolves to an instant whose UTC year has no four-digit spelling), at `where` (on `find`, `findOne`, `count`, `aggregate`, a multi-row `update` and `delete`), at a per-aggregation `filter`, at `having` (by the aggregated column's kind), and through `judgeFilter`. On REST that is `POST /api/v1/data/:object/query` and every other door that reads through the engine. Measured before this on InMemoryDriver and SqlDriver on SQLite, over a `datetime` field with a row in 2026 and a row in 1500:
 
 - `$gt {8000_years_from_now}` answered both rows, and the right answer was none;
 - `$lt {2027_years_ago}` answered the 1500 row, because the resolver spelled year -1 as `-1-10-01` and that text was read as a day in 2001, and the right answer was none;
-- `$lt {1977_years_ago}` resolved to year 49, below the `datetime` floor of 1000, which now applies to a resolved placeholder as it does to a literal.
+- `$lt {1977_years_ago}` resolved to year 49, below the `datetime` floor of 1000, which now applies to a resolved placeholder as it does to a literal;
+- on a `time` field, `$gt {8000_years_from_now}` answered every row: the `time` rule keeps no time of day from an instant whose UTC year has no four-digit spelling, so it compared as text. Such a placeholder is refused now in the words a literal of that instant gets.
 
 **What an author sees.** The refusal names the field, the placeholder as written, its position, the value it resolved to and that value's year, in the temporal-comparand door's words for the year class: `filter on 'opened_at' compares a declared datetime field against "{8000_years_from_now}" at where.opened_at.$gt, a relative-date placeholder that resolved to "+010026-10-01" (the year 10026), an instant whose UTC year falls outside the years 1000 to 9999 …`. It ends by asking for a placeholder whose offset lands inside those years.
 
 **The resolver's spelling** (`@objectstack/core`). A date macro that lands on a day outside 0001..9999 now resolves to that day in the expanded-year form of ECMAScript's date time string format, `+010026-10-01` or `-000001-10-01` (year 0 is `0000-10-01`). It used to take the storage rule's unpadded spelling, `10026-10-01` or `-1-10-01`, which `Date.parse` reads through the host's legacy parser in the host's zone, so a day in year -1 read as one in 2001 and could not be judged. Every consumer of `resolveFilterToken` and `resolveFilterTokens` sees the new spelling for such a day only. A day inside 0001..9999 and a sub-day placeholder's instant are spelled as before.
 
-**Unchanged.** A placeholder that resolves inside its column's years answers as before; a `date` keeps the years 0001 to 0999, which a `datetime` refuses. A placeholder on a column that names no year (text, `time`) and a context placeholder such as `{current_user_id}` are not judged by this range. Every literal comparand answers as before.
+**Unchanged.** A placeholder that resolves inside its column's years answers as before; a `date` keeps the years 0001 to 0999, which a `datetime` refuses, and a `time` field reads the time of day of any instant with a four-digit year, year 0 included. A placeholder on a column with no temporal kind (text, number) and a context placeholder such as `{current_user_id}` are not judged by this range. Every literal comparand answers as before.

packages/objectql/src/engine-resolved-token-year-range.test.ts

@@ -18,6 +18,7 @@
  * | `opened_at $lt {1977_years_ago}` | `0049-10-01` | no row | no row | 400 (the `datetime` floor) |
  * | `placed_on $gt {8000_years_from_now}` | `10026-10-01` | both rows | both rows | 400 |
  * | `having` `max(opened_at) $gt {8000_years_from_now}` | `10026-10-01` | both groups | — | 400 |
+ * | `opens_at` (`time`, 09:00 / 12:00) `$gt {8000_years_from_now}` | `10026-10-01`, compared as text | both rows | both rows | 400 (the [#20480] class) |
  * | `judgeFilter` of the first two | | `{ ok: true }` | | refused |
  *
  * The right answer to each `$gt` / `$lt` above was no row; a literal of each
@@ -235,6 +236,31 @@ describe('[#20844] a relative-date placeholder resolved outside its column\'s ye
     expect(engine.judgeFilter('ledger', { placed_on: { $lt: '{1977_years_ago}' } })).toEqual({ ok: true });
   });
 
+  // [#20480] A `time` column keeps the time of day of an instant whose UTC
+  // year has four digits, and no other: a literal past them is refused by the
+  // door in that class's words, and so is a placeholder resolved past them.
+  it('a time column refuses a placeholder resolved to an instant outside the four-digit years, in the time class\'s words', async () => {
+    for (const [token, resolved, year] of PAST_BOTH.filter(([t]) => t !== '{2026_years_ago}')) {
+      for (const [position, call] of positions('opens_at', '$gt', token)) {
+        const err = await refusalOf(call());
+        const at = `${position} opens_at $gt ${token}`;
+        expect(err, at).not.toBeNull();
+        expect(err!.code, at).toBe('INVALID_FILTER');
+        expect(err!.status, at).toBe(400);
+        expect(err!.message, at).toContain(`"${token}"`);
+        expect(err!.message, at).toContain(`resolved to "${resolved}" (the year ${year})`);
+        expect(err!.message, at).toContain('so no time of day is read from it');
+      }
+    }
+    expect(reads).toHaveLength(0);
+    // Year 0 has a four-digit spelling (`0000-…`), so a time of day is read
+    // from it, as from a literal; so is every year inside 0001..9999.
+    for (const token of ['{2026_years_ago}', '{1977_years_ago}', '{100_years_ago}']) {
+      await expect(engine.find('ledger', { where: { opens_at: { $gt: token } } }), token).resolves.toEqual([]);
+    }
+    expect(reads).toHaveLength(3);
+  });
+
   it('a placeholder on a column with no year, or a context placeholder, is not this judgement\'s', async () => {
     // A text column compares the resolved day as text: no kind, no range.
     await expect(engine.find('ledger', { where: { note: { $gt: '{8000_years_from_now}' } } })).resolves.toEqual([]);

packages/objectql/src/temporal-comparand-door.ts

@@ -199,14 +199,18 @@
  * $lt "{1977_years_ago}"        200, no row        (0049-10-01, below the datetime floor)
  * ```
  *
- * The right answer to the first two is no row, and a literal of each value is
- * refused here. {@link assertResolvedTemporalTokensInRange} and
+ * …and on a `time` field (rows at 09:00 and 12:00), `$gt "{8000_years_from_now}"`
+ * answered both rows: the instant has no four-digit year, so the `time` rule
+ * kept no time of day from it and it compared as text. A literal of each
+ * resolved value is refused here, and the first two answered rows where the
+ * right answer was none. {@link assertResolvedTemporalTokensInRange} and
  * {@link assertHavingResolvedTemporalTokensInRange} close it: the engine's
  * resolution stage hands them the caller's condition and its resolution, the
  * same walk takes both trees side by side, and a comparand written as a date
  * macro is refused when core's `isOutsideTemporalYearRange` puts the value it
- * resolved to outside its column's years — `INVALID_FILTER` / 400, in this
- * door's year-class words, naming the placeholder and the year. ⛔ Not a
+ * resolved to outside its column's years (on a `time` column, the four-digit
+ * years of the instant, the [#20480] class) — `INVALID_FILTER` / 400, in this
+ * door's words for that class, naming the placeholder and the year. ⛔ Not a
  * second pass of the door: every other comparand was judged before
  * resolution. Core's resolver spells a day outside 0001..9999 in the
  * expanded-year form (`+010026-10-01`, `-000001-10-01`), so the range reads
@@ -249,10 +253,9 @@ export interface UninterpretableTemporalComparand {
  * field's years: the placeholder as written, and the value it resolved to.
  */
 export interface ResolvedTokenOutsideYears extends UninterpretableTemporalComparand {
-  kind: 'date' | 'datetime';
   /** The placeholder as the caller wrote it, braces included. */
   token: string;
-  /** The value it resolved to (`value` is the same, for the year class). */
+  /** The value it resolved to. */
   value: unknown;
 }
 
@@ -803,12 +806,16 @@ export type ResolvedTokenJudge = (written: unknown, resolved: unknown) => void;
 
 /**
  * [#20844] Judge one comparand the caller wrote as a relative-date
- * placeholder, by the year of the value it resolved to and nothing else: core's
- * `isOutsideTemporalYearRange` of that value for the column's kind, the range
- * the door asks of a literal. A literal comparand was judged by the door
- * before resolution, and a context placeholder (`{current_user_id}`) names no
- * year, so neither is this judgement's. A `time` column names no year either
- * (core's range says so of every `time` value).
+ * placeholder, by the year of the value it resolved to and nothing else — the
+ * year class the door asks of a literal of the column's kind: core's
+ * `isOutsideTemporalYearRange` for a `date` or a `datetime`, and [#20480] for a
+ * `time` column, which has no year of its own, the class of an instant the
+ * `time` rule keeps no time of day from because its UTC year has no
+ * four-digit spelling — asked as the door asks it, of core's predicate and of
+ * the four-digit years, so year 0 (`0000-…`) reads as it does for a literal.
+ * A literal comparand was judged by the door before resolution, and a context
+ * placeholder (`{current_user_id}`) names no year, so neither is this
+ * judgement's.
  */
 function judgeResolvedToken(
   kind: TemporalComparandKind,
@@ -817,10 +824,11 @@ function judgeResolvedToken(
   resolved: unknown,
   path: string,
 ): ResolvedTokenOutsideYears | null {
-  if (kind === 'time') return null;
   if (classifyFilterToken(written)?.kind !== 'date-macro') return null;
-  if (!isOutsideTemporalYearRange(resolved, kind)) return null;
-  return { field, kind, token: written as string, value: resolved, path };
+  const outside = kind === 'time'
+    ? isUninterpretableTemporalComparand('time', resolved) && isInstantOutsideFourDigitYears(resolved)
+    : isOutsideTemporalYearRange(resolved, kind);
+  return outside ? { field, kind, token: written as string, value: resolved, path } : null;
 }
 
 /** [#20844] The placeholder, where it sits, and what it resolved to — for the message. */
@@ -832,6 +840,25 @@ function resolvedTokenPhrase(hit: ResolvedTokenOutsideYears): string {
 /** [#20844] The fix for a placeholder, ahead of the year class's own for a literal. */
 const RESOLVED_TOKEN_REMEDY = 'Use a relative-date placeholder whose offset lands inside those years.';
 
+/**
+ * [#20844] A hit's words, in the door's sentences for the class a literal of
+ * the same value takes: the kind's year class for a `date` or a `datetime`,
+ * and [#20480] the `time` class for a `time` column.
+ */
+function resolvedTokenWords(hit: ResolvedTokenOutsideYears): { cls: string; where: string; having: string; remedy: string } {
+  if (hit.kind === 'time') {
+    const time = TIME_OUTSIDE_FOUR_DIGIT_YEARS;
+    return { cls: time.why, where: time.where, having: time.having, remedy: REMEDY.time };
+  }
+  const yearClass = yearClassOutside(hit.kind, hit.value);
+  return {
+    cls: `${yearClass.year}, the years a ${hit.kind} value may name`,
+    where: yearClass.where,
+    having: yearClass.having,
+    remedy: `${RESOLVED_TOKEN_REMEDY} ${yearClass.remedy}`,
+  };
+}
+
 /**
  * [#20844] Refuse a relative-date placeholder in `where` (or, by `path`, a
  * per-aggregation `filter`) that resolved to a value outside its declared
@@ -855,12 +882,11 @@ export function assertResolvedTemporalTokensInRange(
   if (!fields || typeof fields !== 'object') return;
   const hit = walkCondition({ ...whereScope(fields), judge: judgeResolvedToken }, written, resolved, path, 0);
   if (!hit) return;
-  const yearClass = yearClassOutside(hit.kind, hit.value);
+  const words = resolvedTokenWords(hit);
   throw invalidFilterError(
     `${operation}('${object}'): filter on '${hit.field}' compares a declared ${hit.kind} field against `
-    + `${resolvedTokenPhrase(hit)}, ${yearClass.year}, the years a ${hit.kind} value may name, so it is `
-    + `not a ${hit.kind} value this platform can interpret. ${yearClass.where} The filter was NOT applied. `
-    + `${RESOLVED_TOKEN_REMEDY} ${yearClass.remedy}`,
+    + `${resolvedTokenPhrase(hit)}, ${words.cls}, so it is not a ${hit.kind} value this platform can `
+    + `interpret. ${words.where} The filter was NOT applied. ${words.remedy}`,
   );
 }
 
@@ -878,11 +904,10 @@ export function assertHavingResolvedTemporalTokensInRange(
 ): void {
   const hit = walkCondition({ ...havingScope(classes), judge: judgeResolvedToken }, written, resolved, 'having', 0);
   if (!hit) return;
-  const yearClass = yearClassOutside(hit.kind, hit.value);
+  const words = resolvedTokenWords(hit);
   throw invalidFilterError(
     `aggregate('${object}'): ${havingColumnPhrase(hit, query)} compares against ${resolvedTokenPhrase(hit)}, `
-    + `${yearClass.year}, the years a ${hit.kind} value may name, so it is not a ${hit.kind} `
-    + `value this platform can interpret. ${yearClass.having} The \`having\` was NOT applied. `
-    + `${RESOLVED_TOKEN_REMEDY} ${yearClass.remedy}`,
+    + `${words.cls}, so it is not a ${hit.kind} value this platform can interpret. ${words.having} `
+    + `The \`having\` was NOT applied. ${words.remedy}`,
   );
 }

packages/rest/src/data-resolved-token-year-range.test.ts

@@ -16,6 +16,7 @@
  * | `opened_at $lt {2027_years_ago}` | 200, the 1500 row (`-1-…` read as 2001) | 400 |
  * | `opened_at $lt {1977_years_ago}` | 200, no row | 400 (the `datetime` floor) |
  * | `placed_on $gt {8000_years_from_now}` | 200, both rows | 400 |
+ * | `opens_at` (`time`, 09:00 and 12:00) `$gt {8000_years_from_now}` | 200, both rows (compared as text) | 400 |
  *
  * The right answer to each was no row. Every refusal sits beside its control:
  * a placeholder resolved inside the range answers the right rows. InMemoryDriver
@@ -45,12 +46,13 @@ const LEDGER = {
     customer_id: { name: 'customer_id', type: 'text' as const },
     placed_on: { name: 'placed_on', type: 'date' as const },
     opened_at: { name: 'opened_at', type: 'datetime' as const },
+    opens_at: { name: 'opens_at', type: 'time' as const },
   },
 };
 
 const ROWS = [
-  { id: 'r2026', customer_id: 'c1', placed_on: '2026-03-01', opened_at: '2026-03-01T10:00:00.000Z' },
-  { id: 'r1500', customer_id: 'c2', placed_on: '1500-03-01', opened_at: '1500-03-01T10:00:00.000Z' },
+  { id: 'r2026', customer_id: 'c1', placed_on: '2026-03-01', opened_at: '2026-03-01T10:00:00.000Z', opens_at: '09:00:00' },
+  { id: 'r1500', customer_id: 'c2', placed_on: '1500-03-01', opened_at: '1500-03-01T10:00:00.000Z', opens_at: '12:00:00' },
 ];
 
 /** field · operator · placeholder · the resolved value and year a refusal names */
@@ -61,6 +63,8 @@ const REFUSED: ReadonlyArray<readonly [string, string, string, string]> = [
   ['placed_on', '$lt', '{2027_years_ago}', '"-000001-09-30" (the year -1)'],
   // The `datetime` floor of 1000 applies to a resolved placeholder as to a literal.
   ['opened_at', '$lt', '{1977_years_ago}', '"0049-09-30" (the year 49)'],
+  // A `time` column keeps no time of day from an instant with no four-digit year.
+  ['opens_at', '$gt', '{8000_years_from_now}', '"+010026-09-30" (the year 10026)'],
 ];
 
 /** field · operator · placeholder · the ids `where` answers — inside the range, the control */