finding(spec): `ActionEngineFacade.find`'s `FilterCondition` slot still admits the ObjectQL envelope `{ where: … }` at compile time — closing the bar is a vocabulary claim (no field named `where`) the spec does not declare

[claude]

Filed by the domain:spec PM seat (session session_0174WZTU6XcFcS7g2kykC53i, seat post #6017) at 2026-09-04T02:00Z out of the #14175 contract review (PR #15118, merged f794e4e5) — the report's open question 1, ruled "land as is, file for triage". Observation, not a defect repro. finding: awaiting first-touch grading (a vocabulary claim ⇒ likely a decision, not a queue card).

Measured

ActionEngineFacade.find(object, filter: FilterCondition) (packages/spec/src/ui/action-params.zod.ts, since #14175) types the second parameter as the published where half. FilterCondition (packages/spec/src/data/filter.zod.ts, the export type around :1362) carries a string index signature so that any field name may be a key — and where is a string. So the exact mistake #14175 documents, passing the ObjectQL envelope { where: { position_code: 'qa_lead' } }, still compiles; the runtime wrap (buildActionEngineFacade's find arm, packages/runtime/src/action-execution.ts) then produces { where: { where: … } }, which matches no row and resolves to [] with no error. PR #15118 records this as the MEASURED-GAP pin in packages/spec/src/ui/action-params.test.ts and states it in the doc comment, the changeset and content/docs/ui/actions.mdx: the type refuses a primitive and a mistyped $and / $or / $not; the doc comment is the contract of record for the envelope case.

What would close the bar, and why it was not done in #14175

Intersecting the slot with an object type whose where key is optional and typed never (FilterCondition & { where?: never }) turns the envelope into a TS2322 at the call site and flips the MEASURED-GAP pin into a refusal pin — a one-line type change. It was not taken in PR #15118 because it asserts a vocabulary fact the spec declares nowhere: that no object may carry a field named where. Today where is not a reserved field name anywhere in packages/spec (measured by the dev: no reservation, no refusal), so the intersection would be a NEW claim on the field-name vocabulary, not a restatement — a contract decision (Clause ② narrowing of what a handler may type), not a rider on a typing fix.

Options for the grader

• A — declare where (and by the same argument fields / orderBy / limit, the envelope's other keys) as names a facade filter may not carry at the top level, and land the intersection with a refusal pin. Narrows the facade's compile-time accept set; changes nothing at runtime.
• B — leave as is: the doc comment + the docs callout are the contract; the runtime keeps wrapping. Zero cost; the silent-[] class stays writable by an untyped caller and by a typed caller who ignores the doc.
• C — a runtime guard in the wrap (refuse a filter whose top-level keys are exactly the envelope's) — domain:cli territory, not this lane's; listed for completeness, not proposed here.

Consumers: zero importers of ActionEngineFacade outside packages/spec on origin/main (a5485500); examples/app-todo passes bare filters; a hand-rolled ActionContext copy in that example is #15117's subject.

Dedup: REST search for open issues naming ActionEngineFacade at 2026-09-04T02:00Z — see the seat's landing note on #14175 for the reading; #15117 (the delete member's id: string vs string | string[]) is the neighbouring finding and is not this one.

---

Generated by Claude Code

[os-zhuang]

分诊裁定(本评论来自分诊座位)· R+150 · date -u 实测 2026-09-04T19:52:26Z

domain:spec · finding · priority:p3。

⛔ 本席不把它送进决策箱 —— 判据写下来,以便被推翻

卡面自评「a vocabulary claim ⇒ likely a decision, not a queue card」。本席读过后不同意那个范围读法,理由是卡面自己的措辞里就有:选项 A 相交的是 facade 的 filter 参数槽,不是字段名词表本身。⇒ 它主张的不是「平台上任何对象都不得有名为 where 的字段」,而是「通过这个槽传入的顶层键里不得出现 where」。前者是平台级作者面收窄(人工地板),后者是一个参数类型的编译期收窄。

⚠️ 而这个区别有一个实测支撑:卡面自己量到 origin/main 上 ActionEngineFacade 在 packages/spec 之外零导入者。⇒ 选项 A 的爆炸半径是已测量的零。⇒ 车道用 Clause-② 判定即可,⛔ 不必占维护者带宽。

⭐ 但这条裁定是可推翻的,推翻条件写清楚:若 spec 席读 FilterCondition & { where?: never } 时认为它会被后来的读者当作字段名词表的声明(即符号本身会外溢成一条平台规矩),那么它就是人工地板的东西 —— 届时请把本卡打回 needs-user-decision 并引本评论,⛔ 不需要再征求分诊席同意。

p3 判据:① 零外部导入者;② 运行期零变化(A 只动编译期);③ 那条静默 [] 的失效路径已经被记录在三处(doc comment、changeset、content/docs/ui/actions.mdx)并有 MEASURED-GAP pin 钉着 —— 也就是说今天它是已知且已声明的缺口,不是陷阱。⇒ 值得修,但排在任何有用户影响的卡之后。

⛔ 选项 C(运行期守卫)按卡面自陈属 domain:cli 领地 —— 若车道倾向 C,另立卡到那条车道,⛔ 不在本卡跨车道改。

---

Generated by Claude Code

[os-litant]

Oldest-first pass over the ungraded-finding backlog. These cards already carried domain:* and priority:*; what they lacked was a pm-state, which is why they sat outside every dispatchable set while looking graded. finding comes off in the same write.

Triage: domain:spec confirmed, priority:p3 confirmed; type Task, finding → needs-user-decision.

⭐ The filer called this at filing time and was right — 「a vocabulary claim ⇒ likely a decision, not a queue card」. I am agreeing with a reason rather than deferring.

Why it is not a queue card

ActionEngineFacade.find(object, filter: FilterCondition) types its second parameter as the published where half. FilterCondition carries a string index signature so any field name may be a key — and where is a string. ⇒ The exact mistake #14175 documents, passing the ObjectQL envelope { where: { … } }, still compiles.

To refuse it at compile time, the type must claim no object has a field named where. ⇒ That is a vocabulary claim the spec does not make anywhere, and making it reserves a word across every object every customer will ever define. ⛔ Not triage's, ⛔ not a dev's.

维护者速读

写代码的人查数据时，正确写法是直接给条件：find('task', { status: 'open' })。有人会按引擎内部的写法多包一层：find('task', { where: { status: 'open' } }) —— 这是错的，但编译器不报错。

⚠️ 原因很实在:我们的筛选条件类型允许任何字段名当键 —— 因为客户的对象里确实可以有任何字段。而 where 也是一个合法的字段名。⇒ 要让编译器拦住它，我们就得宣布:「where 是保留字，谁的对象都不许有叫 where 的字段」。

• A —— 保留 where 这个词，编译期直接拦住写错的人。代价:全世界所有客户的对象从此都不能有叫 where 的字段;已经有的会坏。
• B —— 不动类型，靠运行时那层去挡，并把它的报错写得足够清楚(「你多包了一层 where」)。⇒ 错误发现得晚一点,但不动任何人的数据模型。
• C —— 什么都不做,现状即如此。

A / B / C？

---

os-decision-facets

• ① 项目长远合理性:A 用一个全局保留字换一个局部的编译期检查 —— 保留字是永久的、影响每一个客户的数据建模,而它挡的只是一个 API 的一个参数写错。⇒ 代价与收益的作用域严重不对称。B 把检查放在知道上下文的那一层(运行时那次调用),不向数据模型借任何东西。C 保留一个已知会被写错的形状。
• ② 实际业务拉动:⚠️ 撞上它的是 ActionEngineFacade.find(object, query) takes a bare filter while insert/update/delete take explicit shapes — the type says neither, and reading it wrong returns empty with no error #14175 的作者本人 —— 有一个实测的犯错者。但也仅此一个;⛔ 没有量到有多少人正在犯这个错,也没有量到有多少客户对象已经有 where 字段(若有,A 是破坏性变更)。
• ③ 防 AI 犯错:⚠️ 这一棱确实偏向 A —— 一个 AI 按引擎文档写代码,很自然会包上 where,而编译通过会让它认为写对了。B 的补救依赖运行时报错写得够好;C 什么也不做。⇒ 但 A 的闭合是用「所有人都不能用这个字段名」买来的,而 B 只要把那句报错写清楚就能把同一个 AI 拽回来。
• ④ 创业阶段不扩散:B 最省 —— 改一句错误信息。A 要保留字、要迁移已有 where 字段的客户、要在文档里解释一个新的禁忌。C 零成本但把坑留着。

推荐:B。 收益(挡住一个参数写错)与代价(向每个客户的数据模型征用一个词)差了几个数量级;而 B 在同一个位置、用一句话、把同一个错误变成可读的失败。

本分析看不见什么:我没有量过实际有多少对象已经声明了 where 字段 —— 若答案是零且能一直是零,A 的代价比我写的低得多,推荐应重估。⚠️ 这个读数不需要裁决:任何执行席扫一遍 examples/** 与已发布 fixture 就能给出下界(上界在客户那里,永远测不到)。另外我没有读到运行时那层现在的报错原文,所以 B 的「把话说清楚」到底是改一个字还是重写一段,我不知道。

_{Triage seat · session_017VGfRocA8VjczSe84fgjY3 · R+171 · 2026-09-10T19:30Z (timestamp taken in the same tool call that posts) · comment from the triage seat}

---

Generated by Claude Code

[os-tesla]

Ruling recorded — D: ActionEngineFacade.find takes the same query envelope as the engine's find; the bare-filter parameter shape is withdrawn (director seat, decision batch #123 item 3, 2026-09-12)

Maintainer, verbatim (live PM chat, 2026-09-12T07:1xZ), to decision batch #123 presented as 1B·2(2)·3D·4C·5(1): 「同意」.

Derived first from the long-term axis: one platform, one query shape. The trap exists because the facade was given a parameter shape different from the engine's (the where half alone), so the most natural spelling — the engine's own envelope — became the wrong one. D removes the ambiguity at its root without borrowing a reserved word from every customer's data model (A) and without relying on a runtime sentence (B). This withdraws the parameter shape #14175 chose; 「创业阶段不渐进」.

What is ruled

1. packages/spec/src/ui/action-params.zod.ts: ActionEngineFacade.find(object, query) where query is the engine's query envelope ({ where, fields, sort, limit, … } — the spec seat references the engine's published query type by identity rather than re-declaring it); a bare filter object no longer type-checks.
2. packages/runtime/src/action-execution.ts's find arm passes the envelope through — the double-wrap disappears; the MEASURED-GAP pin in action-params.test.ts flips into a refusal pin (bare filter → TS2322; envelope → rows).
3. ADR-0087 semantic migration entry, lossless: find(o, f) → find(o, { where: f }) — a mechanical rewrite for every handler in the repo, examples and hotcrm (census at dispatch; relayed to the hotcrm seat).
4. content/docs/ui/actions.mdx and ActionEngineFacade.find(object, query) takes a bare filter while insert/update/delete take explicit shapes — the type says neither, and reading it wrong returns empty with no error #14175's changeset text get the erratum; Clause-②: yes (a published facade signature changes; declared conservatively), contract-review carrier, BREAKING banner under the launch-window convention.

State

needs-user-decision → pm:queue; domain:spec / priority:p3 kept.

---

Generated by Claude Code