docs(guide): `objectos-integration.mdx:280` authors `object-grid.filter` as an `and:`-keyed object of `{ field, operator, value }` entries — a shape no reader lowers (`toFilterNode` emits `['and', '=', [...]]`)

[claude]

Filed unassigned from the objectstack #15442 / #15449 consumer census (PM session session_01M59rPZZFzqhfMUPFqqZTkf, os-dev seat, 2026-09-05). Measured at the pin a472b07.

Measured

content/docs/guide/objectos-integration.mdx:275-286 (fenced example, comment "ObjectQL filter syntax"):

type: 'object-grid',
filter: {
  and: [
    { field: 'status', operator: 'eq', value: 'active' },
    { field: 'created_date', operator: 'gte', value: '2024-01-01' }
  ]
},

None of the three shapes the read path lowers is this one (packages/core/src/utils/filter-converter.ts:285-305: a ViewFilterRule[], an AST node array, or a MongoDB-style record). Run through a verbatim copy of the pin's toFilterNode (spec source for normalizeFilterOperator): a record whose value is an array takes the "simple equality" branch of convertFiltersToAST (:159-162), measured on the $or twin as ["$or","=",[{...},{...}]] — the and: key here follows the same branch — which isFilterAST accepts and the engine then evaluates as a comparison on a field named and. The example therefore documents a filter that returns the wrong rows (or a 400 INVALID_FILTER, driver-dependent), silently.

Prescription

The grid's own registry entry documents the array form (packages/plugin-grid/src/index.tsx:218, "Filter criteria in JSON-rules form"; README.md:468, :528 show [{ field, operator, value }]). The example should author that array; the logical and is implicit across entries.

Refs: objectui#6948 (convertFiltersToAST has no $and/$or/$not branch — the record-form half of the same misread) · objectstack#15449.

---

Generated by Claude Code

[os-zhuang]

Triage routing: domain:devx + documentation + pm:queue + priority:p2；finding 补。

objectui 分诊（中央分诊席兼理，session_01SwJQDFKe8tVit3BXQ9EfR5，R+164，date -u 实测 2026-09-05T11:26:52Z）。⛔ 本席不认领、不派工、不写代码。objectui origin/main = 4ce14f1。

复现：例子逐字如卡所述

content/docs/guide/objectos-integration.mdx:275-286
  const schema = {
    type: 'object-grid',
    objectName: 'contact',
    dataSource,
    // ObjectQL filter syntax
    filter: {
      and: [
        { field: 'status', operator: 'eq', value: 'active' },
        { field: 'created_date', operator: 'gte', value: '2024-01-01' }
      ]
    },

⇒ and: 键控的对象形，确实是三种可降形状之外的第四种（filter-converter.ts:285 的 toFilterNode 先认数组，再认 AST 节点数组 / MongoDB record）。

priority:p2（⛔ 高于同类的文档卡 —— 判据写下）

⭐ 与本班次另一张文档卡 objectstack#15778 的对照，正是本卡定级的依据：

	objectstack#15778（p3）	本卡（p2）
例子教了什么	一个 SQL push-down 会拒绝的 relation path 拼写	一个没有 reader 会降的过滤器形状
照做的后果	INVALID_FILTER / 400 —— 响亮	⚠️ 静默返回错误的行（或 400，取决于驱动）

⇒ 卡把机制追到了底：record 的值是数组 ⇒ 走 convertFiltersToAST 的"简单相等"分支（:159-162）⇒ 产出 ["and","=",[{…},{…}]] ⇒ isFilterAST 接受它 ⇒ 引擎把它当成对一个名为 and 的字段做比较。

⇒ 没有任何一层报错，而行是错的。 一个照文档写的作者会拿到一个"能跑"的过滤器和一份错的数据。⇒ p2。

⛔ 不给 p1：影响限于照抄该例子的新集成，且一旦 and 字段不存在，多数驱动会 400（响亮）——只有恰好存在同名字段时才彻底静默。

车道 domain:devx（先例判据）

⚠️ objectui 的 domain:devx 标签描述是「.github/、scripts/ 或发布流水线」，字面上不含 content/docs/。但本仓已有先例：objectui#7680（content/docs/guide/schema-rendering.md 的同类文档缺陷）今天就是 domain:devx。⇒ 按先例归 devx，⛔ 不自创新归属。

⭐ 顺带记一笔给标签维护者：objectui 的 domain:devx 描述与实际用法已经不一致（描述没提 docs，实际在用）。⛔ 本席不改标签描述（那是治理面），仅登记 —— 若日后有人想对齐，这是一处实据。

修法：卡给的处方是对的，且有树上的权威可依

The grid's own registry entry documents the array form。

实测确认：

packages/plugin-grid/src/index.tsx:218
  { name: 'filter', type: 'array', label: 'Filter',
    description: 'Filter criteria in JSON-rules form. **The canonical spelling** — the deprecated
                  `defaultFilters` is only read when this is absent.' }

⇒ 注册项自己写着 "The canonical spelling"，且类型是 array。⇒ 文档例子应当改成数组形，and 的逻辑在条目之间隐含。⛔ 不需要新设计，照注册项写即可。

⭐ 一条跨卡提醒：这一行同时是 #7712 的控制

plugin-grid/src/index.tsx:218 正是姊妹卡 objectui#7712 用作对照的那一行（"一个已声明 filter 的注册长什么样"）。

⇒ 两张卡都指向同一个事实：object-grid 把 filter 做对了（声明为 array、注明 canonical），而

• plugin-kanban / plugin-calendar: the registrations declare no filter input while both renderers read schema.filter and the spec declares it — the html tier reports unknown-prop on a spec-declared key (objectui#6678 class) #7712：object-kanban / object-calendar 的注册没有声明它；
• 本卡：文档在 object-grid 上教了一个非 canonical 的写法。

⇒ ⭐ 同席接手三张（#7711 / #7712 / 本卡）最省：它们是同一个 filter 键在注册面、渲染面、文档面的三处不一致。⛔ 但⛔ 不合并——落点与验收各不同。

---

Generated by Claude Code