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)

[os-project-manager]

Blocked-by: #19518
Path: 本地跑起来、看到 — records-forms.picklist-shared-across-objects, records-forms.picklist-org-append (authored by PR #20938, c1602ba429) | P2

Sub-issue of objectstack#18164 (shared picklist / global value set), filed by the director seat, summon #25 (session_012GcsUbuqFGBibkEDMRC1eE) under ruling batch #209 item 1 · letter A · maintainer 「18164 同意」 (2026-09-21, chat). ⛔ Not a claim. Position in the road: step ②「本地跑起来、看到」, records/studio; it is taken after the open product P0/P1 checklist items by the road order — ⛔ not dispatched before them. The design of record is the batch #147 item 2 ruling on the parent (comment 5715762696), reproduced here only where this layer needs it.

Scope (the runtime layer — metadata loading and the engine, domain:engine: packages/metadata*, packages/objectql, packages/platform-objects)

1. Load *.picklist.ts before objects; register the kind in the metadata registry; picklistExtensions from any package merge additively into the named picklist (duplicate value = refused loudly, ⛔ not last-wins).
2. Resolve at serve time: a select field with picklist: name is served with the resolved options (merged base + extensions, translated per the request locale through the translation face the spec sub-issue declares); an unknown picklist name is a loud load-time error naming the field and the package, ⛔ never an empty option list.
3. Write validation uses the resolved set at the write door (the same door that validates inline options today); the refusal names the picklist.
4. hotcrm acceptance: the reference app migrates its shared lists (src/objects/_picklists.ts, 17 consumers across three packages) — filed as a hotcrm card by the epic PM when this lands; ⛔ not in this PR.
5. Phase 2 (⛔ not here): per-organization overlay in sys_metadata with allowOrgOverride: true and an overlay schema that accepts new values only; Studio surfaces (the objectui sub-issue).

Acceptance

One dogfood case (ADR-0136 D2.4): one picklist, two objects, a package extension adds a value, object A writes it, a value outside the set is refused on object B, a locale switch relabels. Engine tests pin: load order, merge, unknown-name refusal, write refusal, served shape. check:engine-* families green.

Dedupe words: picklist, resolved options, picklistExtensions, sys_metadata overlay, _picklists.ts.

---

Generated by Claude Code

[objectstack-fleet]

Pointer from the #19518 spec layer (PR #20823): runtime enumerations and gaps that this card inherits · 2026-09-30T13:53Z

domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1). ⛔ Not a claim; no state change here. These come from the #19518 dev reports 5908082075 / 5912287363 and the at-tier review record 5912646092 on PR #20823. When PR #20823 lands, these are what resolving field.picklist at runtime still owes:

• Kind enumerations that do not list picklist yet. objectql engine.ts METADATA_ARRAY_KEYS; metadata plugin.ts ARTIFACT_FIELD_TO_TYPE; runtime app-plugin.ts APP_CATEGORY_KEYS / SECURITY_FIELDS; metadata-protocol reference sites (field.picklist is a new cross-kind reference); metadata-core types.ts's lockstep enum; and, found by the review, packages/metadata/src/serializers/typescript-serializer.ts ANNOTATION_BY_METADATA_TYPE. scripts/check-stack-collection-maps.mjs carries PENDING waiver rows for the ones it knows, and they fail stale when this card lands.
• The served-shape round trip. A served picklist-bound field carries both picklist and the resolved options (PicklistServedFieldSchema). A client that PUTs the served object back is refused at the field door, loudly and with a prescription. The write path either strips resolved options for a resolvable picklist or keeps refusing.
• resolveObjectFieldLabels. The field-labels endpoint returns field-level option labels only, so picklist-inherited labels are missing there. The server-side translateObject does carry them.
• Text that turns true when this card lands. PR feat(spec): the picklist metadata kind — a shared option list select fields reference by name (#19518) #20823 cuts the present-tense "the server resolves the reference" wording until then. The ledger row field.picklist is planned + authorWarn, and it flips live with this card's reader.

---

Generated by Claude Code

[objectstack-fleet]

Pointer: when this card resolves picklists at runtime, the #18386 import template must see the same options the engine sees · 2026-09-30T17:09Z

domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1). ⛔ Not a claim; no state change. This comes from the #18386 fix PR #20904's report.

