feat(metadata-protocol): batch publish door returns per-draft advisories on each published[] element

[os-steve]

Fixes#9343

Ruling (recorded on the card 2026-08-17 22:35Z, batch acceptance 「同意」)

Ruled: advisories ride each published[] element of the batch response — same optional, omitted-when-empty shape as PublishMetaItemResponseSchema.advisories on the single-item door (#9176). No parallel top-level map: one concept, both doors consistent. failed[] elements are unaffected (an error finding already aborts per the gating half).

What landed

• packages/metadata-protocol/src/protocol.ts — publishPackageDrafts now destructures the advisories the Phase-1 seam (promoteDraftForPublish) has returned since The publish door discards the runtime authoring gate's advisory findings — and Studio's designer only ever uses that door #9176, captures them per draft on PromotedDraft, and attaches them to the matching published[] element in Phase 2, omitted-when-empty (never advisories: []). The declared return type's published[] element gains the optional advisories key (RuntimeAuthoringIssue[], the The publish door discards the runtime authoring gate's advisory findings — and Studio's designer only ever uses that door #9176 element shape). failed[] untouched. The two stale "the batch caller deliberately does not read it" notes are updated.
• packages/metadata-protocol/src/protocol-publish-drafts-advisories.test.ts — four cases through the REAL publishPackageDrafts (nothing on the gate path stubbed; the [P2/P3] 运行时授权门的 advisory findings 要进响应并被 Studio 渲染 + docs「the gate」补第四列(#4463 收尾) #4717/The publish door discards the runtime authoring gate's advisory findings — and Studio's designer only ever uses that door #9176flow-multi-write-unfiltered warning fixture): (1) a one-draft batch reports the finding on its element with rule id, severity and the full element key set; (2) a mixed batch attaches the key to exactly the raising element — the clean sibling's raw key set is pinned as [name, type, version]; (3) an advisory-free batch is byte-identical (JSON.stringify carries no trace of the key); (4) the gating half is unchanged — an error finding aborts the batch (INVALID_METADATA causal + BATCH_ABORTED siblings) and no advisories key appears anywhere on failed[].
• packages/objectql/src/{protocol-publish-package-drafts,build-probes,protocol-commit-history}.test.ts — the four doubles of the promoteDraftForPublish seam gain advisories: [], the key the real helper has returned since The publish door discards the runtime authoring gate's advisory findings — and Studio's designer only ever uses that door #9176 (drifted seam doubles, surfaced by the new read).
• Changeset: @objectstack/metadata-protocol minor (additive optional key).

Deviations from the dispatch card (measured, not chosen)

• No packages/spec change. The card named protocol.zod.ts as gaining the key, but measured against origin/main the batch publish response has no declared Zod schema anywhere in spec — the batch response face lives solely as publishPackageDrafts' TS return type (grep publishedCount packages/spec/src = zero hits). The ruled shape is fully implementable on that face, so it landed there; declaring the whole batch response schema in spec is a separate [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-class card, filed as follow-up finding 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 #9406. Consequently no generated spec artifacts move (check:generated: all 13 up to date at 292239ca6), no reference docs exist for this response to sync, and the [#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745 "declared = returned" conformance gate cannot cover this door until that declaration exists.
• PR title says feat(metadata-protocol), not the card's feat(spec), for the same reason.
• pnpm --filter @objectstack/spec test was not run: spec is byte-identical to origin/main in this branch, so the run would measure main, not this change.

Verification (all at 292239ca6)

• @objectstack/metadata-protocol full suite: 121 files / 1655 tests green (new file 4/4). DTS build green (measured DEBT-ledger package, no typecheck script); check:type-check-debt --re-measure: 33 entries re-measured, none above recorded (surplus: none).
• @objectstack/objectql (downstream consumer of @objectstack/metadata-protocol) full suite: 215 files / 3811 tests green; tsc --noEmit green.
• Derived gates (node scripts/pm/dispatch-gates.mjs over the changed paths), all green locally: cross-package-test-inputs, durability-log-level, filter-alias-parity, changeset-gate-self-tests, objectui-changeset, query-options-erasure, engine-double-contract, where-matcher, nul-bytes, type-check-coverage, type-check-debt (re-measure), adr-0087-registration, changeset-no-major, empty-changeset, docs-audit affected-docs, spec check:generated.

Reverse verification (from the committed state)

Predicted before the run: the two directional cases go red, the byte-stability and gating-half pins stay green (green-either-way by design). Restored origin/main's protocol.ts into the tree (git restore --source=origin/main), re-ran the new file: 2 failed / 2 passed — exactly the predicted split (both reds are the element-level advisories read returning undefined, i.e. the discard this card is about). Restored from HEAD, re-ran: 4/4 green.

Conditional-field byte-stability proof

Case (3) pins the raw element key set (Object.keys(el).sort() = ['name','type','version']) and asserts JSON.stringify(res) contains no advisories substring — the route hands this object to res.json() verbatim, so this is the wire. An advisory-free batch's response bytes are unchanged.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol, touching 9 documentable anchor(s).

4 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/client-sdk.mdx(via meta.publishItem (sdk), publishItem (sdk))
• content/docs/concepts/metadata-lifecycle.mdx(via ObjectStackProtocolImplementation (symbol))
• content/docs/kernel/contracts/metadata-service.mdx(via /:type/:name/publish (route))
• content/docs/protocol/objectql/state-machine.mdx(via /:name/state/:field (route))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via ObjectStackProtocolImplementation (symbol))
• content/docs/releases/v17.mdx(via ObjectStackProtocolImplementation (symbol), publishPackageDrafts (symbol), getLegalNextStates (sdk), meta.getLegalNextStates (sdk), /:type/:name/publish (route))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

Coarse fallback — 5 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 origin/main → packageMentionDocs.

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 origin/main → pass the list as args.docs.