fix(core,objectql)!: a temporal comparand is refused exactly when the write door refuses it — a real calendar day, an ISO datetime spelling, and a time instant with a four-digit UTC year

[objectstack-fleet]

Fixes #20549
Fixes #20480

Clause-②: no (narrowing)

A family PR: two cards, one branch, one changeset, one commit per card.

• 70b98719c is temporal comparand door admits what the write door now refuses: an impossible day (2026-02-30) is rolled over as a datetime comparand and is a 500 on PostgreSQL as a date comparand, and a non-ISO datetime comparand is read in the host zone #20549. The temporal comparand door now refuses what the write door refuses: a calendar day that does not exist, and a datetime string outside the ISO 8601 spellings the platform writes.
• 0adb1bf84 is core temporal rule: a time comparand spelled with an extended-ISO year (+010000-01-01T10:00:00Z) is compared as text on memory and SQLite: $gt answers 3 of 3 rows, $lt 0, where the same wall clock as a 2026 instant answers 2 / 1 #20480. A time comparand whose instant has no four-digit UTC year is refused, in every spelling.

Measured head: 0adb1bf84, rebased onto origin/main 19fc8d6f1. The two commits since main touch no file that main moved.

The change

@objectstack/core — packages/core/src/utils/temporal-comparand.ts

• Moved, not copied. ISO_DATETIME_WRITE_FORM and namesRealCalendarDay leave record-validator.ts and sit beside readsAsCalendarDay. Both stay module-private, so there is no new root export.

• readsAsCalendarDay (the date reading) now also requires the leading day to exist.

• readsAsInstant (the datetime reading, which a time column also uses for an instant) now requires three things:

  • one of the ISO spellings;
  • a real leading day;
  • an instant that Date.parse reads.

  The bare-integer-string arm is gone (see H3). Epoch milliseconds as a NUMBER are untouched.

