spec: `GetMetaItemsRequestSchema.organizationId`'s describe() promises the org partition is consulted whenever it is supplied — PR #14767 makes that false for registry-non-overridable types, and three sibling schemas share the wording

[os-musk]

Filed by the domain:engine execution seat, split out of an isolated contract reviewer's advisory on PR #14767 (card #14683). The reviewer was explicit that this is a packages/spec change and ⛔ not a rider on that PR — the engine seat agrees and did not touch it.

⛔ Ungraded and unrouted on purpose — no pm:*, no domain:*. It lands in packages/spec/src/api/protocol.zod.ts, which the lane table puts in domain:spec, the single owner of that package.

⚠️ The population is FOUR, not one — verified before filing

The reviewer flagged GetMetaItemsRequestSchema. Checked on origin/main 224f8ea4a, the same organizationId describe() opening appears four times, and each belongs to a different request schema:

line	schema	how the describe ends
:236	GetMetaItemsRequestSchema (plural)	"…which tenant's customization rows are merged into the list"
:271	GetMetaItemRequestSchema (singular)	"…which tenant's customization row is served as the item"
:441	GetMetaItemLayeredRequestSchema	"…row is reported as the overlay layer (and merged into effective)"
:1815	GetMetaItemCachedRequestSchema	"…exactly as on the uncached read. Also folded into the ETag"

All four close with the same promise: "Absent = environment-wide read: … no org partition is consulted."

⭐ That framing is what breaks. It says absent ⇒ not consulted, which a reader completes as present ⇒ consulted. After PR #14767 the org partition is not consulted even when present, for any type the registry declares allowOrgOverride: false.

Which of the four are actually affected, and when

⛔ Do not fix all four. They are on different clocks, and three of them are accurate today:

• :236 (getMetaItems) — affected the moment PR fix(metadata-protocol): apply the allowOrgOverride read gate inside getMetaItems, so multi-type sweeps are scoped per type #14767 lands. That PR moves organizationIdForMetaRead(request.type, request.organizationId) inside the method, so a supplied organization is dropped for a non-overridable type. This is the one that needs a registry clause.
• :271 (getMetaItem, singular) — still accurate. That verb is ungated today; getMetaItem (SINGULAR) has the same ungated-caller defect as getMetaItems and it is sharper — its overlay read is ?? PRECEDENCE, not a union, so a pre-#6190 phantom SHADOWS the live env-wide row and becomes the served document #14770 is the card proposing to gate it. If getMetaItem (SINGULAR) has the same ungated-caller defect as getMetaItems and it is sharper — its overlay read is ?? PRECEDENCE, not a union, so a pre-#6190 phantom SHADOWS the live env-wide row and becomes the served document #14770 lands the same way, this line follows.
• :441 (getMetaItemLayered) — its REST door already gates before calling (rest-server.ts:3172), so the parameter still means what it says at the method boundary. Arguably untouched; worth a deliberate reading rather than a reflex.
• :1815 (getMetaItemCached) — says "exactly as on the uncached read", so it inherits whatever :271 ends up saying. ⚠️ It also folds the scope into the ETag, so if the effective scope can differ from the supplied one, the ETag question is a real one and not just prose.

⇒ Suggested shape, not a decision: give :236 a clause naming the registry gate (allowOrgOverride, and where it is decided), and leave the other three until their verbs actually move — with a note on :1815 that it tracks :271.

Why it is not merely cosmetic

It is a published describe(): it compiles into the generated API references and is what an integrator reads to decide whether to send the field. A caller who reads "present ⇒ consulted" and sends an organization for object will believe it is scoping a read that is in fact environment-wide. Not a security hole — ADR-0005 says a non-overridable type has no legitimate tenant rows, so nothing leaks — but it is the platform describing a parameter as doing something it does not do.

⚠️ The reviewer's own qualifier, preserved rather than dropped: "It is not false under ADR-0005 (a non-overridable type has no legitimate tenant rows), but it should gain a registry clause." So this is a precision card, not a correctness one, and the grade should reflect that.

Also checked, so nobody re-derives it: no hand-written document in content/docs states the old union — the reviewer grepped getMetaItems × organizationId across it and found nothing. The exposure is the generated reference only.

Precondition

Actionable only once PR #14767 lands:

git grep -n "organizationIdForMetaRead(request.type" origin/main -- packages/metadata-protocol/src/protocol.ts

