diff --git a/‎.changeset/20549-comparand-door-real-day-iso.md‎
Lines changed: 44 additions & 0 deletions b/‎.changeset/20549-comparand-door-real-day-iso.md‎
Lines changed: 44 additions & 0 deletions
diff --git a/‎packages/core/src/utils/temporal-comparand.test.ts‎
Lines changed: 167 additions & 5 deletions b/‎packages/core/src/utils/temporal-comparand.test.ts‎
Lines changed: 167 additions & 5 deletions
@@ -0,0 +1,44 @@
+---
+"@objectstack/core": minor
+"@objectstack/objectql": minor
+---
+
+fix(core,objectql)!: a temporal filter comparand is refused with `INVALID_FILTER` / 400 exactly when the same value is refused as a written value — a day that does not exist (`"2026-02-30"`) is no longer rolled over or compared as text, and a non-ISO `datetime` spelling (`"07/15/2026 10:00"`) is no longer read in the server's zone (#20549); and a `time` comparand whose instant has no four-digit UTC year (`"+010000-01-01T10:00:00Z"`) is refused rather than compared as text (#20480)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) a refusal of a filter comparand VALUE at the engine's temporal-comparand door (where, a per-aggregation filter, having) and, through the same predicate, the analytics raw-SQL decline: no authorable key, spelling or stored shape of metadata moves, `packages/spec` is untouched, and no stored row is read or rewritten. What is refused is a temporal string naming a day that does not exist, a datetime string outside the ISO spellings, and a bare integer string; which instant such a string meant (a host zone, a locale's day order, a year or epoch milliseconds) is not something a ledger entry can decide. The other categories are closed on facts: both packages publish (not `unpublished`); no ADR-0087 id covers a comparand value check (not `registered` / `already-registered`); and the change is runtime behaviour, not a TypeScript declaration (not `runtime-interface-only` / `type-surface-only`). -->
+
+**BREAKING**: this narrows what a `date`, a `datetime` and a `time` field accept as a filter comparand. It ships as `minor` under the launch-window convention for accept-set narrowings (`check-changeset-no-major` refuses `major` until GA; the breaking-ness is carried by this banner and the ADR-0087 disposition above).
+
+The record validator already refused the `date` / `datetime` classes as written values (`VALIDATION_FAILED` / `invalid_date`). The comparand door was wider, so a filter admitted what a write refused and answered the wrong rows. The two predicates moved into `@objectstack/core`'s `isUninterpretableTemporalComparand`, and both doors now ask that one rule. A comparand is refused with `INVALID_FILTER` / 400, naming the field, before any driver read, at `where`, a per-aggregation `filter` and `having`:
+
+- **A day that does not exist**, on a `date` or as the day part of a `datetime`: `"2026-02-30"`, `"2026-02-29"` (2026 is not a leap year), `"2026-04-31"`, `"2026-02-30T10:00:00Z"`. `"2028-02-29"` is a real day and is read.
+- **A `datetime` string in any spelling but the ISO 8601 ones the platform writes**, after trimming: `YYYY-MM-DD` (midnight UTC); `YYYY-MM-DDTHH:MM[:SS[.fraction]]` followed by `Z`, a `±HH:MM` or `±HHMM` offset, or nothing (a zone-naive wall clock is UTC, ADR-0074); and `YYYY-MM-DD HH:MM[:SS[.fraction]]` with no zone. Refused now, for example: `"07/15/2026 10:00"`, `"2026/07/15 10:00"`, `"15 July 2026 10:00"`, `"07/08/2026"`, `"Wed, 15 Jul 2026 10:00:00 GMT"`, `"2026-07-15 10:00:00+08:00"` (write it with a `T`), and a bare integer string such as `"2026"` or `"1784109600000"`.
+- **An instant on a `time` column in either class above.** A `time` column reads a comparand that is not a bare wall clock as an instant, by the `datetime` rule, and keeps its UTC time of day — so `"07/15/2026 10:00"` was the host zone's time of day, and `"1784109600000"` a string of epoch milliseconds. A wall clock (`"10:00"`, `"10:00:00.5"`), an ISO instant, a `Date` and an epoch-millisecond number are read as before, in a four-digit year (next).
+- **An instant on a `time` column whose UTC year has no four-digit spelling**, in every spelling (#20480): `"+010000-01-01T10:00:00Z"`, `"-000001-01-01T10:00:00Z"`, `"9999-12-31T23:00:00-02:00"` (year 10000 in UTC), and the epoch-millisecond number or `Date` of any of them. A `time` column keeps the UTC time of day of an instant only when that instant spells a four-digit year; any other one reached the driver as written and was compared with the stored `HH:MM:SS` text. No time of day is read from an extended year. Year 0 (`"0000-06-15T10:00:00Z"`) spells four digits, and its time of day is read as before.
+
+Epoch milliseconds stay a `datetime` comparand as a JSON number: `{ "$gt": 1784109600000 }` is read exactly as before. As a string, a bare integer was read as epoch milliseconds, so `"2026"` meant two seconds after 1970 and matched every later row; send the number, or an ISO instant.
+
+What a caller sees through `POST /api/v1/data/:object/query`, the process in America/New_York, PostgreSQL 16 at `Asia/Shanghai`:
+
+| `where` | memory | SQLite | PostgreSQL | now, on all three |
+|:--|:--|:--|:--|:--|
+| `datetime` `$eq "2026-02-30T10:00:00Z"` | 200, the row stored at `2026-03-02T10:00:00.000Z` | the same | the same | 400 `INVALID_FILTER` |
+| `datetime` `$eq "07/15/2026 10:00"`, `"2026/07/15 10:00"` | 200, the row at `2026-07-15T14:00:00.000Z`, the server process's zone | the same | the same | 400 `INVALID_FILTER` |
+| `date` `$eq "2026-02-30"` | 200 `[]`, compared as text | the same | 500 `DATABASE_ERROR` | 400 `INVALID_FILTER` |
+| `datetime` `$gt "2026"` | 200, every row (read as 2026 epoch milliseconds) | the same | the same | 400 `INVALID_FILTER` |
+| `time` `$gt "+010000-01-01T10:00:00Z"`, rows `09:00` / `10:30` / `12:00` | 200, 3 of 3 (compared as text) | the same | 500 `DATABASE_ERROR` | 400 `INVALID_FILTER` |
+| `time` `$gt` the number of that instant | 200 `[]` | 200, 3 of 3 | 500 `DATABASE_ERROR` | 400 `INVALID_FILTER` |
+
+The refusal names the field and the value, says the filter was not applied, and names the spellings that are read. The rows a non-ISO comparand matched were a property of the deployment host: the same request answered differently on two servers.
+
+**Who is affected.** A caller that filters a `date` or `datetime` field with a string: a REST or SDK client, a saved report or view filter, a dashboard's analytics query (the raw-SQL strategy declines such a comparand, and the engine refuses it), an MCP `query_records` call written by a model. A `{placeholder}` such as `{30_days_ago}`, the empty string, a JS `Date` and an epoch-millisecond number are unchanged.
+
+**Unchanged**, measured identical before and after on memory, SQLite and PostgreSQL:
+
+- a real leap day: `date` `"2028-02-29"`, `datetime` `"2028-02-29T10:00:00Z"`;
+- each ISO spelling above, compared as the same instant whatever the host's zone: `"2026-07-15T14:00:00Z"`, `"2026-07-15T22:00:00+08:00"`, `"2026-07-15 14:00"` (UTC, not the host zone);
+- a `date` comparand with a leading real `YYYY-MM-DD`, still compared as that day (`"2026-07-15T10:00:00Z"` on a `date` is July 15);
+- the same wall clock as a 2026 instant on a `time` column: `$gt "2026-07-15T10:00:00Z"` answers the `10:30` and `12:00` rows, as does its epoch-millisecond number or `Date`;
+- the year range 0001..9999, and every written value (the record validator now asks the same rule it copied, and answers exactly as before).
@@ -106,15 +106,29 @@ describe('[#20240] isUninterpretableTemporalComparand — a date column\'s numbe
     }
   });
 
