feat(spec,metadata-protocol): publish door reports the runtime authoring gate's advisories

[os-steve]

Fixes#9176

What

Mirrors the already-ruled save-door key onto the publish door (#4463 D1/D3, #4717 precedent):

• packages/spec/src/api/protocol.zod.ts — PublishMetaItemResponseSchema gains the same optional, omitted-when-empty advisories key SaveMetaItemResponseSchema carries (RuntimeAuthoringIssueSchema elements, declared once). The save-door describe's "door asymmetry" note is updated — both doors now report.
• packages/metadata-protocol/src/protocol.ts — promoteDraftForPublish captures the gate hook's advisory return (previously discarded at the call site) and hands it out in its result; publishMetaItem attaches it to the response only when non-empty. The batch caller (publishPackageDrafts) deliberately does not read the new key — its response face is a different contract (follow-up filed as publishPackageDrafts still discards the runtime authoring gate's per-draft advisories — Studio's "publish whole app" reports none of them #9343, which remains open and is not addressed here).
• Conformance: packages/objectql/src/publish-meta-response-conformance.test.ts gains the [P2/P3] 运行时授权门的 advisory findings 要进响应并被 Studio 渲染 + docs「the gate」补第四列(#4463 收尾) #4717 directional block — the mirror of the save suite: advisory-raising publish carries the finding through the declared parse (rule id + severity + element key set asserted, not mere presence); zero advisories leaves the key ABSENT, pinned on the raw key set and JSON.stringify (never an empty array); the gating half still refuses the promotion on its envelope (code: 'INVALID_METADATA', status: 422); plus a labelled green-either-way guard.
• Spec pins: packages/spec/src/api/protocol.test.ts gains the declaration-side block (parse carries a verbatim finding; optional; no fabricated []; non-array refused; lossy element refused whole).
• Changeset: minor for @objectstack/spec + @objectstack/metadata-protocol (the save-door precedent's changeset level is not discoverable from this shallow clone; minor per the widened-face standing rule).

Generated artifacts (regenerated with the generators, never hand-edited): packages/spec/authorable-surface/api.json (one line: api/PublishMetaItemResponse:advisories) and content/docs/references/api/protocol.mdx.

Wiring note (PM assumption 1)

The hook's return is discarded one frame below the response builder: the gate call sits in promoteDraftForPublish, whose result publishMetaItem builds the response from. The wiring is still local — the helper's return grew a key; the gating half and the promotion sequence are untouched. Both callers verified: publishMetaItem reads the key, publishPackageDrafts destructures only { singularType, result } (no behaviour change there).

Verification (all at 844a8b2d9 unless noted)

• pnpm --filter @objectstack/spec test — 408 files / 10877 tests green; spec pin file re-run at 844a8b2d9: 56/56.
• pnpm --filter @objectstack/metadata-protocol test — 117 files / 1617 tests green.
• @objectstack/objectql full suite — 213 files / 3769 tests green; both conformance files re-run at 844a8b2d9: 23/23. (Package-suite runs took the tree at the prior commit 7138c1e2c; the only later change is the regenerated reference page, which is no test input.)
• Typecheck: spec green (incl. test-typecheck ledger), objectql green; metadata-protocol is a measured DEBT-ledger package (no typecheck script) — covered by its DTS build (green) and by check:type-check-debt --re-measure at 844a8b2d9: 33 entries, none above its recorded number.
• pnpm --filter @objectstack/spec check:generated at 844a8b2d9 — all 13 artifacts up to date.
• Derived gates run locally (all green): nul-bytes, merge-driver, cross-package-test-inputs, spec-parsed-alias, type-source-resolution, engine-double-contract, where-matcher, query-options-erasure, filter-alias-parity, durability-log-level, role-word, quick-reference-counts, docs-redirects, docs-audit-scope, changeset gates (adr-0087-registration / no-major / empty), objectui-changeset, empty-state, variant-docs, type-check-coverage.

Reverse verification (from the committed state)

Direction predicted before each run; two layers observed:

1. Removing the advisories declaration alone: gen:schema REFUSES the build — the authorable-surface guard reports api/PublishMetaItemResponse:advisories disappeared (the ratchet catches removal before any test can; dist stays stale, suite stays green on the old dist — which is itself the measured reason a test-only reverse verification must also ablate the shard).
2. Removing the declaration AND its shard line (mimicking a remover who regenerates): spec rebuilds, marker proven gone from dist/api/index.js, and the directional conformance case goes red exactly as predicted — strippedKeys returns ['advisories'] (1 failed / 12 passed). Restored from the committed branch, rebuilt, re-run green (13/13).

---

Generated by Claude Code

[os-steve]

CI convergence reading for the Test Core failure (@objectstack/example-showcase#test exit 1 at head 844a8b2d9) — outcome: not reproducible locally on either side, no code change pushed.

Both readings (each after a fresh pnpm --filter '@objectstack/example-showcase^...' build in its own worktree):

• Branch head 844a8b2d9: pnpm --filter @objectstack/example-showcase test → 21 files / 334 tests, all green.
• Current origin/main7337f3049: same command → 21 files / 334 tests, all green.

The log line CI showed is attributable noise, not the cause.[action crm_invoice/submit_signoff] unexpected fault (SqliteError): UNIQUE constraint failed: crm_invoice.number has exactly one source in the repo: a hand-built fixture error in packages/runtime/src/domains/actions-fault-vs-rejection.test.ts (line 168, the #3867 leak-sanitisation case — it constructs new Error('UNIQUE constraint failed: crm_invoice.number') with name = 'SqliteError' and asserts the driver dump is sanitised to a plain 500). The line is emitted by packages/runtime/src/domains/actions.ts line 487's console.error while that suite PASSES (13/13 locally). crm_invoice appears nowhere under examples/ — the showcase app has no such object — so the line in the aggregated Test Core tail is interleaved stderr from a different, passing package task, and the showcase failure's real per-test name remains truncated out of the retrievable log.

Coupling check:examples/app-showcase/ contains no reference to publishMetaItem, PublishMetaItemResponse, or advisories — no showcase fixture pins the publish response key set, so there is no consumer-fixture surface to extend for this change.

Conclusion: order/parallelism or infra flake on the CI runner (consistent with the same run's actions/github-script 429s). Re-run territory.

---

Generated by Claude Code

---

Generated by Claude Code

[os-steve]

Re-run audit (spec seat): failed jobs on runs 32039466851 (Test Core 3/3 + dependent aggregates) and 32039466888 (docs-flag job, pure setup death — actions download 429×3, no step ran) queued for re-run. Basis: the diagnosis comment above — showcase suite green on both the branch head and current main in fresh worktrees, the suspect log line attributed to a passing fixture's interleaved stderr, and the outcome-b coupling hypothesis refuted by grep. Same-run infra weather; plain re-run, nothing skipped or loosened.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/metadata-protocol, @objectstack/spec, 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/deployment/validating-metadata.mdx(via publishMetaItem (symbol))
• content/docs/kernel/contracts/metadata-service.mdx(via /:type/:name/publish (route), /meta/:type/:name/publish (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), publishMetaItem (symbol), /: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

• 1 changed file(s) yielded no anchor (packages/spec/authorable-surface/api.json) — pages documenting those are invisible to this run

Coarse fallback — 113 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.