Skip to content

Commit 9122271

Browse files
docs(skills): objectui teaches CEL for bare-string predicates (#27889)
<!-- claude-projects-attribution: {"github_login":"os-elon-musk"} --> _Requested by **Elon** · [project thread](https://claude.ai/code/project/chan_01WedDzV26nniwxv7jC88B9D?thread=cmsg_01WedDzV26nniwxv7jC88B9DSWGkYzR3Hx2Jbcc8B45cVD)_ domain:skills#2 · os-elon-musk · session_016WV4d1Ffw7D64ARzogMukj Fixes #27587 ## 维护者速读 - 改了什么:`skills/objectui` 里的裸字符串谓词示例全部改成 CEL 写法(`==`、`!=`、`&&`、`!`),运算符清单注明只适用于 `${…}` 模板;指南新增一张 JS → CEL 对照短表;eval 2 改为给出 JS 写法、要求改写成 CEL。 - 为什么改:#27584 合入后,控制台把裸字符串谓词按 CEL 读(和规范、服务端一致),技能还在教 `===` 这类 JS 写法,照抄的 AI 写出的 `hidden` / `visibleWhen` 会出错并把节点藏起来。 - 风险与回滚:只改文档与 eval,无代码、无 schema 变化;回滚即 revert 本 PR。三个文件都在令牌天花板内,没有抬任何一行。 - 先看:`skills/objectui/guides/schema-expressions.md` 的 "Condition fields" 一节(新增的 FROM → TO 清单)。 - 两分钟验证:`node scripts/check-skills-token-ratchet.mjs` 全绿;`pnpm --dir ui exec vitest run scripts/__tests__/check-skill-eval-tokens.test.ts` 29/29 通过。 - 需要你做的:本 PR 欠一次契约复审(fable 档,席位负责),落地为 Tier H,需治理审批人批准。 ## What changes - `rules/protocol.md`: the evaluated-fields table shows `"hidden": "data.status == 'draft'"` (was `===`), and the `visibleWhen` row says a bare string is CEL. - `guides/schema-expressions.md`: - The architecture overview says a bare condition string is CEL, evaluated by `@objectstack/formula` as on the server; the recursive-descent parser is named for `${…}` templates only. - "Supported operators (full list)" now says it is the `${…}` grammar only. - "Condition fields": the bare example is `data.status != 'active'`, and a FROM → TO list follows: `===` / `!==` → `==` / `!=`; `list.includes(x)` → `x in list`, `s.includes('x')` → `s.contains('x')`; `list.length` → `size(list)`; a `data.*` key the scope may lack (`data.x == 1`, `!data.x`, `?.`, `??`) → `has(data.x) && data.x == 1`. - The row-predicate bullet says only a `${…}` `condition` still reads on the legacy engine; a bare `===` / `.includes()` faults on CEL. - The field-level section no longer says node-level conditions run on `SafeExpressionParser`; troubleshooting item 4 says "a bare CEL string or a `${}` template". - Paid down in the same file: the bindable-text-keys paragraph under "What gets expression-evaluated" restated troubleshooting item 1 word for word and is cut. - `evals/schema-expressions.json`: eval 2 now hands over `"visibleWhen": "data.role === 'admin' && data.status === 'active'"` and expects the CEL rewrite (`must_contain` `CEL` and `status == 'active'`, a token the guide teaches). - `.changeset/27587-objectui-skill-teaches-cel-predicates.md`: `@objectstack/skills` patch. ## Why PR #27584 (#27457) made the console read a bare-string predicate as CEL, the way `@objectstack/spec` defines it and the server reads it. Its changeset carries `not-required (no-migration-prescription)`, so the skill is where the JavaScript spellings get redirected. Until now the skill taught those spellings, and an agent following it wrote a gate that faulted and hid the node. ## Verification Each FROM → TO row was measured on the console's `ExpressionEvaluator.evaluateCondition` (built `@objectstack/formula`, `throwOnError` and `onFault`), on this branch's base: | Spelling | Console reading | |---|---| | `data.status === 'draft'` | parse fault, `Unexpected character: =` | | `data.status == 'draft'` | `true` | | `data.tags.includes('vip')` / `data.name.includes('urgent')` | runtime fault, `no matching overload for 'dyn.includes(string)'` | | `'vip' in data.tags` / `data.name.contains('urgent')` | `true` | | `data.items.length > 0` | runtime fault, `No such key: length` | | `size(data.items) > 0` / `data.items.size() > 0` | `true` | | `data.missing == 'x'`, `!data.missing` | runtime fault, `No such key: missing` | | `has(data.missing)` / `has(data.missing) && data.missing == 'x'` | `false`, no fault | | `data.missing?.x` / `data.missing ?? 'd'` | parse fault | | `data.isAuthenticated && data.permissions.canEdit`, `!data.canPerformAction \|\| data.isLocked`, `!data.hasPermission` (the guide's other bare examples) | evaluate, no fault | The fault policy quoted in the guide ("a visibility gate hides the node, `disabled` disables") is the one `SchemaRenderer`'s `visibilityFaultOutcome` and #27584's changeset state. Re-grep of `skills/objectui/**`, evals included, for `===`, `!==`, `&&`, `||`, `.includes(`, `.length`: the remaining hits are `${…}` templates (which keep their own grammar), TypeScript / JSX code, or eval `must_not_contain` JSX strings. No other bare predicate uses a JS-only spelling. Token ratchet (`node scripts/check-skills-token-ratchet.mjs`), priced tokens: | File | Before | After | Ceiling | |---|---:|---:|---:| | `skills/objectui/guides/schema-expressions.md` | 6565 | 6562 | 6571 | | `skills/objectui/rules/protocol.md` | 4366 | 4364 | 4368 | | `skills/objectui/evals/schema-expressions.json` | 536 | 531 | 536 | No ceiling row moves. Gates: `node scripts/pm/dispatch-gates.mjs --commands` derives 45 families on this head; all 45 ran locally after a whole-tree `turbo run build` and exited 0; `dispatch-gates --ran` reconciles 45 derived / 45 run / 0 NOT-MEASURED. Clause-②: no Metadata-protocol: none ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (not touched) - [x] 2. Every name I added uses the casing for its kind. (no names added) - [x] 3. No formatter ran. (`pnpm lint` not run: no source file is touched; the derived gate families are listed under Verification.) - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: n/a. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English (except the `## 维护者速读` block). - [x] The *Before Submitting* list in CONTRIBUTING.md is done. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016WV4d1Ffw7D64ARzogMukj --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2fc3861 commit 9122271

4 files changed

Lines changed: 40 additions & 24 deletions

File tree

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): objectui teaches CEL for a bare-string predicate, with a FROM → TO list for the JavaScript spellings
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
- **Before.** `skills/objectui` taught bare predicates in the legacy JavaScript grammar: `"hidden": "data.status === 'draft'"` in `rules/protocol.md`, `data.status === 'active'` and `data.status !== 'active'` in `guides/schema-expressions.md`, and an operator list (`===`, `!==`, `.includes()`, `.length`) that read as condition syntax. Since #27584 the console reads a bare string in a predicate key as CEL, as the spec defines it and the server reads it, so an agent following the skill wrote a gate that faulted and hid the node.
11+
- **Now.** Every bare-predicate example is CEL. The guide says a bare condition string is CEL on `@objectstack/formula` and that the operator list is the `${…}` template grammar only, and it gives a FROM → TO list measured on the console's evaluator: `===` / `!==` → `==` / `!=`; `list.includes(x)` → `x in list`, `s.includes('x')` → `s.contains('x')`; `list.length` → `size(list)`; a `data.*` key the scope may lack → `has(data.x) && …`, because CEL faults on a missing key. The row-predicate bullet says only a `${…}` condition still reads on the legacy engine. Eval 2 in `evals/schema-expressions.json` hands over a JS-syntax predicate and expects the CEL rewrite.
12+
- No schema, key or behaviour changes.

‎skills/objectui/evals/schema-expressions.json‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,13 @@
2020
},
2121
{
2222
"id": 2,
23-
"prompt": "I need to make a button visible only to admin users AND only when the record status is 'active'. Also, the button should show the record owner's name. Show me the correct schema.",
24-
"expected_output": "Produces a schema with combined visible/hidden expression using && operator, and does not put the owner name in props.label — that envelope is evaluated and then discarded. The name is resolved in the host, or carried on a text node's content.",
23+
"prompt": "My button should show only to admins AND only while the status is 'active', with the owner's name on it. I wrote \"visibleWhen\": \"data.role === 'admin' && data.status === 'active'\" and it never shows. Fix the schema.",
24+
"expected_output": "Says a bare predicate is CEL, so === faults and hides the node; rewrites it with == and &&. The owner name goes on a text node's content, not props.label.",
2525
"files": [],
2626
"assertions": {
2727
"must_contain": [
28-
"visible",
28+
"CEL",
29+
"status == 'active'",
2930
"&&",
3031
"${"
3132
],

‎skills/objectui/guides/schema-expressions.md‎

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,8 @@ Writing and debugging dynamic expressions in ObjectUI schemas. The expression sy
66

77
ObjectUI uses a two-tier expression evaluator:
88

9-
1. **Template expressions** — strings containing `${...}` placeholders: `"Hello ${user.name}"`
10-
2. **Condition expressions** — raw boolean expressions without wrappers: `data.status === 'active'`
11-
12-
Both are parsed by a **recursive-descent parser** (no `eval()`, no `new Function()`). This means expressions are CSP-safe and work under strict Content Security Policy headers.
9+
1. **Template expressions** — strings containing `${...}` placeholders: `"Hello ${user.name}"`, parsed by a **recursive-descent parser** (no `eval()`, no `new Function()`), so CSP-safe.
10+
2. **Condition expressions** — a bare string in a predicate key: `data.status == 'active'`. It is **CEL**, evaluated by `@objectstack/formula`, as on the server.
1311

1412
Key files (for reference, not for editing):
1513
- `packages/core/src/evaluator/ExpressionEvaluator.ts` — main entry point
@@ -55,11 +53,6 @@ this rule. The four cases that decide most schemas:
5553
{ "type": "text", "content": "${data.customer.name}" }
5654
```
5755

58-
`title` / `label` / `value` / `description` are template-evaluated on the types
59-
that declare them -- `statistic` (`label` / `value` / `description`), `card`
60-
(`title` / `description`), `button` (`label`) -- and read raw everywhere else.
61-
The set is closed and declared in `@objectstack/spec`.
62-
6356
## Template expression syntax (`${}`)
6457

6558
### Basic property access
@@ -79,6 +72,9 @@ ${!isLocked} → boolean negation
7972
```
8073

8174
### Supported operators (full list)
75+
76+
The `${…}` grammar only. A bare condition string is CEL — see "Condition fields".
77+
8278
- Arithmetic: `+`, `-`, `*`, `/`, `%`
8379
- Comparison: `>`, `<`, `>=`, `<=`, `==`, `===`, `!=`, `!==`
8480
- Logical: `&&`, `||`, `!`
@@ -237,7 +233,7 @@ name, so calls are case-insensitive.
237233
### Syntax options
238234

239235
The node-level condition keys are `visibleWhen` (show), `hidden` and
240-
`disabled`. Each takes a boolean, a `${}` template, or a raw expression:
236+
`disabled`. Each takes a boolean, a `${}` template, or a bare CEL string:
241237

242238
<!-- os:check -->
243239
```jsonc
@@ -251,9 +247,19 @@ The node-level condition keys are `visibleWhen` (show), `hidden` and
251247

252248
<!-- os:check -->
253249
```jsonc
254-
{ "hidden": "data.status !== 'active'" } // raw expression (no ${} needed)
250+
{ "hidden": "data.status != 'active'" } // bare string = CEL (no ${} needed)
255251
```
256252

253+
A JS-only spelling in a bare string faults: a visibility gate hides the node,
254+
`disabled` disables. FROM → TO:
255+
256+
- `a === b` / `a !== b` → `a == b` / `a != b`
257+
- `list.includes(x)` → `x in list`; `s.includes('x')` → `s.contains('x')`
258+
- `list.length` → `size(list)`
259+
- a `data.*` key the scope may lack (`data.x == 1`, `!data.x`, `?.`, `??`) →
260+
`has(data.x) && data.x == 1`, `!has(data.x) || !data.x`: CEL faults on a
261+
missing key
262+
257263
`visibleOn` / `hiddenOn` / `disabledOn` are retired and refused by name —
258264
rename to `visibleWhen` / `hidden` / `disabled`; the value is unchanged.
259265

@@ -292,10 +298,8 @@ rename to `visibleWhen` / `hidden` / `disabled`; the value is unchanged.
292298
## Field-level conditional rules (`visibleWhen` / `readonlyWhen` / `requiredWhen`)
293299

294300
These live on the **object's field metadata**, are written in CEL, and are
295-
evaluated by `@objectstack/formula` -- a different tier from the node-level
296-
conditions above, which are schema/widget-level and run on the recursive-descent
297-
`SafeExpressionParser`. **How to author them is the `objectstack-data` skill's
298-
job**, under "Conditional Field Rules": the predicate scope, the client-only vs
301+
evaluated by `@objectstack/formula`. **How to author them is the
302+
`objectstack-data` skill's job**, under "Conditional Field Rules": the predicate scope, the client-only vs
299303
client-and-server enforcement split, the invariant-vs-transition-gate choice,
300304
and the protocol-17 removal of the `conditionalRequired` alias are all there.
301305
Author them in the canonical tagged-template form that skill teaches
@@ -332,9 +336,8 @@ Three renderer-side facts that live nowhere else:
332336
operator, value }` form and the `{ expression: "${…}" }` template form are
333337
retired, refused at the schema door by name with the respelling. A STORED
334338
legacy rule still renders through the shared evaluator (a compatibility read,
335-
not an authoring form); a `condition` in legacy-only syntax (`${…}`, `===`,
336-
`.includes()`) still routes to the old engine with a one-time deprecation
337-
warning -- write CEL.
339+
not an authoring form); only a `${…}` `condition` still routes to the old
340+
engine. `===` or `.includes()` faults on CEL. Both warn once -- write CEL.
338341
- **`data.*` is the trap in a row predicate.** A row predicate binds ONE root,
339342
`record.*`; a bare `status` or `data.status` is retired there and faults on
340343
the runtime engine (`Unknown variable`), under each surface's existing error
@@ -637,6 +640,6 @@ When an expression isn't working:
637640
1. **Which key is it on, and does that type declare the key?** `content` and the predicate keys are evaluated and read on every type. `title` / `label` / `value` / `description` are evaluated **only on the types that declare them** — `statistic` (`label` / `value` / `description`), `card` (`title` / `description`), `button` (`label`) — and read raw everywhere else, including on a namespaced spelling such as `ui:statistic`. A `${...}` inside a `props` envelope is evaluated and then discarded. (A `properties` envelope is the one that is evaluated *and* hoisted onto the node — see [`rules/protocol.md`](../rules/protocol.md) for why that is recorded, not recommended.)
638641
2. Is the `${}` syntax correct? Check for unmatched braces.
639642
3. Is the data actually available in scope? Check what the host published on `PredicateScopeProvider` — ⛔ not `SchemaRendererProvider`'s `dataSource`, which publishes no expression root.
640-
4. For conditions: `visibleWhen` / `hidden` / `disabled` take a raw expression or a `${}` template; the `On` spellings are refused.
643+
4. For conditions: `visibleWhen` / `hidden` / `disabled` take a bare CEL string or a `${}` template.
641644
5. Does the expression use a blocked pattern? Check for constructors, `eval`, `window`, etc.
642645
6. Is type coercion causing issues? `${0 && "yes"}` returns `0`, not `false`.

‎skills/objectui/rules/protocol.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ value must clear before it reaches the screen.
1313
| Field | Evaluation Type | Return Type | Example |
1414
|---|---|---|---|
1515
| `content` | Template (`${}`) | string | `"content": "Total: ${data.total}"` |
16-
| `visibleWhen` | Condition | boolean | `"visibleWhen": "data.permissions.canView"` (raw expression, no `${}`) |
17-
| `hidden` | Condition | boolean | `"hidden": "data.status === 'draft'"` |
16+
| `visibleWhen` | Condition | boolean | `"visibleWhen": "data.permissions.canView"` (bare string = CEL) |
17+
| `hidden` | Condition | boolean | `"hidden": "data.status == 'draft'"` |
1818
| `visible` | Condition | boolean | `"visible": "${data.isActive}"` |
1919
| `disabled` | Condition | boolean | `"disabled": "!data.hasPermission"` |
2020
| `title` / `label` / `value` / `description` | Template (`${}`) | Preserves original type | **Only on the component types the spec declares** — see "Rule: Bindable Text Keys" below. `"value": "${data.total}"` on a `statistic` renders the number. |

0 commit comments

Comments
 (0)