[objectstack-fleet]

Requested by Steve · project thread

Part of #31678

Clause-②: no (narrowing)
Metadata-protocol: none
Narrowing: yes. (1) D3 (a): a package field whose picklist only an environment-authored item holds is served with no options and its values are refused. (2) The general outside-closure case, ruled inside ADR-0150 D3 step 3: a package field whose picklist another package holds, with no declared dependency on that package, is refused the same way. N1 is ruled on #31678 (the declared dependency closure only), so this includes a sibling in the same artifact. First-party count: 0 for both in shipped code. No examples/** app and no platform package declares a picklist (only notes in examples/app-showcase/src/coverage.ts mention them). In first-party tests, two fixtures relied on a sibling's list with no declared dependency and get a forced dependencies edit (listed under Tests): manifest-service-residual-objects.test.ts and cli/src/utils/picklist-references.boot-parity.test.ts. HotCRM is not in this session's repository scope, so it is not measured. D3 (a) is not measurable first-party, because no environment exists there.
Skills-docs: none. The published skills never teach a field that names another package's picklist; skills/objectstack-data/SKILL.md mentions picklist only for fieldPatches.

This PR is a draft until the epic seat's final check. N1 is ruled and R2 #31733 has landed, so nothing is held red on this head.

维护者速读

• 改了什么：字段上的 picklist 名称现在按“声明该字段的包”去解析（自己的包 → 已声明依赖的包 + sys → 拒绝），统一走 ADR-0150 的包作用域解析器；同一发布包内的兄弟包也必须声明依赖（N1 已裁决）；api 端点索引改为按（包, 名称）各留一条。
• 为什么改：ADR-0150 D3 要求同名元数据按引用方的包解析，不能再靠“先注册先得”或环境里的同名条目。
• 风险与回滚：收窄。包字段引用了只有环境条目持有的列表，或引用了未声明依赖的其他包（含兄弟包）的列表，会变成无选项、值被拒；启动只告警不失败，启动后安装会被拒。线上第一方计数为 0；两个测试夹具补了依赖声明。回滚即 revert 本 PR，无数据迁移。
• 先看：packages/objectql/src/registry.ts 中的 picklistReferrerOf 与 picklistReferenceVerdict，以及 plugin.ts 中启动审计的告警分支和安装判定。
• 两分钟验证：pnpm --filter @objectstack/objectql exec vitest run src/engine-picklist.test.ts src/plugin-picklist-boot-audit.test.ts src/manifest-service-residual-objects.test.ts，看 “ADR-0150 D3” 相关 describe 全绿。
• 需要你做的：无。席位在史诗最终检查通过后落地。

What changes

Picklist, by the referrer's package (@objectstack/objectql). Every picklist lookup now calls R's resolvePackageScopedName (type picklist), which since R2 #31733 is an adapter over the lean core rule and packageResolutionClosure. There is no second closure walk, no id-prefix reading and no first-registered fallback on any touched path.

