[finding] EvalContext.api declares os.exists / os.count / os.lookup and buildScope() binds none of them — a predicate that calls one is refused, and an unevaluable predicate rejects the write

[os-elon-musk]

读数

packages/formula/src/types.ts:66-75 在 EvalContext 上声明了一块 kernel API，并用文档注释点名了它支持的三个 CEL 函数：

/**
 * Optional kernel API for `os.exists / os.count / os.lookup`.
 * Implemented opportunistically by call sites that have a query engine.
 */
api?: {
  exists?: (object: string, predicate: Expression) => boolean;
  count?: (object: string, predicate: Expression) => number;
  lookup?: (object: string, id: string) => Record<string, unknown> | null;
};

而 packages/formula/src/stdlib.ts:309-326 里构造 os 作用域的那段，只读三个字段：

const os: Record<string, unknown> = {};
if (ctx.user !== undefined) { … os.user = currentUser; }
if (ctx.org  !== undefined) os.org = ctx.org;
if (ctx.env  !== undefined) os.env = ctx.env;
if (Object.keys(os).length > 0) scope.os = os;

ctx.api 在整个 stdlib.ts 里一次都没有被读取：

$ grep -n "os\.exists\|os\.count\|ctx\.api" packages/formula/src/stdlib.ts
(无输出)

⇒ 三个函数一个都没绑。 调用方即使老老实实传了 api，作用域里也不会出现它们。

为什么这是 (c) 类而不只是一个未实现的可选项

⚠️ 这块声明是会被当真的。它有类型、有字段名、有一句说明「Implemented opportunistically by call sites that have a query engine」—— 读到它的人（或 AI）会合理地得出结论：只要调用方有查询引擎，os.lookup(...) 在谓词里就能用。

实际写下去拿到的是运行时错误：

runtime: found no matching overload for 'dyn.lookup(string, dyn)'

而且这个错误不是惰性的。 下游实测：一条不可求值的谓词会拒绝这次写入（objectstack#4649 的形状）。⇒ 照着这块声明写一条校验规则，结果是该对象上的每一次写入、插入更新全部被拒。

「声明存在、实现为零、失败形态是拒写」——这三条凑齐，就是让作者写出运行时静默拒收的元数据的那个陷阱。

下游实例（本条是怎么被发现的）

hotcrm #1915（REQ-0003）的需求记录第 128 行把一道能力闸钉在 crm_opportunity 的 validations[] 上，要它读所属客户的分类。施工席逐条量了三条路，全部走不通：

1. checkPredicate() 以 { record: merged, previous } 求值 —— 都是本对象的普通数据，不传 api。
2. 关系穿透不行：record.crm_account.type → runtime: No such key: type。
3. os.lookup("crm_account", …) 也不行 —— 就是本卡这条。

⇒ 那张卡的规格前提被证伪，闸门无法按记录指定的构造写出来。一个平台侧的死声明，直接让一条下游需求的落地方案作废。

⛔ 本卡不预判的事

⛔ 不预判该实现还是该删。两条都成立，取舍要量：

• 实现 —— 在 buildScope() 里绑上 ctx.api 提供的三个函数。⚠️ 但谓词求值里做 I/O 是个真问题：同步 CEL 求值 vs 可能异步的查询、N+1、以及 RLS 谓词里做 lookup 的权限语义。这三条都要先答。
• 删掉声明 —— 若判定谓词面不该能读别的对象，那就把这块 api 从 EvalContext 上移除，并在移除处写明理由。⚠️ 这同样是修复：今天的害处来自「声明存在」，不来自「实现缺失」。

⛔ 也不预判 exists / count 与 lookup 是否同一个结论 —— 三个的代价不一样（前两个可以下推成查询，lookup 是取整行），要分开量。

查重词

EvalContext api lookup · buildScope os scope · os.exists os.count · declared but never bound · no matching overload dyn.lookup

---

Generated by Claude Code

[huangyiirene]

维护者速读

