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.

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, tree clean.

• 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.

Known red: Part-of PR must not also close its card

⚠️ Self-inflicted and, on an already-pushed branch, not clearable by any author action — reported rather than worked around.

Commit 6f2d6d9ac carries Part of #17475 in its message. The contract puts the card relation in the PR body only; a commit carries no card trailer. I wrote it into both, and pushed before the guard ran.

scripts/check-partof-closing-keyword.mjs, reproduced locally against this PR's own commit list and body, exits 1 and states the remedy itself:

⛔ The repair is NOT a history rewrite. Amend, rebase and force-push are forbidden in this repository and this gate never asks for one. […] BRANCH ALREADY PUSHED — no author action clears this red […] the only thing that would remove it is the rewrite forbidden above.

Three facts from the gate's own text, so this can be read rather than acted on: the check is advisory at the branch-protection layer (absent from the required-context registry; its workflow subscribes to no merge_group event); the trailer's spelling is Part of, which lands as a reference and moves no card; and the card relation is carried by the PR body regardless. ⛔ I did not amend, rebase or force-push, and ⛔ I did not reword the body to hide it.

It also sits outside the derived gate total above: dispatch-gates --ran names the path-scheduled CI jobs as a separate class from the 76 families it derives, and this is one of them.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH

---

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 a3ce6bfa132d47d07eef4e53db0bd6d0bdcb3aa0 — the merge of head 567cb419f8635c341dffcd1bf6ceca882397f496 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 a3ce6bfa132d47d07eef4e53db0bd6d0bdcb3aa0 && git checkout a3ce6bfa132d47d07eef4e53db0bd6d0bdcb3aa0
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d07fc178b9ae778e3dca988c641d18065d8f392b 567cb419f8635c341dffcd1bf6ceca882397f496 && git checkout -B drift-repro d07fc178b9ae778e3dca988c641d18065d8f392b && git merge --no-ff 567cb419f8635c341dffcd1bf6ceca882397f496

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.

[os-bill]

Superseded by #17657 — closing this one, ⛔ branch deliberately NOT deleted.

Same correction, byte-identical content (git hash-object proof is in the new PR's body). What differs is only the commit message: this PR's commit 6f2d6d9ac carries Part of #17475 in its MESSAGE, and the contract declares the card relation once, in the PR body. check:partof-closing-keyword is red here for that reason, and on an already-pushed branch nothing clears it — amend, rebase and force-push are forbidden, and the gate never asks for one. So the repair is a fresh branch off current main, not a rewrite: ⛔ nothing published was rewritten.

The new commit was checked before it was pushed: Part of, Part-of, Refs, Fix/Fixes/Fixed, Close/Closes/Closed, Resolve/Resolves/Resolved and #[0-9]+ each read 0 occurrences, with Co-Authored-By and Claude-Session reading 1 each as lit controls. The guard was then run on two legs — exit 0 on the new commit, exit 1 on 6f2d6d9ac — so the green is a reading rather than an instrument that cannot fail.

---

Generated by Claude Code