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

publishPackageDrafts (Studio's "publish whole app") destructured only
{ singularType, result } from promoteDraftForPublish, which since #9176
RETURNS the #4463 gate's advisory findings — so they were computed and
discarded, per draft, for every draft in the batch.

Per the maintainer's ruling on #9343: advisories ride EACH published[]
element, same optional omitted-when-empty shape as
PublishMetaItemResponseSchema.advisories on the single-item door; no
parallel top-level map; failed[] elements unaffected (an error finding
still aborts the batch, ADR-0067 D2).

The objectql doubles of the promoteDraftForPublish seam gain the
advisories key the real helper has returned since #9176.

Part of #9343


Claude-Session: https://claude.ai/code/session_01Fs18A2DdXLVN2h8PaaFBcP

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

Author: os-steve

.changeset/batch-publish-advisories.md

@@ -0,0 +1,5 @@
+---
+"@objectstack/metadata-protocol": minor
+---
+
+`publishPackageDrafts` (Studio's "publish whole app", `POST /packages/:id/publish-drafts`) now reports the #4463 runtime authoring gate's non-blocking findings on each `published[]` element as an optional `advisories` key — the same element shape and omitted-when-empty discipline as the single-item publish door (#9176). An advisory-free batch's response bytes are unchanged, and `failed[]` elements are unaffected (an `error` finding still aborts the batch). Previously the batch door computed these per-draft findings and discarded them.

packages/metadata-protocol/src/protocol-publish-drafts-advisories.test.ts

@@ -0,0 +1,331 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #9343 — the batch publish door (`publishPackageDrafts`, Studio's "publish
+ * whole app", `POST /packages/:id/publish-drafts`) reports the #4463 runtime
+ * authoring gate's per-draft advisories on each `published[]` element.
+ *
+ * Ruled shape (maintainer, 2026-08-17, recorded on the card): advisories ride
+ * EACH `published[]` element, with the same optional, omitted-when-empty shape
+ * as `PublishMetaItemResponseSchema.advisories` on the single-item door
+ * (#9176) — no parallel top-level map. `failed[]` elements are unaffected: an
+ * `error` finding refuses the promotion, and the batch being all-or-nothing
+ * (ADR-0067 D2) that refusal aborts the whole batch.
+ *
+ * Before #9343 the batch caller destructured only `{ singularType, result }`
+ * from `promoteDraftForPublish` — which since #9176 RETURNS the findings — so
+ * the gate's advisory half was computed and dropped on the floor, per draft,
+ * for every draft in the batch: the same shape #9176 closed one door over,
+ * on the one door bulk/AI authoring actually takes.
+ *
+ * The advisory fixture is the #4717 / #9176 measurement verbatim: a flow
+ * whose ONLY defect is a `delete_record` node declaring `multi: true` with no
+ * `filter` — `lintFlowPatterns` raises `flow-multi-write-unfiltered` at
+ * `severity: 'warning'`, so the promotion succeeds and the finding is exactly
+ * what the advisory channel exists to carry. `runAs: 'system'` is
+ * load-bearing: without it `flow-runas-unscoped` fires at `severity: 'error'`
+ * and the publish becomes a refusal wearing an advisory's clothes.
+ *
+ * Harness: the same faithful stub engine as
+ * `protocol-publish-drafts-org-scope.test.ts` (kept local — self-contained
+ * harnesses are the established shape here, so two tripwires can fail
+ * independently). Flows are env-wide (`flow` is `allowOrgOverride: false`),
+ * saved as package-bound drafts, published through the REAL
+ * `publishPackageDrafts` — nothing on the gate path is stubbed.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { assertEngineDeleteDispatch, assertEngineUpdateDispatch } from '@objectstack/metadata-core';
+import { ObjectStackProtocolImplementation } from './protocol.js';
+
+interface Row {
+    id: string;
+    type: string;
+    name: string;
+    organization_id: string | null;
+    package_id: string | null;
+    state: string;
+    metadata: string;
+    checksum?: string;
+    version?: number;
+    updated_at?: string;
+    created_at?: string;
+}
+
+interface HistoryRow {
+    id: string;
+    event_seq: number;
+    name: string;
+    type: string;
+    version: number;
+    operation_type: string;
+    metadata: string | null;
+    checksum: string | null;
+    previous_checksum: string | null;
+    change_note?: string | null;
+    source?: string | null;
+    organization_id: string | null;
+    recorded_by?: string | null;
+    recorded_at: string;
+}
+
+// Overlay rows are keyed by (type, name, org, state, package_id) — the ADR-0048 key.
+function keyOf(w: Record<string, unknown>) {
+    return `${w.type}|${w.name}|${w.organization_id ?? '__env__'}|${w.state ?? 'active'}|${w.package_id ?? '__nopkg__'}`;
+}
+
+function matchesMetadataWhere(r: Row, where: Record<string, unknown>): boolean {
+    for (const [k, v] of Object.entries(where)) {
+        if (k === '$or') {
+            const clauses = v as Array<Record<string, unknown>>;
+            if (!clauses.some((c) => matchesMetadataWhere(r, c))) return false;
+            continue;
+        }
+        if (v === undefined) continue;
+        if ((r as any)[k] !== v) return false;
+    }
+    return true;
+}
+
+function makeStubEngine() {
+    const rows = new Map<string, Row>();
+    const historyRows: HistoryRow[] = [];
+    let nextId = 0;
+
+    const findRow = (w: Record<string, unknown>): { key: string; row: Row } | null => {
+        if (w.id !== undefined) {
+            for (const [k, r] of rows) if (r.id === w.id) return { key: k, row: r };
+            return null;
+        }
+        if (w.package_id !== undefined) {
+            const k = keyOf(w);
+            const r = rows.get(k);
+            return r ? { key: k, row: r } : null;
+        }
+        for (const [k, r] of rows) if (matchesMetadataWhere(r, w)) return { key: k, row: r };
+        return null;
+    };
+
+    const matchesHistory = (h: HistoryRow, w: Record<string, unknown>): boolean => {
+        if (w.organization_id !== undefined && h.organization_id !== w.organization_id) return false;
+        if (w.type !== undefined && h.type !== w.type) return false;
+        if (w.name !== undefined && h.name !== w.name) return false;
+        if (w.version !== undefined && h.version !== w.version) return false;
+        if (w.operation_type !== undefined && h.operation_type !== w.operation_type) return false;
+        return true;
+    };
+
+    const engine: any = {
+        async findOne(table: string, opts: { where: Record<string, unknown> }) {
+            if (table === 'sys_metadata_history') {
+                return historyRows.find((h) => matchesHistory(h, opts.where)) ?? null;
+            }
+            return findRow(opts.where)?.row ?? null;
+        },
+        async find(table: string, opts: { where: Record<string, unknown> }) {
+            if (table === 'sys_metadata_history') {
+                return historyRows.filter((h) => matchesHistory(h, opts.where));
+            }
+            return Array.from(rows.values()).filter((r) => matchesMetadataWhere(r, opts.where));
+        },
+        async insert(table: string, data: Record<string, unknown>) {
+            if (table === 'sys_metadata_audit') return { id: 'audit_skip' };
+            if (table === 'sys_metadata_history') {
+                nextId += 1;
+                const h: HistoryRow = { id: `h_${nextId}`, ...(data as any) };
+                historyRows.push(h);
+                return { id: h.id };
+            }
+            nextId += 1;
+            const row = { id: `r_${nextId}`, ...(data as any) } as Row;
+            rows.set(keyOf(data), row);
+            return { id: row.id };
+        },
+        async update(_t: string, data: Record<string, unknown>, opts: { where: Record<string, unknown> }) {
+            assertEngineUpdateDispatch(data, opts);
+            const found = findRow(opts.where);
+            if (!found) return { id: null };
+            const merged = { ...found.row, ...(data as any) };
+            rows.delete(found.key);
+            rows.set(keyOf(merged), merged);
+            return { id: found.row.id };
+        },
+        async delete(_t: string, opts: { where: Record<string, unknown> }) {
+            assertEngineDeleteDispatch(opts);
+            const found = findRow(opts.where);
+            if (!found) return { deleted: 0 };
+            rows.delete(found.key);
+            return { deleted: 1 };
+        },
+        async transaction<T>(cb: (ctx: any, info: { owned: boolean }) => Promise<T>): Promise<T> {
+            return cb(undefined, { owned: true });
+        },
+        registry: {
+            registerItem: () => {},
+            registerObject: () => {},
+            // No declared package namespace → publishPackageDrafts skips the
+            // ADR-0028 prefix check (legacy-grandfathered path).
+            getPackage: () => undefined,
+        },
+    };
+    return { engine, rows, historyRows };
+}
+
+const PKG = 'app.ops';
+
+/**
+ * The reachable success-with-advisories fixture (#4717 / #9176, verbatim in
+ * structure): the only defect is the unbounded bulk delete, which
+ * `lintFlowPatterns` reports at `severity: 'warning'`.
+ */
+const advisoryFlow = (name: string) => ({
+    name,
+    label: 'Nightly Purge',
+    type: 'autolaunched',
+    status: 'active',
+    runAs: 'system',
+    nodes: [
+        { id: 'start', type: 'start', label: 'Start' },
+        {
+            id: 'purge',
+            type: 'delete_record',
+            label: 'Purge',
+            config: { objectName: 'audit_logs', multi: true },
+        },
+    ],
+    edges: [{ id: 'e1', source: 'start', target: 'purge' }],
+});
+
+/** The same flow with the bulk write bounded — no finding of any severity. */
+const cleanFlow = (name: string) => {
+    const flow = advisoryFlow(name);
+    (flow.nodes[1] as any).config.filter = [{ field: 'created_at', operator: 'lt', value: '2020-01-01' }];
+    return flow;
+};
+
+/** A flow whose approval expression is broken — `severity: 'error'`, the gating half. */
+const gatedFlow = (name: string) => ({
+    name,
+    label: 'Leave Approval',
+    type: 'autolaunched',
+    status: 'active',
+    runAs: 'system',
+    nodes: [
+        { id: 'start', type: 'start', label: 'Start' },
+        {
+            id: 'approve',
+            type: 'approval',
+            label: 'Approve',
+            config: { approvers: [{ type: 'expression', value: 'record.owner ==' }] },
+        },
+    ],
+    edges: [{ id: 'e1', source: 'start', target: 'approve' }],
+});
+
+/** Stage one env-wide, package-bound flow draft (Studio's "Save Draft" shape). */
+async function stageFlowDraft(
+    protocol: ObjectStackProtocolImplementation,
+    name: string,
+    item: unknown,
+): Promise<void> {
+    await (protocol as any).saveMetaItem({
+        type: 'flow', name, item, packageId: PKG, mode: 'draft',
+    });
+}
+
+describe('publishPackageDrafts carries per-draft advisories on published[] elements (#9343)', () => {
+    it('a batch whose one draft raises an advisory succeeds AND reports it on that element', async () => {
+        const { engine } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(engine);
+        await stageFlowDraft(protocol, 'nightly_purge', advisoryFlow('nightly_purge'));
+
+        const res = await protocol.publishPackageDrafts({ packageId: PKG });
+
+        // The batch succeeded — advisories ride the 2xx, never a refusal.
+        expect(res.failed).toEqual([]);
+        expect(res).toMatchObject({ success: true, publishedCount: 1, failedCount: 0 });
+
+        // The finding reached the caller ON THE ELEMENT, with the id and
+        // severity the rule emits — asserting the RULE ID rather than a bare
+        // non-empty array: an array of the wrong findings is a different
+        // defect from an empty one.
+        const el = res.published[0]!;
+        expect(el).toMatchObject({ type: 'flow', name: 'nightly_purge' });
+        expect(el.advisories).toHaveLength(1);
+        expect(el.advisories![0]!.rule).toBe('flow-multi-write-unfiltered');
+        expect(el.advisories![0]!.severity).toBe('warning');
+        expect(el.advisories![0]!.where).toContain('nightly_purge');
+
+        // The element shape mirrors the single-item door's
+        // `RuntimeAuthoringIssueSchema` element keys (#9176) — the "same
+        // shape, both doors" half of the ruling.
+        expect(Object.keys(el.advisories![0]!).sort())
+            .toEqual(['hint', 'message', 'path', 'rule', 'severity', 'where']);
+    });
+
+    it('a mixed batch attaches advisories to exactly the raising element — the clean sibling carries no key', async () => {
+        const { engine } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(engine);
+        await stageFlowDraft(protocol, 'nightly_purge', advisoryFlow('nightly_purge'));
+        await stageFlowDraft(protocol, 'bounded_purge', cleanFlow('bounded_purge'));
+
+        const res = await protocol.publishPackageDrafts({ packageId: PKG });
+
+        expect(res).toMatchObject({ success: true, publishedCount: 2, failedCount: 0 });
+        const byName = new Map(res.published.map((p) => [p.name, p]));
+        const raising = byName.get('nightly_purge')!;
+        const clean = byName.get('bounded_purge')!;
+
+        // Exactly the raising element reports; per-draft mapping, not batch-level.
+        expect(raising.advisories).toHaveLength(1);
+        expect(raising.advisories![0]!.rule).toBe('flow-multi-write-unfiltered');
+
+        // The clean element's KEY SET is untouched — `advisories: []` would
+        // satisfy a `toHaveLength(0)` while changing the element's bytes,
+        // which is exactly what the omitted-when-empty rule forbids.
+        expect('advisories' in clean).toBe(false);
+        expect(Object.keys(clean).sort()).toEqual(['name', 'type', 'version']);
+    });
+
+    it('an advisory-free batch changes nothing: no element carries the key, byte-identical response', async () => {
+        const { engine } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(engine);
+        await stageFlowDraft(protocol, 'bounded_purge', cleanFlow('bounded_purge'));
+        await stageFlowDraft(protocol, 'second_purge', cleanFlow('second_purge'));
+
+        const res = await protocol.publishPackageDrafts({ packageId: PKG });
+
+        expect(res).toMatchObject({ success: true, publishedCount: 2, failedCount: 0 });
+        for (const el of res.published) {
+            expect('advisories' in el).toBe(false);
+            expect(Object.keys(el).sort()).toEqual(['name', 'type', 'version']);
+        }
+        // Byte-for-byte: the serialized response of a clean batch carries no
+        // trace of the field. `JSON.stringify` is the wire (the route hands
+        // this object to `res.json()` verbatim), and the wire is the promise
+        // being made to existing callers.
+        expect(JSON.stringify(res)).not.toContain('advisories');
+    });
+
+    it('the gating half is unchanged: an `error` finding aborts the batch, and failed[] elements carry no advisories key', async () => {
+        const { engine } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(engine);
+        // Draft saves are never gated (D1) — both stage fine.
+        await stageFlowDraft(protocol, 'leave_approval', gatedFlow('leave_approval'));
+        await stageFlowDraft(protocol, 'nightly_purge', advisoryFlow('nightly_purge'));
+
+        const res = await protocol.publishPackageDrafts({ packageId: PKG });
+
+        // ADR-0067 D2 — all-or-nothing: the error finding refuses the causal
+        // item and rolls back the sibling whose own finding was only advisory.
+        expect(res).toMatchObject({ success: false, publishedCount: 0, failedCount: 2 });
+        expect(res.published).toEqual([]);
+        const causal = res.failed.find((f) => f.name === 'leave_approval')!;
+        expect(causal.code).toBe('INVALID_METADATA');
+        const aborted = res.failed.find((f) => f.name === 'nightly_purge')!;
+        expect(aborted.code).toBe('BATCH_ABORTED');
+        // `failed[]` elements are unaffected by #9343 — the ruling's explicit
+        // boundary: no advisories key appears anywhere on a refused batch.
+        expect(JSON.stringify(res.failed)).not.toContain('advisories');
+    });
+});