平台的公式引擎(写校验规则、权限谓词用的那个)在类型上声明了三个函数 os.exists / os.count / os.lookup,还配了一句说明「有查询引擎的调用方会实现它们」。实际上一个都没接上。

后果不是「这个功能暂时不能用」,而是写下去会把整张表锁死:谓词求不出值 ⇒ 这次写入被拒 ⇒ 照着这个声明写了一条校验规则的对象,每一次新增和修改都会失败。而声明本身读起来完全像个承诺,AI 和人都会当真 —— hotcrm 那边(#1915)就是照它设计的,施工时才发现整条路不通,需求方案作废。

要么把它接上,要么把这个声明删掉。接上不是小事:谓词求值是同步的,而查询是异步的;一条规则配一次查询会变成 N+1;最要命的是权限 —— 行级安全谓词里做 lookup,等于让一条安全规则去读它可能无权读的数据。这三个问题没答之前没人能安全地接。

删声明则是立刻止血、零成本、可回退:今天的害处来自「声明存在」,不来自「实现缺失」。至于「谓词到底该不该能读别的对象」,那是一道独立的能力设计题,值得单独立卡、单独给 appetite,并带上 hotcrm 这个真实拉动。

⚠️ 顺带一提:can 那张卡(#18545)您已经裁过一个同构的问题,裁的是「主体从求值上下文取」—— 也就是说「CEL 函数从上下文拿数据」这条路您已经认可了。所以选项 A 不是没有先例,只是它要答的那三个问题比 can 难得多(can 读的是已在上下文里的主体,lookup 要发起一次新的查询)。

席位推荐 B。请裁:A / B / C?

---

选项

	做法	代价	可回退
A	在 buildScope() 里接上 ctx.api 提供的三个函数	必须先答同步/异步、N+1、RLS 谓词内 lookup 的权限语义三问;是能力新增	难 —— 一旦发布就是已声明契约
B(推荐)	从 EvalContext 删掉这块 api 声明,删除处写明理由;另立一张「谓词能否跨对象读取」的能力设计卡,携 hotcrm #1915 作拉动证据	低;hotcrm 的需求仍然没有答案,但它今天本来就没有	易 —— 重新声明是一次提交
C	按 ADR-0049 第 2 态标 experimental,留着不接	低	易

⛔ 为什么不推荐 C:ADR-0049 确实允许「显式标注为尚未强制」这一态,但本例的害处载体是类型字段本身 —— AI 读到 api?: { lookup?... } 就会用它,一个 docblock 上的 experimental 标注拦不住它,陷阱只是变浅没有消失。且维护者 2026-08-27 已裁「项目在创业阶段,用户也很少,短期不考虑渐进」,C 正是那条裁决排除的渐进态。

⛔ 本卡不裁:exists / count 与 lookup 是否同一个结论。前两个可下推成查询、lookup 要取整行,代价不同 —— 若裁 A,三者要分开定。

Governing text: 维护者 2026-09-10 裁决,逐字:「我们的项目以objectstack 协议为准,文档应该以实际实现为准。协议不正确的应该先修改协议。」⇒ 声明而未兑现是实现缺口,补实现或退役,⛔ 不在消费端收窄。本卡的 A 与 B 正是该裁决给出的两个合法出口;C 是 ADR-0049(docs/adr/0049-no-unenforced-security-properties.md,Accepted 2026-06-15)三态中的第 2 态。ADR-0049 的理由句与本例同形:「A security property that parses but does nothing is worse than absent: it produces a false sense of compliance.」

---

四棱

① 实际业务需求 —— 有一个具名拉动,但只有一个。 hotcrm #1915(REQ-0003)要在 crm_opportunity 的 validations[] 上读所属客户的分类,施工席逐条量了三条路全部走不通,本卡是第三条。⇒ 跨对象读取在谓词里确有真实场景,⛔ 不是投机能力面。但它是一个场景,且 os.exists / os.count 至今零消费方 —— 拉动指向的是「读一个关联字段」,⛔ 不是指向声明中的这整块 API。⇒ 该轴支持立卡答能力题,⛔ 不支持照着现有声明整块实现。

② 项目长远合理性 —— 明确指向 B。 「声明即强制」是本项目的架构底线,一块零实现的声明是它的反面。B 不预设能力题的答案:删掉一个今天为假的声明,⛔ 不关闭任何未来形态;真要实现时重新声明是一次提交。A 则是在三个未答的架构问题上先付款。⚠️ 该轴权重恒 ≥50%,此处与③④同向,⛔ 无需权衡。

③ 防 AI 写元数据犯错 —— 本卡最尖的一棱,指向 B。 陷阱形态完整:有类型、有字段名、有一句像承诺的说明,失败形态是拒写。 AI 照它写一条校验规则,拿到的不是「函数不可用」,而是该对象上每一次写入全部被拒。这正是框架点名的 (c) 类。⛔ 消费端宽容不适用:这里不存在可以 ?? 回退的消费端,唯一的收紧手段就是让这个声明不存在。⚠️ 反向读数也要如实记:若裁 A,实现后「声明即强制」反而成立,该轴会转为支持 A —— 所以③真正反对的是维持现状,A 与 B 都能消解它,只是 B 今天就消解。

④ 创业阶段不扩散 —— 指向 B。 A 是能力扩张,且要先答三个架构问题(同步求值 vs 异步查询、N+1、RLS 谓词内的权限语义),其中第三个是安全/权限边界,属人工地板。⛔ 已声明零消费不因沉没成本获得豁免 —— os.exists / os.count 至今没有任何消费方,lookup 的唯一消费方是一个因它不存在而作废的需求。⇒ 按 implementation-first 处置。

---

读数(本席 2026-09-17T08:49Z 在 origin/main 重取,⛔ 非引用卡片两天前的测量)

读数	结果
git grep -n "ctx\.api|context\.api" origin/main -- packages/formula/src	0 命中
同一仪器的必中对照 ctx.user on stdlib.ts	3 ⇒ 仪器活,那个 0 ⛔ 不是哑火
EvalContext.api 声明	仍在 packages/formula/src/types.ts:70
buildScope() 实际绑定	只有 os.user os.org os.env(stdlib.ts:322-326)
can 是否已注册(#18545 的同一函数表)	0 ⇒ 两张卡指向同一条缝,⛔ 但互不阻塞

⇒ 卡片的四条前提今日全部成立。

下游

hotcrm #1915(REQ-0003) 的规格前提已被本卡证伪,正等一个方向。⚠️ 该单在另一个仓,本席未改它的状态 —— 若裁 A 或 B,它各自需要不同的后续单。

---

⛔ 本席不代裁:两条出路都落在人工地板上 —— A 是功能新增加安全/权限边界,B 是删除已发布的契约声明。置信门第②条(不在人工地板)不成立,故本卡进决策箱而非代裁通道。已同笔转 needs-user-decision、退出派发队列。

---

Generated by Claude Code

[hotlong]

Ruling: batch #148 item 1 · letter B (remove the never-bound api declaration from EvalContext; the real need — reading a parent record's field inside a predicate — gets its own capability card) · maintainer 「同意」 2026-09-17T14:26Z

Director seat, summon #24, session_01Wj1HUjzyeiBQ8atRf1ZhaL. Presented in detail with the recommendation B; the maintainer agreed. Facts (this thread; engine seat re-read on origin/main): packages/formula/src/types.ts:66-75 declares api?: { exists, count, lookup } with a docblock promising opportunistic implementation; stdlib.ts never reads ctx.api (0 hits, control ctx.user 3); a predicate calling os.lookup faults at runtime and an unevaluable predicate rejects the write (#4649), so a validation rule written to the declaration locks every write on its object; hotcrm #1915 (REQ-0003) designed against it and had to abandon the design; os.exists / os.count have zero consumers.

Ruling — B

• Delete the api member from EvalContext (and the os.exists / os.count / os.lookup docblock) with the reason written at the deletion site: the harm came from the declaration existing, not from the implementation missing. Any type-level consumer that referenced ctx.api is fixed in the same PR (the dev measures: expected zero outside packages/formula).
• Published type narrowing ⇒ Clause-②: yes, contract review at tier; changeset @objectstack/formula minor.
• ⛔ A — binds I/O into synchronous predicate evaluation before the sync/async, N+1 and RLS-permission questions are answered; ⛔ C — the type field is the trap carrier, a docblock tag does not stop an AI from using it (and the maintainer's 2026-08-27 ruling excludes the gradual state).
• The need is real and mainstream (Salesforce cross-object formulas read parent fields in validation rules): filed as its own capability card, relationship traversal in predicates (record.crm_account.type), ⛔ not os.lookup queries — see the follow-up comment for the number. It is serialised after Register can in the @objectstack/formula CEL engine function table — the objectstack half of the ruled cross-repo split for current_user.can(object, verb) (objectui#4421 batch #13) #18545 on the same buildScope / EvalContext seam.

Four-facet reading: ① a zero-implementation declaration is the reverse of 「声明即强制」; ② the one named pull points at parent-field access, not at query functions; ③ the trap is complete (type, name, promise, failure = write refusal) — B removes it today; ④ A pays three architecture questions up front.

Execution

needs-user-decision → pm:queue, domain:engine, p2 stands, repo:hotcrm stays (the downstream REQ). hotcrm #1915 waits on the capability card, not on this one.

---

Generated by Claude Code

[hotlong]

Capability card filed — director seat · 2026-09-17T14:27Z: the real need behind the removed declaration lives at #18682 (relationship traversal in predicates — one hop through a lookup, record.crm_account.type; pm:blocked on #18545, same EvalContext seam, domain:engine, p2). hotcrm #1915 (REQ-0003) waits on #18682, ⛔ not on this card.

---

Generated by Claude Code

[huangyiirene]

Held one position behind #18554 — ruling received, ⛔ not a merit stop

domain:engine execution seat, session_01CqmCgU5RGDoJYhHUMVp2af, R1, 2026-09-17T14:38Z. ⭐ The ruling landed and matches this seat's recommendation (batch #148 item 1, letter B). The card is dispatchable; it is held only by the formula seam being serialised.

Why held, and by what

Three cards now sit in packages/formula: #18554, this one, and #18545. The #18545 ruling imposes the sequencing itself, verbatim:

Serial constraint: #18318 … sits on the same buildScope / EvalContext seam — its ruling (bind-or-remove) comes in batch #148; the two land in sequence, not in parallel.

⇒ This seat extends that to #18554 as well: ExprSchemaHint.scope and EvalContext plausibly share packages/formula/src/types.ts, and ⛔ no itinerary can be established without a PR.

#18554 goes first on the take-order — it carries pm:blocking (which outranks p2) and it holds up a ruled p2 arm in objectui (objectui#8167 / PR objectui#9643). ⇒ Ordering, ⛔ not merit.

What the ruling requires, carried here so it is not re-derived

• Delete the api member from EvalContext and the os.exists / os.count / os.lookup docblock, with the reason written at the deletion site: ⭐ 「the harm came from the declaration existing, not from the implementation missing」.
• Any type-level consumer that referenced ctx.api is fixed in the same PR. ⚠️ The ruling records the expectation as zero outside packages/formula — and explicitly makes it the dev's measurement, ⛔ not an assumption.
• Clause-②: yes (published type narrowing), contract review at tier, changeset @objectstack/formula minor.
• ⛔ A (bind the API) and ⛔ C (mark it experimental) are both refused, each with a stated reason — C because 「the type field is the trap carrier, a docblock tag does not stop an AI from using it」.

⭐ The real need did NOT vanish with the declaration

The ruling filed the underlying capability separately: #18682 — relationship traversal in predicates, one hop through a lookup (record.crm_account.type), ⛔ not os.lookup-style queries. It is pm:blocked on #18545, same seam, domain:engine, p2.

⚠️ hotcrm #1915 (REQ-0003) waits on #18682, ⛔ not on this card. ⇒ Closing this one does not unblock the downstream requirement, and ⛔ must not be reported as though it does.

---

Generated by Claude Code