fix(spec,rest,cli): validation diagnostics reach the real defect — named view-union branches + invalid_key/invalid_element descent (#7025) (#7042)

* fix(spec,rest,cli): validation diagnostics reach the real defect (#6391, #5389)

Sweep #7025 — two cases where a refusal is correct but its DIAGNOSTIC cannot
reach the element that actually failed. Both fixes move the diagnostic face
only; the acceptance face is pinned unmoved in both directions.

#6391 — ViewMetadataSchema's union members are contractual, not positional.
Three of its four members were inline expressions with no name, so a consumer
diagnosing a failure could only reach a branch by indexing the nested
invalid_union `errors[]` BY MEMBER POSITION (objectui#3624 shipped exactly that
and had to hold the coupling down with a canary test). The union is now BUILT
from a named record — VIEW_METADATA_BRANCHES / VIEW_METADATA_MEMBERS — so
"member N is the published schema" is one declaration rather than two that can
drift, and diagnoseViewMetadata() returns the failing branch by NAME with that
branch's own leaf issues and real field paths.

The union is deliberately NOT converted to z.discriminatedUnion: that would
move membership (a discriminated union refuses an unknown discriminant outright
where this one falls through all four members, and several of these shapes
carry no discriminant at all). The dispatch is diagnostic — ViewMetadataSchema
remains the only judge of acceptance, and a pin asserts the two never disagree.

Measured: a 41-body corpus run through ViewMetadataSchema before and after
produces byte-identical verdicts, parse output and issue-code sets
(sha256 fca9df8937bbb9f736f11895a6e1ddf23b7fb25d9b13cfa7e67c71c8dfaaf2b2), and
that corpus is now a committed pin.

#5389 — invalid_key / invalid_element are descended, in all three consumers.
Zod hangs a failing record-key / map-element schema's real issues on
`issue.issues` — the same shape as invalid_union's `issue.errors`, one property
name over. The family had already been fixed three times for `errors` (#4971,
#5014, #5341) while none of the three consumers read `issues`, so both codes
surfaced as a bare wrapper line with the prescription stranded in the payload.
formatZodError/formatZodIssue (spec), zodIssuesToFields (the REST wire) and
formatZodErrors (the CLI terminal) now all descend it, additively: the
container's own line/entry is unchanged and the leaves follow it. Unlike a
union's branches — competing candidates, therefore ranked and capped — a
container's issues are the one list the inner schema produced, so every one of
them is reported.

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

* docs(spec): the acceptance-face corpus is 42 bodies, not 41

Comment-only. The pin table is 19 ACCEPT + 23 REFUSED = 42; the header said 41.
No assertion changed.

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

---------

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

Author: os-zhuang

.changeset/view-union-and-container-issue-diagnostics.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/spec": minor
+"@objectstack/rest": patch
+"@objectstack/cli": patch
+---
+
+fix(spec,rest,cli): validation diagnostics reach the real defect — named view-union branches, and `invalid_key` / `invalid_element` descent (#6391, #5389)
+
+Two cases where a refusal fired correctly but its *diagnostic* could not reach the
+element that actually failed. Both fixes change the DIAGNOSTIC face only: every
+input that parsed before parses after, every input refused before is refused
+after, and each refusal keeps its issue codes (ADR-0112 / #6142 — a better
+diagnostic never weakens the envelope). Pinned in both directions.
+
+**#6391 — `ViewMetadataSchema`'s union members are now contractual.** Three of
+its four members were inline expressions with no name, so a consumer diagnosing a
+failure could only reach a branch by indexing the nested `invalid_union`
+`errors[]` **by member position**; objectui shipped exactly that and had to hold
+the coupling down with a canary test (objectui#3606 / PR objectui#3624). The
+union is now built from a named record:
+
+- `VIEW_METADATA_BRANCHES` — the branch names, in the union's own order;
+- `VIEW_METADATA_MEMBERS` — branch name → the schema the union actually holds
+  (`viewItem` is identically `ViewItemWireSchema`, as before);
+- `selectViewMetadataBranch(body)` — which branch a body claims, by the
+  discriminants the members already declare;
+- `diagnoseViewMetadata(body)` — the failing branch **named**, with that branch's
+  own leaf issues and real field paths, so no consumer needs `errors[i]`.
+
+The union is **not** converted to `z.discriminatedUnion`. That would move the
+acceptance face — a discriminated union refuses an unknown discriminant outright
+where this one falls through all four members, and several of these shapes carry
+no discriminant at all. `ViewMetadataSchema` remains the only judge of
+acceptance; the dispatch only explains a verdict it did not make, and a pin
+asserts the two never disagree.
+
+**#5389 — `invalid_key` / `invalid_element` are descended, in all three
+consumers.** Zod hangs a failing record-key / map-element schema's real issues on
+`issue.issues` — the same shape as `invalid_union`'s `issue.errors`, one property
+name over. The family had already been fixed three times for `errors` (#4971,
+#5014, #5341) and none of the three consumers read `issues`, so both codes
+surfaced as a bare wrapper line with the prescription stranded in the payload.
+Now `formatZodError`/`formatZodIssue` (spec), `zodIssuesToFields` (the REST wire)
+and `formatZodErrors` (the CLI terminal) all descend it.
+
+Before / after, a `z.record` with a constrained key:
+
+```
+  ✗ fields.First Name: Invalid key in record
+```
+```
+  ✗ fields.First Name: Invalid key in record
+    ✗ fields.First Name: Invalid identifier. Must be lowercase snake_case …
+```
+
+The expansion is strictly additive on every surface: the container's own line
+(and, on the wire, its own `{field, code: 'invalid_shape', message}` entry) is
+unchanged, and the leaves follow it. Unlike a union's branches — competing
+candidates, therefore ranked and capped — a container's `issues` are the one list
+the inner schema produced, so every one of them is reported.

packages/cli/src/utils/format.ts

@@ -208,18 +208,37 @@ export function createTimer() {
 // ─── Zod Error Formatting ───────────────────────────────────────────
 
 /**
- * How far the branch lines of an expanded union are pushed to sit UNDER the
- * `code: message` line this file prints for the union itself.
+ * How far the nested lines of an expanded issue are pushed to sit UNDER the
+ * `code: message` line this file prints for the issue itself.
  *
  * `formatZodIssue` indents its own depth-0 line by 2 spaces and each nested
  * level by 2 more; this file's per-issue block is at 4/6. Adding 4 puts the
- * first branch level at 8 — one step below the `invalid_union: Invalid input`
+ * first nested level at 8 — one step below the `invalid_union: Invalid input`
  * line it explains — and keeps every deeper level nested relative to it.
  */
-const UNION_BRANCH_REINDENT = '    ';
+const NESTED_ISSUE_REINDENT = '    ';
 
 /**
- * The lines that explain an `invalid_union`, or nothing at all.
+ * [#5389] The issue codes whose real diagnosis is nested one level down, and
+ * which `formatZodIssue` therefore renders as more than one line.
+ *
+ * `invalid_union` puts each candidate branch on `issue.errors[]`; `invalid_key`
+ * / `invalid_element` put the key/element schema's own issues on
+ * `issue.issues[]`. Same defect, two property names — and the gate below has to
+ * name both, or the terminal keeps printing `invalid_key: Invalid key in
+ * record` with the prescription stranded in the payload.
+ *
+ * Kept in step with `CONTAINER_ISSUE_CODES` in `@objectstack/spec`'s
+ * `error-map.zod.ts`, which is where the descent itself lives.
+ */
+const EXPANDABLE_ISSUE_CODES: ReadonlySet<string> = new Set([
+  'invalid_union',
+  'invalid_key',
+  'invalid_element',
+]);
+
+/**
+ * The lines that explain an expandable issue, or nothing at all.
  *
  * Zod folds every branch of a failed union into ONE issue whose own `message`
  * is the literal `"Invalid input"`; each branch's real rejection sits in
@@ -241,18 +260,24 @@ const UNION_BRANCH_REINDENT = '    ';
  * so had to re-implement the ranking — the terminal needs exactly the STRING
  * that spec already exports, so here the reuse is a plain import.
  *
- * Line 0 of that render is the union's own verdict, which the caller has
+ * [#5389] The same import now also covers `invalid_key` / `invalid_element`,
+ * whose diagnosis hangs on `issue.issues[]` instead. Widening the gate is the
+ * WHOLE of this file's share of that fix — the descent is spec's, so the
+ * terminal inherits it the moment it stops refusing to ask.
+ *
+ * Line 0 of that render is the issue's own verdict, which the caller has
  * already printed in this file's own idiom; only the explanation is returned,
  * so the change is strictly ADDITIVE — nothing that printed before #5341 stops
- * printing. A non-union issue renders as a single line, hence never reaches
- * here and could not add one anyway.
+ * printing. An issue with nothing nested renders as a single line, hence never
+ * reaches here and could not add one anyway.
  */
-function unionBranchLines(issue: unknown): string[] {
-  if ((issue as { code?: unknown } | null)?.code !== 'invalid_union') return [];
+function nestedIssueLines(issue: unknown): string[] {
+  const code = (issue as { code?: unknown } | null)?.code;
+  if (typeof code !== 'string' || !EXPANDABLE_ISSUE_CODES.has(code)) return [];
   return formatZodIssue(issue as Parameters<typeof formatZodIssue>[0])
     .split('\n')
     .slice(1)
-    .map((line) => `${UNION_BRANCH_REINDENT}${line}`);
+    .map((line) => `${NESTED_ISSUE_REINDENT}${line}`);
 }
 
 export function formatZodErrors(error: ZodError) {
@@ -291,8 +316,9 @@ export function formatZodErrors(error: ZodError) {
         console.log(chalk.dim(`      received: ${chalk.red((issue as any).received)}`));
       }
 
-      // [#5341] …and, for a union, the branch that actually explains it.
-      for (const line of unionBranchLines(issue)) {
+      // [#5341] …and, for a union — [#5389] or a record key / map element —
+      // the nested issues that actually explain it.
+      for (const line of nestedIssueLines(issue)) {
         console.log(chalk.dim(line));
       }
     }

packages/cli/test/format-zod-union.test.ts

@@ -224,3 +224,42 @@ describe('[#5341] `os validate` delivers a union branch prescription', () => {
     expect(JSON.stringify(payload.errors[0].errors)).toContain('`direction` → `order`');
   }, 120_000);
 });
+
+/**
+ * [#5389] The terminal's share of the 4th/5th family members.
+ *
+ * `invalid_key` / `invalid_element` hang the key/element schema's real
+ * complaint on `issue.issues[]` rather than on `invalid_union`'s
+ * `issue.errors[]`. The descent itself is `@objectstack/spec`'s — reused, not
+ * re-derived, exactly as #5341 reused it for the union — so this file's whole
+ * share of the fix is that its gate stopped saying `code !== 'invalid_union'`
+ * and started naming all three expandable codes.
+ *
+ * Strictly additive, same as #5341: the `code: message` line the terminal
+ * already printed for the container is untouched; only the explanation is new.
+ */
+describe('[#5389] formatZodErrors expands invalid_key / invalid_element', () => {
+  const SnakeKey = z
+    .string()
+    .regex(/^[a-z][a-z0-9_]*$/, "Invalid identifier. Must be lowercase snake_case (e.g. 'first_name').");
+
+  it('prints the key schema prose under the container line', () => {
+    const schema = z.object({ fields: z.record(SnakeKey, z.object({ type: z.string() })) });
+    const out = render(schema.safeParse({ fields: { 'First Name': { type: 'text' } } }).error!);
+    expect(out).toContain('invalid_key: Invalid key in record');
+    expect(out).toContain("Invalid identifier. Must be lowercase snake_case (e.g. 'first_name').");
+  });
+
+  it('prints the element schema prose for a map', () => {
+    const schema = z.map(z.object({ id: z.string() }), z.number().min(5, 'too small'));
+    const out = render(schema.safeParse(new Map([[{ id: 'a' }, 1]])).error!);
+    expect(out).toContain('invalid_element');
+    expect(out).toContain('too small');
+  });
+
+  it('adds nothing to an ordinary issue', () => {
+    // The conservative half: only the three expandable codes may grow lines.
+    const before = render(z.object({ a: z.string() }).safeParse({}).error!);
+    expect(before.split('\n').filter((l) => l.includes('✗'))).toHaveLength(1);
+  });
+});

packages/rest/src/rest-server.ts

@@ -212,8 +212,8 @@ function valueAtPath(input: unknown, path: unknown): unknown {
 }
 
 /**
- * How many levels of nested `invalid_union` are expanded below a top-level
- * issue, and how many equally-informative branches are emitted at one level.
+ * How many levels of nested issues are expanded below a top-level issue, and
+ * how many equally-informative union branches are emitted at one level.
  *
  * Both bounds — and the whole selection policy below — are the ones
  * `formatZodError` landed for the CLI/spec side of this defect (#4971,
@@ -223,9 +223,22 @@ function valueAtPath(input: unknown, path: unknown): unknown {
  * the same, or one mistake gets two different prescriptions depending on whether
  * the author published from the terminal or POSTed to the API (#5014).
  */
-const UNION_EXPANSION_DEPTH_LIMIT = 3;
+const NESTED_EXPANSION_DEPTH_LIMIT = 3;
 const UNION_BRANCH_EMIT_LIMIT = 3;
 
+/**
+ * [#5389] The issue codes that hang their real diagnosis on `issue.issues`
+ * rather than on `invalid_union`'s `issue.errors`.
+ *
+ * `invalid_key` is raised when `z.record(K, V)`'s KEY schema rejects a key (and
+ * by `z.map` for a non-`PropertyKey` key); `invalid_element` when `z.map`'s
+ * VALUE schema rejects the value under such a key. Both carry a bare wrapper
+ * message ("Invalid key in record") with everything the client needs one level
+ * down — the same defect as #5014, one property name over. Kept in step with
+ * `CONTAINER_ISSUE_CODES` in `spec/src/shared/error-map.zod.ts`.
+ */
+const CONTAINER_ISSUE_CODES: ReadonlySet<string> = new Set(['invalid_key', 'invalid_element']);
+
 /** A Zod issue path, normalised to the array Zod always produces. */
 function issuePathOf(issue: any): Array<string | number> {
     return Array.isArray(issue?.path) ? issue.path : [];
@@ -308,6 +321,14 @@ function selectUnionBranches(branches: readonly (readonly any[])[]): readonly (r
  * the branches that explain it, with `field` resolved against the union's own
  * path — branch paths are relative to it.
  *
+ * [#5389] An `invalid_key` / `invalid_element` behaves the same way one property
+ * name over: its own entry (zod's `"Invalid key in record"`, also
+ * `invalid_shape`) followed by the entries on `issue.issues`, whose paths are
+ * likewise relative. The one difference from a union: those issues are not
+ * competing candidates, so they are NOT ranked or capped — every one of them is
+ * a true statement about the value, and dropping any would be dropping a real
+ * diagnosis rather than declining to guess.
+ *
  * The union's entry is kept rather than replaced: it is the only entry naming
  * the slot the client sent, existing clients already read it, and when every
  * branch is uninformative it is still the whole answer. So the expansion is
@@ -343,7 +364,11 @@ function collectIssueFields(
     const branches: readonly (readonly any[])[] = issue?.code === 'invalid_union' && Array.isArray(issue?.errors)
         ? issue.errors.filter((branch: unknown): branch is any[] => Array.isArray(branch))
         : [];
-    const expandable = branches.length > 0 && depth < UNION_EXPANSION_DEPTH_LIMIT;
+    const contained: readonly any[] = CONTAINER_ISSUE_CODES.has(issue?.code) && Array.isArray(issue?.issues)
+        ? issue.issues
+        : [];
+    const expandable = (branches.length > 0 || contained.length > 0)
+        && depth < NESTED_EXPANSION_DEPTH_LIMIT;
 
     const entry = {
         field,
@@ -361,10 +386,17 @@ function collectIssueFields(
     out.push(entry);
     if (!expandable) return;
 
-    for (const branch of selectUnionBranches(branches)) {
-        for (const nested of branch) {
-            collectIssueFields(nested, path, depth + 1, seen, input, inputProvided, out);
+    if (branches.length > 0) {
+        for (const branch of selectUnionBranches(branches)) {
+            for (const nested of branch) {
+                collectIssueFields(nested, path, depth + 1, seen, input, inputProvided, out);
+            }
         }
+        return;
+    }
+
+    for (const nested of contained) {
+        collectIssueFields(nested, path, depth + 1, seen, input, inputProvided, out);
     }
 }
 

packages/rest/src/zod-union-fields.test.ts

@@ -238,3 +238,85 @@ describe('zodIssuesToFields — invalid_union expansion (#5014)', () => {
         });
     });
 });
+
+/**
+ * [#5389] `invalid_key` / `invalid_element` — the same defect, one property
+ * name over, on the same wire.
+ *
+ * `invalid_union` buries a branch's real complaint in `issue.errors[]`; these
+ * two bury the key/element schema's real complaint in `issue.issues[]`. Before
+ * this, a client POSTing a record with a bad KEY got exactly one `fields[]`
+ * entry — `{field: 'fields.First Name', code: 'invalid_shape', message:
+ * 'Invalid key in record'}` — with the sentence naming the rule produced and
+ * dropped, which is #5014 verbatim.
+ *
+ * The expansion is strictly ADDITIVE, same contract as #5014: the container's
+ * own entry stays (it is the only one naming the slot, and existing clients
+ * read it) and the leaf entries follow it. ADR-0114's `{field, code, message}`
+ * shape is unchanged, and the container entry keeps mapping to `invalid_shape`.
+ *
+ * Every fixture drives a REAL `safeParse`, for the reason the file's header
+ * gives: `issue.issues` is Zod's internal shape.
+ */
+describe('zodIssuesToFields — invalid_key / invalid_element descent (#5389)', () => {
+    const fieldsFor = (schema: z.ZodType, value: unknown) => {
+        const r = schema.safeParse(value);
+        expect(r.success, 'the fixture must actually fail to parse').toBe(false);
+        return zodIssuesToFields((r as { error: { issues: unknown[] } }).error.issues, value);
+    };
+
+    const SnakeKey = z
+        .string()
+        .regex(/^[a-z][a-z0-9_]*$/, "Invalid identifier. Must be lowercase snake_case (e.g. 'first_name').");
+
+    it('delivers the KEY schema prescription beside the container entry', () => {
+        const schema = z.object({ fields: z.record(SnakeKey, z.object({ type: z.string() })) });
+        const fields = fieldsFor(schema, { fields: { 'First Name': { type: 'text' } } });
+
+        expect(fields).toEqual([
+            // Unchanged — the entry clients read today.
+            { field: 'fields.First Name', code: 'invalid_shape', message: 'Invalid key in record' },
+            // …and the leaf that says WHY, with the container's path resolved.
+            {
+                field: 'fields.First Name',
+                code: 'invalid_format',
+                message: "Invalid identifier. Must be lowercase snake_case (e.g. 'first_name').",
+            },
+        ]);
+    });
+
+    it('emits EVERY nested issue — a container has no branches to rank', () => {
+        // Deliberate divergence from the union descent: `errors[]` holds
+        // competing candidates, so it is ranked and capped; `issues[]` is the
+        // one list the element schema produced, and each entry is a real field.
+        const schema = z.map(
+            z.object({ id: z.string() }),
+            z.object({ a: z.string(), b: z.string(), c: z.string() }),
+        );
+        const fields = fieldsFor(schema, new Map([[{ id: 'x' }, {}]]));
+        expect(fields[0]).toMatchObject({ code: 'invalid_shape' });
+        expect(fields.map((f) => f.field)).toEqual(['', 'a', 'b', 'c']);
+    });
+
+    it('keeps the catalog code an ADR-0114 member on every entry', () => {
+        const schema = z.object({ fields: z.record(SnakeKey, z.unknown()) });
+        const codes = FieldErrorCode.options as readonly string[];
+        for (const entry of fieldsFor(schema, { fields: { 'Bad Key': 1 } })) {
+            expect(codes).toContain(entry.code);
+        }
+    });
+
+    it('leaves an ordinary issue exactly as it was', () => {
+        const schema = z.object({ a: z.string() });
+        expect(fieldsFor(schema, {})).toEqual([
+            { field: 'a', code: 'required', message: 'Invalid input: expected string, received undefined' },
+        ]);
+    });
+
+    it('still tolerates a container issue with no nested list', () => {
+        expect(zodIssuesToFields([{ code: 'invalid_key', path: ['m', 'k'], message: 'Invalid key in record' }]))
+            .toEqual([{ field: 'm.k', code: 'invalid_shape', message: 'Invalid key in record' }]);
+        expect(zodIssuesToFields([{ code: 'invalid_element', path: ['m'], message: 'Invalid value', issues: 'nope' }]))
+            .toEqual([{ field: 'm', code: 'invalid_shape', message: 'Invalid value' }]);
+    });
+});

packages/spec/api-surface/ui.json

@@ -329,6 +329,8 @@
     "VIEW_CONSOLE_ROW_DECORATIONS (const)",
     "VIEW_FILTER_OPERATORS (const)",
     "VIEW_FILTER_OPERATOR_ALIASES (const)",
+    "VIEW_METADATA_BRANCHES (const)",
+    "VIEW_METADATA_MEMBERS (const)",
     "VIEW_WRITE_PATH_IDENTITY_KEYS (const)",
     "View (type)",
     "ViewData (type)",
@@ -348,6 +350,8 @@
     "ViewKind (type)",
     "ViewKindSchema (const)",
     "ViewMetadata (type)",
+    "ViewMetadataBranch (type)",
+    "ViewMetadataDiagnosis (type)",
     "ViewMetadataParsed (type)",
     "ViewMetadataSchema (const)",
     "ViewParsed (type)",
@@ -382,6 +386,7 @@
     "defineTheme (function)",
     "defineView (function)",
     "defineViewItem (function)",
+    "diagnoseViewMetadata (function)",
     "expandViewContainer (function)",
     "expandViewContainerWithDiagnostics (function)",
     "isAggregatedViewContainer (function)",
@@ -393,6 +398,7 @@
     "reportForm (const)",
     "reportSelectionOrder (function)",
     "resolveI18nLabel (function)",
+    "selectViewMetadataBranch (function)",
     "stripViewConsoleDecorations (function)",
     "validateActionParams (function)",
     "viewForm (const)"