• A field's picklist resolves with the package that declares that field as the caller. The referrers are every packaged own or extend contributor that declares that picklist on that field (picklistReferrerOf). The field is served only when every referrer reaches the same holder; otherwise it is served no options. There is no fold-order pick. A field written only by an environment-authored body (a tenant overlay, an object created in Studio) has no package, so it resolves environment-wide, as before.
• A picklistExtensions entry's extend resolves caller-less (the epic seat's ruling X on this card). An extension still adds its options to the one list its extend names in the environment, whether or not its package depends on that list's package. Extensions are folded onto a field's list only when the caller-less holder is the same holder the field resolved.
• The boot audit (kernel:ready) still throws for a reference no holder can satisfy (not found, ambiguous). For every outside-closure refusal (an environment-only list, or a package outside the declared closure, a sibling included) it warns and the boot goes on (ruling N2). The read serves that field no options and the validator refuses its values.
• The post-seal install judge (the manifest service) judges each pending field reference with its package as caller, through a registry view that overlays the pending artifact's manifests and their lists, and hands the walk the registered residual owners' declared dependencies (ADR-0130 D4, read through R2's residualOwnerDependenciesOf). A manifest's own lists short-circuit. It refuses loudly, carrying R's refusal message, which names every holder. Extension targets are judged caller-less.
• describeUnresolvedPicklistReferences appends R's refusal to each line. Its headline is unchanged.

The api endpoint index, by (package, name) (@objectstack/metadata). MetadataManager.listForIndex('api') (the matcher's listApiItems and the anonymous-flow-door audit) now keeps one slot per (package, name) instead of one per bare name. A package-less row under a name exactly one package holds is that package's customization, so it keeps sharing that slot (first entry wins, registry before loaders, as before). An environment-only row has its own slot. There is no resolver call there: @objectstack/metadata cannot import R (objectql depends on it), and the request side is caller-less. The route grammar and precedence are untouched (they belong to G1 and the router).

Every by-name reader and the referrer it now passes

Reader	Referrer package passed
SchemaRegistry.resolvePicklistFields through finishServedObject (every served object, from foldExtendersOntoDefinition and the no-extenders branch of foldObjectExtendersOnto)	every declaring packaged contributor's packageId (picklistReferrerOf), served only when all reach one holder; null when only an environment-authored body declares the field
SchemaRegistry.resolvePicklistOptions(name, callerPackageId?)	the caller's argument; omitted means package-less
SchemaRegistry.findUnresolvedPicklistReferences / findOutsideClosurePicklistReferences (boot audit, plugin.ts kernel:ready)	each packaged contributor's packageId
SchemaRegistry.findOrphanPicklistExtensions (boot audit)	none (caller-less, ruling X)
registerPicklistExtension / assertPicklistValuesDistinct	none (caller-less, ruling X)
post-seal install judge (plugin.ts, manifest service)	field refs: the pending package's id, with the pending manifests overlaid; extensions: none
protocol-save-door-refusals.ts (@objectstack/metadata-protocol, save door)	none: a package-less caller per R. Not in this card's surface, so not edited
cli/src/utils/seed-record-values.ts	none: a package-less caller per R. Not in this card's surface, so not edited
MetadataManager.listForIndex('api') → EndpointMatcher	none: requests are caller-less. The key is now (package, name), not the bare name

Not in this PR.

• Functions: engine functions by package came with R2 feat(core, metadata-core, objectql): the package-scoped resolution rule as a lean core, engine functions by package #31733; nothing more here.
• Mapping and dataset: no package-referrer reader exists in this card's surface. Their doors (rest import-mapping.ts, analytics-routes.ts) and service-analytics' cube-name reads resolve as package-less callers per R. There is no code for them here.

That is why the first line says Part of, not Fixes.

Tests

New pins, each ablation-verified.

• packages/objectql/src/engine-picklist.test.ts, describe picklist — resolved from the package that writes the reference (ADR-0150 D3):
  • D3 (a): an environment-only list, so the field is served no options, the validator refuses, and findOutsideClosurePicklistReferences names it.
  • Outside the closure: findUnresolvedPicklistReferences is empty and findOutsideClosurePicklistReferences names the field, with R's refusal naming package "com.test.lists".
  • CONTROL: with a declared dependency, the list is served.
  • CONTROL: a package-less referrer is served the environment list.
  • Two packages writing one field's reference: served no options unless both reach the list. CONTROL: both depending on the list's package are served it.
  • An extension extends caller-less with no dependency.
• packages/objectql/src/plugin-picklist-boot-audit.test.ts:
  • describe the picklist boot audit — a list only the environment holds (ADR-0150 D3 (a)): the boot succeeds and serves no options; a late artifact is refused, naming the environment; CONTROL: with a dependency, it registers; a list held by a package outside the closure boots with a warning and no options.
  • describe the picklist install door — a sibling in the same artifact (ADR-0150 D3): a sibling's list with no declared dependency is refused, naming that sibling. CONTROL: with the dependency, the artifact registers.
• packages/objectql/src/manifest-service-residual-objects.test.ts: after start(), a package depending on the residual owner reaches the list its dependency holds.
• packages/metadata/src/metadata-manager-match-endpoint.test.ts, describe the endpoint index keeps one slot per (package, name) (ADR-0150 D4):
  • Two packages' same-named items are both served.
  • CONTROL: a package-less row shares the holder slot, and the first one wins.
  • CONTROL: an environment-only row is served.

Forced test edits (fixtures that relied on outside-closure resolution, which D3 step 3 and the N1 ruling now refuse):

• engine-picklist.test.ts: the HEALTH app gains dependencies: { 'com.test.picklist.core': '^1.0.0' }.
• engine-picklist.test.ts: the load-order test registers its object under com.test.core (the list's own package) instead of com.test.early.
• plugin-picklist-boot-audit.test.ts "boots when the list arrives…": the app gains dependencies: { 'com.test.boot.lists': '^1.0.0' }.
• plugin-picklist-boot-audit.test.ts "after the boot, an artifact that brings its own list…": com.test.late gains the same dependency.
• manifest-service-residual-objects.test.ts "a residual object whose field names a picklist a BODY declares…": the stack's manifest gains dependencies: { 'com.example.acme.service': '^2.4.0' } (N1: a sibling needs a declared dependency).
• packages/cli/src/utils/picklist-references.boot-parity.test.ts: the core body gains dependencies: { 'com.example.parity.app': '^1.0.0' } (N1, same reason).

Red on main. The first round's pins were run against main's source:

• engine-picklist: two red (expected [{Gold}] to be undefined); its three controls pass.
• boot audit: two red (expected ['technology'] to deeply equal [], expected [Function] to throw); its control passes.
• api index: one red (expected undefined to be 'b'); its two controls pass.

The two-referrer, sibling-door and boot-warning pins guard this PR's own rules (on main a sibling's list resolves first-registered), so their proof is the ablations below. The residual-owner pin is green on main too (no closure check there) and guards the install view; its proof is ablation 7.

Ablations (scripts/ablation-replace.mjs; restored each time, blob equal to HEAD):

1. Drop the referrer (always caller-less): two pins red.
2. Fold the boot's environment-held arm back into the throwing set: one red.
3. Remove the api byPackage delegation: one red.
4. Keep only the last referrer (the old fold-order pick): the two-referrer pin red.
5. Judge the install with the whole artifact's lists as every manifest's own: the sibling-door pin red.
6. Warn only for environment-held refusals (N2 for the environment only): three red.
7. Drop residualOwnerDependenciesOf from the install view: the residual-owner pin red (refused at install, "held outside the declared dependency closure of package "com.example.late"").

Acceptance notes

Red line 3.

• (a) Phase-1 one-holder suites are green and untouched: registry-bare-name-one-holder.test.ts, -ai-family, -flow-family, -request-family, and package-scoped-resolver.test.ts. bare-name-one-holder.ts and package-scoped-resolver.ts are not edited.
• (b) Bare-name behaviour (URL, MCP, SDK) is unchanged for every name with one holder, except the declared narrowings above. A package field whose list its own package or its closure holds is served exactly as before. A package-less caller resolves through R's package-less rule (the environment item first, then the unique holder), and the CONTROL pin shows it is served the same list as on main. Api routes answer as before while each api name has one package holder.
• (c) No migration. No key or stored shape changes. ADR-0087 disposition: not-required (no-migration-prescription), in the changeset.
• (d) Clause-②: no (narrowing), above and in the changeset, with a BREAKING banner.

Holds cleared. N1 is ruled on #31678 (declared closure only): the residual test is green with its forced edit. R2 #31733 landed: the core-boundary ratchet and check:lean-entry-closure are green with no change here beyond reading R2's new platform holder kind in sameHolder.

Open questions (seat's call). New names: findOutsideClosurePicklistReferences, picklistReferenceVerdict, and the byPackage option of the private listForIndex. Types: PicklistFieldResolver, UnresolvedPicklistReference, UnresolvedPicklistExtension.

Verification

Head: bf7e3295e9ed0c6ca46217e172e25ed5f4aeaee7.

Everything below ran on this head, after merging main at 2b752aa4f (R2 #31733 included).

• pnpm --filter @objectstack/objectql test: 577 files and 11821 tests pass, 0 red (the core-boundary ratchet and the residual test included).
• pnpm --filter @objectstack/metadata test: 71 files and 987 tests pass.
• packages/cli seed-record-values.test.ts, picklist-references.test.ts, picklist-references.boot-parity.test.ts: 3 files and 48 tests pass. seed-record-values was red only against a stale objectql build; it is green once objectql is rebuilt.
• typecheck for @objectstack/objectql, @objectstack/metadata and @objectstack/cli: exit 0. The cli check:test-typecheck step ran out of the default 2 GB Node heap in this container on the first run and passes with --max-old-space-size=6144.
• eslint (--no-inline-config) on every changed .ts file: exit 0.
• Full pnpm turbo run build: 120 of 120 tasks succeed.
• dispatch-gates --ran: 75 derived, 75 run, 0 not measured, 0 unrun, every one exit 0. check:lean-entry-closure holds its admitted set (15 packages, no denied name) for both @objectstack/objectql/core conditions.
• Dogfood battery (pnpm --filter @objectstack/dogfood test): 440 files and 3654 tests pass, 3 files skipped.
• CI on this head: every check green.
• Red on main and the seven ablations are listed under Tests.

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/metadata, @objectstack/objectql, touching 45 documentable anchor(s).

26 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 87d945873da8e13ae2b6ee5ac43c075203abc337.

⛔ 11 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 65 of 231 client-bound route-ledger rows — the other 166 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 166: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 59 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 107 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 — 32 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 87d945873da8e13ae2b6ee5ac43c075203abc337 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 87d945873da8e13ae2b6ee5ac43c075203abc337

⚠️ 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 87d945873da8e13ae2b6ee5ac43c075203abc337 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

epic:#31527#1 · os-steve · session_01ADHkmP7o3uDTti21wLTfPf

Epic red-line review (preliminary): E6 #31678, head 62e2f40 · 2026-11-09T00:36Z

This is a preliminary verdict. The final check runs on the head after R2 #31716 lands and N1 shows Ruled: on #31678. Two items are owed by then, both under red line 2.

Item 1: picklist referrer with more than one packaged contributor. picklistReferrerOf loops over the own and then the extend contributors and keeps the last one that declares the field with that picklist name. Take an owner and an extender in different packages that both declare status: { picklist: 'stage' }, where each package's closure holds a different stage. The served field then resolves through whichever contributor happens to come last, which is a silent pick of the caller. Required: resolve the reference for every packaged contributor that declares it. If they all agree, serve that answer. If they differ, refuse, naming each contributor and its holder. Add a test that is red without the fix. If the served merge provably takes one author's declaration, then use that author, pin the rule with a test, and state it. Do not rely on loop order.

Item 2: the install judge's artifact-wide declared.has short-circuit. declared collects every picklist name from every manifest in the artifact. A reference from X is therefore accepted when any sibling Y in the artifact declares the name, even when X's closure holds it twice (the read would then refuse) or Y is outside X's closure. This is unchanged from main, and it is the N1 arm, so it is held for the ruling. Under either ruling, the artifact-wide set goes. Keep only X's own manifest's names, and let picklistReferenceVerdict(…, ordered), which already reads the pending manifests, answer the rest. Under N1 = A, that same resolver call reaches siblings through the closure R2 widens. Under N1 = B, the sibling arm refuses with the outside-closure message.

Reads as passing:

• picklist field refs go through R with the referrer's package as the caller;
• extensions resolve caller-less (ruling X);
• an N2 environment-only holder warns at boot and is served with no options, refusing every value on read, so it fails closed;
• the install judge carries R's own refusal text;
• listForIndex('api') keys one slot per (package, name) with no resolver (my E6 ruling);
• the four forced test edits are declared;
• the N1 residual test and the core-boundary ratchet / check:lean-entry-closure are held red and declared, both on the R2 seam.

Not a governed surface. Seat 2 lands it after my final PASS.

[objectstack-fleet]

domain:server#2 · os-steve · session_01ADHkmRb3wUaRcujR7QEm2o

Both items from the preliminary epic review (6729460160) are fixed at head 054df525.

Item 1: picklist referrer with more than one packaged contributor.

• picklistReferrerOf now returns every packaged own/extend contributor whose own declaration names that picklist on the field, each package once. It no longer keeps only the last one.
• The new SchemaRegistry.resolveFieldPicklistOptions asks R once per referrer. The field is served only when every referrer resolves to the same holder (sameHolder). Any other outcome serves no options, so the validator refuses the field's values: one referrer refused or reaching nothing, or two reaching different holders.
• The boot audit already judges each packaged contributor separately (auditPicklistReferences). So each referrer whose own resolution refuses is named, with R's sentence and its candidates.
• Under phase 1, a disagreement can only be one referrer resolved and another refused. A package caller never reaches the environment's item, and a picklist name has at most one package holder.
• Pin in engine-picklist.test.ts, "two packages writing one field's reference: served no options unless BOTH reach the list (no fold-order pick)". The owner has no dependency on the list's package and the extender, folded last, does. The field is served no options, and the audit names com.test.pkg. A CONTROL test has both depending on it and the list is served.
• Ablation (scripts/ablation-replace.mjs, last-wins put back): the pin goes red, 1 failed / 31 passed. Restored with blob == HEAD.

Item 2: the install judge's artifact-wide declared.has short-circuit.

• The artifact-wide set is gone. Each reference short-circuits only on its own manifest's lists (collectManifestPicklistNames(manifest)). Everything else is answered by picklistReferenceVerdict(…, ordered).
• withPendingManifests now also lists each pending manifest's picklists as held by that manifest's package. Before, it overlaid only getPackage. So R judges a sibling's list through the referrer's declared closure, the way the served field will once the artifact registers. Extension targets are still judged caller-less.
• Pins in plugin-picklist-boot-audit.test.ts, describe "the picklist install door — a sibling in the same artifact (ADR-0150 D3)":
  • A two-package artifact whose app has no dependency on the sibling holding the list is refused. The refusal names package "com.test.suite.lists" and nothing registers. This is the N1 arm, marked as pending the ruling.
  • CONTROL: the same artifact with the dependency registers and is served the list.
• Ablation (the artifact-wide set put back): the refusal pin goes red, 1 failed / 10 passed. Restored with blob == HEAD.

Runs on 054df525:

• pnpm --filter @objectstack/objectql typecheck && … test under the lock: 571 files passed and 11659 tests passed. The same two tests are red as before, both still held: the N1 residual test and the core-boundary ratchet (R2 feat(core, metadata-core, objectql): the package-scoped resolution rule as a lean core, engine functions by package #31733).
• eslint on packages/objectql/src (--no-inline-config): exit 0.

Still owed for the final head: merge main once R2 #31733 lands, then the gates and the dogfood battery again on that head.

---

Generated by Claude Code

[objectstack-fleet]

domain:server#2 · os-steve · session_01ADHkmRb3wUaRcujR7QEm2o

CI on 62e2f40c: two red checks, and neither is a new defect.

• Build Core (job 128913936556) fails at check:lean-entry-closure. It reports FORBIDDEN @objectstack/metadata-protocol in the @objectstack/objectql/core closure, and UNLISTED @objectstack/lint and @objectstack/sdui-parser, which it pulls in. This is the R seam the body already declares (Acceptance notes, "Held red, pending R2"). package-scoped-resolver.ts statically imports packageDependencyClosure from the root barrel of @objectstack/metadata-protocol, and this PR is the first time registry.ts calls it from the core closure. R is not this card's to edit. The root fix is R2 feat(core, metadata-core, objectql): the package-scoped resolution rule as a lean core, engine functions by package #31733: the resolver core moves to @objectstack/core and the closure walk moves to @objectstack/metadata-core. This branch merges main once R2 lands. It will stay red on 054df525 too, for the same reason.
• TypeScript Type Check (job 128917572711): the typecheck-workspace lane concluded cancelled, not failed. The push of 054df525 superseded that run, and the run on the new head is in progress. Locally, typecheck for @objectstack/objectql and @objectstack/metadata exits 0 on both heads.

---

Generated by Claude Code

[objectstack-fleet]

domain:server#2 · os-steve · session_01ADHkmRb3wUaRcujR7QEm2o

Test Core (4/8) on 054df525 (job 128918340662): the one red test is manifest-service-residual-objects.test.ts › "a residual object whose field names a picklist a BODY declares is served with that list". That is the N1 sibling case, held red on this draft and declared in the body (Acceptance notes, "Held red, pending N1"). It is waiting on the maintainer's N1 ruling on #31678.

If another shard goes red on core-boundary.ratchet.test.ts, that is the R seam covered in 6729623082, which R2 #31733 fixes.

No other test in this shard failed. Nothing new to fix here.

---

Generated by Claude Code

[objectstack-fleet]

domain:server#2 · os-steve · session_01ADHkmRb3wUaRcujR7QEm2o

Test Core (1/8) on 054df525 (job 128918340435): three tests are red in @objectstack/cli. I reproduced all three locally (packages/cli, vitest run on the two files: 3 failed / 12 passed).

• picklist-references.boot-parity.test.ts, both cases ("a list a SIBLING package of the same artifact declares: both doors accept it" and "a name no package of the artifact declares: both doors refuse it, at the same field"). The fixture artifact has com.example.parity.core naming a list that its sibling com.example.parity.app declares, with no declared dependency between them. So the boot refuses it with R's outside-closure sentence. This is the N1 arm, held with the residual test until the maintainer's ruling on objectql/rest/analytics: picklist, mapping, dataset, the api matcher's name key and engine functions by referrer (ADR-0150 child E6) #31678.
• seed-record-values.test.ts › "judges a picklist-bound field against the options the stack's picklist resolves". This one is this PR's, and it is not declared yet. The cli judge registers the stack's picklists package-less, and its objects through ObjectQL#registerObject with no package, which defaults to '__runtime__'. R treats '__runtime__' as a package, so D3 (a) refuses the environment list. This is a narrowing wider than the declared one. I've put it to the epic seat with options, and I'm recommending treating the compatibility default '__runtime__' as a package-less referrer. Nothing is pushed until that is ruled.

---

Generated by Claude Code

[objectstack-fleet]

epic:#31527#1 · os-steve · session_01ADHkmP7o3uDTti21wLTfPf

Epic red-line review, final: E6 #31678, head bf7e329 · 2026-11-09T05:50Z

Verdict: PASS.

• Items 1 and 2 from 6729460160: both done, as accepted at 054df52. A field is served only when every packaged referrer reaches the same holder. The install judge short-circuits only on the reference's own manifest.
• N1 Ruled declared-closure-only (6729820123): a sibling in the artifact with no dependency is refused at install. Both forced dependencies edits (the residual fixture and cli boot-parity) are listed, and the Narrowing: line counts them as test fixtures, with a shipped first-party count of 0. Severity follows N2: the boot audit warns on every outside-closure refusal (findOutsideClosurePicklistReferences), the read serves no options, and the install judge refuses.
• After the R2 merge: sameHolder compares on R2's platform kind. The install judge's pending-manifest view forwards residualOwnerDependenciesOf, so there is one closure, pinned, with ablation 7 red.
• Held reds are gone: the core-boundary ratchet, check:lean-entry-closure (admitted set held), the residual test and cli seed-record-values are all green. The last of these was only a stale objectql build.
• Checks: objectql 11821/0 red, 75/75 derived gates, dogfood 3654 tests, CI green.

Seat 2 marks it ready, accepts and lands it. It is not a governed surface. Child A records the ADR-0130 dated note and the picklist-references.ts:42 comment (the list on #31685).

[objectstack-fleet]

domain:server#2 · os-steve · session_01ADHkmQKZzp4DLtqiCkZZRM

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: bf7e3295e9ed0c6ca46217e172e25ed5f4aeaee7
Local-runs: none
Scope: packages/cli/src/utils/picklist-references.boot-parity.test.ts, packages/metadata/src/metadata-manager-match-endpoint.test.ts, packages/metadata/src/metadata-manager.ts, packages/objectql/src/engine-picklist.test.ts, packages/objectql/src/manifest-service-residual-objects.test.ts, packages/objectql/src/picklist-resolution.ts, packages/objectql/src/plugin-picklist-boot-audit.test.ts, packages/objectql/src/plugin.ts, packages/objectql/src/registry.ts + packages/objectql/src/package-scoped-resolver.ts, packages/core/src/package-scoped-resolution.ts, packages/metadata-core/src/package-closure.ts, packages/objectql/src/engine-registration.ts, packages/cli/src/utils/picklist-references.ts, packages/cli/src/utils/seed-record-values.ts, packages/metadata-protocol/src/protocol-save-door-refusals.ts, packages/metadata/src/endpoint-matcher.ts, packages/metadata/src/stored-envelope.ts, docs/adr/0150-behavioural-metadata-addressed-by-package-objects-keep-the-literal-prefix.md (read on origin/main fdfcc7a, never reviewed)

Inputs: card #31678 (body and all 10 comments, rulings 6728478528, 6728613177 and 6729820123 included), PR #31731 body and file list, the net diff of bf7e3295 against its merge-base with main (2b752aa4, 10 files, +837/-75), and the 54 check-runs on the head: 37 success, 17 skipped (UI, docs, opt-in and draft-only legs), 0 failure, 0 pending. main has moved 6 lines in packages/objectql/src/plugin.ts since the merge-base (ADR-0150 D8 ledger backfill at kernel:ready, #31727); it touches neither hunk of this PR and GitHub reports the head mergeable and clean.

① Derived judgments

Every accept-set and public-surface change the diff implies, each judged against ADR-0150 D3/D4 on main and R/R2 as merged (resolvePackageScopedHolders in @objectstack/core, packageResolutionClosure in @objectstack/metadata-core):

1. A served object's packaged field resolves its picklist from the package that declares the field (picklistReferrerOf → resolveFieldPicklistOptions → resolvePicklistOptions(name, caller) → resolvePackageScopedName). Own list → unique holder in the declared closure plus sys → refusal naming every candidate. The referrer is read off the own/extend contributors whose own declaration names that list on that field, tenant-authored layers excluded; a reference no packaged layer writes resolves caller-less. Right: D3's rule and D3's overlay sentence ("a reference written in an environment-authored overlay is the environment's reference"), no first-registered fallback and no fold-order pick anywhere on the path.
2. Two packaged layers writing one field's reference: served only when every referrer reaches the same holder, else no options. Right by red line 2 (ambiguity reported, never guessed). See ④ F2 for the one arm the audit does not name.
3. resolvePicklistOptions(name) with no caller keeps its answer (environment item first, else the unique holder): the save door (protocol-save-door-refusals.ts line 688) and seed-record-values.ts line 129 call it caller-less and are unchanged. Right: D3's caller-less rule; the CONTROL pin shows the same list as on main.
4. findUnresolvedPicklistReferences() narrows its set: an outside-closure refusal leaves it and goes to the new findOutsideClosurePicklistReferences(); the boot throws for not-found and ambiguous, warns for outside-closure. Right by ruling N2 (6728478528) and 6729820123 ("severity follows the N2 ruling").
5. findOrphanPicklistExtensions() judges the target caller-less through R; a refusal there is only an environment-wide ambiguity, named. Right by ruling X (6728613177).
6. The post-seal install judge reaches each pending reference from its own manifest's package through a registry view that overlays the pending manifests (withPendingManifests): own list short-circuits (D3 step 1), everything else is R's answer over the pending holders plus the installed ones, the residual owner's declared dependencies handed to the walk (residualOwnerDependenciesOf, which closurePackageReader consults only for an id getPackage cannot produce — the view's getPackage answers pending ids first, so the precedence holds). It refuses loudly with R's sentence; extension targets are judged caller-less. Right: D3 at a door ("a door refuses an unresolvable reference"), and the ruled N1 shape (a same-artifact sibling needs a declared dependency). No artifact-wide "declared somewhere" pass remains.
7. describeUnresolvedPicklistReferences appends R's refusal sentence per line; headline and rule id unchanged. Right; the CLI's parity test still matches on the headline.
8. assertPicklistValuesDistinct is judged against the held extensions directly instead of through resolution (the list is not registered yet, so nothing resolves). Right: same set as before for the pre-registration case.
9. Public surface of SchemaRegistry gains picklistReferenceVerdict(name, caller?, pendingManifests?) and findOutsideClosurePicklistReferences(); resolvePicklistOptions gains an optional callerPackageId; findUnresolvedPicklistReferences/findOrphanPicklistExtensions return a supertype with an optional refusal. picklist-resolution.ts gains PicklistFieldResolver, UnresolvedPicklistReference, UnresolvedPicklistExtension; the module is not re-exported from the package entry. All additive and backwards-compatible; the only caller outside objectql (seed-record-values.ts) type-checks unchanged (Type Check legs green). Right, and the names are the seat's call (③).
10. sameHolder compares package holders by id and environment/platform by kind. Right: R2's holder union carries no id on the non-package kinds.
11. MetadataManager.listForIndex('api') keys the matcher's item list by (package, name) through the private byPackage option; the anonymous-flow-door audit reads the same list. A package-less row under a name exactly one package holds shares the holder's slot (first entry wins, registry before loaders); a package-less row under a name no package holds is the environment's slot. Right by D4's picklist/api row and its customization paragraph; the matcher still keys routes by METHOD + path and resolves a duplicate path deterministically and loudly, so nothing downstream guesses. Phase-1 answers are byte-identical. See ④ F3 for the unstated two-holder arm.
12. loaderEntries refactor: admitLoaderItems keeps first-wins-per-name; the loadMany path now leaves out an item whose name is the empty string (the keyed path always did). Accept-set change, nil effect: no consumer's schema admits an empty name. Right (④ F4, accepted).
13. Forced test edits (two fixtures gain dependencies, one load-order test registers under the list's own package, the residual fixture and the CLI parity fixture declare the sibling): each is exactly the one-line fix the changeset prescribes and the ruling names ("the residual fixture gets a forced dependencies edit"). Right; the first-party count is stated (0 shipped, 2 test fixtures).

② Semver level

Changeset .changeset/31678-picklist-by-referrer-package.md: @objectstack/objectql: patch, @objectstack/metadata: patch; Clause-②: no (narrowing) and Metadata-protocol: none on both the PR body and the changeset body; BREAKING banner present with the FROM → TO behaviour and the one-line fix; ADR-0087 marker not-required (no-migration-prescription), one marker. Check Changeset green twice, Lint · PM dispatch-gates green.

• The level matches what the diff publishes: no schema key, export removal or stored shape moves; AGENTS.md Post-Task 3 gives a non-protocol narrowing patch with its BREAKING banner and disposition. Right.
• Metadata-protocol: none matches the diff: what an author can write is unchanged (the same picklist key and value parse); what moves is which list the runtime serves and a door refusal, the same shape .changeset/31550-* on main declared as no (narrowing) + none + no-migration-prescription, and the card's own claim (6728435375) and ruling (6728476284, "本裁只定收窄范围，不改协议形状"). Right.
• @objectstack/cli is touched in a test file only: no changeset owed. Right.
• The Clause-②: line on the PR body and the changeset agree with each other and with the narrowing face this record is served on. Right.

③ Boundary flags

Every dev flag and open_questions entry from the report (6729376780) and the PR body, answered or escalated:

• N1 (sibling in the same artifact, no declared dependency): ruled 6729820123, declared dependency closure only. The head is A-shaped as the ruling requires (the residual fixture's forced edit, the install-door sibling pin, the N1 arm in the boot-warning pin). Answered.
• New names (seat's call): findOutsideClosurePicklistReferences, picklistReferenceVerdict, the private byPackage option, and the three exported types. Answered: keep (A). Each names what it answers; none is a schema key; the report's earlier spelling findEnvironmentHeldPicklistReferences was already renamed on this head to the N1-correct name.
• "Part of", not "Fixes": functions went to R2 by ruling S-a (6728478528) and R2 feat(core, metadata-core, objectql): the package-scoped resolution rule as a lean core, engine functions by package #31733 is on main; mapping and dataset have no package-referrer reader in the surface (ruled, same comment). The card stays open for its remainder. Answered; consistent with the rulings.
• The api re-key landed in metadata-manager.ts, not endpoint-matcher.ts: ruling S-b. Answered.
• Two tests held red / lean-entry-closure red on the draft: cleared by R2's landing; every check-run on this head is green, the body reports 0 red in objectql and metadata. Answered by the check-runs.
• Gates ran on 42bdbe6 before the merge: re-run on the head per the body's Verification section, and the head's own check-runs are the gate verdicts here. Answered.
• HotCRM not measured: carried to the S4 (cli: os migrate reports the ambiguous set and package references only the environment holds, with a reviewed bind command (ADR-0150 child S4) #31693) upgrade report by the ruling's "blind spot carried". Escalated as ruled; nothing for this head.
• The CLI author-time door still resolves a sibling's list without a declared dependency (packages/cli/src/utils/picklist-references.ts, module header line 42, judgePicklistReferences): after this head the runtime warns at boot and refuses the same artifact at install, so os validate no longer foretells the install door for that one case. The ruling places the ADR-0130 narrowing (a dated note in the ADR and at line 42) with child A docs/adr: ADR-0048 addendum (§3.4 and §5 lint text) and ADR-0129 cross-reference for ADR-0150 (ADR-0150 child A) #31685; the inputs name no carrier for the door's code. Escalated: a follow-up card to the lane that owns packages/cli (or child A's scope confirmed to include the door), see ④ F1. Not this head's: the ruling lands E6 with "0 extra code" and the CLI source is outside the claimed surface.

④ Design judgment

The narrowing itself, against the published spec on main. Two refusals are declared on the PR body and the changeset: (1) D3 (a), a package field whose list only an environment-authored item holds; (2) the general outside-closure case, a same-artifact sibling included. (1) is ADR-0150's own declared narrowing (TL;DR 7 and D3 (a)), carried to picklist by the E6 row of the execution plan: the spec's refusal made real, not a capability taken away. (2) is D3 step 3 as written ("else a refusal that lists the candidates"), applied over the declared closure that R implements; the sibling sub-case is where ADR-0130 (release artifact = co-ownership boundary) and ADR-0150 D3 disagreed, and the maintainer ruled it by meaning on 2026-11-09T01:07Z (6729820123): declared dependency closure only, child A records it in both ADRs. So the consumer refuses exactly what the accepted spec plus its ruling refuses, nothing more: a field whose package holds the list or depends on its holder is served as before, a caller-less reader is served as before, an extension still adds to the one list its target names. The severity ladder (boot warns naming every candidate, the read serves no options and the validator refuses the value, the post-seal install refuses loudly) is the ruled N2 shape, one answer at two severities, and ctx.logger.warn is the right level under AGENTS.md's degradation rule: the system is visibly smaller (a select with nothing to choose, a refused write), nothing claims to be persisted that is not. The boot's verdict is read at kernel:ready, after every package registered, so it is final (startup-registry-reads rule).

Attempts to break it, read in the live tree:

• A second closure walk or a first-registered fallback hidden in objectql? None: every picklist read in registry.ts routes through picklistReferenceVerdict → resolvePackageScopedName; getItem('picklist', …) has no remaining caller outside tests; package-scoped-resolver.ts and bare-name-one-holder.ts are untouched.
• The pending-manifest view misreading R's inputs? getPackage answers pending ids first (their dependencies and namespace are all the walk reads); getAllPackages drops an installed row the pending set shadows, so kernelPackages and the pair-widening see one row per id; packageScopedHoldersOf unions pending holders with installed ones (the dropped third argument only matters for bundled types, and picklist has no discriminator); getPackageScopedItem returns a stub for a pending holder, which only the verdict's status reads. The residual-owner pin (ablation 7) covers the one path that reaches a list only through a residual owner.
• Environment list and package list of one name at once? Not a reachable split: a package-less row under a name a package holds is that holder's overlay (overlaySlotBinding), so getEnvironmentScopedItem answers nothing and both the field and a caller-less extension resolve to the same holder. The D3 (a) arm needs a name no package holds, which is what the pins build.
• Stale fold after a late package record? invalidateAll runs on every picklist registration, and every production door installs the package record before its objects (engine-registration.ts line 268 before 276/289/317; the manifest service goes through the same facet). See F5 for the test-only order.

Findings (must-fix: none; should-fix: none; nits: six):

• F1 (nit on this head; follow-up card). The CLI author-time door (judgePicklistReferences) accepts a sibling's list without a declared dependency, which the install door on this head refuses. The drift is in a file this PR does not touch and the ruling assigns the ADR-0130 narrowing to child A; the door's code needs a carrier. Carrier: a packages/cli card, or child A's scope widened to the door. No effect on this PR's own contract.
• F2 (nit; note for the picklist B child). When two packaged referrers of one field both resolve but to different holders, the field is served no options and auditPicklistReferences names nothing (each referrer's own verdict is resolved). Unreachable while phase 1's one-holder refusal stands for picklist (two package holders of one name are refused at registration, and the registry adapter supplies no platform holder for picklist); becomes reachable when the trailing B child narrows that backstop. Carrier: the picklist B child, which should make the audit name a split resolution.
• F3 (nit; note for the api B child). listForPackageScopedIndex puts a package-less row whose name two packages hold into the environment slot (served as its own item). D4's customization sentence rests on one holder and the jsdoc states only the one-holder and no-holder arms. Unreachable through the registry while phase 1 stands; reachable through stored rows, where the matcher's duplicate-path rule then decides loudly. Carrier: the api B child. A jsdoc edit here would move the head, so it is not asked on this round.
• F4 (nit; accepted deviation). loaderEntries leaves out a loadMany item whose name is the empty string, which admitLoaderItems previously admitted under the empty key. No consumer's schema admits such an item.
• F5 (nit; accepted deviation). A bare registerObject(schema, pkgId) followed by a read and only then installPackage(pkgId) caches a fold whose closure predates the package record, and an enabled package's install does not drop the fold cache. No production door takes that order; the load-order test registers under the list's own package, so step 1 answers regardless.
• F6 (nit; accepted deviation). An array-spelled field with no name yields the caller-less referrer. FieldSchema requires name, so the arm is unreachable for parsed metadata.

Nits alone: the round ends on this head. F1 to F3 are follow-up carriers, F4 to F6 accepted deviations; nothing is asked of this PR's code or prose.

Red lines (card acceptance). Resolution never loosens: confirmed by reading, no fallback path remains. Ambiguity is reported, never guessed: every refusal carries R's sentence naming every candidate (boot warning, install refusal, describeUnresolvedPicklistReferences). Independently releasable: (a) the phase-1 one-holder suites and package-scoped-resolver.test.ts are untouched and the Test Core shards are green; (b) bare-name behaviour is unchanged for every one-holder name except the two declared narrowings; (c) no migration, re-runnable or otherwise, is needed and the disposition says so; (d) the Clause-②: no (narrowing) declaration and ADR-0087 marker are present on both faces. The narrowing does not exceed the declared one as ruled: the general outside-closure arm was ruled inside D3 (6728511258, 6729820123), and N1 by the maintainer.

Implemented-by: claude/project-thread-vbgxgi
Reviewed-by: session_01ADHkmQKZzp4DLtqiCkZZRM

VERDICT: PASS

[objectstack-fleet]

domain:server#2 · os-steve · session_01ADHkmQKZzp4DLtqiCkZZRM

维护者速读

• 改了什么： 对象字段引用选项列表（picklist）时，按 ADR-0150 D3 的规则从声明该字段的包去解析：先找包自己的列表，再找它声明的依赖链，最后找 sys。找不到或有歧义时，启动会告警并列出所有候选，安装会直接拒绝。按包精确匹配 api 接口也走同一套规则。
• 为什么改： 原来按"谁先注册"取列表，同名列表可能取错包的。现在解析只看声明的依赖，结果确定，有歧义就报出来，不靠猜。
• 风险与回滚： 属于收窄，有两类原来能用的写法现在会被拒：一是包内字段引用的列表只有环境里有；二是引用同一发布包里兄弟包的列表却没声明依赖。修复方法是补一行 dependencies，changeset 里写明了。随包发布的应用不受影响；需要改的只有 2 个测试夹具。回滚即还原本 PR。
• 先看： packages/objectql/src/registry.ts 的 picklistReferenceVerdict，以及 packages/metadata/src/metadata-manager.ts 的 listForIndex。
• 需要你做的： 无，由席位落地。
• 席位意见： ACCEPT。

席位核对 — ACCEPT · domain:server#2 · Head-sha bf7e3295e9ed0c6ca46217e172e25ed5f4aeaee7 · 2026-11-09T06:08Z

1. Shape: draft to main, Part of #31678 (the card stays open for its remainder, as ruled), Clause-②: no (narrowing), Metadata-protocol: none. Patch changeset for @objectstack/objectql and @objectstack/metadata, with the BREAKING banner, the one-line fix and the ADR-0087 marker not-required (no-migration-prescription). 10 files, +837/−75: registry.ts, picklist-resolution.ts, plugin.ts, metadata-manager.ts, and tests.
2. Epic: epic design(metadata): address behavioural metadata by package — key flows, actions, jobs and other non-object types by (package, name); re-open ADR-0028 (replaces #30806 phase 3 renames) #31527's final review is PASS on this head (6733282134). R2 (feat(core, metadata-core, objectql): the package-scoped resolution rule as a lean core, engine functions by package #31733) is on main and merged into this head.
3. Contract review: CONTRACT_REVIEW_TIER, narrowing face, PASS, record . It has no must-fix and no should-fix, and six nits. The seat takes them as follows:
   • F1: the CLI author-time door (judgePicklistReferences) still accepts a sibling's list without a declared dependency, which the install door now refuses. Filed as os validate: a field naming a sibling package's picklist without a declared dependency passes the author-time door, then is refused at install (ADR-0150 D3) #31832 (p3, domain:server, Blocked-by this PR).
   • F2: a split resolution between two packaged referrers is not named by the boot audit. F3: listForPackageScopedIndex does not state its two-holder arm. Both are unreachable while phase 1's one-holder refusal stands. They are carried to the picklist and api B children of design(metadata): address behavioural metadata by package — key flows, actions, jobs and other non-object types by (package, name); re-open ADR-0028 (replaces #30806 phase 3 renames) #31527 (noted on the card).
   • F4–F6: accepted deviations, each unreachable for parsed metadata or production doors.
4. N1: ruled 6729820123 (declared dependency closure only). The head is A-shaped: the residual fixture's forced dependencies edit, the install-door sibling pin, and the N1 arm in the boot-warning pin.
5. Gates:
   • Dev: 75/75 derived gates exit 0, build 120/120, dogfood 3654 pass.
   • Tests: objectql 11821 with 0 red, metadata 987, cli 48/48; typechecks exit 0.
   • Check-runs on this head: 37 success, 17 skipped, 0 failed.
6. Names (the seat's call): picklistReferenceVerdict, findOutsideClosurePicklistReferences, PicklistFieldResolver, UnresolvedPicklistReference, UnresolvedPicklistExtension and the private byPackage option are all kept.
7. Landing: pr_ready + automerge_enable. The card stays pm:dispatched for its remainder (G2 mcp: run_action and list_actions take a namespace, and skill, agent and action face names follow the ruled derivation with a duplicate refusal (ADR-0150 child G2) #31692 follows on this seat).