-  it('leaves the time rule alone — a wall clock has no year', () => {
+  // [#20480] A wall clock has no year, but a `time` column reads a number or a
+  // `Date` as an INSTANT and keeps its UTC time of day — and the rule keeps one
+  // only when the instant's UTC year has a four-digit spelling. Year 0 does
+  // (`0000-…`), so its time of day is read; year 10000, year -1 and the Date
+  // range's extremes do not, and the rule handed them back unchanged — a
+  // number compared with `HH:MM:SS` text. Those are refused now; this pin
+  // asserted all of them read before.
+  it('[#20480] a time column reads the time of day of every instant with a four-digit UTC year, and refuses the rest', () => {
+    const YEAR_0 = new Set(['[#20264] the first millisecond of year 0', '[#20264] the last millisecond of year 0']);
     for (const [name, ms] of [...OUT_OF_RANGE, ...PAST_THE_DATE_RANGE, ...IN_RANGE]) {
-      expect(isUninterpretableTemporalComparand('time', ms), `number, ${name}`).toBe(false);
-      expect(isUninterpretableTemporalComparand('time', new Date(ms)), `Date, ${name}`).toBe(false);
+      const spelled = temporalStorageForm(ms, 'time');
+      const keeps = typeof spelled === 'string' && /^\d{2}:\d{2}:\d{2}(\.\d{3})?$/.test(spelled);
+      const expected = !(IN_RANGE.some(([n]) => n === name) || YEAR_0.has(name));
+      expect(keeps, `the rule keeps a time of day for ${name}`).toBe(!expected);
+      expect(isUninterpretableTemporalComparand('time', ms), `number, ${name}`).toBe(expected);
+      if (Number.isFinite(new Date(ms).getTime())) {
+        expect(isUninterpretableTemporalComparand('time', new Date(ms)), `Date, ${name}`).toBe(expected);
+      }
     }
   });
 
   it('does not judge NaN, ±Infinity or an Invalid Date — they name no instant and no year', () => {
-    for (const kind of ['date', 'datetime'] as const) {
+    for (const kind of ['date', 'datetime', 'time'] as const) {
       for (const value of [Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY, new Date(Number.NaN)]) {
         expect(isUninterpretableTemporalComparand(kind, value), `${kind} ${String(value)}`).toBe(false);
       }
@@ -155,7 +169,8 @@ describe('[#20264] isUninterpretableTemporalComparand — a datetime string outs
     ['year 0099 — inside the range', '0099-03-04T10:00:00.000Z'],
     ['a 2026 instant (the control)', '2026-02-01T10:00:00.000Z'],
     ['a 2026 zone-naive timestamp (the control)', '2026-02-01 10:00'],
-    ['epoch milliseconds for 2026, as a string (the control)', '1769940000000'],
+    // [#20549] The 2026 epoch-millisecond control is a NUMBER now: as a
+    // string it is refused with every other bare integer string (below).
   ];
   it('refuses each, on datetime and on date', () => {
     for (const [name, value] of REFUSED) {
@@ -169,9 +184,156 @@ describe('[#20264] isUninterpretableTemporalComparand — a datetime string outs
     for (const [name, value] of READ) {
       expect(isUninterpretableTemporalComparand('datetime', value), name).toBe(false);
     }
+    expect(isUninterpretableTemporalComparand('datetime', 1769940000000), 'epoch milliseconds for 2026, a number').toBe(false);
   });
   it('a time column judges no year — its rule keeps a time of day', () => {
     expect(isUninterpretableTemporalComparand('time', '0000-06-15T10:00:00.000Z')).toBe(false);
     expect(isUninterpretableTemporalComparand('time', '10:00')).toBe(false);
   });
 });
+
+// [#20549] The write door (the record validator) refuses a string whose
+// leading `YYYY-MM-DD` names a day that does not exist, and a `datetime`
+// string outside the ISO 8601 spellings the platform writes. The comparand
+// door was wider: measured under TZ=America/New_York on driver-memory, SQLite
+// and PostgreSQL 16, `datetime $eq "2026-02-30T10:00:00Z"` matched the row
+// stored at 2026-03-02T10:00Z (rolled over), `"07/15/2026 10:00"` matched
+// 2026-07-15T14:00Z (the process zone), and `date $eq "2026-02-30"` answered
+// 200 [] on memory and SQLite and 500 on PostgreSQL. The two predicates moved
+// here from the validator, which now asks this function, so one rule answers
+// both doors.
+describe('[#20549] isUninterpretableTemporalComparand — a real calendar day, and an ISO spelling for a datetime', () => {
+  const IMPOSSIBLE_DAYS = ['2026-02-30', '2026-02-29', '2026-04-31', '2026-13-01', '2026-00-10', '2026-06-00', '2100-02-29'];
+
+  it('refuses a leading day that does not exist — on a date, and as the day part of a datetime', () => {
+    for (const day of IMPOSSIBLE_DAYS) {
+      expect(isUninterpretableTemporalComparand('date', day), `date ${day}`).toBe(true);
+      expect(isUninterpretableTemporalComparand('date', `${day}T10:00:00Z`), `date ${day}T10:00:00Z`).toBe(true);
+      expect(isUninterpretableTemporalComparand('datetime', day), `datetime ${day}`).toBe(true);
+      expect(isUninterpretableTemporalComparand('datetime', `${day}T10:00:00Z`), `datetime ${day}T10:00:00Z`).toBe(true);
+      expect(isUninterpretableTemporalComparand('datetime', `${day} 10:00`), `datetime ${day} 10:00`).toBe(true);
+    }
+  });
+
+  it('reads every real day beside them — the leap days and the month ends, the discriminating half', () => {
+    for (const day of ['2028-02-29', '2000-02-29', '2026-02-28', '2026-04-30', '2026-12-31', '0004-02-29', '2026-01-01']) {
+      expect(isUninterpretableTemporalComparand('date', day), `date ${day}`).toBe(false);
+      expect(isUninterpretableTemporalComparand('datetime', day), `datetime ${day}`).toBe(false);
+      expect(isUninterpretableTemporalComparand('datetime', `${day}T10:00:00Z`), `datetime ${day}T10:00:00Z`).toBe(false);
+    }
+  });
+
+  it('refuses a datetime string outside the ISO spellings — each one Date.parse reads', () => {
+    const NOT_ISO = [
+      '07/15/2026 10:00', '2026/07/15 10:00', '15 July 2026 10:00', '07/08/2026',
+      'Wed, 15 Jul 2026 10:00:00 GMT', '2026-07-15 10:00 PM', '2026-07-15t10:00:00z',
+      '2026-07-15 10:00:00+08:00', '2026-07-15 10:00Z', '+002026-07-15T10:00:00Z', '2026-07', '2026-7-15',
+      // A bare integer string: epoch milliseconds to the rule, a year to its author.
+      '2026', '1769940000000', '-1',
+    ];
+    for (const value of NOT_ISO) {
+      expect(Number.isFinite(Date.parse(value)) || /^-?\d+$/.test(value), `the control: ${value} is read by someone`).toBe(true);
+      expect(isUninterpretableTemporalComparand('datetime', value), value).toBe(true);
+    }
+  });
+
+  it('reads each ISO spelling the write door writes, the same instant in every host zone — the discriminating half', () => {
+    const ISO = [
+      '2026-07-15', '2026-07-15T10:00', '2026-07-15T10:00:00', '2026-07-15T10:00:00.123',
+      '2026-07-15T10:00:00Z', '2026-07-15T10:00:00.000Z', '2026-07-15T10:00:00.123456Z',
+      '2026-07-15T18:00:00+08:00', '2026-07-15T18:00:00+0800', '2026-07-15T05:00:00-05:00',
+      '2026-07-15 10:00', '2026-07-15 10:00:00', '2026-07-15 10:00:00.5', '  2026-07-15T10:00:00Z  ',
+    ];
+    for (const value of ISO) {
+      expect(isUninterpretableTemporalComparand('datetime', value), value).toBe(false);
+    }
+  });
+
+  it('still refuses what the grammar admits but no clock reads', () => {
+    for (const value of ['2026-07-15T25:00:00Z', '2026-07-15T10:60:00Z', '2026-07-15T10:00:00+99:99']) {
+      expect(isUninterpretableTemporalComparand('datetime', value), value).toBe(true);
+    }
+  });
+
+  it('leaves a date column\'s own reading alone: a real leading day, whatever follows it', () => {
+    // The `date` rule collapses a leading day, so an instant on a real day is
+    // that day (#20481); only the day's existence is new.
+    for (const value of ['2026-07-15T10:00:00Z', '2026-07-15 10:00', '2026-07-15T10:00:00+08:00']) {
+      expect(isUninterpretableTemporalComparand('date', value), value).toBe(false);
+    }
+    expect(isUninterpretableTemporalComparand('date', '2026/07/15'), 'the #20481 shape, as before').toBe(true);
+  });
+
+  it('an instant on a time column is read by the datetime rule, so the same two classes are refused there', () => {
+    for (const value of ['07/15/2026 10:00', '2026/07/15 10:00', '2026-02-30T10:00:00Z', '1784109600000', 'Wed, 15 Jul 2026 10:00:00 GMT']) {
+      expect(isUninterpretableTemporalComparand('time', value), value).toBe(true);
+    }
+    // The wall clocks and the ISO instants beside them — the discriminating half.
+    for (const value of ['10:00', '10:00:00', '10:00:00.5', '2026-07-15T10:00:00Z', '2026-07-15T18:00:00+08:00', '2026-07-15 10:00']) {
+      expect(isUninterpretableTemporalComparand('time', value), value).toBe(false);
+    }
+    expect(isUninterpretableTemporalComparand('time', Date.UTC(2026, 6, 15, 10)), 'epoch milliseconds as a number').toBe(false);
+  });
+
+  it('keeps the comparand-only exemptions and the non-string readings', () => {
+    for (const kind of ['date', 'datetime'] as const) {
+      expect(isUninterpretableTemporalComparand(kind, ''), `${kind} empty`).toBe(false);
+      expect(isUninterpretableTemporalComparand(kind, '   '), `${kind} blank`).toBe(false);
+      expect(isUninterpretableTemporalComparand(kind, '{today}'), `${kind} placeholder`).toBe(false);
+      expect(isUninterpretableTemporalComparand(kind, 1769940000000), `${kind} epoch-ms number`).toBe(false);
+      expect(isUninterpretableTemporalComparand(kind, new Date(Date.UTC(2026, 1, 28))), `${kind} Date`).toBe(false);
+    }
+  });
+});
+
+// [#20480] The `time` half of the one temporal rule. A `time` comparand that
+// is not a bare wall clock is read as an INSTANT by the `datetime` rule and
+// keeps its UTC time of day — only when that instant's UTC year has a
+// four-digit spelling. `+010000-01-01T10:00:00Z` passed this door (`Date.parse`
+// reads it) and came back from the rule unchanged, so the driver compared it
+// as text: `$gt` answered 3 of 3 rows on memory and SQLite, and PostgreSQL
+// answered 500. The same instant spelled with four digits in its own zone
+// (`9999-12-31T23:00:00-02:00`), as a number or as a `Date` answered 0 or 3
+// by driver. Every spelling is refused now; no time of day is read from an
+// extended year.
+describe('[#20480] isUninterpretableTemporalComparand — a time column\'s instant outside the four-digit years', () => {
+  const Y10000_10 = Date.parse('+010000-01-01T10:00:00Z');
+  const YNEG1_10 = Date.parse('-000001-01-01T10:00:00Z');
+
+  it('refuses the card\'s spelling and every other spelling of an instant the rule keeps no time of day for', () => {
+    for (const value of [
+      '+010000-01-01T10:00:00Z',          // the card's comparand
+      '-000001-01-01T10:00:00Z',
+      '9999-12-31T23:00:00-02:00',        // year 10000 in UTC
+    ]) {
+      expect(isUninterpretableTemporalComparand('time', value), value).toBe(true);
+    }
+    for (const value of [Y10000_10, YNEG1_10, new Date(Y10000_10), new Date(YNEG1_10), 8.64e15, -8.64e15, 8.64e15 + 1]) {
+      expect(isUninterpretableTemporalComparand('time', value), String(value)).toBe(true);
+    }
+  });
+
+  it('reads the time of day of the same wall clock in a four-digit year — the 2026 control and the year edges', () => {
+    for (const value of [
+      '2026-01-01T10:00:00Z', '2026-01-01T10:00:00.000Z', '2026-01-01T18:00:00+08:00',
+      '9999-12-31T10:00:00Z', '0001-01-01T10:00:00Z', '0000-06-15T10:00:00.000Z',
+      Date.parse('2026-01-01T10:00:00Z'), new Date(Date.parse('2026-01-01T10:00:00Z')),
+      Date.parse('0000-06-15T10:00:00Z'), new Date(Date.parse('9999-12-31T23:59:59.999Z')),
+    ]) {
+      expect(isUninterpretableTemporalComparand('time', value), String(value)).toBe(false);
+      expect(temporalStorageForm(value, 'time'), `the rule keeps a time of day for ${String(value)}`).toMatch(/^\d{2}:\d{2}:\d{2}(\.\d{3})?$/);
+    }
+    for (const value of ['10:00', '10:00:00', '23:59:59.999']) {
+      expect(isUninterpretableTemporalComparand('time', value), value).toBe(false);
+    }
+  });
+
+  it('agrees with the rule: an instant is refused on a time column exactly when the rule hands it back unchanged', () => {
+    for (const value of [
+      '+010000-01-01T10:00:00Z', '9999-12-31T23:00:00-02:00', '2026-01-01T10:00:00Z', '0000-06-15T10:00:00.000Z',
+      Y10000_10, YNEG1_10, Date.parse('2026-01-01T10:00:00Z'), 8.64e15, 8.64e15 + 1, -8.64e15,
+    ]) {
+      expect(isUninterpretableTemporalComparand('time', value), String(value)).toBe(temporalStorageForm(value, 'time') === value);
+    }
+  });
+});