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

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

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fs18A2DdXLVN2h8PaaFBcP

* chore(spec): regenerate reference docs for the publish-door advisories describe (#9176)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fs18A2DdXLVN2h8PaaFBcP

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-steve

.changeset/publish-door-advisories.md

@@ -0,0 +1,6 @@
+---
+"@objectstack/spec": minor
+"@objectstack/metadata-protocol": minor
+---
+
+The publish door now reports the runtime authoring gate's advisory findings (#9176). `POST /api/v1/meta/:type/:name/publish` carries the same optional, omitted-when-empty `advisories` key the save door already carries (#4463 D1/D3, #4717): `PublishMetaItemResponseSchema` declares it (`RuntimeAuthoringIssueSchema` elements, declared once in `@objectstack/spec`), and `publishMetaItem` attaches the findings the promotion-time gate run returns instead of discarding them. A clean publish's response bytes are unchanged — the key is present only when at least one `warning`/`info` finding was raised; `error` findings still refuse the promotion as the 422 envelope. This matters most for Studio / MCP / AI authors, whose designer takes draft-then-publish on every edit and has no CLI to surface the same findings.

content/docs/references/api/protocol.mdx

@@ -1211,6 +1211,7 @@ List packages response
 | **seedApplied** | `{ success: boolean; inserted: integer; updated: integer; error?: string; … }` | optional | Outcome of materializing a published `seed` body into data rows. Present ONLY when the published type is `seed` — publishing a seed is what makes its rows live, so the load rides along with the metadata promotion. Best-effort: a seed-load problem is surfaced here, never thrown, so a caller must check `seedApplied.success` instead of assuming the 200 covered the data. Absent on the batch path, which suppresses the per-item apply and loads every seed body in one later pass. |
 | **materializeApplied** | `{ success: boolean; inserted: integer; updated: integer; error?: string }` | optional | Outcome of the ADR-0086 P2 publish-time materializer — the step that projects the published body into its data-plane row (e.g. `permission` → `sys_permission_set`, under the owning package). Present ONLY when a materializer is registered for this metadata type, which is why it is optional: its absence means "no materializer ran", never "it failed". Best-effort, same contract as `seedApplied`. |
 | **projectionApplied** | `{ success: boolean; error?: string }` | optional | Outcome of the awaited ADR-0094 mutation projector — the post-persist step that materializes this metadata into its derived data-plane read model. The same receipt `{@link SaveMetaItemResponseSchema}` carries, because the projector runs on BOTH write doors: a direct active save and this draft→active promotion. Present ONLY when a projector is registered for this metadata type. Best-effort — a projector failure is reported here and logged, never thrown. |
+| **advisories** | `{ rule: string; path: string; where: string; message: string; … }[]` | optional | Non-gating findings from the #4463 runtime authoring gate — the same shared author-time rules `os validate` / `os build` / `os lint` run, applied to the DRAFT body this promotion carried to `active` (#9176, the same key `SaveMetaItemResponseSchema` carries, because the gate runs on both write doors by #4463 D1). The promotion SUCCEEDED; these are what the gate has to say about it anyway. Present ONLY when at least one advisory was raised — an empty array is never emitted, so a clean publish's response bytes are unchanged and absence means "nothing to report", never "the gate did not run". Advisory by construction: every entry has `severity` `warning` or `info`, because an `error` finding refuses the promotion and arrives as the 422 `invalid_metadata` envelope instead of here. A caller that ignores this key behaves exactly as before. This door is the one Studio's designer takes on every edit (draft save, then publish), and a Studio / MCP / AI author has no CLI at all — which is the gap #4463 exists to close. |
 | **message** | `string` | optional | Human-readable receipt, e.g. `Published draft — type=view, name=cases [seq=3]`. The producer sets it on every publish today; it stays optional to match the producer's own signature and its `SaveMetaItemResponse` twin, and because an absent human-readable string strips no data — the failure mode #5745 exists to prevent. |
 
 
@@ -1389,7 +1390,7 @@ List packages response
 | **seq** | `integer` | ✅ | Monotonic sequence number of the metadata event this write appended to the item history (sys_metadata_history.event_seq). Orders writes; unlike `version` it is not an OCC token. |
 | **state** | `Enum<'draft' \| 'active'>` | ✅ | Lifecycle the body was written into: "draft" when the request asked for draft mode (`?mode=draft`), otherwise "active" (published and live). A draft is staged only — it is not served to the runtime until published. |
 | **projectionApplied** | `{ success: boolean; error?: string }` | optional | Outcome of the awaited ADR-0094 mutation projector — the post-persist step that materializes this metadata into its derived data-plane read model (e.g. `permission` → `sys_permission_set`). Present ONLY when a projector is registered for this metadata type, which is why it is optional: its absence means "no projector ran", never "the projection failed". Best-effort by design — a projector failure is reported here and logged, never thrown, so a caller that needs the read model to be live must check `projectionApplied.success` rather than rely on the 200. |
-| **advisories** | `{ rule: string; path: string; where: string; message: string; … }[]` | optional | Non-gating findings from the #4463 runtime authoring gate — the same shared author-time rules `os validate` / `os build` / `os lint` run, applied to this body on its way to `active`. The write SUCCEEDED; these are what the gate has to say about it anyway (#4717, closing #4463 D3). Present ONLY when at least one advisory was raised — an empty array is never emitted, so a clean save's response bytes are unchanged and absence means "nothing to report", never "the gate did not run". Advisory by construction: every entry has `severity` `warning` or `info`, because an `error` finding refuses the write and arrives as the 422 `invalid_metadata` envelope instead of here. A caller that ignores this key behaves exactly as before. Runtime-only: the CLI surfaces the same findings on its own stdout, and a Studio / MCP / AI author has no CLI at all, which is the gap #4463 exists to close. NOTE the door asymmetry — `POST /meta/:type/:name/publish` does not carry this field yet (its declaration landed separately as #7294); the gate runs on both doors, only the save door reports. |
+| **advisories** | `{ rule: string; path: string; where: string; message: string; … }[]` | optional | Non-gating findings from the #4463 runtime authoring gate — the same shared author-time rules `os validate` / `os build` / `os lint` run, applied to this body on its way to `active`. The write SUCCEEDED; these are what the gate has to say about it anyway (#4717, closing #4463 D3). Present ONLY when at least one advisory was raised — an empty array is never emitted, so a clean save's response bytes are unchanged and absence means "nothing to report", never "the gate did not run". Advisory by construction: every entry has `severity` `warning` or `info`, because an `error` finding refuses the write and arrives as the 422 `invalid_metadata` envelope instead of here. A caller that ignores this key behaves exactly as before. Runtime-only: the CLI surfaces the same findings on its own stdout, and a Studio / MCP / AI author has no CLI at all, which is the gap #4463 exists to close. The gate runs on both write doors (#4463 D1), and both report: `POST /meta/:type/:name/publish` carries the same key on `PublishMetaItemResponseSchema` (#9176). |
 | **message** | `string` | optional |  |
 
 

packages/metadata-protocol/src/protocol.ts

@@ -3801,10 +3801,12 @@ export class ObjectStackProtocolImplementation implements
      *
      * [#4717] Throws on the gating half, RETURNS the advisory half. Advisories
      * do not block anything, so the only honest place for them is the 2xx the
-     * write earns — `saveMetaItem` attaches them to its response, and the only
-     * other caller (the draft→active promotion in `publishMetaItem`) simply
-     * ignores the value, which is why adding this channel could not change what
-     * either door does.
+     * write earns — `saveMetaItem` attaches them to its response, and since
+     * #9176 the draft→active promotion does the same: `promoteDraftForPublish`
+     * hands the findings out and `publishMetaItem` attaches them, so both
+     * write doors report what D1 makes both of them measure. (The batch route
+     * `publishPackageDrafts` still discards its per-draft findings — its
+     * response face is a different contract.)
      * Returns an empty array on every early return: no rules ran, so there is
      * nothing to report, and "clean" is told apart from "nothing ran" by the
      * gate's own `rulesRun`, not by this.
@@ -13653,6 +13655,15 @@ export class ObjectStackProtocolImplementation implements
          * closed on the spec side.
          */
         projectionApplied?: MutationProjectionOutcome;
+        /**
+         * [#9176] Present ONLY when the #4463 runtime authoring gate raised at
+         * least one non-blocking finding against the draft body this promotion
+         * carried to `active` — an empty array is never emitted, so a clean
+         * publish's response bytes are unchanged (the #4717 discipline, one
+         * door over). Every entry is `warning`/`info` by construction: an
+         * `error` finding refuses the promotion as the 422 instead.
+         */
+        advisories?: RuntimeAuthoringIssue[];
     }> {
         // #4432 — CANONICAL TYPE KEY. See {@link canonicalMetaType}. This is the
         // SEVENTH `/meta` entry point, and until #8769 it was the only one that
@@ -13736,7 +13747,7 @@ export class ObjectStackProtocolImplementation implements
         // site has no transaction of its own, so recording it in the `catch` is
         // where it always effectively landed; what changed is that the helper no
         // longer assumes that on behalf of the batch route too.
-        const { singularType, orgId, result } = await this.promoteDraftForPublish(request)
+        const { singularType, orgId, advisories, result } = await this.promoteDraftForPublish(request)
             .catch(async (err: unknown) => {
                 await this.recordPendingDenialAudit(err);
                 throw err;
@@ -13779,11 +13790,17 @@ export class ObjectStackProtocolImplementation implements
             seedApplied?: { success: boolean; inserted: number; updated: number; error?: string; errors?: unknown[] };
             materializeApplied?: PublishMaterializeResult;
             projectionApplied?: MutationProjectionOutcome;
+            advisories?: RuntimeAuthoringIssue[];
         } = {
             success: true,
             version: result.version,
             seq: result.seq,
             message: `Published draft — type=${request.type}, name=${request.name} [seq=${result.seq}]`,
+            // [#9176] Omitted-when-empty, never `advisories: []` — a clean
+            // publish's response bytes are unchanged, and absence means
+            // "nothing to report", never "the gate did not run" (#4717's
+            // ruling, point 2, carried to this door).
+            ...(advisories.length > 0 ? { advisories } : {}),
         };
         const effects = await this.runPublishSideEffects({
             singularType,
@@ -13852,6 +13869,17 @@ export class ObjectStackProtocolImplementation implements
     }): Promise<{
         singularType: string;
         orgId: string | null;
+        /**
+         * [#9176] The #4463 gate's advisory half for this promotion — the
+         * non-blocking findings `assertRuntimeAuthoringRules` RETURNS (its
+         * gating half throws before this method resolves). Empty when the
+         * gate raised nothing or did not run (no draft, package-author
+         * channel); `publishMetaItem` attaches it to its response only when
+         * non-empty, exactly as `saveMetaItem` does one door over. The batch
+         * caller (`publishPackageDrafts`) deliberately does not read it —
+         * its response face is a different contract.
+         */
+        advisories: RuntimeAuthoringIssue[];
         result: { version: string; seq: number; item: MetadataItem; packageId: string | null };
     }> {
         const singularType = PLURAL_TO_SINGULAR[request.type] ?? request.type;
@@ -13909,8 +13937,13 @@ export class ObjectStackProtocolImplementation implements
             { type: singularType, name: request.name, org: orgId ?? 'env' } as Parameters<typeof repo.get>[0],
             { state: 'draft' },
         );
-        if (draftForGate) {
-            this.assertRuntimeAuthoringRules({
+        // [#9176] The gate's return is its advisory half (#4717): captured and
+        // handed out so `publishMetaItem` can attach it to the 2xx this
+        // promotion is about to earn, exactly as `saveMetaItem` attaches its
+        // own. Held in a local, never on `this` — the gate is per-write and
+        // two concurrent publishes must not read each other's findings.
+        const runtimeAdvisories: RuntimeAuthoringIssue[] = draftForGate
+            ? this.assertRuntimeAuthoringRules({
                 type: singularType,
                 name: request.name,
                 state: 'active',
@@ -13919,8 +13952,8 @@ export class ObjectStackProtocolImplementation implements
                 // it the draft door would be a bypass for this refusal alone,
                 // which is the exact hole #4463 D1 closed for the other 26.
                 organizationId: orgId,
-            });
-        }
+            })
+            : [];
 
         const artifactBacked = this.isArtifactBacked(singularType, request.name);
         const intent: 'override-artifact' | 'runtime-only' = artifactBacked
@@ -13943,7 +13976,7 @@ export class ObjectStackProtocolImplementation implements
                 // present-and-undefined for the historical resolution to hold.
                 ...('packageId' in request ? { packageId: request.packageId ?? null } : {}),
             });
-            return { singularType, orgId, result };
+            return { singularType, orgId, advisories: runtimeAdvisories, result };
         } catch (err: any) {
             if (err instanceof ConflictError) {
                 const conflict: any = new Error(