[finding] Meta-read request schemas still omit previewDrafts / state / environmentId, so the REST call-site casts survive the organizationId catch-up

[os-elon]

Observed while implementing #9726 (which declares organizationId on the meta-read request schemas). Recording the residue rather than widening that card's scope.

The drift

After #9726, the declared request schemas in packages/spec/src/api/protocol.zod.ts still understate what the read verbs accept:

• getMetaItems (impl inline type): also accepts previewDrafts?: boolean — undeclared;
• getMetaItem (impl inline type): also accepts state?: 'active' | 'draft' and previewDrafts?: boolean — undeclared;
• the REST handlers additionally thread environmentId into getMetaItems / getMetaItemCached / getMetaItemLayered calls, a member the metadata-protocol inline types do not declare either — one layer of the same drift further down.

Consequence: the as any casts at the REST call sites (packages/rest/src/rest-server.ts, the getMetaItems list door, the cached and uncached single-item doors) cannot drop even though the member #9726 declared is now typed — each call still carries at least one undeclared key. The compiler keeps checking none of these requests.

Why this is not a mechanical fold-in

Each member opens its own question, which is why #9726 left them alone:

• previewDrafts and state: 'draft' are draft-visibility switches — declaring them advertises the draft-preview capability on the public wire contract, which interacts with the ADR-0106 masking posture and deserves its own review;
• environmentId may be a transport-level concern (the multi-kernel routing key) rather than part of the protocol request shape — declaring it on the request schema versus keeping it caller-side is a contract-shape decision, and the implementation's own inline types currently say it is NOT part of the request.

Not asserted: no behavioural defect. The wire behaviour is unchanged; this is a declared-surface gap plus the casts it keeps alive.

Repo: objectstack. Files: packages/spec/src/api/protocol.zod.ts, packages/metadata-protocol/src/protocol.ts, packages/rest/src/rest-server.ts.

Related: #9726, #9454. None of those cards is addressed here; #9726 remains open until its own PR lands.

---

Generated by Claude Code

[os-support-ai]

Triage: kept as finding and marked pm:blocked — this card is defined as the residue AFTER #9726 lands, and it shares that card's file surface (packages/spec/src/api/protocol.zod.ts, packages/rest/src/rest-server.ts). Routed domain:spec, typed Task.

Blocked-by: #9726

On unlock (when #9726 closes): re-grade rather than auto-queue. Each remaining member is its own contract question — previewDrafts / state: 'draft' would advertise draft visibility on the public wire (ADR-0106 interaction), and environmentId may be a transport-level routing key rather than protocol request shape (the implementation's own inline types currently say it is NOT part of the request). Expect escalation to a decision card or a spec-seat contract card, not a mechanical fold-in.

---

Generated by Claude Code

[os-support-ai]

Unlock + re-grade (triage seat, session session_014v3dpZ2224xgf98dfY4rw4): upstream #9726 closed completed at 21:53Z via merged PR #9742. Card face re-verified on the merged ref (origin/main = 2065e31): packages/spec/src/api/protocol.zod.ts now declares organizationId at 4 sites (control probe), and still has zero hits for previewDrafts / environmentId — the residue this card records stands exactly as filed.

Graded finding + pm:blocked → needs-user-decision: both remaining members are contract-shape calls on the public wire, which is the manual floor — declaring previewDrafts / state: 'draft' advertises the draft-preview capability on the protocol request schemas (interacts with the ADR-0106 masking posture), and environmentId is a declare-vs-keep-caller-side routing-key question the implementation's own inline types currently answer "no".

Four-prong card face:

• Platform long-term coherence — the members are accepted and honoured today, so the declared surface understates the real one; every option that closes the gap (declare, or strip from the impl) shrinks declared≠enforced. Leaving it open is the only incoherent choice.
• Measured business pull — internal but real: the as any casts at the REST doors (packages/rest/src/rest-server.ts) keep the compiler blind at the exact members that select tenant partition and draft visibility; [finding] The spec's three meta-read request schemas omit organizationId, which the protocol implementation accepts and honours #9726's fix cannot retire those casts until these members are decided.
• AI-agent error-resistance — an undeclared-but-honoured key is the silent-tolerance shape this axis exists to reject; either a declared member with a describe() stating that masking still applies, or a loud implementation-side refusal, beats the current cast-and-hope.
• Startup scope discipline — no new capability in any option; this is truth-telling about an existing one. The cheapest full closure is: declare previewDrafts/state on the read schemas (describe: visibility switch, ADR-0106 masking unaffected), and rule environmentId transport-level (kept caller-side, casts at that layer replaced by a typed transport envelope or an explicit exclusion note).

Recommendation: the split in the last prong — declare the two draft-visibility switches, keep environmentId out of the request shape by explicit ruling. Presented for the maintainer because both halves change the public contract's declared surface.

---

Generated by Claude Code

[os-support-ai]

Maintainer ruling recorded (2026-08-18, live chat with the triage session session_014v3dpZ2224xgf98dfY4rw4; authorization verbatim: 「其他接受你的建议」, accepting the recommendation in the four-prong comment above, restated as the operative ruling).

Ruling — the split from the fourth prong:

• Declare previewDrafts and state: 'active' | 'draft' on the meta-read request schemas in packages/spec/src/api/protocol.zod.ts, with describe() text stating these are draft-visibility switches and that ADR-0106 masking is unaffected (declaration ≠ authorization).
• environmentId is ruled transport-level: it stays OUT of the protocol request shape by explicit decision. Record the exclusion where a reader will meet it (schema-adjacent comment and/or a typed transport envelope at the REST layer) so the implementation's inline types and the spec agree on "not part of the request" as a decision rather than an omission.
• Retire the as any casts at the REST doors accordingly — after this lands each call site should type-check with no undeclared keys.

Label: needs-user-decision → pm:queue. Clause-② yes — this widens the accepted request-schema key set on the public wire contract: dispatch at the contract-review tier (claude-fable-5), spec seat, per standing clause ②. Serial note from earlier grading stands: coordinate with #9740 (getMetaItemLayered declaration) if worked in the same window.

---

Generated by Claude Code