[decision] filter-builder's two operator vocabularies: which one is the truth — and it must settle objectui#6349's two parked name-authority rows

[os-tesla]

Decision needed. Filed by the domain:ui PM seat (os-tesla) at R32, to keep four records alive that would otherwise go quiet.

Why this card exists at all

objectui#7561 was narrowed by triage to a single-site repair (the Select's identity comparison going through normalizeFilterOperator). That repair is delivered in PR objectui#9305 and it carries Fixes #7561 — so merging it closes the only card where the vocabulary question is written down.

⭐ The delivering seat spotted this and raised it rather than merging over it. It is right, and the lossy part is specific: a closed card appears in no open-queue census, so the records below stop being discoverable by anyone sweeping for open work.

⇒ this card is the vocabulary question's home. PR objectui#9305 keeps Fixes #7561 — that repair really is complete, and calling a finished deliverable "Part of" would misrepresent it.

The question

filter-builder has two operator vocabularies and they are very nearly disjoint — the overlap is three members (equals, contains, in).

• FilterOperatorSchema (packages/types/src/zod/complex.zod.ts) — the spec's canonical snake_case set: equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, greater_than_or_equal, less_than, less_than_or_equal, in, not_in, is_null, is_not_null.
• The dropdown (packages/components/src/custom/filter-builder.tsx, defaultOperators) — camelCase plus capabilities the spec set has no name for: equals, notEquals, contains, containsCaseInsensitive, notContains, isEmpty, isNotEmpty, greaterThan, lessThan, greaterOrEqual, lessOrEqual, before, after, between, in, notIn, startsWith, endsWith, isNull, isNotNull, exists, notExists.

Three candidate directions, none local:

1. The mirror follows the dropdown (camelCase). Matches what renders and what onChange emits back to the host — but forks from @objectstack/spec's VIEW_FILTER_OPERATORS, which the component itself imports and folds through.
2. The dropdown follows the mirror (canonical snake_case). Contract-first — but rewrites the ids every stored filter carries and every consumer of foldFilterGroupToSpecRules reads.
3. The mirror accepts both dialects, the way the component's own arity fold already does.

⛔ The hard constraint on direction 3, recorded twice and still binding

Direction 3 conflicts directly with this repo's cited spec ruling on objectui#7379 (contains vs icontains). AST_OPERATOR_MAP's comment says an operator "must never be folded onto" its sibling — "That is a semantic boundary, not two spellings of one thing."

⇒ whoever rules the vocabulary must read these two together, or the repo ends up with opposite rulings on adjacent surfaces.

⭐ Four records this card carries forward

1. The three directions above, with their costs.
2. The capability-bearing dropdown ids with no spec twin — containsCaseInsensitive, isEmpty, isNotEmpty, before, after, between, exists, notExists. ⚠️ The delivering seat counted seven; a naive set difference gives eight, because some of these arguably fold (before/after onto less_than/greater_than, exists/notExists onto is_not_null/is_null). ⛔ I am not resolving that here — whoever rules must restate the membership explicitly, because "which of these are real capabilities" is half the decision. Under direction 2 these ids lose their names.
3. ⭐⭐ objectui#6349's two parked name-authority rows. FilterBuilderCondition and FilterGroup are declared in both @object-ui/types and @object-ui/components; 46 exported type names carry a second authority — 42 of them are named by no family card #6349 batch 3 (PR fix(components,plugin-grid,app-shell): one authority for ComboboxOption, NamedActionDef and OrgTranslate (objectui#6349 batch 3) #7691) tried to converge them, stopped and reported instead, and the rows were parked on objectui#7561 "because converging the name retypes operator — so whatever is ruled must settle those two rows too." ⇒ this is an acceptance criterion of the vocabulary ruling, not a related note. Verified at source in two independent comments on objectui#7561 (5548770124, 5560863302).
4. objectui#7993's input, which points at direction 2: the spec treats the camelCase spellings as the DEPRECATED alias form, with less_than canonical.

Measured, so the decision is not made in the abstract

The blank-trigger symptom is already fixed by PR objectui#9305 — ⛔ do not treat urgency as an input here. What remains is which vocabulary is the truth.

⭐ MUST-CHECK answered: objectstack #15442 / #15449's filter-converge ruling does NOT cover this surface. Triage asked for a check rather than a conclusion and the seat reported a reading rather than a verdict. ⇒ no upstream ruling pre-empts this one.

⚠️ NOT MEASURED, and it prices direction 2: how many stored filters in real tenants carry camelCase ids. Nobody in this container can read that. Direction 2 rewrites every one of them, so whoever rules should want that number or should say explicitly that they are ruling without it.

⛔ What this card is not

• ⛔ Not a re-opening of PR objectui#9305's narrowed repair. That is complete, correct and reviewed separately.
• ⛔ Not objectui#9302 (needsValueInput reads the operator raw against the exported valueless set) — same class, different site, its own card.
• ⛔ Not a claim that any direction is cheap. All three are contract-shaped.

Refs: objectui#7561 (the home this replaces) · PR objectui#9305 (the delivered narrowing) · objectui#7379 (the must never be folded onto constraint) · objectui#7993 (camelCase is the deprecated alias form) · objectui#6349 (the two parked name-authority rows) · objectui#6939 / PR objectui#7560 · objectui#9302 · objectstack#15442 / #15449 (checked, not covering)

---

Generated by Claude Code

[os-tesla]

Ruling recorded — 2, as a director-seat class-one adjudication: the filter-builder dropdown speaks the protocol's operator set; camelCase is the deprecated alias accepted on read and rewritten on write; no spec card is filed for the ids the protocol does not name (director seat, decision batch #129 item 2, 2026-09-13)

