fix(formula): null-guarded numeric formulas + floor/ceil + reject date arithmetic (#3306)

[os-zhuang]

Fixes#3306.

Shipped template Field.formula fields silently evaluated to null on the pinned runtime — no parse error, no build warning, no runtime error. Root-caused to three independent CEL-engine gaps (full ground-truth diagnosis in #3306); this closes all three.

The three gaps

#	Gap	Before	After
①	cond ? <number> : null (the null-guard idiom)	cel-js ternary unifier rejects int≠null — even true ? 5 : null faulted → whole formula nulls	compiles and evaluates
②	floor / ceil unregistered	floor(...) → no matching overload → null	registered + in the catalog
③	date arithmetic (end - start + 1, today() + 30)	compiles clean (dyn), nulls at runtime — the silent gate hole	build ERROR → daysBetween/daysFromNow/addDays

How

• ① Null-guard — AST pre-pass wraps the non-null branch of cond ? x : null in dyn(...) (value-preserving, null-branch-only, idempotent), so a concrete branch unifies with null. Mirrors the merged Bare dateField == today() silently returns false — fix via AST temporal-comparison rewrite in the CEL engine #3183rewriteTemporalEquality; applied in compile(), evaluate(), and the build soundness check.
• ② floor/ceil — registered in stdlib (return int, round toward −∞/+∞ — not trunc, so floor(-1.2) == -2), added to CEL_STDLIB_FUNCTIONS + objectstack-formula SKILL.md (the anti-drift skill-catalog-sync gate enforces this).
• ③ Date-arith gate — the soundness check types date/datetime fields as google.protobuf.Timestamp and flags date/duration arithmetic against a number as a hard error. Sound by construction — only arithmetic-against-a-number is flagged; ordering (date < today(), date < "2026-01-01" string-lex), equality (Bare dateField == today() silently returns false — fix via AST temporal-comparison rewrite in the CEL engine #3183), and concatenation ("Due: " + date) are runtime-tolerated and stay clean. A != null guard no longer masks the inner fault (== null no-op overloads registered in the check-only env).

Result

The two fields from the issue now compute:

tenure_years: record.hire_date == null ? null : daysBetween(record.hire_date, today()) / 365 → 6
days: ... ? daysBetween(record.start_date, record.end_date) + 1 : null → 5

Tests

• null-guard: compile + eval (incl. both hr templates, null branch → null), genuine mismatch still errors.
• floor/ceil: semantics incl. floor(-1.2) == -2, double-arg coercion, catalog drift-guard.
• date-arith: RED on the shipped time_off.days bug and behind a != null guard; GREEN on all 6 runtime-tolerated date uses; stack-level validateStackExpressions RED-on-broken / GREEN-on-rewrite.

242 formula tests + 239 lint tests green; @objectstack/formula typecheck + DTS clean.

Downstream heads-up: ③ adds a new build-time error. A formula/predicate doing arithmetic on a date/datetime field that previously built (and nulled at runtime) will now fail objectstack build — this only fires for expressions that were already returning null. Corrective message names the fix.

The template-side rewrites (hr_employee.tenure_years, hr_time_off_request.days) ship in a companion PR against the templates repo, plus wiring validateStackExpressions into templates CI.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 20, 2026 5:35am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/formula, @objectstack/lint.

7 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/formulas.mdx(via @objectstack/formula)
• content/docs/data-modeling/validation.mdx(via @objectstack/formula)
• content/docs/permissions/authorization.mdx(via @objectstack/lint)
• content/docs/plugins/packages.mdx(via @objectstack/formula)
• content/docs/protocol/objectui/record-alert.mdx(via @objectstack/formula)
• content/docs/releases/v15.mdx(via @objectstack/formula)
• content/docs/releases/v16.mdx(via @objectstack/formula)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.