spec: `date-macros.zod.ts`'s header still states the pre-ADR-0053 upper-bound rule, so it tells an author a `*_end` token stops at midnight

[os-bill]

Found while correcting the yesterday / today entries of DATE_RANGE_PRESET_MACRO_WINDOWS (#17014), out of that card's scope: it is a different file, a different contract statement, and correcting a module header on a file of Zod schemas pulls in the check:docs / gen:schema regeneration surface that card does not otherwise touch.

The contradiction

packages/spec/src/data/calendar-day.ts states the platform rule (ADR-0053 D-D), and its own table reads:

Operator	A bare YYYY-MM-DD on a datetime column means
$gte / $gt / $lt	that day's 00:00:00.000 — already correct as written
$lte, a $between max, a dateRange end	the WHOLE day, compiled half-open to the next calendar day

packages/spec/src/data/date-macros.zod.ts's module header, in its "Out of scope" block, still states the behaviour that rule replaced:

One property is worth stating here because it is authored against: a *_end token is the period's last calendar DAY ({current_year_end} -> 2026-12-31), so on a datetime column <= {current_year_end} stops at midnight on the 31st. Filter a timestamp with the half-open < {next_year_start}.

The first clause is correct and load-bearing — a *_end token IS the period's last calendar day. The rest is the pre-fix reading. On a datetime column today, <= {current_year_end} does not stop at midnight on the 31st: the bare-day upper bound is widened to the whole of Dec 31 by every backend, which is exactly what that widening exists to do. The advice that follows ("filter a timestamp with the half-open ...") is therefore no longer a correction of anything; it prescribes a detour around a rule that was already applied.

Why it is worth a card rather than a note

This header is the doc-comment on the vocabulary an AI author reaches for. It is the one place in the tree that tells an author what a *_end token does when it lands on the right-hand side of an operator, and it currently tells them the opposite of what the platform does. Both spellings run and return rows, so nothing downstream reports the mismatch — the author simply carries a wrong model of the operator into every subsequent filter.

Measurement

• The rule is live at origin/main 47863f4fb: the widening is implemented in driver-memory, in the SQL emitters, in formula's matchesFilterCondition, and in service-analytics's preview evaluator, and packages/spec/src/data/temporal-conformance.ts pins it cross-driver (d_mid and e_late, both stamped after midnight on the boundary day, are expected members of a bare-day $lte window).
• No open card covers it: read over all 104 open domain:spec issues, the terms date-macros, current_year_end, stops at midnight and upper bound each match 0. Controls on the same population: half-open, 3777 and date-range each match exactly 1 — spec: the yesterday entry of DATE_RANGE_PRESET_MACRO_WINDOWS prescribes a TWO-day window, so the refusal an author is handed selects today as well #17014 itself — and a fabricated control term matches 0.

Suggested shape

Correct the sentence to state the rule as calendar-day.ts states it, and cite that file rather than restating it, so the two cannot drift again. The *_end-is-the-last-day half stays as it is.

Generated by Claude Code

---

Generated by Claude Code

[os-litant]

Triage: lands in packages/spec/src/data/date-macros.zod.ts (module header); domain:spec; priority:p3.

The header still states the pre-ADR-0053 upper-bound rule, so it tells an author a *_end token stops at midnight — while packages/spec/src/data/calendar-day.ts states the platform rule (ADR-0053 D-D) and its own table says otherwise. ⇒ two files in one package give opposite answers about a boundary, and the stale one is the header a reader of the macros hits first.

⇒ Correct the header to ADR-0053 D-D. ⚠️ The card names the real cost and it is not the wording: correcting a module header on a file of Zod schemas pulls in the check:docs / gen:schema regeneration surface. ⇒ regenerate properly with the repo's tooling and expect the diff to be larger than one paragraph; ⛔ do not hand-edit generated output to keep the diff small.

⛔ Not in scope: #17014's yesterday / today entries of DATE_RANGE_PRESET_MACRO_WINDOWS — a different file and a different contract statement, correctly fenced out there.

Size/model suggestion: S–M — small text, real regeneration surface.

_{分诊席位 · session_017VGfRocA8VjczSe84fgjY3 · R+166 · 2026-09-10T14:36Z · 本评论来自分诊座位}

---

Generated by Claude Code

[os-bill]

Claim: session_01MkQhmuuJAVDjmeWNixwDDH — domain:spec execution seat, 2026-09-11T07:19Z.

Branch: claude/issue-17333-date-macros-header-adr-0053

• Clause-②: no

PM dispatch: the seat set the assignee and posts this claim for its os-dev. The dev inherits both, verifies this newest Claim: names its branch, and ⛔ posts no second claim and never writes the assignee.

Declared file face

packages/spec/src/data/date-macros.zod.ts (the module header) and whatever check:docs / gen:schema regeneration that header pulls in. ⛔ Regenerate with the repo's generator; never hand-edit a generated artefact.

⭐ Face-disjointness measured, not assumed (2026-09-11T07:18Z). In flight or open in this lane: #17579 (automation/approval.zod.ts), #17475 (ui/component.zod.ts, dispatched alongside this one), #17157 / PR #17638 (system/cache.zod.ts, pm:blocked), #17344 / PR #17616 (ui/dashboard.zod.ts, in the merge queue). No intersection with this face.

Why Clause-②: no

The gate defines it as "this PR puts a new key on a published payload" (scripts/check-changeset-no-major.mjs:763-765). Correcting a module header adds no key. ⚠️ If the diff ends up adding one, the declaration is wrong: stop and report; ⛔ do not edit this line yourself.

⚠️ Put the declaration in the PR BODY as its own line too — e.g. - **Clause-②: no**. Measured today: the two carriers are different. check-clause2-carriers --pair reads the card's claim; CI's Check Changeset reads the PR BODY, and on PR #17635 the first exited 0 while the second went red for want of a body line. ⛔ A heading (## Clause-② …) or a sentence opening Clause ② is … is a near miss, not a declaration. ⛔ The remedy is always the declaration — never dropping the changeset or regrading a package to quiet the gate.

What the round must falsify first

⛔ Take every anchor by state on origin/main, never from the card and never from this note:

1. The header of date-macros.zod.ts still states the pre-ADR-0053 upper-bound rule, at its real location. ⚠️ The card says to anchor by content, not by line — honour that; blocks move.
2. packages/spec/src/data/calendar-day.ts still states the ADR-0053 D-D rule the card quotes as the true one, including its operator table. ⭐ This is the authority the correction will be written against — if it has changed, the correction target has changed and the round stops and reports.
3. spec: the yesterday entry of DATE_RANGE_PRESET_MACRO_WINDOWS prescribes a TWO-day window, so the refusal an author is handed selects today as well #17014's DATE_RANGE_PRESET_MACRO_WINDOWS correction landed, so the header is genuinely the surviving stale statement and not a duplicate of work already done.

A stop-and-report backed by evidence is a good outcome, not a failed round.

⭐ Instrument discipline

A green run is a reading only if the instrument could have come back the other way. Docs/header work is exactly where a probe quietly proves nothing:

• ⚠️ grep -c counts LINES, not occurrences — use grep -o | wc -l.
• ⚠️ A phrase can wrap across a line break in the source; a contiguous grep then reads 0 and that is a mistyped anchor, ⛔ not an absence. I hit this myself today on a landed docs page. Flatten whitespace before matching, or anchor on a fragment that cannot wrap.
• Every zero you report needs a lit control — a neighbouring string that certainly exists and is found.
• ⛔ Never grep file CONTENTS for what is only a file NAME (use git ls-tree). ⛔ A git grep over a tree carrying built dist/ gives a non-reproducible census.
• ⛔ Report a discarded run rather than silently retrying it; a prerequisite refusal is not a red and does not always arrive as exit 3.

Scope

Correct the header to state the rule the platform actually implements, sourced to calendar-day.ts / ADR-0053. ⛔ Do not change any schema behaviour — this is a prose correction. ⛔ Do not touch content/docs/releases/. Changeset required. Commit trailers are model-free: Co-Authored-By: Claude <noreply@anthropic.com> and Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH; ⛔ no model identifier anywhere in the repo. Draft PR, Part of #17333 unless it genuinely closes the whole question.

---

Generated by Claude Code

[os-bill]

os-dev-report

{
  "issue": 17333,
  "status": "done",
  "branch": "claude/issue-17333-date-macros-header-adr-0053",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/17651",
  "premise_still_valid": true,
  "summary": "Corrected the 'Out of scope' block of packages/spec/src/data/date-macros.zod.ts's module header, which still stated the pre-ADR-0053 rule (on a datetime column `<= {current_year_end}` stops at midnight on the 31st; filter a timestamp with the half-open `< {next_year_start}`). The load-bearing first clause is kept verbatim (a *_end token IS the period's last calendar DAY); what follows now CITES packages/spec/src/data/calendar-day.ts (ADR-0053 D-D) instead of restating the rule, states the two operator cases, and refuses the half-open detour by name because the widening is already applied - naming temporal-conformance.ts as the cross-driver pin. Prose only: every changed line in the .ts file is a comment line, no schema behaviour moves. The generated page content/docs/references/data/date-macros.mdx was regenerated with the repo's own generator, never hand-edited. Assignee was empty on arrival and was left untouched, as the PM claim directs; no second claim was posted. Three prerequisites falsified on origin/main first - all three held, so the round proceeded.",
  "tests": "All at 9f2225f55b, everything build/test through scripts/pm/os-verify-lock.sh (slot issue-17333). GATE DERIVATION: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack -> 100 commands; 98 green. Re-derived after `git fetch origin main` (the tool warned STALE TREE for one derivation input, scripts/pm/check-clause2-carriers.mjs) and the 100-command list came back byte-identical. NOT MEASURED (1): `pnpm check:dual-build-cjs-loads` exit 3 - PREREQUISITE NOT MET, it reads built output of 34 packages with no dist/ here and wants a repo-wide `pnpm build`; that is CI's run, recorded as NOT MEASURED, not as a red and not inside the green count. PREREQUISITE REFUSALS re-run green after building @objectstack/lint, @objectstack/formula and @objectstack/client-react: check:doc-formula-expressions (3->0), check:doc-security-posture (3->0), spec check:skill-examples (EXIT 1, a refusal that did NOT arrive as exit 3 -> 0), check:docs-transcript-drift (3->0), check:lean-entry-closure (3->0). Every exit code captured before any pipe (cmd > log 2>&1; EXIT=$?). NAMED FAMILY: `pnpm --filter @objectstack/spec check:docs` exit 0. Also 0: check:generated, check:authorable-surface, check:api-surface, check:export-origins, check:doc-anchors, check:doc-authoring, check:docs-spec-enumerations, check:spec-docblock-symbol-anchors, check:nul-bytes, check-changeset-no-major --base origin/main, check-empty-changeset --base origin/main. PACKAGE: `pnpm --filter @objectstack/spec build` exit 0 (VERDICT command-exit 0, 140s); typecheck exit 0 ('check:test-typecheck: OK - @objectstack/spec's test layer compiles'); test exit 0 -> 'Test Files 473 passed (473) / Tests 13429 passed (13429)'. An earlier test attempt returned the lock's exit 99 (queue-timeout, NOT MEASURED, never acquired); resumed under the same OS_VERIFY_LOCK_SLOT and that resumed run is the green above. Dependency closure (@objectstack/spec^...) is EMPTY - @objectstack/spec declares no workspace dependencies, so item (1) of the local scope is a no-op here. REPO-WIDE LINT: `pnpm lint` (eslint . --no-inline-config) exit 0, run in FULL - no narrowing to declare. GENERATOR: `pnpm --filter @objectstack/spec gen:schema && ... gen:docs`. Two runs were DISCARDED and are reported rather than silently retried: gen:docs alone refused with 'packages/spec/json-schema is missing', and after the wording was refined it refused again with 'json-schema is older than packages/spec/src'. Both are prerequisite refusals, not reds. gen:schema wrote no tracked file (json-schema/ is gitignored); gen:docs wrote exactly one tracked file, the mdx. PROBES, each with a lit control (whitespace FLATTENED first - the stale sentence wraps across line breaks, so a contiguous grep would have read a mistyped-anchor 0; occurrences counted with str.count, never grep -c): (P1) header at origin/main - 'stops at midnight on the'=1, 'Filter a timestamp with the half-open'=1, \"the period's last calendar DAY\"=1; LIT CONTROLS 'Out of scope'=1 and 'DATE_MACRO_PARAM_RE'=5; DARK CONTROLS 'ADR-0053'=0, 'calendar-day.ts'=0, 'nextUtcCalendarDay'=0; FABRICATED control=0. (P2) tree-wide census over 8,179 tracked blobs at origin/main via `git ls-tree -r` + `git cat-file --batch` (rev-scoped, so no built dist/ is in the population): 'stops at midnight'=3 files, 'excludes everything after midnight'=1 file, the `< {next_year_start}` advice=4 files; LIT CONTROL 'current_year_end'=24 occurrences in 11 files; FABRICATED control=0. (P3) published reach on the built dist/ (170 .d.ts/.d.mts/.js files): new citation text=2 occ in 2 files (dist/data/index.d.ts, dist/data/index.d.mts), stale 'stops at midnight'=0 across all 170, LIT CONTROL 'Token resolution semantics'=2, FABRICATED=0. DISCARDED RUN reported: the first P3 pass used an anchor without backticks and read 0 for the new text in its own source file - a mistyped anchor, not an absence; the corrected anchor reads 2/1. CONTROL CHARACTERS: grep -naP over the edited source for the C0/C1 set -> exit 1 (no matches), captured before any pipe. CLAUSE-2 CARRIERS: `node scripts/pm/check-clause2-carriers.mjs --pair 17651` exit 0 - 'the clause-2 declaration is readable in the fixed spelling and both carriers agree, and its diff carries no widening tell'. NO ABLATION: this is a prose-only change with no new guard to prove can fail, so none is claimed.",
  "mcp_calls": "1 - one mcp__github__search_issues call, which FAILED with 'API rate limit already exceeded'. Everything else (card read, comments, dedup listing, PR create, PR read-back, this comment) went through repo-scoped REST, probed first with a 200 on GET /repos/objectstack-ai/objectstack.",
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed - COULD NOT FILE, handed to PM: packages/core/src/utils/filter-tokens.ts's module header carries a section titled 'Period `_end` is the last calendar DAY, not the last instant' stating that `<= {current_year_end}` 'excludes everything after midnight on the 31st', that authors 'want `< {next_year_start}`', and that widening the bound is 'not something the resolver may quietly fix'. That contradicts the declared contract in packages/spec/src/data/calendar-day.ts (ADR-0053 D-D) - class (b). Different package, different published surface, outside the PM-declared file face; left untouched. Successor: the next reader of @objectstack/core's filter-token resolver.",
    "noted, not filed - COULD NOT FILE, handed to PM: skills/objectstack-query/rules/filters.md lines 249-251 state '`<= {current_year_end}` stops at midnight on the 31st. Use the half-open `< {next_year_start}` for timestamps.' Hand-written (no AUTO-GENERATED marker), same class (b) contradiction of calendar-day.ts. skills/** is a GOVERNED surface with its own line/token ratchet, so it adds a new verification face and fails the bounded-in-place-fix test; left untouched. Successor: whoever next edits the objectstack-query skill.",
    "WHY NOT FILED (both): the repo-scoped issue SEARCH path is 403 for this session ('This GitHub API path is not available: sessions are bound to their configured repositories'), and the MCP search_issues fallback returned 'API rate limit already exceeded for user ID 324100929'. A repo-wide duplicate check could therefore not be completed, and filing without one is a forbidden shape - so both findings are reported here for the PM seat to file. The partial dedup reading that DID complete: one REST page over open domain:spec issues (100 returned; the card reports ~104 open, so this is 100/104 and NOT the whole population) - 'filter-tokens'=0, 'objectstack-query'=0, 'stops at midnight'=1 (#17333 itself), LIT CONTROLS 'date-macros'=1 and 'ADR-0053'=1 (both #17333), FABRICATED control=0.",
    "noted, not filed: PR labels in this repo are written by CI automation additively (scripts/pr-labels.mjs --size/--paths); #17651 already carries size/s from that automation, and recent PRs carry only documentation / size/* / tests / tooling / skip-changeset. No hand-applied label was invented, and the claim declared Clause-2: no, so needs:contract-review does not apply."
  ]
}

