feat(spec): converge ComponentPropsMap['element:number'].filter onto the ViewFilterRule array form (#12039, ui#6206 Option B)

[claude]

Fixes #12039

Key 2 of the card, and the half that completes it (Key 1 landed via PR #12120): ComponentPropsMap['element:number'].filter converges onto the ViewFilterRule array form.

Ruling of record (implemented exactly; not re-decided)

• ui#6206-B (maintainer batch adjudication 2026-08-25, acceptance verbatim 「同意」): one filter orthography platform-wide — the entry's filter becomes z.array(ViewFilterRuleSchema).optional(), the shape every other filter input in component.zod.ts already declares (record:related_list, its Add-affordance picker).
• Option-A sequencing (issue comment 5409255480; maintainer 「第三批决策(5 张) 同意」): consumer first, then spec. The consumer half is done — objectui#6828 landed and the objectstack pin .objectui-sha on origin/main is d8ec8d6d4f011b11c8eb1e6dbd364ef206711391, which carries it (comments 5492894409, 5502817852).
• The ruling's own caveat, binding: "re-run the recorded refusal measurement if the pin has moved by execution time" and "if the runtime genuinely cannot take the array form, that is a fork back to triage, not a silent flip". Step 0 below is that re-run, executed before any edit.

Step 0 — measurement at the pin (before any edit)

Premise re-verified on origin/main @ 8094834 at fetch time: packages/spec/src/ui/component.zod.ts:1802 read filter: FilterConditionSchema.optional().describe('Filter criteria') inside ElementNumberPropsSchema; siblings at lines 1089 / 1125 read z.array(ViewFilterRuleSchema).

At objectui pin d8ec8d6d… (cd ../objectui && git fetch origin d8ec8d6d…, read with git show PIN:PATH, nothing checked out in the shared tree):

1. Adapter lowers on the aggregate path — git show PIN:packages/data-objectstack/src/index.ts, aggregate() at lines 4841–4927: the analytics branch reads payload.where = Array.isArray(params.filter) ? translateFilterArray(params.filter) : params.filter (lines 4924–4926, the objectui#6828 change, with its header comment naming objectui#6302). The spec-shape branch (where) stays strict by the 2026-08-30 option-A ruling and is not the element's path. PASS.

2. Pin test exists and covers rule-object arrays — git show PIN:packages/data-objectstack/src/aggregate-filter-lowering.test.ts succeeds; cases cited: "translates a single rule into an AST tuple" ([{ field: 'stage', operator: 'equals', value: 'won' }] → ['stage', '=', 'won']), "the lowered value passes the AST gate the raw one fails" (isFilterAST(rules) false → true after lowering), "maps operator aliases the way the find() path does", "joins several rules with and", "lowers rules SPREAD into a logical node", and the cross-path parity block "produces the SAME where as the AST-tuple equivalent". PASS.

3. Renderer is an opaque pass-through — git show PIN:packages/components/src/renderers/basic/elements.tsx: ElementNumberRenderer declares filter?: unknown (line 373) and calls adapter.aggregate(props.object, { field, function: props.aggregate, groupBy: '_all', filter: props.filter }) (lines 402–407); the fallback adapter.find(props.object, { $filter: props.filter }) (line 419) goes through the same translateFilterArray via convertQueryParams. Nothing between the authored array and the adapter rewrites it. PASS.

4. objectstack analytics door, replayed from PR feat(spec): converge ComponentPropsMap['object-grid'].data onto ViewDataSchema (ui#6207 Option A); record the ui#6206-B measurement fork #12120's Key 2 section (tsx script over service-analytics src after building its dependency closure — pnpm --filter '@objectstack/service-analytics^...' build, VERDICT command-exit 0):

   • isFilterAST([{ field: 'stage', operator: 'equals', value: 'won' }]) → false
   • isFilterAST([['stage', '=', 'won']]) → true
   • lowerAnalyticsWhere({ where: [{ field: 'stage', operator: 'equals', value: 'won' }] }) → throws [analytics] received a 'where' array that is not a filter: …
   • lowerAnalyticsWhere({ where: [['stage', '=', 'won']] }) → { "stage": "won" }

   Expected and acceptable: the door itself is unchanged by design (raw rule-object array refused, AST tuples accepted). What changed since the recorded fork is reading 1 — the adapter now lowers before the wire — so the end-to-end chain is authored array → adapter lowering → AST → accepted. The stop condition (readings 1 or 2 failing) did not trigger.

The change

• packages/spec/src/ui/component.zod.ts — the element:number entry's filter only: z.array(ViewFilterRuleSchema).optional() with a describe that names the orthography and the migration id; ViewFilterRuleSchema was already imported. FilterConditionSchema stays imported because element:record_picker.filter (now line 2141) still uses it — observed, not changed, per the dispatch.
• ADR-0122 fallout (the same shape Key 1 hit): ViewFilterRuleSchema normalizes operator on parse (input ≠ infer — ViewFilterRuleParsed already exists for that reason), so ElementNumberPropsSchema leaves the isomorphic pin family: ElementNumberPropsParsed declared, the Iso818 pin deleted with its receipt, the pin count 836 → 835 in the header, the test title and the assertion.
• ADR-0087: accept-set change on a published props-map entry ⇒ BREAKING under the launch-window convention. D3 semantic entry packages/spec/src/migrations/entries/semantic/18.element-number-filter-rule-array.ts (surface / replacement / reason / acceptanceCriteria, following Key 1's 18.object-grid-data-view-data-converged.ts); registry.ts regenerated with gen:migration-registry (144 semantic entries; Key 1's object-grid-data-view-data-converged and feat(spec): refuse undeclared keys on address and location values — AddressSchema / LocationValueSchema strict (#13802) #14335's address-location-value-unknown-keys-refused both present). Changeset .changeset/element-number-filter-rule-array.md: @objectstack/spec minor, **BREAKING**, FROM → TO block, and the adr-0087: registered element-number-filter-rule-array marker.
• Tests (packages/spec/src/ui/component.test.ts, new describe block): array form accepted and echoed (the card's acceptance criterion); the real ViewFilterRuleSchema is what is wired (eq normalizes to equals; a scalar in value is refused at filter.0.value); the record form refused at the filter path with code: 'invalid_type', expected: 'array' (both the plain record and the operator-object record); an orthography pin that element:number and record:related_list give the same verdicts on the same value; a multi-rule positive control with a real in rule.
• Generated products regenerated by check:generated --fix after proving exactly three stale: api-surface/ui.json + export-origins/ui.json (the new ElementNumberPropsParsed export) and content/docs/references/ui/component.mdx (the array shape). authorable-surface was already green (the key set did not change). No hand-docs edit: the only prose mention of element:number under content/docs (ui/pages.mdx:187) lists element names and says nothing about the filter shape.
• No consumer-side alias, no fallback arm accepting the record form.

Ruled migration check — the sweep

Commands (tracked files on this branch):

git grep -n -A12 "ElementNumberPropsSchema\.\(parse\|safeParse\)\|ComponentPropsMap\['element:number'\]\|type: 'element:number'\|type=\"element:number\"" -- . ':!content/docs/references' ':!packages/spec/CHANGELOG.md' ':!packages/spec/api-surface' ':!packages/spec/export-origins' ':!packages/spec/declaration-map' ':!packages/spec/authorable-surface*' ':!.changeset' ':!packages/spec/src/migrations' | grep -E "filter: \{|filter: \["
grep -rn "element:number" examples skills packages/create-objectstack content/docs packages/apps

Result: one in-repo author of the props-level record form — packages/spec/src/ui/component.test.ts "should accept full number props" (filter: { status: 'paid' }), rewritten in this PR to [{ field: 'status', operator: 'equals', value: 'paid' }] (fixture triage: it used the form this entry alone accepted; its assertions are about format/prefix/suffix and still hold, plus one on the parsed filter). The three page.test.ts hits author dataSource.filter (ElementDataSourceSchema, a different key and schema — not this entry). Zero authors in examples/, skills/, packages/create-objectstack/, content/docs/ (other than the name list), packages/apps/. Out-of-repo authors get the prescription via the ADR-0087 entry.

Verification

Union derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (no paths; stderr stamped "derived from the tree of 'objectstack-ai/objectstack' at commit 8068a7f"): 74 commands, each run under scripts/pm/os-verify-lock.sh through a runner that redirects output to a per-command log and captures the exit code before any pipe. HEAD for every reading below: 8068a7f31 (git rev-parse --short HEAD after the last commit; the tree was clean throughout).

Named must-haves, each on 8068a7f31:

• pnpm --filter @objectstack/spec run typecheck — tsc --noEmit clean, check:scripts-typecheck clean, "check:test-typecheck: OK — @objectstack/spec's test layer compiles under packages/spec/tsconfig.test.json; 54 file(s) / 262 error(s) / 146 pinned signature(s) held" (VERDICT command-exit 0; re-run after the last commit).
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/ui/component.test.ts src/type-alias-convention.pin.test.ts — Test Files 2 passed (2), Tests 238 passed (238).
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 (the full spec suite) — Test Files 450 passed | 1 skipped (451); Tests 12111 passed | 1 skipped (12112), Duration 325.86s, VERDICT command-exit 0.
• pnpm --filter @objectstack/spec check:generated — "✓ All 15 generated artifacts are up to date" (that run includes check:migration-registry ✓, check:spec-changes ✓, check:upgrade-guide ✓, check:docs ✓, check:authorable-surface ✓, check:test-typecheck ✓).
• check:api-surface ✓ and check:export-origins ✓ (exit 0 on the rebuilt dist); check:authorable-surface ✓ ("🔒 authorable-defaults/ verified against upstream d62f990 — 1236 default(s) unchanged"; no anchor hand-edited, baseRev left to lag); scripts/check-adr-0087-registration.mjs — "✓ check-adr-0087-registration: 1 declared-breaking changeset(s), each carrying an ADR-0087 disposition … registered element-number-filter-rule-array (new here)"; check:doc-authoring — "✓ doc authoring guard: 14375 customer-facing string(s) across 705 spec sources clean — no internal issue-id references"; check:nul-bytes — "check-nul-bytes: OK (scanned 7843 text file(s) -- 7843 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).".

The rest of the 74-command union: 72 of 74 exit 0 on 8068a7f31, per-command exit codes captured from redirection. Readings that first printed PREREQUISITE NOT MET / "dist is OLDER than src" (their own words: nothing measured, not a finding) were re-run after the prerequisite was built — pnpm --filter '@objectstack/lint...' build, then turbo run build --filter='./packages/*' --filter='./packages/*/*' (70/70 tasks successful, VERDICT command-exit 0) — and are green: check:doc-formula-expressions, check:doc-security-posture, check:browser-reachable-entries, check:dual-source-exports, check:entry-nameability, check:exported-any, check:skill-examples ("✅ 259 prose examples type-check across 3 surface(s)"), check:dev-prereqs ("✓ 67 package build artifacts present"), check:dual-build-cjs-loads ("102 published require entry point(s) across 66 package(s) load"), check:type-check-coverage ("67/78 workspace packages type-checked"), check:type-check-debt ("27 ledger entr(ies) re-measured … none above its recorded number"). check:query-options-erasure ran alone under the lock after a first attempt was cut by the container's foreground cap: "✓ query-options-erasure ratchet holds: 67 unswept non-test site(s) in 17 file(s), none new". The ratchet families (check:slot-lookup, check:query-options-erasure, check:type-check-debt, check:spec-parsed-alias, check:where-matcher, check:engine-double-contract, check:test-source-alias) are all green on this head. The two remaining commands are the not-runnable-here pair below.

Type-level reverse verification against the rebuilt dist/*.d.ts (probe file in packages/lint, tsc --noEmit --ignoreConfig against @objectstack/spec/ui): the record form filter: { status: 'won' } → red, TS2353 … 'status' does not exist in type '{ field: string; operator: unknown; value?: … }[]'; the array form → green (0 errors). The probe was deleted afterwards.

Not runnable here, by their own verdicts: check:react-declaration-parity (needs objectui's sdui.manifest.json, produced only by pnpm sdui:manifest on a pin bump — an on-demand gate by maintainer decision; this is the gate whose exemption element:number.filter:array becomes deletable downstream) and check-test-completeness (reads a saved turbo run test log; NOT MEASURED locally per its text). Repo-wide pnpm lint and the multi-package farm are CI's runs (declared narrowing — CI runs the farm on this PR).

H17 note

packages/spec/src/ui/view.zod.ts is not touched — ViewFilterRuleSchema is imported from it in component.zod.ts only (on-hold #8346 declares it Restart-touch).

Session: https://claude.ai/code/session_01GDA48PuRFrHyRfdkBz8m21

🤖 Generated with Claude Code

https://claude.ai/code/session_01GDA48PuRFrHyRfdkBz8m21

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

4 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ⚠️ 2 changed file(s) yielded no anchor (packages/spec/api-surface/ui.json, packages/spec/export-origins/ui.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/spec/api-surface/ui.json, packages/spec/export-origins/ui.json) — pages documenting those are invisible to this run
• 4 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 5ec4f6fa4c60e0e0a40986ee6a5d3a4b4b380c6c → packageMentionDocs.

Which tree this was computed on

This run read content/docs from bc118cab41209b26b8cbf393c8c767de9df9edb1 — the merge of head 8068a7f317684f55c70fcc33e182ea0d67395cb7 into base 5ec4f6fa4c60e0e0a40986ee6a5d3a4b4b380c6c, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin bc118cab41209b26b8cbf393c8c767de9df9edb1 && git checkout bc118cab41209b26b8cbf393c8c767de9df9edb1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 5ec4f6fa4c60e0e0a40986ee6a5d3a4b4b380c6c 8068a7f317684f55c70fcc33e182ea0d67395cb7 && git checkout -B drift-repro 5ec4f6fa4c60e0e0a40986ee6a5d3a4b4b380c6c && git merge --no-ff 8068a7f317684f55c70fcc33e182ea0d67395cb7

node scripts/docs-audit/affected-docs.mjs --json 5ec4f6fa4c60e0e0a40986ee6a5d3a4b4b380c6c

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.