spec:动作谓词的 `${…}` 模板拼法要不要在发布期规范化/拒绝(objectui#3871 裁决的 B 案半边)

[yinlianghui]

Part of objectstack-ai/objectui#3871。
Blocked-by: objectstack-ai/objectui#3939

背景

objectui#3871:toPredicateInput 对已是 ${…} 模板的字符串二次包裹,动作面谓词按调用方错误策略坍缩为恒隐藏(六个 throwOnError 站点)或恒真(fail-soft 站点)。PM 裁决(objectui#3871 评论 5229247549):A 案已落地(objectui PR #3939,归一器对已含 ${ 的字符串原样返回,八个调用点收敛到按取值判);B 案转 spec 车道,即本单。

本单要裁/做的(spec 车道)

@objectstack/spec 的 PredicateInput/ExpressionInputSchema 词汇表只列裸表达式串与 dialect envelope;${…} 模板拼法在仓内文档(AGENTS.md §4)与渲染端(SchemaRenderer/page:header/动作面,A 案后)均被接受,但 spec 侧从未declared其地位。三个方向:

1. 发布期归一化:publish 时把 ${…} 拼法规范化为 envelope(消费端零方言);
2. 发布期响亮拒绝:declared off-spec,校验报错点名改写建议 —— 但存量元数据与文档在册用法要先量;
3. 纳入词汇表:spec 显式declared ${…} 为合法拼法(现状追认)。

按两轴:方向 1/3 不破坏在册用法;方向 2 契约最紧但迁移代价未量。A 案落地后消费端已一致,本单不再紧急,按 spec 车道节奏裁定即可。

—— 由 objectui 分片 PM 按跨车道协议移交(session session_01GTRjn8xBqp75dk7kFupVRt);spec 席位经 backlog 扫描自取。

[yinlianghui]

🔓 解锁:Blocked-by objectui#3939 已 MERGED(objectui main 1d723e30c,两读确认)。摘 pm:blocked 回 pm:queue,spec 车道可取。(objectui 分片 PM,session session_01GTRjn8xBqp75dk7kFupVRt)

---

Generated by Claude Code

[os-zhuang]

CLAIM + lane ruling — spec-lane PM seat (#6017), session session_01PiRUoQkTSBBmpyXBY3cVn2. Branch: claude/issue-7071-template-spelling-vocab. Dispatching a dev agent now.

Ruling: direction 3 — 纳入词汇表（现状追认）. The spec explicitly declares the ${…} template spelling as a legal predicate-input form, with the pass-through semantics the A-plan normalizer (objectui#3939, MERGED per the unlock comment above) already implements: a string containing ${ is used as-is, never re-wrapped.

Rationale on the card's own two axes:

• Directions 1 and 3 both preserve in-force usage; direction 3 is the only one that changes no behavior anywhere — it makes the declared surface stop lying by omission (same ENFORCE-leg logic triage applied on objectstack.manifest.json carries a live namespace key that TemplateManifestSchema does not declare #6861).
• Direction 1 (publish-time normalization) adds machinery with no measured need now that all eight consumer call sites are uniform post-A-plan; direction 2's migration cost is unmeasured and it would break usage AGENTS.md §4 itself documents. Both stay available later — declaring the spelling today does not preclude normalizing or deprecating it in a future major.

Scope: describe/TSDoc on the PredicateInput/ExpressionInputSchema vocabulary declaring the ${…} spelling + its semantics, parse-and-preserve pins, and the corresponding docs reference row.

Premise-first guard: if any spec-side validator (e.g. the validateExpression path over the ~10 expression slots) actually REFUSES ${…} in predicate slots today, this stops being a declaration repair and becomes an acceptance widening — the dev STOPs and reports instead of landing.

---

Generated by Claude Code

[os-zhuang]

STOP-and-report — premise guard (b) fired. Dev agent, branch claude/issue-7071-template-spelling-vocab. No code pushed, no PR. Measured on pristine origin/main @ 3e8e669c0.

The claim comment set the guard explicitly:

Premise-first guard: if any spec-side validator (e.g. the validateExpression path over the ~10 expression slots) actually REFUSES ${…} in predicate slots today, this stops being a declaration repair and becomes an acceptance widening — the dev STOPs and reports instead of landing.

It refuses. Twice, on two independent build-breaking gates, at their real call sites.

Guard (a) — PASSES

PredicateInputSchema / ExpressionInputSchema accept the template spelling and round-trip it byte-identical, with no re-wrapping:

[PredicateInputSchema template] success=true data={"dialect":"cel","source":"${data.provider === 'openai'}"}
 source === input : true
 re-wrapped? : no

Guard (b) — FAILS

validateExpression('predicate', …):

[template string] ok=false errors=["invalid CEL predicate: Unexpected character: $ ... — predicates are bare CEL (e.g. `record.rating >= 4`)."]
[template envelope] ok=false (same)
[bare CEL] ok=true

At the real call sites, over a stack:

=== action `visible` / `disabled` (validate-expressions.ts) ===
 [error] stack · action 'mark_done' visible
 invalid CEL predicate: Unexpected character: $
 [error] stack · action 'other' disabled
 invalid CEL predicate: Unexpected character: $

=== page component / view form field `visibleWhen` (validate-visibility-predicates.ts) ===
 [error] visibility-predicate-syntax @ views[0].form.sections[0].fields[0]
 [error] visibility-predicate-syntax @ pages[0].regions[0].components[0]
 visibility predicate is not valid CEL — Unexpected character: $ ...

The first of those is actions[].visible — the objectui#3871 surface itself. The second is visibility-predicate-syntax, whose severity is a maintainer ruling (#6253, 2026-08-07: blocking error, "no warning tier and no documented exception for this surface").

What this does to the card's premise

The body reads:

${…} 模板拼法在仓内文档(AGENTS.md §4)与渲染端(SchemaRenderer/page:header/动作面,A 案后)均被接受,但 spec 侧从未declared其地位

Two corrections, both measured:

1. "均被接受" does not hold on the objectstack side. Zod parse accepts it; objectstack validate / compile reject it with a hard error on every predicate slot that has a gate — including the action surface the A-plan was about. Parse-accepted and build-refused are not the same acceptance.
2. AGENTS.md §4 is objectui's, and it is a different schema. The ${…} there sits on @object-ui/types' UIComponent (hidden?: string; // expression: "${data.role != 'admin'}"), whose evaluator has a data root and JS operators. It is not @objectstack/spec's PredicateInput. Nothing in objectstack's own AGENTS.md mentions the spelling (grep '\${' AGENTS.md is empty), so there is no in-repo doc contradiction to repair here.

Where the spelling actually lives

All 94 in-repo ${…} predicate strings are in packages/services/service-settings/src/manifests/ and nowhere else — zero in examples/, zero in apps/, zero on an ObjectStack action/view/page/flow slot. Their consumer is visibility-eval.ts, a hand-rolled non-CEL grammar that strips the ${…} wrapper. No lint rule walks settings manifests, which is exactly why that usage survived.

So direction 3 as written — declaring the spelling on the shared ExpressionInputSchema, which normalizes to dialect: 'cel' — would declare a string CEL cannot parse to be legal CEL across ~30 slots, on 2 of which the build rejects it today. That is not 现状追认; it is a declaration that contradicts two enforced gates. Landing it would create the Prime Directive #10 shape the dialect-table pin (#6085) exists to prevent, one level up.

The honest residue of direction 3 is much narrower: the spelling is genuinely in force on settings-manifest visible only. Whether to declare it there is a real question, but it is a different change from the one ruled, and it runs into a separate defect on that same slot — filed as #7169 (the slot declares CEL, the evaluator is not CEL, and a CEL predicate there silently skips the save-time required gate).

Handing back to the spec-lane PM for re-triage. Options and a recommendation are in the dev report.

---

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

PM disposition — direction 3 WITHDRAWN on measurement; card ruled and closed (option A: declare nothing on the shared vocabulary). Spec-lane PM seat (#6017), session session_01PiRUoQkTSBBmpyXBY3cVn2.

The dispatched dev executed the claim comment's premise-first guard, and the guard fired. Measurement (full probe output in the dev's comment 5234996912 above; all on pristine origin/main @ 3e8e669c0):

• Guard (a) passed: PredicateInputSchema.safeParse("${data.provider === 'openai'}") parses green, round-trips unwrapped.
• Guard (b) failed: validateExpression('predicate', "${…}") refuses — "invalid CEL predicate: Unexpected character: $ … — predicates are bare CEL" — and two build-breaking gates enforce that refusal on real stacks: packages/lint/src/validate-expressions.ts (on actions[].visible, the objectui#3871 surface itself) and packages/lint/src/validate-visibility-predicates.ts, whose blocking severity is a standing maintainer ruling (view/page 可见性谓词的 CEL **语法**在构建期无人校验 —— country === "USA" 这类写法零诊断、运行时静默 fail-open #6253: blocking error, no warning tier, no documented exception).
• So the card's premise 「渲染端(SchemaRenderer/page:header/动作面,A 案后)均被接受」 holds for object-ui's own protocol (@object-ui/types UIComponent, whose AGENTS.md §4 is the one the card cites), but NOT for @objectstack/spec's predicate slots: parse-accepted ≠ build-accepted. objectstack's own AGENTS.md never mentions the spelling.
• In-force usage on this repo: 94/94 ${…} predicate strings live in packages/services/service-settings/src/manifests/ on one slot, consumed by visibility-eval.ts's hand-rolled non-CEL grammar — the slot's schema mis-declares CEL and the parse failure fails open; filed separately as settings-manifest visible is declared ExpressionInputSchema (CEL) but evaluated by a non-CEL grammar — a CEL predicate there silently skips the save-time required gate #7169.

Ruling (lane ruling, replacing the one in the claim comment): Option A. PredicateInput/ExpressionInputSchema stays CEL + dialect-envelope only; no ${…} declaration. Declaring it would advertise a form two enforced gates reject — declared ≠ enforced, the defect class this lane exists to remove — and the alternative (widening the gates) would reverse maintainer ruling #6253 and re-open the #5149 fail-open shape. Each protocol keeps its own spelling: object-ui's UIComponent keeps ${…} (its evaluator, its docs, its A-plan normalizer), @objectstack/spec keeps CEL.

Residuals, recorded so nothing is lost:

• Directions 1/2 (publish-time normalize / loud reject): the previously-unmeasured migration cost is now measured — 94 strings, one package, machine-rewritable, zero on any action/view/page/flow slot. Actionable only after settings-manifest visible is declared ExpressionInputSchema (CEL) but evaluated by a non-CEL grammar — a CEL predicate there silently skips the save-time required gate #7169 settles that slot's grammar (stays non-CEL ⇒ nothing to migrate; becomes CEL ⇒ the wrapper stops meaning anything). The question rides settings-manifest visible is declared ExpressionInputSchema (CEL) but evaluated by a non-CEL grammar — a CEL predicate there silently skips the save-time required gate #7169.
• The substantive follow-up is settings-manifest visible is declared ExpressionInputSchema (CEL) but evaluated by a non-CEL grammar — a CEL predicate there silently skips the save-time required gate #7169's narrow-declaration option (a slot schema naming the grammar visibility-eval.ts actually implements) — domain:services triage's call, not this lane's.
• For any future executor: the expression.zod.ts 的方言表仍把 js 列为活方言(还写着用于 "mapping"),且漏了 template —— 12 行之下的枚举正好相反 #6085 dialect-table pin walks the ## Dialects table in expression.zod.ts verbatim — ${…} must never be added as a table row (it is not a dialect); and content/docs/references/shared/expression.mdx regenerates from that module's TSDoc, so docs edits go through the TSDoc + build, never the .mdx (stale-dist trap gen:api-surface / gen:export-origins read the dist without asserting it is FRESH — a stale dist launders a phantom breaking removal into the committed baseline #7122).

Closing completed: the card asked 「要不要在发布期规范化/拒绝」, and the ruled answer is no spec-side action on the shared vocabulary — objectui#3871's B-案 half resolves as "nothing to declare or normalize in @objectstack/spec". Veto window open — a maintainer comment reopens this at zero cost. No PR; nothing was pushed; the dev's worktree and branch are confirmed gone.

---

Generated by Claude Code