docs(spec): say only what holds before the picklist reference is resolved (#19518)

[objectstack-fleet]

Part of #19518

Clause-②: no

Follow-up to #20823. The server does not resolve a picklist reference yet, so four sentences that said it does are deleted or restated: the FieldSchema.picklist describe, its doc comment, the PicklistServedFieldSchema doc comment, and the refusal of picklist with options. The reference pages that copy the describe are regenerated with check:generated --fix. There is no behavior or assertion change.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 1 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/spec/src/data/picklist.zod.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

12 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-driven.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/data-modeling/external-datasources.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/data-modeling/field-types.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/data-modeling/validation-rules.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/deployment/troubleshooting.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/deployment/validating-metadata.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/getting-started/quick-reference.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/kernel/contracts/data-engine.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/protocol/backward-compatibility.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/protocol/objectql/types.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/protocol/objectui/concept.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/ui/forms.mdx (via FieldSchema (symbol, a top-level const))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via FieldSchema (symbol, a top-level const))
• content/docs/releases/v17/17-1.mdx (via FieldSchema (symbol, a top-level const))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/src/data/picklist.zod.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 137 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 07356a6ab0b9b04ab8791db1f15b3f5b67759ca2 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 07356a6ab0b9b04ab8791db1f15b3f5b67759ca2

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

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 07356a6ab0b9b04ab8791db1f15b3f5b67759ca2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3ccc350fab32cb4c728e664071f63b559abdd4fd
Local-runs: none

Reviewed read-only: card #19518 (body and all twelve comments, among them the seat's ruling 5913074894 (B), its landing note 5913418487, and the dev reports 5913048688 and 5914573661), the review record 5912646092 on PR #20823 whose item 1 flagged the four sentences, PR #20878's body, its six-file list and the net diff from merge-base 07356a6ab0 to the head (+16 / -16), the tree on main (origin/main at 4edb61449b, which holds addbbf02ab, the landing of #20823), and the head's check-runs. Read with git show, git grep, git diff, git log and git patch-id only; nothing checked out, built, tested or re-run.

① Derived judgments

Accept set: unchanged. The diff touches three string literals and two doc comments in packages/spec/src/data/, five generated table rows in content/docs/references/, and adds one changeset. No schema, refinement, type, export, test or fixture moves. The superRefine block at field.zod.ts 2128-2155 still refuses picklist on a non-option type at path picklist and picklist together with options at path options; only the second refusal's message changes, by one phrase. Nothing accepted on main is refused at the head and nothing refused is accepted. Right.

Public surface, each change named:

1. FieldSchema.picklist .describe() loses its third sentence ("The server resolves the reference: the field clients read carries the resolved options."). The string ships in @objectstack/spec dist, in the generated JSON schema (packages/spec/json-schema/, gitignored at .gitignore line 63, so no tracked copy exists) and in the five reference-page rows. Right: it is the sentence item 1 of 5912646092 named, and on main it is false. git grep of picklist over every packages/*/src outside spec finds only the CLI i18n walk, a driver-sql classification row, lint prose and audit prose, no resolver; packages/spec/liveness/field.json grades the key planned, "not yet resolved by the server", with authorWarn.
2. The regenerated copies: field.mdx (1 row), object.mdx (2 rows), migration.mdx (2 rows). git grep of the describe's opening words at the head finds exactly those five rows plus the source, so every tracked copy moved. main has not touched any of the six files since 07356a6ab0 (empty git diff --stat against origin/main), so the pages are current against the tip as well. Right.
3. The pair-refusal message: "the shared list supplies them" becomes "the picklist holds them". A runtime-visible string (the issue message a failing parse answers), not an accept-set change. No test pins either literal: picklist.test.ts asserts toContain('picklist') on this message (line 119) and nothing else, and a git grep for "cannot both be declared", "takes its options from exactly" and "Name of a shared" across every test and script at the head finds no hit. Right.
4. Two doc comments (the FieldSchema.picklist docblock; the PicklistServedFieldSchema docblock). Source and hover text, read by authors and AI. Right, sentence by sentence below.

Every changed or added sentence, tested against the tree on main at landing:

• Describe, as it now reads. "Name of a shared picklist whose options this field offers — instead of options, never with it." True now: picklist is SnakeCaseIdentifierSchema.optional(), and the door refuses it with options (path options). "Option types only (select, radio, multiselect, checkboxes, tags)." True now: the refusal tests SINGLE_OPTION_TYPES (select, radio) and MULTI_OPTION_TYPES (multiselect, checkboxes, tags), field-value.zod.ts 141-148; the list is exactly the union. "Whose options this field offers" states the authored intent and makes no served-shape claim, so it reads correctly beside the ledger's warning.
• FieldSchema.picklist docblock, the restated line: "PicklistServedFieldSchema declares the served form." True now: the schema exists (picklist.zod.ts 159-166), is exported, and its own describe is "The served form of a picklist-bound field". "Declares" is what a schema with no producer on main does. The next sentence, retained unchanged ("Option labels translate under picklists.NAME.options.VALUE, which every referencing field inherits"), is true of the translator now: translateObject in i18n-resolver.ts (2802-2811) looks a picklist-bound field's option up under the list when no field-level entry exists, pinned by feat(spec): the picklist metadata kind — a shared option list select fields reference by name (#19518) #20823's ablation A3; it acts on served options, so it has an effect on a served object once picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519 resolves them.
• PicklistServedFieldSchema docblock. The cut sentence ("Every consumer that reads field.options today … nothing a client does changes for a picklist-bound field") is the one the review named, and its removal is right: on main a consumer reading field.options on a picklist-bound field reads nothing. The paragraph now ends at "still naming the list they came from." One retained sentence still reads in the present tense: "What a client receives for that field carries both: options, RESOLVED … and picklist". It sits under the docblock's own opening, "the contract the object read exits owe a client", and the module docblock (lines 22-24) says "once the reference is resolved", so it reads as the owed contract. As a contract statement it is true now; as a fact about a served field it is true only after picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519 lands. It was not among the four the review flagged, and ruling 5913074894 fixed this PR's cut to those four ("the ruled cut stays exactly as it is"), so it is not a defect of this PR; carried in ③.
• Refusal message, the prescription as it now reads: "Keep picklist: 'NAME' and delete options: the picklist holds them (to offer a new value, add it to the picklist, or through picklistExtensions when another package owns it). Or delete picklist to keep an inline list of this field's own." True and actionable now: a picklist item declares options with min(1) (PicklistSchema), so the picklist does hold them; "add it to the picklist" is an authored edit to a *.picklist.ts or defineStack({ picklists }); picklistExtensions is a declared stack collection whose PicklistExtensionSchema is { extend, options min 1 }, described as "owned by another package (additive only)", so the parenthetical matches the shape; deleting options or deleting picklist each yields a field the door accepts. "Holds" states the declared source without claiming resolution, which is the correction the review asked for. An author who takes the first branch on main today gets a field the liveness rule warns on (authorHint: "Keep inline options on fields that must work today"), and the message does not say otherwise.
• Changeset .changeset/19518-picklist-wording.md: "the picklist field key's description, two doc comments and the refusal of picklist with options no longer say that the reference is resolved and its options served". True: that is the four hunks, one each. Clause-②: no: right, see ②.
• PR body. "The server does not resolve a picklist reference yet" — true on main (the grep above; feat(spec): the picklist metadata kind — a shared option list select fields reference by name (#19518) #20823's own changeset says "This release does not resolve the reference"; the ledger row names picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519 as the reader, "not landed"). "four sentences that said it does are deleted or restated: the FieldSchema.picklist describe, its doc comment, the PicklistServedFieldSchema doc comment, and the refusal of picklist with options" — true, hunk for hunk (two deleted, two restated). "The reference pages that copy the describe are regenerated with check:generated --fix" — true: the three pages carry exactly the describe's new text and nothing else in them moved. "There is no behavior or assertion change" — true for the accept set and for every test; the one runtime-observable difference is the refusal message's wording, which the body itself names as a restatement. "Part of picklist metadata kind — spec: picklist collection, Field.select({ picklist }), server-resolved options, translation face (phase 1 of objectstack#18164) #19518" — right: the card stays open for the Tier H docs PR (5913418487), and Part-of PR must not also close its card is green.

Delta check against the ruling. 5913074894 (B) ordered a follow-up from a fresh branch off the new main, carrying the dev's two round-3 commits and a patch changeset, touching packages/spec/src/data/** and content/docs/references/** only. Verified: the branch point 07356a6ab0 contains addbbf02ab; 107b5e0518 and c9eca3df29 have git patch-id --stable cb436dd6aafc31b1… and 4bde9dacada4c96e…, the ids the round-3 report gave for 830102dc7e and f072bf2215; the per-file ids from 07356a6ab0 to the head equal the six in the dev's report; 3ccc350fab adds only the changeset. The file surface is the ruled one plus the ruled changeset, and the six commits' worth of content is the round-3 cut, unwidened.

② Semver level

• @objectstack/spec: patch — matches the diff. The describe ships in dist and in the published JSON schema, and the refusal message ships in dist, so the PR publishes from a released package and AGENTS.md (on main) item 3 forbids skip-changeset for it; nothing is added, removed, widened or narrowed, so minor would overstate. The PR carries no skip-changeset label (labels: documentation, size/s, tooling, needs:contract-review, protocol:data), and Check Changeset is green on its newest run.
• Clause-②: no on both the changeset and the PR body, with no arm — correct under the same rule: no accept-set change and no published shape change, and no with patch is a well-formed pair. Governed Surface Queue Guard is green; the dev's check-governed-merges --branch HEAD read 0 of 6 paths governed, consistent with the ruling's "neither is governed".
• No other package changes; no other changeset owed.

③ Boundary flags

Dev report 5913048688 (round 3, on the old branch). open_questions 1, "queued at 388dcceb29: dequeue (A) or follow-up PR (B)?" — ruled B by 5913074894; delivered as this PR and verified by patch-id above. Answered. Its deviations: the round-3 push was refused (GH006) and neither retried nor re-routed; the worktree was kept for the unpushed commits; dispatch-gates --ran was NOT MEASURED at f072bf2215 because that head could not reach the PR. All three are superseded by the ruling and by the new head's own check-runs. Answered. out_of_scope_findings: none.

Dev report 5914573661 (this PR). open_questions: none. out_of_scope_findings: none. Narrowings and deviations read off its summary and tests:

• Six gate families NOT MEASURED locally (PREREQUISITE NOT MET, no built dist in the fresh worktree; a build was queued twice and never took the lock): check:doc-formula-expressions, check:doc-security-posture and check:skill-examples are hosted by Type Check · consumer gates (lint.yml 6666-6712); check:docs-transcript-drift by Type Check · workspace (lint.yml 6033); check:lean-entry-closure and check:dual-build-cjs-loads by Build Core (ci.yml 2123-2147). All three hosting jobs are success on the head, so the narrowing is covered. Answered.
• An empty branch was pushed first as a write probe; the assignee was set through label-write.mjs; the dev wrote no label. Process, not contract; nothing to answer.
• The report's CI reading (33 success, 2 skipped at 15:38Z) differs from the final read below only because Auto Label and Check PR Size re-ran at 15:39:51Z on a later event and skipped; their earlier runs were success. No gate changed verdict.

The earlier dev reports on the card (5908082075, 5912287363) belong to PR #20823: their open questions and findings were ruled by 5908214854 and 5912334912 and answered in 5912646092 ③, and this PR reopens none of them. The one item of that record this PR carries out is its own wording flag, item 1, which is the whole of this PR.

Reviewer's own flags, none blocking:

1. A fifth "supplies" survives inside the ruled surface. field.zod.ts 2649-2650, the selectFromPicklist docblock: "no options of its own: the picklist supplies them, and FieldSchema refuses the two together." Same verb the PR retired in the refusal message, same file. Here "supplies" names the declared source of the options (true now) and the sentence makes no served-field claim, so it does not repeat the flagged falsehood; but it is the wording the seat chose to retire, two thousand lines up. Not among the four the review flagged, and outside the ruled cut. For the seat: a one-word touch ("holds them") on the next docs pass or on picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519's PR.
2. Present-tense resolution claims outside this PR's ruled surface, both landed with feat(spec): the picklist metadata kind — a shared option list select fields reference by name (#19518) #20823 and true only after picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519: packages/drivers/driver-sql/src/builtin-column-collision.ts line 107 ("names the shared option list the server resolves into options") and packages/spec/src/system/i18n-resolver.ts line 2802 ("A picklist-bound field is served with its list's options resolved onto it"). Both are code comments no author is shown, and neither path is under packages/spec/src/data/** or content/docs/references/**, so ruling B did not put them in this PR. Escalated: a pointer on picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519 so they are re-read when the ledger row flips to live.
3. The retained served-contract sentence (① above): "What a client receives for that field carries both" in the PicklistServedFieldSchema docblock. Reads as the owed contract under its own heading, with the module docblock's "once the reference is resolved" beside it. Escalated with item 2 to picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519, where it becomes plainly true; no change asked of this PR.
4. Not delivered and not expected here, by ruling: the Tier H docs PR (the NORTH-STAR line, the two records-forms items, the coverage.json classification), A select / radio field with neither options nor picklist: refuse it at the FieldSchema door (an accept-set narrowing), or keep it at the ADR-0078 completeness gate? (split from #19518) #20827 ("neither"), picklist kind: the os CLI compile / validate / lint path accepts *.picklist.ts, picklists and picklistExtensions, and os validate refuses a picklist that names no picklist (Scope 6 of #19518) #20825 (CLI) and picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519 (runtime). The card stays open under Part of.

Check-runs on 3ccc350fab32cb4c728e664071f63b559abdd4fd, read last, deduplicated by name keeping the newest started_at: 39 runs, 35 names — 31 success, 4 skipped (Auto Label, Check PR Size, Console Pin Gate, Packed-tarball smoke (opt-in)), 0 failed, 0 still running; the newest run started 2026-09-30T15:39:53Z. Green by name: Build Core, Build Docs, Check Changeset, Check Documentation Links, Dogfood Regression Gate (1/3, 2/3, 3/3, roster), Dogfood Verify CLI, Flag docs affected by code changes, Governed Surface Queue Guard, Lint & Repo Gates, No other open PR may claim the same issue, No other open PR may claim the same single-writer path, Part-of PR must not also close its card, Spec property liveness, Temporal Conformance (live PG + MySQL), Test Core (1/6 to 6/6, roster), The card this PR closes must claim this branch, Type Check · consumer gates, Type Check · debt ledger, Type Check · source gates, Type Check · workspace, TypeScript Type Check, filter. The PR head re-read after the check-runs is still this sha; the PR is a draft, as the ruling's process leaves it until this record is adopted.

Implemented-by: claude/issue-19518-picklist-wording
Reviewed-by: session_01Sfe5YjBLwB9J3y8fvm2xq1

VERDICT: PASS

Adopted and posted by domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1) · 2026-09-30T15:50Z · rendered by the seat's at-tier review subagent on this head. The seat read its served tier family from the subagent transcript before posting.

• The fifth "supplies them" (field.zod.ts 2649-2650) rides the next PR that edits field.zod.ts: fields: number rendering honours the authored useGrouping (1 key) #20313, whose claim will name it. There is no new head here.
• The present-tense comments outside this surface (driver-sql builtin-column-collision.ts:107, i18n-resolver.ts:2802) go to picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519, whose landing makes them true. The seat's pointer 5912707861 on picklist metadata kind — runtime: resolve picklist → options when serving field metadata, validate writes against the resolved set, apply package-level extensions (phase 1 of objectstack#18164) #19519 already carries the class.
• Not governed. needs:contract-review comes off in a separate act after this record reads back, and then the PR goes ready and into the merge queue.

---

Generated by Claude Code