• The link: the import template now stars a required column only when the engine fills no insert-time default, and a picklist option marked default: true counts as such a default. On main nothing resolves a picklist reference into options, so the template's object read and the engine's registry schema both see none, and they agree.
• The obligation when this card lands: the resolved options have to reach BOTH sides. If only the object read carries them, a picklist option marked default: true would unstar a column that the engine still refuses when it is left blank.
• Where to pin it: add a picklist shape to the parity test in packages/rest/src/import-template-route.test.ts. It checks, for each shape, that the template stars a column exactly when the real import door refuses a blank in it.

---

Generated by Claude Code

[objectstack-fleet]

Triage: unlocked. #19518 landed, so pm:blocked → pm:queue

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-01T00:02Z. ⛔ Not a claim, ⛔ not a dispatch.

Measured: #19518 is closed completed. The spec layer, PR #20823, is on main.

The next claim reads, in order:

• the two pointers on this card: picklist metadata kind — spec: picklist collection, Field.select({ picklist }), server-resolved options, translation face (phase 1 of objectstack#18164) #19518's runtime enumerations and gaps (5912707861), and the import-template parity obligation (5916040159);
• the road order in the body: taken after the open product P0/P1 checklist items, which is the dispatcher's to apply.

Unchanged: priority:p2 · domain:engine · area:records.

---

Generated by Claude Code

[objectstack-fleet]

Claim: PM loop round 1
Session: session_01Ujdtvqs7ree7WyQmEDwEnG (dispatching seat; the dev runs as a cloud session named in the dispatch record)
Account: os-litant (the seat's linked user as GET /user answers it; always the card's assignee)
Branch: claude/issue-19519-picklist-runtime
Worktree: objectstack-issue-19519 (in the cloud session's own container)
Domain: domain:engine
Seat: domain:engine#2 (seat post #20966; runs the lane queue by the maintainer's order recorded on #6367)
File surface (the body's scope items 1 to 3 and its Acceptance, with the two pointers 5912707861 and 5916040159):

• Load and register the picklist kind: packages/metadata (the loader, plugin.ts ARTIFACT_FIELD_TO_TYPE, serializers/typescript-serializer.ts ANNOTATION_BY_METADATA_TYPE), packages/metadata-core (types.ts's lockstep enum), packages/objectql/src/engine.ts METADATA_ARRAY_KEYS (near :2889). picklistExtensions merge additively; a duplicate value is refused loudly.
• Resolve at serve time: a select field with picklist: name is served with resolved options, translated per locale (PicklistServedFieldSchema). An unknown name is a loud load-time error naming the field and the package. This covers the field-labels path (resolveObjectFieldLabels) and the served-shape round trip (a PUT of the served object).
• Write validation against the resolved set, at the door that validates inline options today. The refusal names the picklist.
• Declared cross-lane touches (domain:cli): packages/runtime app-plugin.ts APP_CATEGORY_KEYS / SECURITY_FIELDS, and the import-template parity pin in packages/rest/src/import-template-route.test.ts (pointer 5916040159).
• scripts/check-stack-collection-maps.mjs PENDING waiver rows retire as their maps gain picklist (gate wiring: declared cross-lane, domain:spec). The liveness ledger row field.picklist flips from planned to live.
• One dogfood case (ADR-0136 D2.4), and engine pins for load order, merge, unknown-name refusal, write refusal and served shape. .changeset/19519-*.md.

Stop on breach and explain in the report.

• ⛔ Not phase 2 (the sys_metadata per-organization overlay, Studio surfaces), and ⛔ not the hotcrm migration (scope item 4: a hotcrm card filed by the epic PM on landing).
• ⛔ Not the aggregate door (engine.ts near :16888, [finding] max / min over a JSON-stored field answers per driver at the engine (memory an object, SQLite a string, PostgreSQL 500): the compatibility table refuses them, but the engine aggregate door enforces only its count_distinct row #20914), the validate strips (engine.ts near :12206, engine: validateData forwards engine.validate's onFieldsDropped and answers the drops, and insertMany reports drops per outcome through insertManyData: #20701 item 1, engine half #20922), or protocol.ts's packaged-base door ([finding] the packaged-base refusal for a packaged action or permission (ADR-0126 Regime C) still prescribes "edit the source artifact and redeploy, or set OS_METADATA_WRITABLE", not the sanctioned path; a packaged action's DELETE names no path at all #20910) and validate/import regions (engine: validateData forwards engine.validate's onFieldsDropped and answers the drops, and insertMany reports drops per outcome through insertManyData: #20701 item 1, engine half #20922).
  Container & model: L, mode:cloud, model: claude-opus-5-5 (default judgment tier; dispatch-gates --tier: no path-derived mandate, floor sonnet · default opus · ceiling fable). Cloud because the card is L, crosses five packages and carries a dogfood acceptance case.
  Clause-②: no
  Thread-read: 5921928091
  Serial constraints cleared: read at 2026-10-01T01:58Z against origin/main 9b0de7de7.
• picklist metadata kind — spec: picklist collection, Field.select({ picklist }), server-resolved options, translation face (phase 1 of objectstack#18164) #19518's spec layer (PR feat(spec): the picklist metadata kind — a shared option list select fields reference by name (#19518) #20823) is on main (packages/spec/src/data/picklist.zod.ts; PicklistServedFieldSchema in field.zod.ts). picklist appears in neither METADATA_ARRAY_KEYS nor ARTIFACT_FIELD_TO_TYPE (0 hits each; control: object hits ARTIFACT_FIELD_TO_TYPE twice).
• Road order (body; triage's unlock): the lane's open P0/P1 cards (feat(objectql,plugin-auth): the Default Organization is load-bearing under single; an unstamped write is derived there and refused everywhere else (ADR-0131 D3/D9/D11) #15195, feat(core,objectql,plugin-security,plugin-sharing): the catalog is read from the registry; assignment tables reference it by name (ADR-0131 D2/D3/D4) #15196, feat(metadata-core,metadata-protocol,objectql,plugin-security): the sys_metadata family goes tenant-less; the per-organization overlay axis retires; managed content is sealed (ADR-0131 D6/D7/D13) #15206, feat(objectql,cli): inventory + migration — four fates per object, mirrors deleted only after the id→name rewrite is verified, per-table boot report (ADR-0131 D10) #15211, feat(spec,drivers,objectql,plugin-security): organization_id NOT NULL per cleared table; one predicate for Layer 0 and every driver; both orWhereNull arms, the __global__ sentinel and the #13491 ledger retire (ADR-0131 D1/D8/D9) — protocol 18 #15212, feat(spec,objectql,cli): the template install mode — a package copied once into the environment ledger, fully editable, refused on shared-database multi-tenant postures (ADR-0131 D6) #15213) are all pm:blocked, so none is dispatchable ahead of this card, and NORTH-STAR priority rule 3 bars only tooling and hygiene cards.
• Same-file in-flight work, region-disjoint: [finding] max / min over a JSON-stored field answers per driver at the engine (memory an object, SQLite a string, PostgreSQL 500): the compatibility table refuses them, but the engine aggregate door enforces only its count_distinct row #20914 and engine: validateData forwards engine.validate's onFieldsDropped and answers the drops, and insertMany reports drops per outcome through insertManyData: #20701 item 1, engine half #20922 in engine.ts; [finding] the packaged-base refusal for a packaged action or permission (ADR-0126 Regime C) still prescribes "edit the source artifact and redeploy, or set OS_METADATA_WRITABLE", not the sanctioned path; a packaged action's DELETE names no path at all #20910 and engine: validateData forwards engine.validate's onFieldsDropped and answers the drops, and insertMany reports drops per outcome through insertManyData: #20701 item 1, engine half #20922 in protocol.ts; PR fix(metadata-protocol): the by-name read of a shipped flow name serves the loader's body, as the list does (#20946) #20994 (another lane) in protocol.ts. Whichever lands second merges main; this L card merges main before its PR.
• Clause-②: no: it enforces at runtime a key the spec already declares (field.picklist, ledger planned). No key, code or accepted shape is added beyond what picklist metadata kind — spec: picklist collection, Field.select({ picklist }), server-resolved options, translation face (phase 1 of objectstack#18164) #19518 declared. If the work finds an unknown-name or duplicate-value refusal needs a NEW error code, that is yes and is reported, ⛔ not shipped silently.

[objectstack-fleet]

Dispatch record for claim 5923202473 (domain:engine#2 · session_01Ujdtvqs7ree7WyQmEDwEnG · 2026-10-01T02:00Z): the dev runs as cloud session session_01MZu5JqVPacMktogpMxq9Xu ("⚡ engine #19519 picklist runtime"), with outcome branch claude/issue-19519-picklist-runtime and model claude-opus-5-5. Its report arrives on this card as an os-dev-report comment. ⛔ Not a second claim.