docs(spec): state what the object-* blocks declare on record_picker filter docblock

[os-bill]

Part of #17475

• Clause-②: no

Correcting one parenthetical in the filter docblock on ElementRecordPickerPropsSchema. Prose only: no declaration moves, no accept set changes, no schema is touched.

Supersedes PR #17652

#17652 carried the identical correction but its commit message also carried Part of #17475. The card relation is declared once, in the PR body; a commit carries no card trailer, so check:partof-closing-keyword was red there. On an already-pushed branch nothing clears that without a history rewrite, and amend / rebase / force-push are forbidden here — so this is a fresh branch off current origin/main, not a rewrite. ⛔ Nothing published was rewritten and the old branch is left in place.

Content identity proven, not assumed — git hash-object on this branch against git rev-parse 567cb419f8:PATH:

path	this branch	superseded head
packages/spec/src/ui/component.zod.ts	d81a58da6c	d81a58da6c
.changeset/17475-record-picker-filter-docblock.md	bc9a24292c	bc9a24292c

Lit control on the same instrument: AGENTS.md, a path deliberately not copied, reads d756b7c087 here against 94cac72c99 there — so the comparison could have come back the other way. git log 567cb419f8..origin/main over both paths is empty, so nothing on main was reverted by taking them.

Commit message, checked before the push (occurrences via grep -o | wc -l, never grep -c): Part of, Part-of, Refs, Fix/Fixes/Fixed, Close/Closes/Closed, Resolve/Resolves/Resolved and #[0-9]+ each read 0; lit controls on the same text read Co-Authored-By 1, Claude-Session 1, object-* 3, filter 10.

Gate run on two legs, because a green whose instrument cannot fail is not a reading: scripts/check-partof-closing-keyword.mjs exits 0 on this commit and 1 on 6f2d6d9ac, naming that commit's Part of #17475.

Generators re-run on the newer base: pnpm --filter @objectstack/spec build then gen:docs (222 files) leave the tree carrying only the two paths above. ⛔ No generated artefact was hand-edited.

The falsified sentence

The docblock (anchored by content: Filter rules narrowing which records the picker offers, never by line — the block moves) claimed:

the four object-* blocks declare filter as z.unknown(), no orthography at all — #15449

Re-measured on origin/main, not inherited from the card

The card's census is from fd62a66b7c; this branch was cut from 76c9fab30c and then merged origin/main at bc2bf01c8a. Every number below was taken again on that tree.

1. Census — occurrences, not lines (grep -o | wc -l, on git show origin/main:packages/spec/src/ui/component.zod.ts so no built dist/ is in the population):

probe	occurrences
filter: z.unknown() — dark	0
z.unknown() — lit control, same file, same instrument	61
ViewFilterRuleSchema — lit control	14

The lit controls come back non-zero on the same instrument and the same file, so the dark zero is a reading and not a matcher that finds nothing.

Eight Zod filter declarations exist in the file and all eight are z.array(ViewFilterRuleSchema).optional() (lines 1122, 1158, 1853, 2229, 2490, 2704, 2772, 2882 on origin/main). A ninth filter: line, at 1460, is a KeySetGuidance prose string — not a declaration. The card's grep -n '^ filter:' reading of 7 is the two-space-indent subset of the same set.

2. The object-* block count — measured, not copied. The docblock says four. The family is six:

ComponentPropsMap key	schema	filter door
object-grid	ObjectGridPropsSchema	z.array(ViewFilterRuleSchema).optional()
object-metric	ObjectMetricPropsSchema	z.array(ViewFilterRuleSchema).optional()
object-kanban	ObjectKanbanPropsSchema	z.array(ViewFilterRuleSchema).optional()
object-calendar	ObjectCalendarPropsSchema	z.array(ViewFilterRuleSchema).optional()
object-form	ObjectFormPropsSchema	none declared
object-master-detail-form	ObjectMasterDetailFormPropsSchema	none declared

So "four" is right as a count of filter doors and wrong as a count of the family — and the sentence gave no way to tell which it meant. The file's own header says so independently: #7751 then GREW the map by the object-* block family -- six entries. The corrected prose states both numbers and names all six blocks.

3. #17166 / PR #17473 landed and did fence this key out. 7aae0050bb docs(spec): name all five exportOptions members on object-grid, not two (#17473) is an ancestor of origin/main (git merge-base --is-ancestor exit 0 — positive ancestry, which is self-certifying even on this shallow checkout). Its diff to component.zod.ts touches zero lines containing filter or object-*. Unpaid work, not a duplicate.

4. Wrap-across-line-break handled. Under a naive whitespace flatten the target sentence reads 0 in the source — because a JSDoc block carries a leading * on every line. Stripping the comment prefix before collapsing gives 1. That zero was a mistyped anchor, not an absence, and the edit was anchored on the contiguous two-line span with a uniqueness assertion (hits !== 1 aborts).