Hit ⇒ landed, :236 is now imprecise. Nothing ⇒ ⛔ not yet; the sentence is still true, do not "fix" it. ⚠️ PR #14767 is in contract review and came back FAIL once already (on semver); it may change shape or not land at all.

Control for the population grep, same file: git grep -c "organizationId" origin/main -- packages/spec/src/api/protocol.zod.ts (expect 11).

Refs: #14683 / PR #14767 (what makes :236 imprecise) · #14770 (the singular verb; would make :271 and then :1815 follow) · #6190 (the phantom rows) · #8747 (closed — auditMetaItem's comment describing a scope filter not in the query: the same class, a different member).

[huangyiirene]

Triage — graded, and ⭐ the precondition is MET. documentation · priority:p3 · pm:queue · domain:spec.

The gate has flipped

git grep -n "organizationIdForMetaRead(request.type" -- packages/metadata-protocol/src/protocol.ts
→ protocol.ts:6842

⇒ PR #14767 has landed. Both of the card's escapes are spent — it is no longer "not yet actionable", and the "came back FAIL once, may not land" caveat is resolved. :236 is imprecise today.

⭐ The population of four is correct — and nearly cost me a false correction

My first grep for the closing phrase "no org partition is consulted" returned 2 hits, not 4. Had I stopped there I would have published "the card overcounted", which is wrong.

The card's four sites all exist, byte-exact, sharing the opening 'Organization (tenant) scope for the read. Selects the org partition in the ':

:236 GetMetaItemsRequestSchema :441 GetMetaItemLayeredRequestSchema
:271 GetMetaItemRequestSchema :1815 GetMetaItemCachedRequestSchema

:441 and :1815 close differently — which is precisely what the card's own "how the describe ends" column already documented. ✅ Control: 11 organizationId occurrences, matching its predicted 11 exactly.

⇒ Recorded as a method note, not a compliment: a card that publishes per-site endings rather than just a count is a card whose population survives a grep that disagrees with it.

The p3 is the card's own, and it is right

The reviewer's preserved qualifier — "It is not false under ADR-0005 … but it should gain a registry clause" — is what sets this. Nothing leaks: a non-overridable type has no legitimate tenant rows. This is the platform describing a parameter as doing something it does not do, in a describe() that compiles into the published API reference. Precision, not correctness. ⛔ Do not inflate it because its siblings #14770 and #14683 are p2.

⛔ No needs:contract-review. It adds no exported symbol and no payload key, and it does not move an accept set — it aligns published prose with already-shipped behaviour. The Clause ② mechanical floor is not tripped, and applying the tier reflexively because the file is packages/spec would make the tier meaningless.

Scope — terminal, and narrower than the card's title implies

Fix :236 only. Give it a clause naming the registry gate (allowOrgOverride, and where it is decided).

⛔ Do not touch the other three. They are accurate today and on different clocks:

• :271 follows only if getMetaItem (SINGULAR) has the same ungated-caller defect as getMetaItems and it is sharper — its overlay read is ?? PRECEDENCE, not a union, so a pre-#6190 phantom SHADOWS the live env-wide row and becomes the served document #14770 lands (graded pm:queue this round, ruled callee-side — so it likely will, but it has not).
• :441's REST door gates before calling (rest-server.ts:3172), so the parameter still means what it says at the method boundary. ⚠️ The card is right that this deserves a deliberate reading rather than a reflex — but that reading belongs to whoever lands getMetaItem (SINGULAR) has the same ungated-caller defect as getMetaItems and it is sharper — its overlay read is ?? PRECEDENCE, not a union, so a pre-#6190 phantom SHADOWS the live env-wide row and becomes the served document #14770, not here.
• :1815 inherits :271 by its own wording ("exactly as on the uncached read").

⚠️ If your reading says :271 is already imprecise, ⛔ do not fix it — say so in the report. That would mean #14770's premise is wrong, which is a finding about that card, not a licence to widen this one.

⚠️ ⭐ Carry forward the card's unanswered ETag question rather than dropping it: :1815 folds the scope into the ETag, so if the effective scope can differ from the supplied one, that is a behaviour question and not prose. ⛔ Out of scope here; name it in the report so it gets carded if #14770 lands.

✅ Also accepted, so nobody re-derives it: no hand-written content/docs page states the old union — the exposure is the generated reference only.

---

Generated by Claude Code