# Formula Calendar Primitives — Performance Learned

## 2026-08-25 — Runtime and SQL parity correction

- Candidate: Core `fdaca4ac1ad9e542e064198a95064d9e8be6b6c3`, corrected
  through `9c95b5f6394b2b03ca81f4b71ff040afe431b23d`.
- Workload shape: cached expression programs evaluate target-clamp month addition
  and calendar-day difference; the analytics compiler lowers the same cataloged
  primitives into TiDB expressions.
- Review evidence: the initial kernel SQL walker preserved a DateTime time
  component for a function cataloged as Date, and three calendar evaluators did
  not all consult the active function registry for arity. Direct probes
  reproduced both disagreements.
- Performance constraint: the correction must keep date/month operands single
  sourced, avoid allocations on registry arity checks, and avoid redundant Date
  normalization when the compiler statically proves a Date input.

### Registry correction benchmark

- Harness: Apple M4, cached expression program, five runs per primitive,
  `go test ./pkg/expression -run '^$' -bench BenchmarkCalendarPrimitive
  -benchmem -count=5`.
- Before registry-backed arity: target clamp median 618.4 ns/op, 480 B and 7
  allocations; day difference median 596.5 ns/op, 456 B and 6 allocations.
- Naively routing arity checks through the public cloning lookup raised medians
  to about 739.9 ns/op and 687.6 ns/op and added one 48-byte allocation.
- Owning-layer correction: `Registry.CheckArity` now reads the registry-owned
  immutable value directly while public `Lookup` retains defensive cloning.
  Corrected medians before range validation were 643.1 ns/op and 614.4 ns/op
  with the original allocation counts.
- The analytics compiler omits a redundant outer `DATE(...)` only when the
  input is statically proven Date; DateTime and unknown inputs normalize
  explicitly.

### SQL DATE range parity loop

- Run: Core Codex Review `32875494294` at
  `dc8bf62b5e4d9eefaa1b51ea895e15535e6d41c9`, followed by a local TiDB
  integration probe.
- Before change, active runtime returned year-10000 values for target-clamp,
  Salesforce month-add, and day-add while frozen TiDB expressions returned
  NULL beyond the year-9999 upper boundary.
- A provisional MySQL-style year-1000 lower bound was falsified by TiDB:
  `1000-01-01 - 1 month` is the valid date `0999-12-01`. A second probe showed
  `0001-01-01 - 1 month` becomes NULL, establishing the measured parity range
  as years 1..9999.
- The final shared guard performs allocation-free integer range checks before
  date construction and prevents extreme month counts from wrapping the month
  index.
- Final same-harness five-run result: target clamp median 654.1 ns/op, 480 B and
  7 allocations; day difference median 635.1 ns/op, 456 B and 6 allocations.
  Allocation counts and emitted SQL shape are unchanged.

### Operation-specific lower boundary

- Adversarial review at `8d2dc8c684270b5d04ba699f68def47ef11640d6`
  identified that TiDB `DATEDIFF` accepts stored year-0000 dates even though
  `DATE_ADD` cannot produce a year-0000 result. Reusing the add-result guard in
  day difference therefore over-constrained a read-only operation.
- Next hypothesis: keep the shared range guard on date-producing month/day add
  paths, remove it from ordinal subtraction, and prove year-0000 active/frozen
  day-difference parity in TiDB. This should also recover the day-difference
  microbenchmark delta without affecting target-clamp.
- Result: the real TiDB active/frozen integration test passed for year-0000
  `DATEDIFF`; the add-only guard remains and ordinal subtraction is direct
  again. A follow-up five-run benchmark retained 480 B/7 and 456 B/6 allocation
  counts but wall-time samples were unusually noisy (target 750.6..1114 ns,
  day difference 643.6..729.9 ns), so they are not used as a latency comparison.
  The target path is byte-identical to the prior measured candidate and the day
  difference path removes two year-bound checks; no new work exists on either
  valid hot path.