Publish refusals: declare failed[].issues + seedApplied.issues, then trim error to a headline (#10895)

* fix(metadata-protocol): publish refusals state a headline; the prose rides the declared issues[] channel

Declare-then-trim (#10524): PublishPackageDraftsResponseSchema's failed[]
element declares the issues[] the producer has emitted since #8333, and
seedApplied declares the seed refusal's issues[]; then the #4463 gate's 422
message and seedRequestValidationError's message shrink to one-sentence
headlines (count + path [rule|code] locators) instead of restating the prose
the structured channel carries.

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

* chore: changeset + regenerated spec artifacts for #10524

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

---------

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

Author: Elon Musk

.changeset/publish-error-headline-issues.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/spec': minor
+'@objectstack/metadata-protocol': patch
+'@objectstack/runtime': patch
+---
+
+Publish refusals no longer render each validation finding twice (#10524) — declare-then-trim.
+
+**Declared (spec, additive):** `PublishPackageDraftsResponseSchema.failed[]` elements now
+declare `issues[]` (the `RuntimeAuthoringIssueSchema` findings the producer has emitted
+since #8333 but no declared parse could carry), and `seedApplied` declares `issues[]`
+(`{ path, message, code? }`, the seed-body schema refusal's findings). Typed consumers —
+the SDK's `PublishPackageDraftsResponse`, any `parse` through the schema — can now read
+the structured findings back instead of having them silently stripped.
+
+**Trimmed (producers):** the #4463 author-time gate's 422 message and
+`seedRequestValidationError`'s message are one-sentence headlines — total count plus up to
+three `path [rule]` / `path [zod-code]` locators — instead of restating the issue prose
+that `issues[]` carries on the same response. Consumers that render only `error` (CLI,
+logs) keep what failed, where, under which rule, and how many; consumers that render both
+channels stop repeating themselves. The old `(+N more)` tail is subsumed by the leading
+count. Both catches that surface the seed refusal onto `seedApplied` now thread the
+structured findings beside the headline.
+
+Error `code`/`status` vocabularies, `advisories`, the DESTRUCTIVE_CHANGE (409) message,
+and `saveMetaItem`'s spec-validation 422 message are unchanged. Messages are not contract
+(the machine-readable channels are `code` and `issues[]`), so this is not a breaking
+change and registers no migration.

content/docs/references/api/protocol.mdx

@@ -1248,7 +1248,7 @@ List packages response
 | **publishedCount** | `integer` | ✅ | Number of drafts promoted to active — `published.length`. 0 on every refusal path (the batch is all-or-nothing, ADR-0067 D2). |
 | **failedCount** | `integer` | ✅ | Number of items that did not publish — `failed.length`. On a rollback this counts the WHOLE batch: the causal item plus every sibling marked BATCH_ABORTED. |
 | **published** | `{ type: string; name: string; version: string; advisories?: object[] }[]` | ✅ | Every draft promoted to active, in publish order. Empty on every refusal path. |
-| **failed** | `{ type: string; name: string; error: string; code?: string }[]` | ✅ | Items that did not publish. Because the batch is all-or-nothing (ADR-0067 D2), a non-empty list means NOTHING landed: `published: []`, `publishedCount: 0`. |
+| **failed** | `{ type: string; name: string; error: string; code?: string; … }[]` | ✅ | Items that did not publish. Because the batch is all-or-nothing (ADR-0067 D2), a non-empty list means NOTHING landed: `published: []`, `publishedCount: 0`. |
 | **seedApplied** | `{ success: boolean; inserted?: integer; updated?: integer; error?: string; … }` | optional | Aggregate outcome of materializing EVERY published `seed` body in one multi-pass loader run (cross-seed references need the whole set). Present ONLY when the batch published at least one seed. Two producers, one key: the batch itself self-applies (`applySeedBodies`), and the REST door back-fills the same key for custom protocols that do not — never both (an externalId-less seed would double-insert). Best-effort: a seed problem is surfaced here, never thrown. |
 | **materializeApplied** | `{ success: boolean; inserted: integer; updated: integer; failures: object[] }` | optional | ADR-0086 P2 — aggregate result of publish-time materializers across the batch (e.g. `permission` → `sys_permission_set`), including side-effect failures surfaced by the per-item effects loop. Present ONLY when at least one published item had a registered materializer or a side-effect failure. Best-effort, same contract as `seedApplied`. |
 | **probes** | `any` | optional | ADR-0038 L3 post-publish runtime probe report — one real read per published artifact (seeded objects have rows, views are readable, widget dataset selections execute). DELIBERATELY OPAQUE in this contract (#9406): the key is declared and carried through verbatim, but its inner shape is intentionally not modeled until a consumer needs a field of it. Present only when something was publishable; probes never fail the publish. |

docs/audits/2026-07-unknown-key-strictness-ledger.counts.md

@@ -257,7 +257,7 @@ directory rather than per file.
 | Dir | Sites |
 |---|---|
 | `ai/` | 77 |
-| `api/` | 406 |
+| `api/` | 407 |
 | `cloud/` | 83 |
 | `identity/` | 32 |
 | `integration/` | 10 |

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

@@ -380,7 +380,14 @@ describe('publishPackageDrafts judges each draft against the BATCH closure (#103
         const causal = res.failed.find((f) => f.name === 'customer_dashboard')!;
         expect(causal.code).toBe('INVALID_METADATA');
         expect(causal.error).toMatch(/widget-dataset-unknown/);
-        expect(causal.error).toMatch(/no_such_dataset_xyz/);
+        // [#10524] `error` is a headline now (path + rule locators); the
+        // dataset NAME lives in the finding's message, once, on the
+        // structured channel the batch response declares (`failed[].issues`).
+        const unknownDs = (causal as any).issues.find(
+            (i: any) => i.rule === 'widget-dataset-unknown',
+        );
+        expect(unknownDs.message).toMatch(/no_such_dataset_xyz/);
+        expect(causal.error).not.toContain(unknownDs.message);
         // ADR-0067 D2 — all-or-nothing: the healthy sibling is aborted, not
         // published around the refusal.
         expect(res.failed.find((f) => f.name === 'shyx_customer_ds')?.code).toBe('BATCH_ABORTED');

packages/metadata-protocol/src/protocol.batch-verb-driver-code.test.ts

@@ -441,16 +441,20 @@ describe('[#8441] [GUARD] the Studio publish surface still gets the code it bran
         // WHICH DRAFT.
         expect(failure.type).toBe('flow');
         expect(failure.name).toBe('leave_approval');
-        // WHICH FIELD — the located path, in the human sentence (#8333's half).
+        // WHICH FIELD — the located path, in the human sentence (#8333's
+        // half). [#10524] The sentence is a HEADLINE: path and rule id stay
+        // in it, and the message prose lives once, in `issues[]` below.
         expect(failure.error).toContain('flows[0].nodes[1].config.approvers[0].value');
-        expect(failure.error).toContain('does not parse as CEL');
+        expect(failure.error).toContain('[approval-expression-invalid]');
+        expect(failure.error).not.toContain('does not parse as CEL');
         // …and the machine-readable halves the form highlights with. `code` is
         // THIS card's field: catalogued, so it passes through byte for byte.
         expect(failure.code).toBe('INVALID_METADATA');
         expectCataloged(failure.code);
         expect(Array.isArray(failure.issues)).toBe(true);
         expect(failure.issues[0].path).toBe('flows[0].nodes[1].config.approvers[0].value');
         expect(failure.issues[0].rule).toBe('approval-expression-invalid');
+        expect(failure.issues[0].message).toMatch(/does not parse as CEL/);
     });
 });
 

packages/metadata-protocol/src/protocol.batch-verb-driver-text.test.ts

@@ -594,9 +594,16 @@ describe('[#8333] [GUARD] a spec-validation failure on the publish path still na
         // WHICH DRAFT.
         expect(failure.type).toBe('flow');
         expect(failure.name).toBe('leave_approval');
-        // WHICH FIELD — the located path, in the human sentence.
+        // WHICH FIELD — the located path, in the human sentence. [#10524]
+        // The sentence is a HEADLINE now: it keeps the path and the rule id
+        // (this pin's guarded property — the withhold must not blank WHICH
+        // FIELD of WHICH DRAFT) while the message prose lives once, in
+        // `issues[]` below, instead of being restated here — every console
+        // rendering both channels was showing each finding twice.
         expect(failure.error).toContain('flows[0].nodes[1].config.approvers[0].value');
-        expect(failure.error).toContain('does not parse as CEL');
+        expect(failure.error).toContain('[approval-expression-invalid]');
+        expect(failure.error).not.toContain('does not parse as CEL');
+        expect(failure.issues[0].message).toMatch(/does not parse as CEL/);
         // …and the machine-readable halves the Studio form highlights with.
         expect(failure.code).toBe('INVALID_METADATA');
         expect(Array.isArray(failure.issues)).toBe(true);
@@ -632,6 +639,19 @@ describe('[#8333] the seed request’s schema rejection DECLARES itself, so the
         // multi-line stringified `ZodError`, which is why this is evidence.
         expect(r.error).toContain('seeds.0.mode');
         expect(r.error).not.toContain('"code":');
+
+        // [#10524] The message is a HEADLINE (count + `path [zod code]`
+        // locators); the curated per-key prose rides the receipt ONCE,
+        // structurally, on `issues[]` — which is what lets the sentence stop
+        // restating it without the author losing anything. Only the declared
+        // 422 threads this key; the driver-fault cases below stay issue-less.
+        expect(Array.isArray(r.issues)).toBe(true);
+        const modeIssue = r.issues!.find((i: any) => i.path === 'seeds.0.mode');
+        expect(modeIssue).toBeDefined();
+        expect(typeof modeIssue!.message).toBe('string');
+        for (const i of r.issues!) {
+            expect(r.error).not.toContain(i.message);
+        }
     });
 
     it('the unreadable-bodies guard is untouched — a different fact, a different sentence', async () => {

packages/metadata-protocol/src/protocol.ts

@@ -2046,8 +2046,10 @@ function clientFacingFailureCode(err: unknown): string | undefined {
  *
  * The author is also strictly better off: the old path stringified a whole
  * `ZodError`, so `seedApplied.error` was a multi-line JSON dump of raw zod
- * internals. This is the curated summary {@link zodIssuesToMetadataIssues}
- * already produces for every other authoring surface.
+ * internals. The curated findings {@link zodIssuesToMetadataIssues} produces
+ * for every other authoring surface ride this error's `issues` — surfaced on
+ * `seedApplied.issues` by the catches (#10524) — and the message is their
+ * one-sentence headline.
  *
  * [#8443] EXPORTED alongside {@link clientFacingFailureText}: the runtime
  * package-publish door parses the SAME `SeedLoaderRequestSchema` in its own
@@ -2059,19 +2061,40 @@ function clientFacingFailureCode(err: unknown): string | undefined {
  */
 export function seedRequestValidationError(zodIssues: unknown): Error {
     const issues = zodIssuesToMetadataIssues(zodIssues);
-    const summary = issues.slice(0, 3)
-        .map((i: { path: string; message: string }) => `${i.path || '<root>'}: ${i.message}`)
-        .join('; ');
+    // [#10524] `message` is a HEADLINE — count plus `path [zod code]`
+    // locators — never a restatement of the issue prose: the same `issues`
+    // array rides the error structurally, and the catches that surface this
+    // refusal thread it onto `seedApplied.issues` beside the headline, so
+    // the author's curated per-key prose still arrives exactly once.
     const err = new Error(
-        `[invalid_metadata] the published seed bodies failed spec validation: ${summary}`
-        + (issues.length > 3 ? ` (+${issues.length - 3} more)` : ''),
+        `[invalid_metadata] the published seed bodies failed spec validation: `
+        + metadataIssueHeadline(issues),
     );
     (err as any).code = 'INVALID_METADATA';
     (err as any).status = 422;
     (err as any).issues = issues;
     return err;
 }
 
+/**
+ * [#10524] The one-sentence headline for a refusal whose per-path detail
+ * rides `issues[]` structurally: total count plus up to three
+ * `path [zod code]` locators. Restating the issue MESSAGES here is exactly
+ * the duplication #10524 removed — every console rendering both channels
+ * showed each finding twice — so the message names WHERE and HOW MANY and
+ * leaves the prose to the structured channel. The leading count subsumes the
+ * old `(+N more)` tail. The author-time gate composes its own analogue with
+ * `[rule]` locators (`runtime-authoring-gate.ts`), deliberately: rule ids
+ * and zod codes are different vocabularies and folding them into one helper
+ * would blur which one a reader is looking at.
+ */
+function metadataIssueHeadline(issues: MetadataIssueEntry[]): string {
+    const locators = issues.slice(0, 3)
+        .map((i) => `${i.path || '<root>'}${i.code ? ` [${i.code}]` : ''}`)
+        .join('; ');
+    return `${issues.length} issue${issues.length === 1 ? '' : 's'} — ${locators}`;
+}
+
 /**
  * A batch row that names no record id for an operation that needs one — a
  * caller error, so it carries VALIDATION_FAILED / 400 rather than falling
@@ -13304,6 +13327,19 @@ export class ObjectStackProtocolImplementation implements
                 const parsed = schema.safeParse(request.item);
                 if (!parsed.success) {
                     const issues = zodIssuesToMetadataIssues(parsed.error.issues);
+                    // [#10524] Deliberately NOT trimmed to the headline the
+                    // author-time gate and `seedRequestValidationError` now
+                    // compose, although this is the same duplication shape on
+                    // the 422 envelope face (message prose + `details.issues`).
+                    // Measured during that card: this message is quoted on
+                    // faces where it is the SOLE carrier — `duplicatePackage`'s
+                    // `failed[].error` threads no `issues`, and three #8333
+                    // GUARD pins hold the author's prescription ("Unrecognized
+                    // key(s) …", the `defineView(` spelling) to it. Trimming
+                    // here without first declaring a structured channel on
+                    // those faces deletes the prescription from the wire —
+                    // the declare-then-trim order, violated. Filed as its own
+                    // card; see the #10524 PR for the measurement.
                     const summary = issues.slice(0, 3)
                         .map((i: { path: string; message: string }) => `${i.path || '<root>'}: ${i.message}`)
                         .join('; ');
@@ -14838,7 +14874,10 @@ export class ObjectStackProtocolImplementation implements
     private async applySeedBodies(
         bodies: unknown[],
         organizationId: string | null,
-    ): Promise<{ success: boolean; inserted: number; updated: number; error?: string; errors?: unknown[] }> {
+    ): Promise<{
+        success: boolean; inserted: number; updated: number; error?: string; errors?: unknown[];
+        issues?: Array<{ path: string; message: string; code?: string | undefined }>;
+    }> {
         try {
             const seeds = bodies.filter(
                 (b: any) => b && typeof b.object === 'string' && Array.isArray(b.records),
@@ -14905,6 +14944,17 @@ export class ObjectStackProtocolImplementation implements
             return {
                 success: false, inserted: 0, updated: 0,
                 error: clientFacingFailureText(e, 'seed apply failed'),
+                // [#10524] A DECLARED refusal's structured findings ride the
+                // receipt beside the headline `error` — the message is a
+                // one-sentence headline now, so this is where the per-key
+                // prose reaches the author. Guarded by the same declaration
+                // test as the text above: only the declared 422
+                // (`seedRequestValidationError`) attaches `issues`; no driver
+                // error carries them (the #8441 measurement), so nothing
+                // undeclared is routed around the withhold.
+                ...(declaresClientRefusal(e) && Array.isArray(e?.issues)
+                    ? { issues: e.issues }
+                    : {}),
             };
         }
     }

packages/metadata-protocol/src/runtime-authoring-gate.ts

@@ -635,11 +635,30 @@ export function evaluateRuntimeAuthoringGate(args: {
     if (result.errors.length === 0 && localIssues.length === 0) return { error: null, advisories };
 
     const issues = [...result.errors.map(toIssue), ...localIssues];
-    const summary = issues
+    // [#10524] Two renderings of one array, two audiences — deliberately NOT
+    // one string:
+    //
+    // - `detail` is the WHOLE refusal — path, rule and message prose — and
+    //   goes only where no structured channel exists: the operator's
+    //   un-deduped hatch warn below (#4463 acceptance).
+    // - the thrown 422's `message` is `headline`: what failed, where, which
+    //   rules, how many. Every wire face the message lands on carries the
+    //   SAME `issues` array structurally (`error.details.issues` on the
+    //   single-item 422, `failed[].issues` on the batch response), so
+    //   restating the issue prose in the message made every console render
+    //   each finding twice — the summary-then-bullets duplication this trim
+    //   removes. The leading count subsumes the old `(+N more)` tail; the
+    //   prose lives once, in `issues[]`.
+    const locators = issues
         .slice(0, 3)
-        .map((i) => `${i.path || i.where || '<root>'}: [${i.rule}] ${i.message}`)
+        .map((i) => `${i.path || i.where || '<root>'} [${i.rule}]`)
         .join('; ');
-    const detail = summary + (issues.length > 3 ? ` (+${issues.length - 3} more)` : '');
+    const headline = `${issues.length} issue${issues.length === 1 ? '' : 's'} — ${locators}`;
+    const detail = issues
+        .slice(0, 3)
+        .map((i) => `${i.path || i.where || '<root>'}: [${i.rule}] ${i.message}`)
+        .join('; ')
+        + (issues.length > 3 ? ` (+${issues.length - 3} more)` : '');
     // The registry's own disclosure, plus the gate-local rule when it was
     // applicable to this type. `rulesRun` exists so a caller can tell "clean"
     // from "nothing ran"; a judgement that can refuse a write and never appears
@@ -668,7 +687,7 @@ export function evaluateRuntimeAuthoringGate(args: {
     }
 
     const err = new Error(
-        `[invalid_metadata] ${args.type}/${args.name} failed author-time validation: ${detail}`,
+        `[invalid_metadata] ${args.type}/${args.name} failed author-time validation: ${headline}`,
     );
     (err as any).code = 'INVALID_METADATA';
     (err as any).status = 422;