Maintainer, verbatim (live PM chat, reply received 2026-09-13T07:0xZ), to decision batch #129 presented as 1A·2(2)·3A·4(1)·5S: 「你是项目总监，9306 这种为什么你不直接决策呢？而且不是说要以协议为准吗？还需要立卡问 spec 多次一举啊。这个也需要更新skills。其他同意。」

The correction is taken as written, twice over. First, this card should not have been presented: route 2 pulls a consumer surface back to the protocol's declared set, which is the class-one side of the charter's mechanical boundary (SKILL.md:395 「拉回已声明契约 ⇒ 代裁车道」; :400-403 the three criteria — ① the standing ruling 「以 objectstack 协议为准」 and objectui#7993's recorded reading that the camelCase spellings are the DEPRECATED alias form decide the direction; ② the failure direction is a refused / normalised id, one revert away; ③ no floor moves). Second, the seat's proposed spec card asking whether the protocol should gain between / is_empty / icontains was redundant: the protocol is the answer; a capability it does not name is not offered.

What is ruled

1. defaultOperators in packages/components/src/custom/filter-builder.tsx emits the FilterOperatorSchema ids (equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, greater_than_or_equal, less_than, less_than_or_equal, in, not_in, is_null, is_not_null) and nothing else. The mirror type follows.
2. Stored filters carrying camelCase ids keep loading: normalizeFilterOperator accepts the camelCase spellings as deprecated aliases (objectui#7993) and the builder writes the canonical id back — a lossless read-side conversion, ⛔ not a second vocabulary.
3. The eight dropdown ids with no protocol twin: before / after → less_than / greater_than and exists / notExists → is_not_null / is_null (same semantics, folded on read); between, isEmpty, isNotEmpty, containsCaseInsensitive are removed from the dropdown — zero measured pull, and objectui#7379's semantic boundary forbids folding a case-insensitive contains onto contains. ⛔ No spec card. If a customer ever needs one of them, the card is filed then, with the pull attached.
4. objectui#6349's two parked name-authority rows converge on the @object-ui/types declaration with operator typed as the protocol set — an acceptance criterion of this card.
5. objectui#9302 (needsValueInput reads the raw operator) is unchanged and lands after 1.

State

needs-user-decision → pm:queue; domain:ui kept; priority:p3 added (the user-visible symptom is already fixed by PR objectui#9305; this is contract alignment). Recorded for the maintainer's 追认表 as a class-one adjudication.

---

Generated by Claude Code

[os-tesla]

Ruling amended — item 3 of 5651809976 was wrong: the protocol ALREADY names every capability the dropdown offers; nothing is removed, and objectui's own 14-member FilterOperatorSchema is the stale mirror (director seat, 2026-09-13T07:03Z)

Maintainer, verbatim (live PM chat, 2026-09-13T07:0xZ), minutes after the ruling above: 「协议就是答案，但是协议是否正确也是需要你考虑的，从平台长远合理性的角度考虑，并参考主流相关平台」

Acting on that, the seat read the protocol instead of the card's copy of it. packages/spec/src/ui/view.zod.ts:243 VIEW_FILTER_OPERATORS is 20 members, ⛔ not 14:

equals not_equals contains not_contains icontains starts_with ends_with
greater_than less_than greater_than_or_equal less_than_or_equal in not_in
is_empty is_not_empty is_null is_not_null before after between

The 14-member FilterOperatorSchema this card quotes lives in objectui's packages/types/src/zod/complex.zod.ts — it is objectui's mirror, six members behind the protocol. ⇒ Every dropdown id has a protocol twin, and the seat's "remove between / isEmpty / isNotEmpty / containsCaseInsensitive" was a mistake made by not reading the protocol before ruling on it. Item 3 is replaced as follows; items 1, 2, 4, 5 stand with the set corrected to the 20.

Corrected mapping (22 dropdown ids → protocol)

equals→equals · notEquals→not_equals · contains→contains · containsCaseInsensitive→icontains · notContains→not_contains · isEmpty→is_empty · isNotEmpty→is_not_empty · greaterThan→greater_than · lessThan→less_than · greaterOrEqual→greater_than_or_equal · lessOrEqual→less_than_or_equal · before→before · after→after · between→between · in→in · notIn→not_in · startsWith→starts_with · endsWith→ends_with · isNull→is_null · isNotNull→is_not_null · exists→is_not_null · notExists→is_null (the last two are the only ids with no twin of their own; they fold to the null checks). objectui#7379's boundary is honoured by construction: contains and icontains stay two operators.

The protocol-correctness check the maintainer asked for

Judged against mainstream filter UIs (director-seat memory pointers, ⛔ not measured): Airtable and Notion offer is empty / is not empty and a case-insensitive contains as the default; Dataverse FetchXML has between, begins-with, ends-with, null / not-null, in; Salesforce list-view filters have equals / not equal / contains / starts with / less or greater than. The protocol's 20 cover that set and keep the null-vs-empty and case-sensitive-vs-insensitive distinctions explicit rather than collapsed. ⇒ The protocol is right as it stands; nothing to add, nothing to remove.

Execution (replaces item 1 and 3)

1. @object-ui/types' FilterOperatorSchema becomes the protocol's set — import VIEW_FILTER_OPERATORS from @objectstack/spec/ui rather than a local literal, so the mirror cannot fall behind again (the same reasoning the protocol's own docblock at :257-268 gives for isMultiOperator).
2. defaultOperators emits the 20 protocol ids; the camelCase spellings remain readable as deprecated aliases (item 2, unchanged).

pm:queue / domain:ui / priority:p3 unchanged.

---

Generated by Claude Code