• (core temporal rule: a time comparand spelled with an extended-ISO year (+010000-01-01T10:00:00Z) is compared as text on memory and SQLite: $gt answers 3 of 3 rows, $lt 0, where the same wall clock as a 2026 instant answers 2 / 1 #20480) There is a new private helper, keepsTimeOfDay(value). It asks temporalStorageForm(value, 'time') itself whether the rule keeps an HH:MM:SS time of day. The time arm now refuses an instant string the rule hands back unchanged. So does a finite number or a valid Date, which the time arm never judged before.

  • Year 0 spells 0000-…, so it is still read.
  • NaN, Infinity and an Invalid Date stay unjudged.

@objectstack/objectql

• validation/record-validator.ts (the write door). The date / datetime arm is now readable && !isUninterpretableTemporalComparand(t, value).

  • Its private copies are deleted.
  • readable stays on top. It is the one place the two doors differ, on purpose: a NUMBER is refused as a written value but read as a comparand.
  • The time arm is not in the diff.

• temporal-comparand-door.ts. The verdict is unchanged: core's predicate, INVALID_FILTER / 400, naming the field, before any read. The refusal text changes only as far as the new classes need, because "compare false for EVERY row" is untrue for them:

  • whose calendar day does not exist;
  • not one of the ISO 8601 spellings;
  • (core temporal rule: a time comparand spelled with an extended-ISO year (+010000-01-01T10:00:00Z) is compared as text on memory and SQLite: $gt answers 3 of 3 rows, $lt 0, where the same wall clock as a 2026 instant answers 2 / 1 #20480) an instant whose UTC year falls outside the years 0001 to 9999, so no time of day is read from it.

  Each has a where and a having sentence. The remedy now says "on a calendar day that exists" and "epoch milliseconds as a number". The junk class and the year class keep their exact words.

Measured, before and after

Through engine.find over InMemoryDriver, SqlDriver on SQLite, and SqlDriver on a live PostgreSQL 16.13. The process ran under TZ=America/New_York, and the server at Asia/Shanghai. Base is cd901d7a5; after is 0adb1bf84. Rows are r1 2026-03-02T10:00Z / 09:00, r2 2026-07-15T14:00Z / 10:30, and r3 2028-02-29T10:00Z / 12:00.

comparand	base: memory / SQLite / PostgreSQL	after, all three
datetime $eq "2026-02-30T10:00:00Z"	[r1] (rolled over) / [r1] / [r1]	400 INVALID_FILTER
datetime $eq "07/15/2026 10:00", "2026/07/15 10:00"	[r2] (process zone) / [r2] / [r2]	400
date $eq "2026-02-30"	[] / [] / 500 DATABASE_ERROR	400
time $gt "+010000-01-01T10:00:00Z" (the #20480 card)	3 of 3 / 3 of 3 / 500	400
time $lt the same	[] / [] / 500	400
time $gt "9999-12-31T23:00:00-02:00" (UTC year 10000)	[] / [] / 500	400
time $gt the number or Date of +010000-01-01T10:00Z	[] / 3 of 3 / 500	400
time $gt "07/15/2026 10:00"	[] (14:00 UTC, the process zone)	400
datetime $gt "2026"	every row (read as 2026 epoch ms)	400
datetime $gt 1769940000000 (a number)	3 of 3	unchanged, 3 of 3
controls: leap day 2028-02-29 on date and datetime; ISO Z, +08:00 and zone-naive "2026-07-15 14:00"; time $gt / $lt "2026-07-15T10:00:00Z"; time $gt "10:00"	[r3], [r3], [r2]×3, [r2,r3] / [r1], [r2,r3]	identical

After commit 1 alone, the #20480 card's literal row already read 400 on all three, because it is not an ISO spelling. The UTC-year-10000 ISO spelling and the number and Date spellings still answered as at base. The second commit closes those (see H1).

PM hypotheses — which held

• H1: partly held. Tightening readsAsInstant to the ISO form refuses the card's +010000-… spelling as a side effect (measured after commit 1). It does not close the class: 9999-12-31T23:00:00-02:00 is an ISO spelling whose UTC year is 10000, and the number and Date never reached the string arm. So time needs its own arm, which is commit 2.
• H2: held. The validator calls core's one predicate for both arms and deletes its copies. No root export was added: export * from temporal-comparand.ts exposes exactly the three symbols it did before. Clause-② stays no (narrowing).
• H3: measured. One legitimate difference is kept, and one is removed.
  • An epoch-ms NUMBER is refused by the write door (readable) and read as a comparand. This predates this PR, is scoped by the An unparseable date comparand on a datetime filter is passed through and compares false — HTTP 200, zero rows, no diagnostic — while an unknown {placeholder} is correctly rejected 400 (17.0.0 GA) #8690 ruling (strings only), and is now asserted in engine-temporal-comparand-door.test.ts.
  • A zone-naive ISO string is admitted by both doors, so there is no divergence.
  • An epoch-ms STRING is refused by the write door. The comparand door read it, and two earlier suites pinned it as a control. I found no producer: the token resolver and the analytics date range emit ISO text, and no test in the repo filters with one. The same arm read "2026" as two seconds after 1970, and matched every row on all three backends. Zone 1's direction ("the comparand door refuses what the write door refuses") and the claim's "datetime: only the ISO 8601 spelling the write door admits" therefore cover it, and it is refused. The two pins are flipped, with load-bearing assertions (below). Because earlier cards pinned it, this is raised in the report as an open question rather than decided silently.
  • A date string with a real leading day and text Date.parse cannot read after it (2026-07-15T25:00) is refused by the write door. It is read by the comparand door as its day, the record validator: a date field written as a non-ISO string ("2026/07/15") answers 201 and is stored verbatim as "2026/07/15", a non-day, on memory and SQLite, because the date arm admits any Date.parse-readable string #20481 shape. This predates this PR and is outside both cards' classes, so it is left as is (Acceptance notes).
• H4: held. service-analytics/src/comparand-shape.ts is not edited. Its judgeTemporalLiterals calls core's predicate, so the raw-SQL decline moves with it. The whole suite is green on 0adb1bf84: 135 files, 3171 tests, under TZ=America/New_York. No pin flipped.
• H5: nothing to carry. Core's namesRealCalendarDay stays private, so there is still nothing for packages/rest/src/import-coerce.ts to read in place of its own copy.

Compile faces — one conclusion each

The door is the engine's single filter collection point, in front of every driver. The pins show zero driver reads on every refusal: a recording driver in objectql, and the REST door over SQLite and PostgreSQL.

1. driver-sql applyFilterCondition, with driver-sqlite-wasm and turso LOCAL: already compliant, behind the door. Measured: the refusal happens before any read on SQLite and PostgreSQL. The driver's deliberate pass-through (temporalFilterValue('t','at','not-a-date')) is unchanged.
2. turso RemoteTransport.buildWhereSQL: already compliant, behind the same door. Not measured, because no turso server was available.
3. service-analytics compileScopedFilterToSql (RLS read side): explicitly out of scope. It compiles the platform's injected RLS predicate, which the door never judges by design (the door's docblock: "an injected read filter is the platform's own").
4. service-analytics lowerAnalyticsWhere: changed by inheritance. A comparand core now refuses is declined off the raw-SQL strategy to the ObjectQL strategy, whose engine.aggregate passes the door. The suite is green, as in H4.
5. formula matchesFilterCondition: explicitly out of scope. It evaluates authored RLS check predicates and formula conditions, not a caller's where. Its own 2026-02-30 text-fallback pin (matches-filter.test.ts:180) is unchanged.

• Half face, objectql applyHaving / matchesHaving: changed. assertHavingTemporalComparandsInterpretable runs the same predicate. It is pinned in engine-temporal-comparand-door.test.ts (temporal comparand door admits what the write door now refuses: an impossible day (2026-02-30) is rolled over as a datetime comparand and is a 500 on PostgreSQL as a date comparand, and a non-ISO datetime comparand is read in the host zone #20549 and core temporal rule: a time comparand spelled with an extended-ISO year (+010000-01-01T10:00:00Z) is compared as text on memory and SQLite: $gt answers 3 of 3 rows, $lt 0, where the same wall clock as a 2026 instant answers 2 / 1 #20480 having rows) and engine-aggregate-having-temporal-door.test.ts (core temporal rule: a time comparand spelled with an extended-ISO year (+010000-01-01T10:00:00Z) is compared as text on memory and SQLite: $gt answers 3 of 3 rows, $lt 0, where the same wall clock as a 2026 instant answers 2 / 1 #20480 rows, plus the parity table computed from the predicate).
• Per-aggregation filter: changed, and pinned in the same two files and in engine-aggregate-temporal-storage-rule.test.ts.
• driver-memory checkCondition: behind the door. Measured: the engine over InMemoryDriver refuses every row above. The driver's admitted-controls half is pinned.
• driver-mongodb translateFieldOperators: behind the door, not measured, because no MongoDB was available.

Pins

#20549 (commit 1):

• core temporal-comparand.test.ts, a new describe:
  • impossible days on date and datetime (plus the datetime day part) are refused, and leap days and month ends are read;
  • 15 non-ISO datetime spellings are refused, each shown Date.parse-readable (or a bare integer) as the control;
  • 14 ISO spellings are read;
  • T25:00 and +99:99 are refused;
  • the date reading of an instant on a real day is kept;
  • the time instant half is covered;
  • the exemptions (empty string, blank, {today}, an epoch-ms number, a Date) are kept.
• objectql engine-temporal-comparand-door.test.ts, a new describe:
  • 14 comparands × $eq / $gt / $in member → INVALID_FILTER / 400 naming the field, with zero reads, and not the junk class's words;
  • the leap day and ISO controls in the same it;
  • the per-aggregation filter and having positions;
  • a one-rule corpus pin: over 32 strings × 2 fields, a string is refused as a comparand exactly when engine.insert refuses it with invalid_date;
  • the number difference, asserted.
• rest data-temporal-write-real-day-iso.test.ts, beside the write door's twin rows: POST /api/v1/data/:object/query answers 400 INVALID_FILTER for the card's values with no read, and the leap and ISO controls find their rows, on SQLite and on live PostgreSQL.
• Driver halves:
  • sql-driver-20264-temporal-year-range.test.ts gains a leap row and an it over 7 ISO spellings, on the dialect matrix CI's Temporal Conformance (live PG + MySQL) job runs;
  • memory-20525-temporal-write-real-day-iso.test.ts gains comparand controls under America/New_York.

#20480 (commit 2):

• core: a new describe covers the card's spelling, UTC year 10000 and year -1, numbers and Dates, and the Date-range extremes, all refused. The 2026 control and year 0 are read. An agreement pin: refused exactly when temporalStorageForm(v, 'time') === v.
• objectql engine-temporal-comparand-door.test.ts: five spellings × $gt / $lt / $eq at where, plus the per-aggregation filter and having, with zero reads, beside the 2026 control and year 0.
• engine-aggregate-having-temporal-door.test.ts: two refused rows, and two 2026 controls on max(time).
• rest: a time field on SQLite and live PostgreSQL. The card's instant, the UTC-10000 ISO spelling and the number answer 400, with no read. The 2026 instant, the offset and the number answer 2 / 1.
• Drivers:
  • sql-driver-time-live-dialects.test.ts gains the 2026 control in five spellings, on live PostgreSQL and MySQL (CI's temporal job);
  • memory-temporal-storage-form.test.ts gains four 2026 control rows.

Flipped pins, one round (sweep ①). Each keeps a load-bearing assertion of the new semantics:

• core temporal-comparand.test.ts: the temporal values outside the years a four-digit text or a backend holds: a datetime comparand for year 10000 or −1 misorders on memory/SQLite and 500s on PostgreSQL; a date in year 0000 500s on PostgreSQL; a date write stores +010000-… verbatim #20264 control '1769940000000' (string) moves to the number 1769940000000, read. The string is refused in the temporal comparand door admits what the write door now refuses: an impossible day (2026-02-30) is rolled over as a datetime comparand and is a 500 on PostgreSQL as a date comparand, and a non-ISO datetime comparand is read in the host zone #20549 describe. The core temporalStorageForm: the date arm leaves a year outside 1000..9999 unpadded — over REST the epoch-ms number for 0999-06-15 counts $gt 0 / $lt 7 on InMemoryDriver and SQLite (correct 6 / 0); its ISO string counts 6 / 0 #20240 "leaves the time rule alone" test becomes a per-value verdict: year 0 and in-range are read; years 10000 / -1 and the Date extremes are refused, with the rule's own output asserted.
• objectql engine-aggregate-temporal-storage-rule.test.ts: the family row "an epoch-ms string $gt on a datetime counts 3" is now INVALID_FILTER / 400 at both positions, for "1769940000000" and "2026". The number of the same instant still counts 3.
• objectql engine-temporal-year-range.test.ts: "a time field judges no year" becomes year 0 read (three spellings, three reads) and years 10000 / -1 refused (five spellings), with no further read.
• objectql engine-date-year-range-door.test.ts: the time half becomes year 0 read (two reads) and 10000 / -1 refused.
• objectql engine-aggregate-having-temporal-door.test.ts: "the number for 10000-01-01 on max(time) — not judged on time" moves from the unchanged table to the refused table (INVALID_FILTER / 400, no read, and the where twin agrees).

The repo-wide sweep found no other same-semantic pin, re-run on 0adb1bf84. It covered quoted 4–14 digit strings under a filter operator on a temporal field, slashed or worded datetime comparands, and extended-year comparands on time fields, over every *.test.ts. Truly illegal shapes keep their refusal assertions verbatim.

Verification, on 0adb1bf84

Every suite below ran under TZ=America/New_York. PostgreSQL cells ran against a live PostgreSQL 16.13 at Asia/Shanghai.

• pnpm --filter @objectstack/core test: 57 files / 1536 tests passed.
• @objectstack/objectql, whole suite: 336 files / 6674 tests passed.
• @objectstack/rest, whole suite with live PostgreSQL: 228 files, 4422 passed / 22 skipped. The changed file ran verbosely, and both the sqlite and live postgres cells executed every temporal comparand door admits what the write door now refuses: an impossible day (2026-02-30) is rolled over as a datetime comparand and is a 500 on PostgreSQL as a date comparand, and a non-ISO datetime comparand is read in the host zone #20549 and core temporal rule: a time comparand spelled with an extended-ISO year (+010000-01-01T10:00:00Z) is compared as text on memory and SQLite: $gt answers 3 of 3 rows, $lt 0, where the same wall clock as a 2026 instant answers 2 / 1 #20480 it.
• @objectstack/driver-memory test: 62 files / 1436 passed.
• @objectstack/driver-sql test with live PostgreSQL: 208 files passed / 3 skipped, 4023 tests passed / 95 skipped. The two changed files ran verbosely: the SQLite and live-postgres cells ran; MySQL is a named skip.
• @objectstack/service-analytics: 135 files / 3171 passed.
• typecheck passed for all five: core, objectql, rest, driver-memory and driver-sql (the test layers included, with their test-typecheck-debt.json ledgers unchanged).
• pnpm check:driver-conformance, before (19fc8d6f1) and after (0adb1bf84): identical, 50 covered cells, 0 DEBT, 0 exempt, dialect axis 10 of 10.
• node scripts/pm/dispatch-gates.mjs --commands on the final head derived 67 commands. All 67 ran with exit 0.
  • check:dual-build-cjs-loads and check:type-check-debt first exited 3 (PREREQUISITE NOT MET, no workspace dist/). They were re-run with exit 0 after turbo run build --filter='./packages/*' --filter='./packages/*/*'.
  • --ran over the recorded exit codes: "67 derived famil(ies) accounted for — 67 run, 0 NOT-MEASURED (a DERIVED zero)".
  • The five artifact-roster gates whose rosters sit under a changed directory also ran, exit 0: check-changeset-fixed, check:authz-resolver, check:filter-alias-parity, check:object-def-param-keys and check:tenant-chokepoint.
• Lint, narrowed and declared (the repo-wide pnpm lint is CI's). eslint --no-inline-config --format json over the 14 changed .ts files: 14 files, 0 errors, 0 warnings.
  • Population: eslint.config.mjs's **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} / packages/** objects cover all 14.
  • Invariance: the config never enables type-aware linting (no parserOptions.project, no typed rules), so this diff cannot move a verdict on an untouched file.
• Ablation, two legs each, through scripts/ablation-replace.mjs and scripts/ablation-dist-preflight.mjs, with a trap restore. Each restore was proven: blob == HEAD, and a clean git status --porcelain.
  • A (temporal comparand door admits what the write door now refuses: an impossible day (2026-02-30) is rolled over as a datetime comparand and is a 500 on PostgreSQL as a date comparand, and a non-ISO datetime comparand is read in the host zone #20549). The readsAsInstant ISO / real-day guard was deleted: anchor 1 → 0, and the marker was absent from packages/core/dist. Core's predicate suite went 3 failed / 23, and the objectql door suite went 2 failed / 14 (the refusal and the aggregation/having tests). The corpus agreement pin stayed green, correctly, because both doors moved together. Restored and rebuilt, the marker is present in 2 dist files, and 23/23 and 14/14 pass.
  • B (core temporal rule: a time comparand spelled with an extended-ISO year (+010000-01-01T10:00:00Z) is compared as text on memory and SQLite: $gt answers 3 of 3 rows, $lt 0, where the same wall clock as a 2026 instant answers 2 / 1 #20480). The time arm's non-string verdict was replaced with return false: the marker was present in dist before, and absent after. Core went 3 failed / 23; four objectql files went 4 failed / 82. Restored and rebuilt, the marker is present, and 82/82 pass.

NOT MEASURED:

• MySQL cells: not provisioned in this container. They run in CI's Temporal Conformance (live PG + MySQL) job, in sql-driver-time-live-dialects.test.ts and sql-driver-20264-temporal-year-range.test.ts.
• turso remote and MongoDB: no server.
• The PostgreSQL cells in packages/rest ran locally, but no CI job provisions PostgreSQL for that package. CI's PostgreSQL coverage of this card is the driver-sql half above.

Acceptance notes (not filed)

• A date comparand with a real leading day and unreadable trailing text ("2026-07-15T25:00") is read as its day. The write door refuses the same string through Date.parse. This predates this PR and is outside both cards' classes.
• The time year class's wording is chosen by core's isOutsideTemporalYearRange on the instant. For a year-0 instant in a non-ISO spelling on a time column (refused for its spelling), the message would name the year class instead. The verdict is right; the edge is theoretical.
• The in-flight spec lane branch for [finding] nextUtcCalendarDay('9999-12-31') answers '10000-01-01', so on SQLite a datetime $lte '9999-12-31' or a $between maximum on that day answers no rows #20600 (datetime.ts, having-filter.ts, matches-filter.ts) has not landed, and no file here overlaps it.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

16 anchor(s) derived from 2 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 5 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 33 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 6bff748bbd484f00906c8d9a58f5a3621a20c2e6 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 81a8ee3b4d4aabc72b3eb6cbd00e95f73fc95af5 — the merge of head 0adb1bf84e39d365124b3ac710470808ee9ce4e7 into base 6bff748bbd484f00906c8d9a58f5a3621a20c2e6, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 81a8ee3b4d4aabc72b3eb6cbd00e95f73fc95af5 && git checkout 81a8ee3b4d4aabc72b3eb6cbd00e95f73fc95af5
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 6bff748bbd484f00906c8d9a58f5a3621a20c2e6 0adb1bf84e39d365124b3ac710470808ee9ce4e7 && git checkout -B drift-repro 6bff748bbd484f00906c8d9a58f5a3621a20c2e6 && git merge --no-ff 0adb1bf84e39d365124b3ac710470808ee9ce4e7

node scripts/docs-audit/affected-docs.mjs --json 6bff748bbd484f00906c8d9a58f5a3621a20c2e6

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 0adb1bf84e39d365124b3ac710470808ee9ce4e7
Local-runs: none

Inputs read: cards #20549 and #20480 (bodies and every comment, the triage rulings, the claims, the os-dev-report and the seat answer 5894035143 included); PR #20668's body, its 15-file list and the net diff of refs/review/20668 against origin/main (merge-base 19fc8d6f1; origin/main has since moved to 6c11ef9ecb, and none of the 15 files, nor packages/core/src/utils/, packages/objectql/src/ or service-analytics/src/comparand-shape.ts, moved with it); and the head's check-runs. Where a claim is about origin/main, I read the file there with git show.

① Derived judgments

Accept-set changes the diff implies — each judged right.

1. date string comparand: a leading YYYY-MM-DD must now name a real day (readsAsCalendarDay is namesRealCalendarDay). Right — it is the write door's own predicate (record validator: the temporal write arms trust Date.parse — date 2026-02-30 is stored verbatim (500 on PostgreSQL), datetime 2026-02-30T10:00:00Z rolls over to March 2, and a non-ISO datetime is read in the host zone #20525), moved not copied: the two private functions are deleted from record-validator.ts and reappear byte-equal in core, module-private. Pinned in core (7 impossible days, 7 real days including 0004-02-29 and 2000-02-29) and at the engine.
2. datetime string comparand: only an ISO_DATETIME_WRITE_FORM spelling on a real day that Date.parse reads; the bare-integer-string arm of readsAsInstant is deleted. Right by the governing text (triage 5883337906: "the comparand door refuses what the write door refuses"; the claim's "datetime: only the ISO 8601 spelling the write door admits"). On origin/main the write door already refused every bare integer string and every non-ISO spelling, so the narrowing is exactly the write door's set. Epoch milliseconds as a NUMBER are untouched on date/datetime (the pre-existing year-range judgement only), and the corpus pin (32 strings x 2 fields, refused as a comparand iff engine.insert answers invalid_date) holds the two doors to one rule.
3. time column, string comparand (temporal comparand door admits what the write door now refuses: an impossible day (2026-02-30) is rolled over as a datetime comparand and is a 500 on PostgreSQL as a date comparand, and a non-ISO datetime comparand is read in the host zone #20549 commit, an alongside narrowing): a non-wall-clock string is read through the same readsAsInstant, so a non-ISO or impossible-day instant is refused on time too. Judged right, see ③ item 2.
4. time column, every spelling (core temporal rule: a time comparand spelled with an extended-ISO year (+010000-01-01T10:00:00Z) is compared as text on memory and SQLite: $gt answers 3 of 3 rows, $lt 0, where the same wall clock as a 2026 instant answers 2 / 1 #20480): a finite number, a valid Date or an ISO instant string is refused when temporalStorageForm(v, 'time') hands it back unchanged (keepsTimeOfDay). Right — on origin/main canonicalTimeOfDay keeps a time of day only from an instant whose toISOString() spells YYYY-, so the predicate asks the rule rather than copying its year arithmetic; year 0 spells 0000- and stays read (pinned three ways); NaN/Infinity/Invalid Date stay unjudged. 9999-12-31T23:00:00-02:00 is UTC year 10000, as the changeset says. The card's +010000-01-01T10:00:00Z would already have fallen to item 2 alone, which is why the second arm was needed for the number, the Date and the offset spelling (H1 partly held, correctly reported).
5. Write door (record-validator.ts date/datetime arm): readable && !isUninterpretableTemporalComparand(t, value). Judged equivalent to the old four-term guard on every input: for a string, old = Date.parse(raw) finite AND ISO form (trimmed) AND real day AND year in range; new = the same three plus Date.parse of the same string after the rule's own ISO normalisation, which cannot flip a string Date.parse already read. The rule's two comparand-only exemptions (blank, {token}) are stopped by readable as before; a NUMBER stays refused by readable — the one deliberate difference between the doors, now asserted. The changeset's "every written value answers exactly as before" is true. The time arm is untouched (verified: not in the diff).
6. Refusal prose (temporal-comparand-door.ts): three misread classes on where and having, ordered year class, then misread, then junk. Each sentence judged true for every hit it can be shown on: the impossible-day class only fires when the leading day is refused and its year is in range; the not-ISO class only when Date.parse reads the string or it is a bare integer (so "the server's own parser decides the instant" is what did happen); the time year class only when core's isOutsideTemporalYearRange on the instant says so, and year 0 on time is never a hit, so "outside the years 0001 to 9999, so no time of day is read from it" never misstates. The datetime remedy now says "on a calendar day that exists" and "epoch milliseconds as a number"; both true. The junk class keeps its exact words (pinned by not.toContain('compare false for EVERY row') on the new classes).
7. Public surface: packages/core/src/index.ts does export * from temporal-comparand.ts, whose exports are the same three symbols on origin/main and on the head (TemporalComparandKind, temporalComparandKind, isUninterpretableTemporalComparand, unchanged signatures). The door module is not re-exported from objectql's root; its four exports and the UninterpretableTemporalComparand members are unchanged; record-validator.ts loses only private symbols. No new root export, no signature change.

Compile faces — one conclusion each, and each checked. All eight faces the dispatch named carry a conclusion in the PR body.

• driver-sql applyFilterCondition (with sqlite-wasm and turso local): behind the door — right; the engine runs assertTemporalComparandsInterpretable before any driver read, pinned by the recording driver (zero reads) and the REST door over SQLite and PostgreSQL.
• turso RemoteTransport.buildWhereSQL: it exists here (packages/drivers/driver-turso/src/remote-transport.ts:1168) and is reached through TursoDriver behind the same door; "already compliant, not measured" holds.
• service-analytics compileScopedFilterToSql: out of scope — right; it compiles the injected RLS predicate, which the door's docblock on origin/main (lines 388-389: "an injected read filter is the platform's own") excludes by design.
• service-analytics lowerAnalyticsWhere: changed by inheritance — right; NativeSQLStrategy.canHandle (native-sql-strategy.ts:297) calls findUninterpretableTemporalMember, whose judgeTemporalLiterals (comparand-shape.ts:473) calls core's predicate, so the decline moves without an edit there (H4).
• formula matchesFilterCondition: out of scope — right; it evaluates authored RLS check predicates, and its own impossible-day text-fallback pin ("an impossible day is not rolled over", matches-filter.test.ts ~line 180) is on origin/main and not in the diff.
• objectql having-filter (applyHaving/matchesHaving): changed — right; assertHavingTemporalComparandsInterpretable runs at engine.ts:16488 ahead of them and gained the misread branch; pinned in two files.
• driver-memory checkCondition: behind the door, measured — right.
• driver-mongodb translateFieldOperators: behind the door, not measured — acceptable (see ③ item 5).

Producer sweep. I searched non-test source on origin/main for a temporal where built from Date.now()/getTime() as a string or from toLocale*String(): none. filter-tokens.ts emits toISOString() text. The five flipped pins are the only in-repo readers of the retired spellings, and each keeps a load-bearing assertion of the refusal (code and status, no read).

Nits, not failing. The changeset's "Who is affected" paragraph says "a JS Date and an epoch-millisecond number are unchanged" — true within that paragraph's stated scope (date/datetime fields), incomplete for time, where the same changeset's fourth bullet and the table's last row state the number/Date refusal. The PR body names the measured base as cd901d7a5 while the test docblocks say f1e921ab8e; neither is shipped prose and the after-cells are what the pins hold. The dev's theoretical edge (a year-0 instant in a non-ISO spelling on time would be named by the year class rather than the spelling class) is a message-class edge with the right verdict.

② Semver level

• Changeset .changeset/20549-comparand-door-real-day-iso.md: @objectstack/core: minor, @objectstack/objectql: minor, a **BREAKING** banner, Clause-②: no (narrowing), and one adr-0087: not-required (no-migration-prescription) marker. The two packages whose source changed are exactly the two bumped; rest, driver-memory, driver-sql are test-only in this diff, and service-analytics changes by inheritance with no source edit. Right.
• Level: an accept-set narrowing is BREAKING; check-changeset-no-major.mjs refuses major until GA (its header, Record the launch-window versioning convention's end condition — post-GA the fixed group returns to strict semver #14043), so minor plus the banner is the convention the repo runs. The changeset's sentence saying so is true.
• Clause-②: no (narrowing): judged no — per ① item 7 there is no new root export and no published-signature change; the arm is (narrowing) because isUninterpretableTemporalComparand's accept set shrinks. The PR body and both claims carry the same line.
• ADR-0087 disposition not-required (no-migration-prescription): substantively right (no authorable key, export or config field is removed or renamed; a filter VALUE class is refused; packages/spec untouched; no stored row read or rewritten), and mechanically the changeset carries no prescription in any arm the gate reads: no FROM/TO label, no arrow line, no migration-framed heading (the body has no headings), no retirement framing, and its one table's header (where, memory, SQLite, PostgreSQL, "now, on all three") has no OLD_COLUMN_RE cell, so it is not header-framed. The remedy line "send the number, or an ISO instant" is a sentence, not a rewrite frame.
• Shipped CHANGELOG.md prose: every factual sentence judged true against origin/main and the diff — the ISO grammar matches the regex; the refused examples are each pinned; "2026-07-15 10:00:00+08:00" is outside the space form (no zone), so "write it with a T" is right; the before-cells for the three card rows are the cards' own measurements; the time number row's before-cells ([] memory, 3 of 3 SQLite, 500 PostgreSQL) follow from the drivers on origin/main (JS number-vs-string compares false; SQLite orders every TEXT above INTEGER; PostgreSQL has no operator comparing time with an integer); the datetime $gt "2026" row follows from instantMs reading a bare integer string as epoch ms; the Unchanged list is pinned (leap day, ISO spellings across two zones, date leading-day reading, the 2026 time control in five spellings on memory, SQLite and live PostgreSQL/MySQL cells).

③ Boundary flags

1. open_questions — bare integer strings (H3). The card thread holds the seat's answer, comment 5894035143: A, as implemented. Judged consistent with the governing text in my inputs: triage 5883337906 and the claim's surface both say the comparand door refuses what the write door refuses, and on origin/main the write door refused "2026" and "1769940000000" on both kinds; the two earlier pins were labelled "the control" in their own test text, not an accepted spelling. No repo producer exists (sweep above). Answered; not escalated.
2. The time column's instant half narrowed alongside (commit 1). The claim names only the extended-year class for time. Judged right and inside the claim's direction: a time column reads a non-wall-clock comparand through the shared datetime reading, so keeping the old reading for time alone would need a second copy of the pre-temporal comparand door admits what the write door now refuses: an impossible day (2026-02-30) is rolled over as a datetime comparand and is a 500 on PostgreSQL as a date comparand, and a non-ISO datetime comparand is read in the host zone #20549 predicate, which the claim forbids ("⛔ no second copy"), and would leave the host-zone defect ("07/15/2026 10:00" as the process zone's time of day) open on one kind. Declared in the changeset (bullet 3), pinned in core, and the driver/REST controls hold. Answered; not escalated.
3. Pins placed outside the spec conformance kit. The kit is packages/spec/src/data/temporal-conformance.ts; the claim's file surface excludes packages/spec, and the kit's own header says storage form is asserted in each driver's own suite. The pins follow the landed temporal values outside the years a four-digit text or a backend holds: a datetime comparand for year 10000 or −1 misorders on memory/SQLite and 500s on PostgreSQL; a date in year 0000 500s on PostgreSQL; a date write stores +010000-… verbatim #20264/record validator: the temporal write arms trust Date.parse — date 2026-02-30 is stored verbatim (500 on PostgreSQL), datetime 2026-02-30T10:00:00Z rolls over to March 2, and a non-ISO datetime is read in the host zone #20525 layout (engine recording driver, REST over SQLite and PostgreSQL, driver halves on the live-dialect matrix and memory). Answered: right.
4. History rewritten with --force-with-lease before any PR existed. The five conditions: branch named claude/issue-20549-…; both commits on the branch carry one author and one committer identity, so nobody else pushed it; the PR did not exist at the time (opened afterwards, no reviewer or approval); the lease spelling is the dev's statement, which the diff cannot show, but the outcome — two clean commits on the merge-base with no foreign author — is what the rule protects. Answered.
5. NOT MEASURED — MySQL, turso remote, MongoDB. MySQL cells run in CI's Temporal Conformance (live PG + MySQL) job, in progress when read; its conclusion is that cell's verdict. turso remote and MongoDB have no server here and both faces sit behind the door, whose refusal precedes any driver. The rest package's PostgreSQL cells ran locally with no CI job for them, as declared. Answered; recorded as declared.
6. Two out-of-scope findings. (a) The write door's time arm is wider than the comparand door: verified on origin/main record-validator.ts:1330-1335 — hasDate is the unanchored /\d{4}-\d{2}-\d{2}/, which matches inside +010000-01-01, and timeOfDay admits a Z/offset suffix the time storage rule never reads. A class (a) finding with a measured reach (POST /api/v1/data/:object: 201 on SQLite, 500 on PostgreSQL). Not fixed in place was right — matching core's rule would also refuse offset wall clocks, a narrowing no triage pinned. Escalated to the seat: file it as its own card, the write-side twin of core temporal rule: a time comparand spelled with an extended-ISO year (+010000-01-01T10:00:00Z) is compared as text on memory and SQLite: $gt answers 3 of 3 rows, $lt 0, where the same wall clock as a 2026 instant answers 2 / 1 #20480, domain:engine. (b) H5 — nothing to carry; noted.

Check-runs on the head, read at 2026-09-29T16:20Z, not waited on: 31 runs — 13 success (Auto Label, Type Check · source gates, Type Check · debt ledger, Governed Surface Queue Guard, filter, Check Changeset, Check PR Size, Flag docs affected by code changes, Part-of PR must not also close its card, The card this PR closes must claim this branch, No other open PR may claim the same single-writer path, No other open PR may claim the same issue, Check Documentation Links); 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke); 15 in_progress (Build Core, Test Core 1/6 to 6/6, Temporal Conformance (live PG + MySQL), Dogfood Regression Gate 1/3 to 3/3, Dogfood Verify CLI, Type Check · consumer gates, Type Check · workspace, Lint & Repo Gates). No failure. The derived families still running (tests, lint and repo gates incl. check:adr-0087-registration, the live-dialect cells) are adjudicated by their own conclusions; this record judges the contract and does not stand in for them — the PR is not a governed-surface PR, and the seat arms it only once every check is green, as the ordinary rule says.

Implemented-by: claude/issue-20549-comparand-door-real-day-iso
Reviewed-by: session_01DEvba2nBuD4tWzfq8r8NFY

VERDICT: PASS

---

Generated by Claude Code