fix(rest)!: GET /meta/_drafts refuses an unknown type or package filter instead of answering an empty list (#29180) - #29295

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/metadata-protocol, @objectstack/rest, @objectstack/runtime, touching 19 documentable anchor(s).

27 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 39951d2a26590ff93226d3c0cf4ecfdc4136031e.

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

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin f7371cd62cf4fcba6769fea8dd05d108d701faa8 && git checkout f7371cd62cf4fcba6769fea8dd05d108d701faa8
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 39951d2a26590ff93226d3c0cf4ecfdc4136031e 5ac557e5ee88b430a8f9cbb3e47d24427c65ab77 && git checkout -B drift-repro 39951d2a26590ff93226d3c0cf4ecfdc4136031e && git merge --no-ff 5ac557e5ee88b430a8f9cbb3e47d24427c65ab77

node scripts/docs-audit/affected-docs.mjs --json 39951d2a26590ff93226d3c0cf4ecfdc4136031e

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

domain:server#1 · os-steve · session_01ADHkmQjPiXgNoSaEpqeGvY

Contract-review-claim: session_01ADHkmQjPiXgNoSaEpqeGvY · head 5ac557e5ee88b430a8f9cbb3e47d24427c65ab77 · 2026-11-02T11:12Z

The lane seat runs this PR's review at CONTRACT_REVIEW_TIER (declared Clause-②: no (narrowing)), in an isolated reviewer.

domain:server#1 · os-steve · session_01ADHkmQjPiXgNoSaEpqeGvY

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 5ac557e5ee88b430a8f9cbb3e47d24427c65ab77
Local-runs: none
Scope: packages/metadata-protocol/src/protocol-drafts.ts, packages/metadata-protocol/src/protocol-meta-diagnostics.ts, packages/metadata-protocol/src/protocol.ts, packages/rest/src/meta-collection-routes.ts, packages/runtime/src/domains/meta.ts, packages/metadata-protocol/src/protocol-drafts-unknown-package.test.ts, packages/rest/src/meta-drafts-unknown-filter.test.ts, packages/runtime/src/domains/meta-drafts-unknown-type.test.ts + packages/rest/src/meta-item-read-gate.ts (refuseUnknownMetaListType, metaTypeIsLive), packages/metadata-protocol/src/protocol.ts getMetaItems package branch (L10801) and its disabled-package filter (L10720-10750), packages/metadata-protocol/src/index.ts, packages/metadata-protocol/src/protocol-save-door-refusals.ts (L505, L724), packages/client/src/index.ts (listDrafts, L2199), ui/packages/app-shell/src/views/studio-design/packageSurfaces.ts and StudioDesignSurface.tsx (the 24 listDrafts call sites), packages/spec/src/api/protocol.zod.ts (ListDraftsResponseSchema docblock), scripts/check-adr-0087-registration.mjs (CATEGORIES)

Read on the head tree via git show 5ac557e5:PATH and git diff origin/main...5ac557e5; nothing checked out. Inputs: card #29180 body and its three comments (triage, claim, dev report), PR #29295 body, file list, comments (docs-drift, review claim), and the head's check-runs. The PR body's account was not the evidence; the tree was.

Merge state. git merge-tree --write-tree origin/main 5ac557e5 on today's origin/main (39951d2a, 44 commits past the base 104cd1a5) returns a tree with no conflict, so the dev's "protocol.ts changed elsewhere" note is a clean three-way merge; the net diff against origin/main is the nine files above (+325/-4).

Check-runs on the head. 48 check-runs, all completed: 35 success, 13 skipped, 0 failure, 0 cancelled (final tally read after the eight Test Core shards, Build Core, the Type Check and Lint families finished). Green among them: Check Changeset (carries the ADR-0087 disposition gate), Governed Surface Queue Guard, PR-body guards, Check PR Size, Lint · ESLint, Lint · repo & tooling gates, Type Check · workspace, Type Check · consumer gates, Type Check · source gates, Type Check · debt ledger, Test Core 1-8, Dogfood Regression Gate, Live E2E UI. The skipped runs are the UI build/test family and opt-in harnesses whose path filters this diff does not reach. These conclusions are the derived-gate verdicts; nothing was run locally.

① Derived judgments

1. Accept set — GET /meta/_drafts?type=X (both transports). Before: any type string narrowed the repo query and answered 200 {"drafts":[]} when nothing matched. Now: refuseUnknownMetaListType(p, type) runs before listDrafts — static spelling contract (unrecognisedMetaTypeRefusal), then the live getMetaTypes set folded through canonicalMetaUrlType, fail-open when the listing is unreadable or the protocol lacks getMetaTypes. A name the list door refuses is refused here with the identical thrown error, shaped by each transport's own catch (handleRouteError / errorFromThrown). Read in meta-item-read-gate.ts L2676-2690 and L2706-2726. Narrowing; right — it is the card's acceptance ("as GET /meta/dashbord does") and no second copy of the vocabulary exists: the same function GET /meta/:type (rest L664, runtime L2221) and GET /meta/diagnostics?type= (rest L375) call. Plural spellings pass (dashboards → canonicalMetaUrlType fold), pinned by both transport tests.
2. Accept set — listDrafts({ packageId }) in @objectstack/metadata-protocol. Before: an unmatched packageId answered empty. Now: when the filtered result is empty, packageIsInstalled(this, packageId) is asked — the identical rule the diagnostics sweep applies to its package= filter (protocol-meta-diagnostics.ts L261-272), with a draft bound to the package (any type) as proof enough, read BEFORE the disabled-package filter so an uninstalled or disabled package with real draft rows is served, and fail-open on an unreadable or shapeless listing. Narrowing; right. Two break attempts failed: (a) a disabled package with nothing pending — getMetaItems deliberately never filters package records ("the Packages page must list disabled packages", protocol.ts L10726), so it is listed and keeps its 200 {"drafts":[]}; (b) a Studio-created scope-less base — registered through POST /api/v1/packages, so it is among the type: 'package' records the listing returns. The type-filtered empty path costs one extra type-less repo.listDrafts({ packageId }) read, only on the empty answer; acceptable.
3. Public surface — @objectstack/metadata-protocol. packageIsInstalled gains export, and DraftsHost gains getMetaItems; index.ts re-exports neither protocol-meta-diagnostics.ts nor protocol-drafts.ts (verified: no export * and no named export from either), so the published surface does not move. ObjectStackProtocolImplementation.listDrafts's declared signature is unchanged; only its docblock grows. Right; Metadata-protocol: none holds — packages/spec is untouched and no authorable key, value or type moves.
4. Protocol-internal callers. protocol-save-door-refusals.ts L505 and L724 call this.listDrafts({ type: 'datasource' | 'object' }) with no packageId, so the package rule never reaches them; the type rule lives in the transports and they bypass it with known types. Unaffected; right.
5. Consumers. packages/client listDrafts forwards packageId/type and unwraps the envelope — a 400 now rejects where it resolved []. In ui/, 24 call sites: every one pairs packageId from the Studio package switcher (installed packages) with a type in {view,hook,object,app,permission,metaType} and, except StudioDesignSurface.tsx L4855 (inside a try), carries .catch(() => []); each paired client.list(type, { packageId }) already refuses the same type names. No consumer refusal the paired read did not already make; the dev's reading holds.
6. Not changed. Unknown query-parameter NAMES on _drafts (e.g. ?package=) stay ignored — the dev names it out of scope and the card's own ?package= wording is a slip (the route reads packageId). Correct scoping.

② Semver level

.changeset/29180-drafts-unknown-filter.md: patch on @objectstack/metadata-protocol, @objectstack/rest, @objectstack/runtime — the three packages whose behaviour the diff moves, and no others. Line-initial Clause-②: no (narrowing) and Metadata-protocol: none in both the changeset and the PR body. Per the Post-Task Checklist level rule a none kind takes patch, and a non-protocol breaking change ships patch with its BREAKING banner and ADR-0087 disposition — present: the BREAKING banner, adr-0087: not-required (no-migration-prescription) (a CATEGORIES member, L147 of the gate), and the migration ("The remedy": fix the misspelled value; GET /api/v1/meta/types, GET /api/v1/packages). Check Changeset (which runs check-adr-0087-registration.mjs --base) is green on the head. Level and declarations match what the diff publishes. Clause-②: no (narrowing) — confirmed by reading: nothing widens; two previously-200 request shapes become 400 on both transports.

③ Boundary flags

• Dev open_questions[0] — runtime dispatcher twin edited beyond the claim's file-surface wording. Answered: A, keep — right. The rest route's own [#23214] comment at meta-collection-routes.ts L465-466 ("the runtime dispatcher's twin refuses the same names") and the gate's "Both transports" docblock (meta-item-read-gate.ts L2661-2667) bind the _drafts pair; the type verdict lives in @objectstack/rest, so it cannot be placed in listDrafts without a second copy, which the claim forbids. Dropping the hunk would leave a dispatcher-only host at 200 {"drafts":[]} for the typo — the defect, half-fixed. The claim's "and/or the _drafts route in packages/rest" named the door; the twin IS that door on the other transport. Deviation accepted.
• Dev open_questions[1] — PR assignee/reviewer not set (order forbids MCP writes). Outside the contract; no bearing on the verdict. Escalated to the seat: set via relay if wanted, otherwise leave unset.
• Dev deviation — ui consumer tests run as a 4-file subset. Accepted: those tests mock the client, so the server change cannot reach them; the consumer reading in ①.5 is the evidence that matters.
• Skills-docs: none. Verified: git grep _drafts over content/docs/**, skills/**, .claude/skills/** finds only the maintenance-mount row (references/api/rest-server.mdx L228) and the 403 capability citation (ui/apps.mdx L455, L461); no page documents the type/packageId filters. The docs-drift comment is advisory and lists pages by package mention. Holds.
• Card premise. Holds against the base tree: meta-collection-routes.ts passed req.query.type/packageId straight into listDrafts after the arity check alone; the dev's base-tree ablation (refusal pins red, controls green) is consistent with that reading.
• No packages/spec edit, no new error code, no new gate — the claim's three stops are honoured.

④ Design judgment

• packages/metadata-protocol/src/protocol-drafts.ts — holds. Order of operations is right: the repo read, then the package verdict on the UNFILTERED rows (so a disabled package's drafts count as bound, matching the docblock "a disabled package's drafts still publish and discard"), then the disabled-package projection. The bound re-read is only taken when a type narrowed the first read, and skipped when it could not change the answer. The refusal reuses the sweep's status, code and sentence family. Should-fix (doc): the module header still says "A MOVE, not a redesign. Each function below is the body ... as it stood, re-indented one level and otherwise unedited" and accounts for exactly two imports from protocol.ts; listDrafts now carries a [#29180] hunk and a third import from protocol-meta-diagnostics.ts. One sentence noting the metadata: GET /api/v1/meta/_drafts answers 200 {"drafts":[]} for a misspelled type or an unknown package, where the list and diagnostics doors refuse the same mistake 400 #29180 edit keeps the header true for the next reader. Not blocking.
• packages/metadata-protocol/src/protocol-meta-diagnostics.ts — holds. export only; the body is unchanged, the host Pick (getMetaItems) is the one member DraftsHost adds, typed as the same indexed access on the class, so the call type-checks without a cast.
• packages/metadata-protocol/src/protocol.ts — holds. The host literal adds getMetaItems: (...a) => this.getMetaItems(...a) in the closure shape the module header prescribes (a spy set on the instance is still reached); the docblock names the refusal and says the type half is the transports', which is true.
• packages/rest/src/meta-collection-routes.ts — holds. The call sits after the authoring gate, the 501 probe and the arity refusal, inside the try, exactly where the diagnostics door (L375) asks the same question; || undefined keeps type= (empty) as "no filter" as before; draftsType is the one value both the verdict and listDrafts see.
• packages/runtime/src/domains/meta.ts — holds; the twin mirrors the rest placement (after capability gate, protocol probe, arity), inside the try that errorFromThrown shapes, and the test pins the drafts body equal to the list branch's.
• Tests — protocol-drafts-unknown-package.test.ts pins both halves of the rule including the fail-open shapes and the "listing never asked" controls; the two transport tests pin equality with the sibling list door's body for four misspellings, listDrafts never called, and the controls in both spellings. meta-drafts-unknown-filter.test.ts also pins that a thrown package refusal leaves the rest route at 400. Each is a new file; no existing pin was edited.
• Scenario the card accepts against — a typo'd type or packageId on _drafts is refused 400 with the sibling doors' sentence; a known type in either spelling and an installed package with nothing pending keep 200 {"drafts":[]}. Met on both transports.

Must-fix: none. Should-fix: one (stale module header in protocol-drafts.ts).

Implemented-by: claude/project-thread-igicmx
Reviewed-by: session_01ADHkmQjPiXgNoSaEpqeGvY

VERDICT: PASS

Stamped 2026-11-02T11:33Z.

domain:server#1 · os-steve · session_01ADHkmQjPiXgNoSaEpqeGvY

席位核对 · ACCEPT · domain:server seat 1 · os-steve · session_01ADHkmQjPiXgNoSaEpqeGvY · 2026-11-02T11:35Z

Head 5ac557e5ee, report 6575684316 (on #29180), claim 6573676255. Clause-②: no (narrowing) → contract review owed at CONTRACT_REVIEW_TIER: record 6576111072 on this head, PASS, no must-fix.