You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 9122271
Browse filesBrowse the repository at this point in the historyBrowse 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>
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.
Copy file name to clipboardExpand all lines: skills/objectui/evals/schema-expressions.json
+4-3Lines changed: 4 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -20,12 +20,13 @@
20
20
},
21
21
{
22
22
"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.",
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.
13
11
14
12
Key files (for reference, not for editing):
15
13
-`packages/core/src/evaluator/ExpressionEvaluator.ts` — main entry point
@@ -55,11 +53,6 @@ this rule. The four cases that decide most schemas:
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
299
303
client-and-server enforcement split, the invariant-vs-transition-gate choice,
300
304
and the protocol-17 removal of the `conditionalRequired` alias are all there.
301
305
Author them in the canonical tagged-template form that skill teaches
@@ -332,9 +336,8 @@ Three renderer-side facts that live nowhere else:
332
336
operator, value }` form and the `{ expression: "${…}" }` template form are
333
337
retired, refused at the schema door by name with the respelling. A STORED
334
338
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.
338
341
-**`data.*` is the trap in a row predicate.** A row predicate binds ONE root,
339
342
`record.*`; a bare `status` or `data.status` is retired there and faults on
340
343
the runtime engine (`Unknown variable`), under each surface's existing error
@@ -637,6 +640,6 @@ When an expression isn't working:
637
640
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.)
638
641
2. Is the `${}` syntax correct? Check for unmatched braces.
639
642
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.
641
644
5. Does the expression use a blocked pattern? Check for constructors, `eval`, `window`, etc.
642
645
6. Is type coercion causing issues? `${0 && "yes"}` returns `0`, not `false`.
|`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