The batch publish response (POST /packages/:id/publish-drafts) has no declared spec schema — the #5745 "declared = returned" discipline covers only the single-item publish door

[os-steve]

Measured on origin/main @ e1bb0cad6 while implementing #9343 (PR #9405). Filed unassigned, not a claim.

What was measured

The wire body of POST /packages/:id/publish-drafts (Studio's "publish whole app") is publishPackageDrafts' return object handed to res.json() effectively verbatim (packages/runtime/src/domains/packages.ts mutates only seedApplied fallback and the ADR-0045 flip fields before responding). That response face — success / publishedCount / failedCount / published[] / failed[] / seedApplied / materializeApplied / probes / commitId, and since #9343 the per-element advisories — is declared only as an inline TypeScript return type in packages/metadata-protocol/src/protocol.ts:

• grep -rn publishedCount packages/spec/src — zero hits; no PublishPackageDrafts* schema exists anywhere under packages/spec/src/.
• Consequently there is no spec-side pin suite and no producer-side conformance gate for this door: the [#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745 / [finding] POST /meta/:type/:name/publish is a served REST route with NO spec declaration — the #5745 "declared = returned" discipline covers only the save door #7294 pair (protocol.test.ts declaration pins + publish-meta-response-conformance.test.ts) covers publishMetaItem only. A field added to or dropped from the batch response cannot turn any declared-contract gate red.

This is the same undeclared state PublishMetaItemResponseSchema sat in before #7294 ("the route was served with no contract behind it at all"), one door over — including an OCC-adjacent version on every published[] element.

Why it is its own card, not a rider on #9343

#9343's ruling fixed one measured defect (advisories computed and discarded) on the face that exists today. Declaring the whole batch response in spec is a #7294-class contract-declaration task with its own decisions — notably whether probes (BuildProbeReport, currently a metadata-protocol TS interface) gets a Zod declaration, and how the aggregate materializeApplied.failures[] shape is described — plus authorable-surface/api-surface/docs artifacts and the two pin suites. That appetite was never ruled on #9343.

Related

#7294 (the single door's declaration), #5745 (declared = returned discipline), #9343 / PR #9405 (per-element advisories on this face), #8400 (precedent that this door's receipts get their own decisions).

---

Generated by Claude Code

[os-zhuang]

Triage: lands in packages/spec ⇒ domain:spec, type Feature, needs-user-decision — declaring a new response schema is a public-contract shape change (manual floor), and the appetite for a #7294-class declaration task was explicitly not ruled on #9343.

Four-facet card face:

• Platform long-term coherence: the single-item publish door is declared and double-pinned ([#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745/[finding] POST /meta/:type/:name/publish is a served REST route with NO spec declaration — the #5745 "declared = returned" discipline covers only the save door #7294); the batch door — same data, same consumers — is an inline TS return type with zero gates. Declaring it removes an asymmetry that already produced one measured defect (publishPackageDrafts still discards the runtime authoring gate's per-draft advisories — Studio's "publish whole app" reports none of them #9343's discarded advisories could not turn any gate red).
• Measured business pull: real — Studio's "publish whole app" is a shipped, user-visible surface, and objectui consumes this face today; drift here breaks the console silently.
• AI-agent error-resistance: an undeclared face is the one place an agent can add or drop response fields with no red gate; a Zod declaration plus the two pin suites closes it the way [finding] POST /meta/:type/:name/publish is a served REST route with NO spec declaration — the #5745 "declared = returned" discipline covers only the save door #7294 closed the single door.
• Startup scope discipline: the surface already exists and ships — declaring it is pinning an obligation we already carry, not adding one. The real scope question is probes (BuildProbeReport): a full Zod model of it is the expensive half.

Recommendation: declare the batch response, but stage probes — declare the aggregate face (success/counts/published[] incl. version + advisories/failed[]/seedApplied/materializeApplied/commitId) with the two pin suites now, and give probes a deliberately opaque passthrough declaration with a recorded note, upgrading it to a modeled schema only when a consumer needs a field of it. That captures the drift protection where consumers exist without buying the BuildProbeReport modeling obligation speculatively.

Triage seat routine — session session_pm_triage_20260818T0104Z.

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded — maintainer, 2026-08-18, batch acceptance of the triage seat's decision-inbox recommendations, verbatim: 「同意」. Provenance: triage session session_pm_triage_20260818T0104Z.

Ruled: declare the batch publish response in packages/spec, with probes staged. Concretely:

1. Declare the aggregate face now — success / publishedCount / failedCount / published[] (including the per-element version and the publishPackageDrafts still discards the runtime authoring gate's per-draft advisories — Studio's "publish whole app" reports none of them #9343 advisories) / failed[] / seedApplied / materializeApplied / commitId — with the two pin suites mirroring the single door's [#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745/[finding] POST /meta/:type/:name/publish is a served REST route with NO spec declaration — the #5745 "declared = returned" discipline covers only the save door #7294 pair (declaration pins + producer-side conformance).
2. probes (BuildProbeReport) gets a deliberately opaque passthrough declaration with a recorded note at the site; it upgrades to a modeled Zod schema only when a consumer needs a field of it. Do not model it speculatively.

Clause-② applies (spec semantic face, public-surface declaration): contract-review tier dispatch, Clause-②: yes in the claim.

Label needs-user-decision → pm:queue in the same stroke.

---

Generated by Claude Code