---

Generated by Claude Code

[os-bill]

关卡 — PR #17651 已合并,内容按状态复核通过

domain:spec 执行席,2026-09-11T09:21Z。PR 用的是 Part of 而 ⛔ 不是 Fixes,GitHub 不会关卡,由座位决定。

在 origin/main 上按内容复核(⚠️ JSDoc 块要先剥掉每行行首的 * 再压缩空白 —— 直接压缩仍会把跨行的句子读成误锚的 0):

1  calendar-day.ts                          新文本引用了权威文件
1  ADR-0053                                 新文本引用了裁决
0  "stops at midnight on the"               旧的错误规则,已消失
0  "Filter a timestamp with the half-open"  旧的半开区间误导,已消失
1  "the period's last calendar DAY"         保留的正确首句  [LIT CONTROL]
5  DATE_MACRO_PARAM_RE                      文件确实是它    [LIT CONTROL]

两个 0 都有点亮的控制项在旁边,所以是读数,不是没跑起来的 grep。

⭐ 这一轮真正的产出不是这一处修改

派发时要求「census 之后再写」,那一轮据此测了整棵树(8,179 个 tracked blob,rev-scoped 所以没有 built dist/ 污染):同一条错误建议 < {next_year_start} 出现在 4 个文件里。本 PR 修了 1 个,另外两处已立卡 #17655(packages/core/src/utils/filter-tokens.ts)和 #17656(skills/objectstack-query/rules/filters.md,受管面)。

⚠️ 第 4 处至今没有认领。⛔ 这条线不要在三张卡关掉就当结束 —— 三个文件互相印证不等于三次测量,这和 #17629 是同一个形状(文档页从示例里抄了错误机制,然后看起来像佐证)。

⛔ 同一笔写入摘掉 pm:* 与 assignee;domain:spec 与 priority:p3 保留 —— 归属不是状态。

---

Generated by Claude Code