feat(formula,lint): advisory type-soundness warnings for expressions (#1928 tier 4)

[os-zhuang]

What

Closes the last open guardrail from #1928. A Field.formula, record-scoped predicate, or flow/automation condition that uses a text or boolean field with an arithmetic (+ - * / %) or ordering (< > <= >=) operator against a number faults the runtime overload and silently evaluates to null (e.g. record.title * 2, record.is_active + 1, a flow condition status - 1 > 0). The build now surfaces this as a non-blocking warning naming the offending field and the fix.

This is Tier 4 from the issue's staged plan — deferred by the maintainer until a warning channel existed. It now does (shipped for tier 3 in #1933), so this lands as advisory warnings.

Soundness (the ADR-0032 design law — flag only what the runtime would also fail)

The build checker's type map deliberately mirrors runtime, verified empirically against the pinned cel-js (8.0.0):

• Number / currency / percent / date / datetime → dyn, so the cases the runtime rescues never warn:
  • record.amount / 100 — the fix(formula): register mixed double/int arithmetic overloads (#1928) #1930 registerOperator (double×int) fix.
  • record.due == today() and numeric-string / ISO-date values — the string-hydration retry.
  • numeric-coded select option values (e.g. priority >= 3).
• Equality (== / !=) is excluded — a heterogeneous equality is runtime-safe (evaluates to false), never a fault. The real example-crm formula record.status == "converted" || … is correctly not flagged.
• In flow/automation conditions, flow variables stay dyn (unlisted → dyn) and are never flagged — only a typed field misused is.
• Only genuinely free-text scalar types (text, textarea, email, url, phone, markdown, html, richtext) → string, and boolean/toggle → bool.

Changes

• @objectstack/formula — new firstTypeMismatch(source, fieldCelTypes, scope) (builds a typed cel-js env — a record struct for record scope, bare top-level variables for flattened flow conditions — and reports arithmetic/ordering overload faults), plus an optional fieldTypes hint on validateExpression. A narrow spec-type → CEL-type map keeps false positives near-zero.
• @objectstack/lint — validateStackExpressions threads each object's field types into every checked site:
  • record-scoped (record.<field>) — formula fields, validation rules, action / hook / sharing predicates;
  • flattened flow / automation conditions (bare field).
    Warnings are advisory in objectstack build / validate (fatal only under --strict), matching the tier-3 channel.

Acceptance (#1928)

• A text/boolean field misused in arithmetic/comparison is flagged at build with an actionable, field-named message.
• The cases the runtime now handles (amount / 100, date-vs-today(), equality, string concat, null-guards, flow variables) are not flagged.
• Covers both Field.formula / predicates and flow conditions.

Testing

• @objectstack/formula — 219 green (+13: record + flattened cases; number/date/select/equality/concat/null-guard/flow-variable no-warn; scope gating).
• @objectstack/lint — 232 green (+5 integration cases, incl. flow conditions).
• Both suites green on the cel-js 7.6.1 → 8.0.0 bump; DTS builds type-check clean.

Not done (needs a decision, out of scope)

The issue also floated wiring this into an agent-callable validate_expression tool for authoring-time feedback. That tool does not exist in the codebase today, and the only runtime hook (validateFlowExpressions at registerFlow) has no object-schema access and only raises errors — so bringing tier-4 there is a runtime change (object-registry injection + a warning channel), not a small follow-up. Left for a separate, sign-off-gated PR.

Refs: #1928, ADR-0032. Runtime arithmetic fix #1930, tier-1 #1931, tier-3 #1933.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hnji7EEYR2mGt6pY53a8Bm

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Canceled		Jul 18, 2026 6:54am

[github-actions]

📓 Docs Drift Check

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

6 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)

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.