docs(core): state the dateRange end offset as a derived property, not a typed count

[os-musk]

Fixes #17341

Clause-②: no

The docblock above PRESET_WINDOW_TOKENS in packages/core/src/utils/analytics-date-range.ts
records why this table states its own ends instead of reading the spec's prescription pair —
and it ended on a hand-typed census: "so its ends are one day earlier for the eight period
presets." That count was correct when written and went false when #17338 corrected today
and yesterday to close on their own last day. The sentence is load-bearing (it is the recorded
reason the design is what it is), so the fix is the census, not the digit.

The census — population, method, reading

Population: the declared vocabulary DATE_RANGE_PRESETS (packages/spec/src/data/date-range-presets.ts),
read at this head — 13 names. packages/spec/** was read only; nothing in it is edited here.

Method: executable, at 00b994374. For each preset, resolve the spec's prescribed end
(DATE_RANGE_PRESET_MACRO_WINDOWS[p][1], unwrapped) through the one resolver
(resolveFilterToken) to a calendar day, take nextUtcCalendarDay of it, render that day's
start in the reference zone, and compare with the end this module actually returns. Swept over
8 reference instants × 4 zones = 32 cells per preset — the instants include both DST
transition days and both year edges, the zones include Pacific/Chatham (+12:45) and
America/New_York.

Reading:

class	count	presets
population (DATE_RANGE_PRESETS)	13	—
prescribed end is non-null (calendar)	10	today yesterday this_week last_week this_month last_month this_quarter last_quarter this_year last_year
prescribed end is null (rolling open arm)	3	last_7_days last_30_days last_90_days
spec end is exactly one CALENDAR day earlier	10 / 10	all of the calendar row, 0 exceptions over 320 cells
calendar presets that are NOT	0	—

So the split at this head is ten / three, which is what the card predicted — but it is now
measured rather than typed, and the prose no longer carries the digit at all: it states the
predicate ("every calendar preset, with no remainder") and the test derives the split from the
spec table. An eleventh preset now reds the pin instead of rotting the sentence.

One thing the census corrected in the card's own terms: "one day earlier" is a calendar
day, not 86_400_000 ms. Pacific/Chatham leaves DST on the first Sunday of April, so
2026-04-05 — exactly the day this_week's prescription names as its last — is 25 hours long
there. An elapsed-milliseconds reading of the same sentence measures 1.0416… days on that cell
and is wrong. The implementation was always right (every boundary here is a macro token); only
the wording was ambiguous, and the pin now fixes the unit.

Hard stop, checked and clear: the census shows all ten agreeing in one uniform way. There is
no new disagreement between this table's ends and the spec's prescription, so this stayed a
comment fix and did not become a defect report.

Does the justification still hold? (asked, answered, not dropped)

Yes, and it is stronger than before: the offset used to be irregular (two presets were not "one
day earlier" at all), and is now uniform across all ten. ⛔ But uniform is not derivable, and the
docblock now says so — deriving the ends from the spec's would mean shifting a resolved day by
one in this file, i.e. calendar arithmetic performed here, which is the second implementation
the module header exists to refuse. That is the risk the newly-uniform table creates for the next
reader, so it is recorded rather than left to be rediscovered.

The pin, and proof it can fail

New describe('#17341 …') block in analytics-date-range.test.ts. It counts nothing: both
families are read off DATE_RANGE_PRESET_MACRO_WINDOWS, the open-arm family is asserted equal to
this module's ROLLING, and a vacuity control asserts both families are non-empty.

Ablation (one-shot, on the committed state, restored):

leg	on-disk proof	result
mutate this_week end token next_week_start → week_end	anchor 1→0, mutant 0→1; blob 4f6d4829 → af99f042	2 failed / 43 passed, and both failures are in the new block
restore git checkout HEAD -- path	blob back to 4f6d4829, git diff HEAD empty	45 passed (45)

The mutated leg is the point: under a wrong end token every pre-existing assertion in the file
still passed. Nothing in the resolution path goes through dist (the test imports the module
relatively, inside its own package), so no build step stands between the mutation and the run.

Verification

what	command	reading
① dependency closure	pnpm --filter '@objectstack/core^...' build	exit 0
② affected package	pnpm --filter @objectstack/core test	51 files / 1305 tests passed
② affected package	pnpm --filter @objectstack/core typecheck	exit 0 (incl. check:test-typecheck: 4 files / 4 errors, ledger held)
③ derived gates	node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack → 53 commands	53 / 53 exit 0

Gate derivation ran against the actual changed files (2 paths, three-dot vs merge base
82cb69fed) and was reconciled with --ran. pnpm check:type-check-debt first exited 3
(PREREQUISITE NOT MET — OOM at the 4096 MB cap this container prefixes, which the gate itself
named as the tighter of the two ceilings); re-run at 8192 MB it exits 0 — "5 ledger entries
re-measured in 102.6s, 55 raw tsc errors total, none above its recorded number". Two other gates
(check:dual-build-cjs-loads, check:lean-entry-closure) exited 3 on an unbuilt tree and exit 0
after turbo run build over all 72 workspace packages. ⛔ No exit 3 is reported here as a pass.

Release declaration — skip-changeset, measured

This diff publishes nothing, and that is a measurement rather than a judgement. @objectstack/core
ships files: ["dist","README.md","CHANGELOG.md"]. Built at this head:

• negative probes, text unique to the edited docblock — Chatham 0 dist files, 86_400_000 0;
• positive controls — the exported symbol resolveAnalyticsDateRangePreset 4, the module
  header's STOPS BEFORE 2, the exported interface's own TSDoc the ten calendar presets 2
  (so exported-symbol and module-header comments do reach dist/*.d.ts; this docblock sits on a
  module-private const and does not);
• dist/index.js.map has sourcesContent: false, so no source text ships through the maps either.

The other changed file is a test. ⇒ route 2 of the Check Changeset job ("it releases nothing →
apply the skip-changeset label", marked PREFERRED there). ⚠️ The dispatch order asked for a
changeset; this is the one place this PR departs from it, on the measurement above, and it is
flagged in the report rather than chosen silently.

Acceptance notes

• The module header (the ten CALENDAR presets / the three ROLLING) and the
  ResolvedAnalyticsDateRange docblock still carry typed counts. Both are true at this head —
  the census confirms 10 and 3 — so they are not defects and are not filed. They are also no
  longer unguarded: the new pin asserts the spec-derived open-arm family equals this module's
  ROLLING and that every spec-derived calendar preset is endExclusive, so the PR that adds an
  eleventh preset reds here and is routed to this file. Noted, not filed.
• endExclusive, the three rolling last_N_days presets and every START are untouched, as analytics-date-range.ts says the spec's prescription ends are "one day earlier for the eight period presets" — PR #17338 makes it ten, and makes that sentence false #17341
  said they would be. The "STARTS agree exactly" half of the sentence was re-checked and is still
  true; its pin already existed and is unchanged.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/core/src/utils/analytics-date-range.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/core/src/utils/analytics-date-range.ts) — pages documenting those are invisible to this run
• 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.

Coarse fallback — 24 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 3ef96b47120a989d9333aeeeb6181bc371bc9b52 → packageMentionDocs.