fix(formula): converge the CEL pushdown parser onto the canonical front end, with an rc grace window (#6132)

[os-zhuang]

Fixes #6132

Implements the maintainer's A′ ruling of 2026-08-08, recorded verbatim on the issue:

1. Converge now (rc window): packages/formula/src/cel-to-filter.ts drops its private limitless getParseEnv and parses through packages/lint 绕过 @objectstack/formula 直接 parse CEL —— 两个解析入口对「什么能解析」会给出不同答案 #4812's parseCelToAst(with DEFAULT_LIMITS). Within-limits predicates: byte-identical behavior.
2. rc grace, GA flip: during 17.0.0-rc.x an over-limit predicate on the pushdown path still compiles + emits a WARN naming the exceeded limit; at v17 GA the runtime flips to fail-closed refusal (the parse-error ⇒ RLS_DENY_FILTER path). Implement the flip as a single dated switch (a named const, default = rc-grace) so GA needs a one-line change; record the intended flip point in a comment + the changeset.
3. Sister entrance: cel-engine gains a reason-carrying variant so a limit refusal names WHICH limit was exceeded (maxAstNodes / maxDepth / maxListElements) instead of a bare parse-error. Wire the WARN (and the future refusal) to use it.

---

Premises, re-measured on current main (a5d2573)

The issue's facts were measured on bc67c28e2. Re-verified before writing code; every one holds, including after PR #6677's same-day rewrite of cel-engine.ts.

shape	old private env	parseCelToAst	celEngine.compile()	isPushdownableCel (before)
300-term addition	parses	refuses	bounds: Exceeded maxAstNodes (256)	unsupported (arithmetic)
80-term conjunction	parses	refuses	bounds: Exceeded maxAstNodes (256)	ok — reached real pushdown SQL
60-level parens	parses	refuses	bounds: Exceeded maxDepth (32)	ok
40-level nesting	parses	refuses	bounds: Exceeded maxDepth (32)	ok
200-element $in	parses	refuses	bounds: Exceeded maxListElements (64)	ok
64-element $in (AT the bound)	parses	parses	ok	ok
65-element $in	parses	refuses	bounds: Exceeded maxListElements (64)	ok

What changed

packages/formula/src/cel-engine.ts — the sister entrance (ruling §3).
parseCelToAstWithReason(source, opts?) returns { ok: true, ast } or a discriminated refusal: 'empty' / 'parse' (not valid CEL) / 'bounds' (valid CEL, over budget) carrying { limit, limitValue, measured, summary }. parseCelToAst is now parseCelToAstWithReason(...) collapsed to null — its #4812 contract is untouched, and that is pinned.

The verdict is graded by the same classifyCelFault compile/evaluate use — error class plus structured code, never prose. PR #6677's fresh by-code table is not touched; cel-parse-reason.test.ts pins that a bounds overrun is bounds on both entrances with the same summary, that a syntax fault is parse on both, and that an author-controlled field name spelling Exceeded_maxAstNodes is still graded parse (the #6223 hazard).

The limit key comes from ParseError#summary (Exceeded maxAstNodes (256) — built by Parser#limitExceeded from a fixed key set), never #message (which is formatErrorWithHighlight's rendering of the author's own source line). The captured key is validated against DEFAULT_LIMITS, so a cel-js that rephrases the sentence degrades to "bounds, limit unknown" instead of inventing a limit name.

The measure is cel-js's own accounting, not a second implementation of it: the smallest limits[key] under which the source parses, every other bound lifted, found by exponential probe + binary search (O(log n) parses, capped at 64× the bound). A node-walk would report 3 for a 60-deep parenthesis nest, because maxDepth counts parenthesised recursion that leaves no AST node behind. Measuring happens only on the grace path, where an unbounded parse has already occurred — a bounds refusal never re-parses a source it has just declared too big.

packages/formula/src/cel-pushdown-limits.ts (new) — the dated switch (ruling §2).
CEL_PUSHDOWN_LIMITS_MODE: 'rc-grace' | 'fail-closed', shipping 'rc-grace'. Intended flip point: the v17.0.0 GA release — when packages/formula/package.json leaves 17.0.0-rc.x. Flipping is exactly one line; the module docblock says so, names the two assertions that go red on it, and states that nothing else needs to move.

packages/formula/src/cel-to-filter.ts — the convergence (ruling §1).
getParseEnv is gone. Both entry points (compileCelToFilter, isPushdownableCel) go through parseForPushdown, which asks the canonical entry and then, on a bounds refusal, either WARNs and compiles off the unbounded AST (rc-grace) or fails closed (fail-closed).

The GA refusal is { ok: false, reason: 'parse-error', detail: 'Exceeded maxAstNodes (256)' } — deliberately the existing reason, not a fourth one: parse-error is what every consumer already routes to its deny path, and a new reason value would be a new branch none of them has. Which bound was blown rides in detail.

The WARN is emitted once per source (bounded memo), through globalThis.console rather than the bare console global — this package builds with neither the DOM lib nor @types/node, and a bare embedder must degrade to silence, not to a ReferenceError thrown from inside a security compiler.

A1 — within-limits parity: measured, and it holds

Corpus: 1604 candidate strings harvested from every suite that drives compileCelToFilter / isPushdownableCel (formula, lint × 2, plugin-security, plugin-sharing, service-analytics, the dogfood conformance ledger and authz matrix), plus the SQL-bridged form of each. 710 sources parse under both front ends. AST differences: 3 — all of them rewriteNullableTernary's dyn(…) wrap on a null-guard ternary. Zero verdict changes.

The issue flagged this as scope to pin rather than discover: "a ternary was already non-pushdownable, but the REASON it is non-pushdownable changing is behavior". Measured across seven ternary shapes (top-level, as a comparison operand, as an in container, as a receiver of a comparison, as a string-method argument), reason and detail are byte-identical before and after — the ?: node faults in lowerCondition / classify before the lowerer ever descends into a branch, so the wrap the rewrite adds inside a branch is never reached:

record.done ? 'y' : null            old {unsupported, 'unsupported operator "?:"'}  new identical
record.a == (record.b ? 'x' : null) old {unsupported, 'unsupported operand "?:"'}   new identical

cel-to-filter-parse-convergence.test.ts rebuilds the pre-#6132 environment — the one place in the repo that still may — and demands an equal CelFilterCompileResult for all 47 corpus shapes, plus an explicit assertion that the AST really does differ for a ternary (so the pin cannot go vacuous).

No corpus source was newly refused: the corpus contains no over-limit predicate.

A2 — the authoring-time lint face

Confirmed, and no packages/lint edit is needed at either switch position.

• The general CEL lint face already refuses over-limit sources, independently of this change, because it converged onto parseCelToAst in packages/lint 绕过 @objectstack/formula 直接 parse CEL —— 两个解析入口对「什么能解析」会给出不同答案 #4812/refactor(formula,lint): parseCelToAst 成为唯一的 CEL 解析入口 (#4812) #6130. Measured: a 60-level-nested visibleWhen yields visibility-predicate-syntax (error), message visibility predicate is not valid CEL — Exceeded maxDepth (32).
• An over-limit sharing condition is already an authoring error today, under the shipping rc-grace default: expression-invalid, quoting Exceeded maxAstNodes (256). validateSharingRuleEnforceability correctly stays silent — it defers parse-error to the rule that owns syntax, and that rule reports it.
• The two enforceability gates (validateRlsPredicateEnforceability → isSupportedRlsExpression, validateSharingRuleEnforceability → compileCelToFilter) are downstream of this switch, and both suites pin "the lint verdict IS the consumer's verdict" in both directions. Authoring reporting therefore flips with the runtime by construction and cannot drift from it. Measured: flipping the switch to fail-closed turns an 80-term RLS using from clean into rls-predicate-unparseable (error), with no lint change.

One thing worth a follow-up, not touched here (cross-lane surface, and out of this card's scope): at GA an over-limit RLS predicate is reported under the id rls-predicate-unparseable with prose about SQL-vs-CEL syntax, which is off-label for a bounds overrun even though the message does carry the exact Exceeded maxAstNodes (256) detail. A rls-predicate-over-budget id with its own hint would read better. Flagged, not done.

A3 — per-consumer declarations

consumer	call	verdict
plugin-security RLSCompiler.compileExpression	compileCelToFilter(cel, { variables: { current_user } })	already-conforming. Any !ok → null → RLS_DENY_FILTER when it is the only applicable policy. No source change; new test pins both switch positions end-to-end.
plugin-security RLSCompiler.compileFilter	!isSupportedRlsExpression(predicate) (the ADR-0056 D4 drop-warning)	already-conforming. Both sides of the comparison move together, so the flip cannot produce a silently dropped policy — pinned: at fail-closed the drop emits DROPPED (no enforcement).
formula isSupportedRlsExpression	isPushdownableCel(sqlPredicateToCel(x))	changed at GA (it is the wrapper the issue called out as no independent gate). At rc-grace: unchanged.
plugin-sharing bootstrapDeclaredSharingRules	compileCelToFilter(cel, { variables: {} })	already-conforming. !ok → rule skipped + boot WARN. At GA an over-limit condition stops being seeded — and it is already an authoring error today (A2), so it cannot reach boot from a stack that passed os build.
service-analytics read-scope-sql	consumes the FilterCondition the RLSCompiler emits	already-conforming; no CEL parse of its own.
lint validateRlsPredicateEnforceability	isSupportedRlsExpression / isPushdownableCel	changed at GA, by construction, with no edit. Clean at rc-grace, rls-predicate-unparseable at fail-closed.
lint validateSharingRuleEnforceability	compileCelToFilter	already-conforming. Defers parse-error to the syntax rule, which already reports over-limit conditions today.
lint validateVisibilityPredicates, validateNullGuards	parseCelToAst	out of scope, already-conforming. Already on the canonical front end; untouched by this change.

Tests

Rejection- and WARN-class tests assert specific identity; there is no bare toThrow() anywhere in the diff.

• cel-parse-reason.test.ts (24) — the sister entrance: which limit, its platform value, the exact summary, the measure (200 for the 200-element list, exactly), no measurement/no unbounded parse unless asked; parseCelToAst's null contract; both-entrance agreement with celEngine.compile; the by-code hazard.
• cel-to-filter-parse-convergence.test.ts (56) — A1, both directions, against the rebuilt old env.
• cel-to-filter-limits.test.ts (27) — the switch in both positions on the three measured shapes: rc-grace compiles + WARNs (asserting the limit name, limit <N>, Exceeded <limit> (<N>), a numeric measure strictly over the bound, the GA consequence, once-per-source dedupe, and that the compiled filter is real); fail-closed refuses with the exact { reason, detail } and does not warn; a genuine syntax fault keeps its own detail in both. Boundary shapes at the bound are admitted in both positions. The shipped default is pinned to rc-grace.
• plugin-security/rls-pushdown-limits.test.ts (20) — the same three shapes on the RLS path: rc-grace → real filter, not the sentinel, no drop-warning, console WARN naming the limit; fail-closed → RLS_DENY_FILTER, with an observable DROPPED (no enforcement) log, no grace WARN, and the multi-policy blast radius stated.

No new fake engine was introduced, so the assertEngineDeleteDispatch rule does not apply to this diff.

Reverse verification — direction written before running

Each pin was expected to fail if its subject were removed, and each was run in that state before being run in the passing state:

1. Revert the convergence (restore the private limitless env in cel-to-filter.ts) → every fail-closed assertion in cel-to-filter-limits.test.ts and rls-pushdown-limits.test.ts must fail, and the grace WARNs must stop firing. (Expected: red.)
2. Delete the rewriteNullableTernary half of A1 — i.e. assert the ternary AST is equal across front ends → cel-to-filter-parse-convergence.test.ts's "the rewrite really does change the AST" must fail, proving the reason-parity pins below it are not vacuous. (Expected: red.)
3. Flip CEL_PUSHDOWN_LIMITS_MODE to 'fail-closed' → exactly the two documented assertions go red (the shipped-default pin and the rc-grace suite), and nothing else — the property that makes the GA flip a one-line change with a known blast radius. (Expected: exactly those, red.)
4. Grade the bounds fault as parse (drop the code === 'limit_exceeded' arm) → the both-entrance agreement test and every "names the limit" assertion must fail. (Expected: red.)

Results are reported in the final comment on #6132.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bx3H8DJhBsmgDoMp8Tz87T

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 8, 2026 3:08pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/formula.

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/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.