The correction

The parenthetical now folds the four filter doors into the enumeration of array-declared doors it belongs in, keeps the #15449 citation as provenance for when they moved, and names the two blocks that carry no filter key at all.

Generated pages: verified on this tree, with a live control

pnpm --filter @objectstack/spec gen:docs regenerates 222 files and leaves the tree clean — a comment docblock is not a .describe(), so content/docs/references/** does not move.

That clean reading is admissible because the instrument was shown to swing the other way. Positive control, trap-restored: a marker was appended to a neighbouring .describe() string on the same schema, proven on disk (grep -c 0 → 1; blob hash d81a58da6c → e341d20797), then gen:schema + gen:docs were re-run — content/docs/references/ui/component.mdx went modified. Restored with git checkout HEAD -- ..., hash back to d81a58da6c, gen:schema + gen:docs re-run from the restored source, git status --porcelain empty.

A first attempt at that control is reported rather than hidden: it exited 1 on a prerequisite refusal (packages/spec/json-schema is older than packages/spec/src), which measured nothing and was discarded, not retried in silence.

Why a changeset, measured rather than assumed

@objectstack/spec files[] ships dist and src/**/*.zod.ts. After a build, the corrected sentence is present in 2 published dist files (dist/ui/index.js, dist/ui/index.mjs) and the old falsified fragment in 0; the lit control (the sibling .describe() prose) hits the same 2 files. The docblock ships. patch on @objectstack/spec.

Verification

Run at 567cb419f8 on the superseded branch; the content of this branch is byte-identical (proof below), rebuilt and re-generated on the newer base d07fc178b9.

• pnpm --filter @objectstack/spec build — VERDICT command-exit 0.
• pnpm --filter '@objectstack/spec^...' build — empty run: No projects matched the filters. packages/spec has no workspace dependencies, so the closure leg measured nothing and is reported as such.
• pnpm --filter @objectstack/spec typecheck — VERDICT command-exit 0; check:test-typecheck: OK — 54 file(s) / 259 error(s) / 144 pinned signature(s) held.
• pnpm --filter @objectstack/spec test — VERDICT command-exit 0; Test Files 473 passed (473), Tests 13429 passed (13429).
• pnpm lint (eslint . --no-inline-config, the repo-wide population) — exit 0. Run whole, at this HEAD, so no narrowing is claimed and none needs defending.
• Derived gate families, via node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (change set taken by the script from the merge base, not hand-listed): 76 derived, 75 run green, 1 NOT MEASURED, 0 unrun, reconciled with --ran carrying a recorded exit code per family.

Two families were re-run rather than reported from a misinvocation:

• check:doc-formula-expressions first exited 3 — PREREQUISITE NOT MET, unbuilt @objectstack/formula / @objectstack/lint. Nothing was measured. After building both: exit 0.
• check:react-declaration-parity first exited 1 with MANIFEST is not set — this gate did NOT run. Re-run as CI runs it (MANIFEST="$PWD/sdui.manifest.json" ... --baseline react-declaration-parity.baseline.json --strict): exit 0, no new DECLARATION divergence vs accepted baseline.
• check:lean-entry-closure first exited 3 on an unbuilt @objectstack/objectql. After building it: exit 0.

NOT MEASURED, declared: pnpm check:dual-build-cjs-loads exits 3 — PREREQUISITE NOT MET, 48 packages have no dist/; clearing it is a repo-wide pnpm build, which is CI's run and not this round's. Recorded as exit 3, never as a pass.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH

---

Generated by Claude Code

[os-bill]

Supersedes #17652, which is now closed. ⛔ Its branch is deliberately left in place.

#17652 carried the identical correction; its commit message also carried Part of #17475, which the contract puts in the PR body only. This branch was cut fresh from origin/main rather than rewriting anything published.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 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 — 135 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 d07fc178b9ae778e3dca988c641d18065d8f392b → packageMentionDocs.

Which tree this was computed on

This run read content/docs from bdeb98399615fc745574eb38336f7c23a08f05b4 — the merge of head c65d38699c3f2a31999c77f6485b4433cc667b2f into base d07fc178b9ae778e3dca988c641d18065d8f392b, 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 bdeb98399615fc745574eb38336f7c23a08f05b4 && git checkout bdeb98399615fc745574eb38336f7c23a08f05b4
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d07fc178b9ae778e3dca988c641d18065d8f392b c65d38699c3f2a31999c77f6485b4433cc667b2f && git checkout -B drift-repro d07fc178b9ae778e3dca988c641d18065d8f392b && git merge --no-ff c65d38699c3f2a31999c77f6485b4433cc667b2f

node scripts/docs-audit/affected-docs.mjs --json d07fc178b9ae778e3dca988c641d18065d8f392b

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