fix(docs,lint): 两处裸引用公式样例改回 canonical,并补上公式样例的 CEL 语义门 (#5116) (#5140)

* fix(docs,lint): canonical `record.` prefixes in two formula examples + a CEL semantic gate (#5116)

#5026 activated the field-formula check in validate-expressions.ts and its
real-metadata sweep found two doc examples teaching the bare-reference form:

  content/docs/data-modeling/fields.mdx:230   'quantity * price * (1 - discount / 100)'
  content/blog/context-window-is-the-constraint.mdx:108  cel`amount * probability`

A bare reference in a record-scoped CEL expression does not throw — it resolves
to nothing and the expression silently evaluates to null. Both are corrected to
the canonical `record.` form, verified by loading each into a minimal
spec-valid stack and running the activated validateStackExpressions (RED before,
GREEN after). packages/spec/src/data/field.test.ts:363 demonstrated the same
wrong spelling and is corrected too; its assertion is unchanged.

Adds `@objectstack/lint`'s check:doc-formula-expressions, the semantic gate that
was missing: check:doc-authoring judges literal SHAPE and check:skill-examples
runs tsc, so a formula that compiles and is semantically wrong passed both
(`expression` is typed `string`). The verdict is validateExpression imported
from @objectstack/formula — the same call `os build` makes, not a lookalike.

The discriminator is the design: `expression:` carries three unrelated contracts
in this corpus (record-scoped CEL, flow-flattened predicate where a bare ref is
CORRECT, and a cron string), so sites are opted in only by parsed structure —
`Field.*({ expression })` or `type: 'formula'` beside `expression`. A block that
looks like it carries one but cannot be extracted is a hard error, not a skip.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018iARDqtrhQgz6fVHDeDkbQ

* fix(lint): write the dedup key's control chars as escapes, not raw bytes (#5116)

`check:nul-bytes` (#4890) caught a raw NUL at
packages/lint/scripts/check-doc-formula-expressions.mjs:258 — offset 11513,
well outside git's 8000-byte binary sniff, which is exactly the blind spot that
gate exists for. A scan for every control byte found a second one beside it
(0x01, which the NUL gate does not even look for), both in the extraction
dedup key.

Replaced by script with their `\u….` escape sequences — byte-equivalent at
runtime, so the verdict is unchanged: the gate's self-test still passes 11/11
and the corpus scan still reports the same 22 clean examples across 375 files
/ 1408 TS blocks. Added a comment saying both control chars are deliberate and
must stay escaped, since a raw one is invisible in review and a literal NUL
makes grep/ripgrep treat the whole file as binary and silently return zero
matches.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018iARDqtrhQgz6fVHDeDkbQ

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: xuyushun441-sys

.changeset/doc-formula-example-cel-gate.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(docs,lint): 修正两处裸引用公式样例,并给公式样例补一道 CEL 语义门 (#5116)
+
+#5026 把字段公式校验从 `f.formula`(spec 按名拒绝的别名)收敛到声明的
+`f.expression`,**激活了一条从未跑过的检查**。它的真实元数据扫描顺带发现文档和博客
+里有两处公式样例写的是**裸引用**:
+
+- `content/docs/data-modeling/fields.mdx` — `'quantity * price * (1 - discount / 100)'`
+- `content/blog/context-window-is-the-constraint.mdx` — ``cel`amount * probability` ``
+
+裸引用在 CEL 里不报错,而是**静默求值为 null**:公式表达式把记录绑定在 `record`
+命名空间下,顶层的 `quantity` 什么也解析不到。照这两行写出来的元数据,在 #5026
+之后会被 `os build` / `os validate` 判红 —— 文档教的写法和平台的门直接矛盾。两处
+都已改成 canonical 的 `record.` 前缀形式。
+
+**新增 `@objectstack/lint` 的 `check:doc-formula-expressions`**,堵住让这两条长期
+存活的那个洞。`check:doc-authoring` 看的是字面量的**形状**,`check:skill-examples`
+对标记块跑 `tsc --noEmit` —— 两者之间,"能编译但 CEL 写错"的样例没有任何门:
+`expression` 的类型就是 `string`,`'quantity * price'` 和
+`'record.quantity * record.price'` 编译得一样好,而只有后者能用。
+
+判决直接 import `@objectstack/formula` 的 `validateExpression` —— 和 `os build`
+走的是同一个调用,不是仿制品。于是文档是被**规则本身**把关,而不是被规则的一种方言
+把关(Prime Directive #12)。
+
+门的难点不在判决而在**判据**:同一个 `expression:` 键在语料里承载至少三种互不相干的
+契约 —— 记录作用域的 CEL 公式、flow 的扁平作用域谓词(那里裸引用是**对的**)、以及
+`schedule` 下压根不是 CEL 的 cron 串。按键名匹配会把后两类全部误判为红。所以它只认
+**解析后的结构**,且只认两种不可能有歧义的形状:`Field.*({ expression })`,以及
+`type: 'formula'` 与 `expression` 并列的对象字面量。无法提取的块**报错而不是跳过**
+("absence must be loud")。
+
+覆盖面是明说的,不含糊:只看 TS/TSX 代码块、只看能静态取出的表达式源、不做字段存在性
+校验(文档片段没有对象声明)、flow / action / validation 谓词**刻意不在范围内**。

.github/workflows/lint.yml

@@ -588,6 +588,30 @@ jobs:
       - name: Check skills TypeScript examples compile
         run: pnpm --filter @objectstack/spec run check:skill-examples
 
+      # The SEMANTIC half of the same surface (#5116). The gate above proves a
+      # formula example COMPILES; it cannot prove the CEL is right, because
+      # `expression` is typed `string` — `'quantity * price'` type-checks exactly
+      # as well as `'record.quantity * record.price'`, and only the second one
+      # works. A bare reference does not throw at runtime either: it resolves to
+      # nothing and the expression silently evaluates to null. That is how two doc
+      # examples stayed wrong until #5026's activation sweep found them — one of
+      # them in content/blog/, which check:skill-examples does not scan at all.
+      #
+      # The verdict is `validateExpression` imported from @objectstack/formula —
+      # the same call `os build` / `os validate` makes — never a lookalike, so the
+      # docs are gated by the rule rather than by a dialect of it. Hence its home
+      # in packages/lint (which owns that verdict) and its place in this
+      # post-build job: it reads the built formula package like its neighbours.
+      #
+      # Deliberately narrow: a site is opted in only by parsed structure that can
+      # mean nothing else (`Field.*({ expression })`, or `type: 'formula'` beside
+      # `expression`), because the corpus spells three unrelated contracts with
+      # the one key `expression:` — a cron string, and a flow-scoped predicate
+      # where a bare reference is CORRECT, are the other two. Self-test first,
+      # both directions.
+      - name: Check docs formula examples are valid CEL
+        run: pnpm --filter @objectstack/lint run check:doc-formula-expressions
+
       # Same anti-drift class as the gates above, for the generated translation
       # bundles in packages/platform-objects/src/apps/translations/. Nothing
       # regenerated them either, so they rotted three ways at once (#3670):

content/blog/context-window-is-the-constraint.mdx

@@ -105,7 +105,7 @@ export const Opportunity = ObjectSchema.create({
     probability: Field.percent({ label: 'Probability', defaultValue: 0.5 }),
     expected_revenue: Field.formula({
       label: 'Expected Revenue',
-      expression: cel`amount * probability`,
+      expression: cel`record.amount * record.probability`,
     }),
   },
 });

content/docs/data-modeling/fields.mdx

@@ -227,7 +227,7 @@ profile_image: Field.avatar({ label: 'Profile Image' }),
 // Formula
 total: Field.formula({
   label: 'Total',
-  expression: 'quantity * price * (1 - discount / 100)',
+  expression: 'record.quantity * record.price * (1 - record.discount / 100)',
 }),
 
 // Summary (roll-up)

packages/lint/package.json

@@ -22,7 +22,8 @@
     "build": "tsup",
     "dev": "tsc -w",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "check:doc-formula-expressions": "node scripts/check-doc-formula-expressions.mjs --self-test && node scripts/check-doc-formula-expressions.mjs"
   },
   "dependencies": {
     "@marcbachmann/cel-js": "^8.0.0",