fix(spec): declare ViewMetadata as the union of its members' input types, not unknown

ViewMetadata was z.input of ViewMetadataSchema, a z.preprocess whose input
type is unknown, so the published name type-checked any value. It is now
read off VIEW_METADATA_MEMBERS, the members the schema's union runs. The
runtime schema is unchanged.

A type-level pin (view-metadata-type.test.ts) refuses unknown, a key no
member declares and a non-object, and types one body per member that the
door accepts through that member. The metadata serializer's comment that
documented the unknown now states why view stays unannotated.

Claude-Session: https://claude.ai/code/session_013RDBh5DqXd2xnLwvHLgLFr
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/metadata/src/serializers/typescript-serializer-annotation.test.ts

@@ -12,7 +12,7 @@
  *  - a spec-valid body must type-check with no diagnostic at all;
  *  - the same body plus one undeclared key must fail with exactly TS2353. That
  *    is what makes the annotation a check: a spec type that is `unknown` (as
- *    `ViewMetadata` is) would pass the first file and the second.
+ *    `ViewMetadata` once was) would pass the first file and the second.
  *
  * `@objectstack/spec` is resolved the way a consumer of a saved file resolves
  * it, through this package's `node_modules` and the `exports` map's `types`,

packages/metadata/src/serializers/typescript-serializer.ts

@@ -27,9 +27,13 @@ import { sortObjectKeys } from './sort-object-keys.js';
  * `unknown` or another type's shape.
  *
  * Two metadata types are deliberately absent:
- * - `view`: `ViewMetadataSchema` is a `z.preprocess`, so its input type, and
- *   with it `ViewMetadata`, is `unknown`. Annotating with it would check
- *   nothing.
+ * - `view`: `ViewMetadataSchema` is a `z.preprocess`, so its input type is
+ *   `unknown`. `ViewMetadata` is declared instead as the union of the input
+ *   types of the members the schema's union runs, so it is not the bound
+ *   schema's `z.input` and this table's rule excludes it. The rule holds for a
+ *   reason here: the view door accepts bodies `ViewMetadata` refuses (the
+ *   preprocess removes the console's row `id`s before any member judges the
+ *   body), so annotating a saved view with it could be false.
  * - `book`: `Book` is written by hand and lacks the `_packageId` /
  *   `_provenance` protection keys `BookSchema` accepts, so a book the loader
  *   has stamped would fail against it.

packages/spec/src/ui/view-metadata-type.test.ts

@@ -0,0 +1,81 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#19871] The published type `ViewMetadata` names a `view` body; it is not `unknown`.
+ *
+ * `ViewMetadataSchema` is a `z.preprocess`, whose input type is `unknown`, so the type declared as
+ * `z.input<typeof ViewMetadataSchema>` WAS `unknown`: any value type-checked against a name and a
+ * TSDoc that promise a persisted view body. It is now the union of the input types of
+ * `VIEW_METADATA_MEMBERS`, the members the schema's union runs.
+ *
+ * Two halves, judged by two programs:
+ *
+ * - The TYPE half is judged by `tsc -p tsconfig.test.json` (the package's `typecheck` script, via
+ *   `check:test-typecheck`), not by vitest. Each `@ts-expect-error` below asserts that its line
+ *   does NOT compile. While `ViewMetadata` was `unknown` every one of them compiled, so each
+ *   directive was unused: TS2578 in a file with no `test-typecheck-debt.json` entry, which reds the
+ *   gate. The member bodies are typed through the published name, so a later narrowing that drops
+ *   a member is a compile error on its line.
+ * - The RUNTIME half ties those typed bodies to the door: each one parses, through the member it
+ *   is written for, so the fixture really covers every member.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  VIEW_METADATA_BRANCHES,
+  diagnoseViewMetadata,
+  type ViewMetadata,
+  type ViewMetadataBranch,
+} from './view.zod';
+
+// ── One body per member, each typed through the published name ────────────────────────────────
+
+const viewItem: ViewMetadata = {
+  name: 'crm_lead.all',
+  object: 'crm_lead',
+  viewKind: 'list',
+  config: { type: 'grid', data: { provider: 'object', object: 'crm_lead' }, columns: ['name'] },
+};
+const container: ViewMetadata = {
+  object: 'crm_lead',
+  list: { type: 'grid', data: { provider: 'object', object: 'crm_lead' }, columns: ['name'] },
+};
+const listOverlay: ViewMetadata = { type: 'grid', columns: ['name'], object: 'crm_lead', viewKind: 'list' };
+const formOverlay: ViewMetadata = {
+  type: 'simple',
+  sections: [{ label: 'Main', fields: ['name'] }],
+  object: 'crm_lead',
+  viewKind: 'form',
+};
+
+const BODY_OF_EACH_MEMBER: Record<ViewMetadataBranch, ViewMetadata> = {
+  viewItem,
+  container,
+  listOverlay,
+  formOverlay,
+};
+
+// ── What `ViewMetadata` refuses at compile time ──────────────────────────────────────────────
+
+const someValue: unknown = JSON.parse('{"nope":1}');
+// @ts-expect-error -- `unknown` is not a view body; it was assignable while ViewMetadata was `unknown`.
+const fromUnknown: ViewMetadata = someValue;
+// @ts-expect-error -- `notAViewKey` is declared by no member (TS2353).
+const undeclaredKey: ViewMetadata = { type: 'grid', columns: ['name'], object: 'crm_lead', viewKind: 'list', notAViewKey: 1 };
+// @ts-expect-error -- a view body is an object.
+const scalar: ViewMetadata = 42;
+void [fromUnknown, undeclaredKey, scalar];
+
+describe('[#19871] ViewMetadata is a view body, not unknown', () => {
+  it('has a typed body for every member of the union', () => {
+    expect(Object.keys(BODY_OF_EACH_MEMBER).sort()).toEqual([...VIEW_METADATA_BRANCHES].sort());
+  });
+
+  for (const branch of VIEW_METADATA_BRANCHES) {
+    it(`the ${branch} body typed as ViewMetadata parses, through the ${branch} member`, () => {
+      const diagnosis = diagnoseViewMetadata(BODY_OF_EACH_MEMBER[branch]);
+      expect(diagnosis.success).toBe(true);
+      expect(diagnosis.branch).toBe(branch);
+    });
+  }
+});

packages/spec/src/ui/view.zod.ts

@@ -6306,8 +6306,25 @@ export type ViewParsed = z.infer<typeof ViewSchema>;
 export type ViewItem = z.input<typeof ViewItemSchema>;
 /** A ViewItem record as it travels the WIRE — the authoring shape plus Studio's round-trip keys (#5074). */
 export type ViewItemWire = z.input<typeof ViewItemWireSchema>;
-/** Any persisted `view` metadata body: container | ViewItem record | flattened overlay (#3095). */
-export type ViewMetadata = z.input<typeof ViewMetadataSchema>;
+/**
+ * Any persisted `view` metadata body: container | ViewItem record | flattened overlay (#3095) —
+ * the union of the INPUT types of the members {@link ViewMetadataSchema}'s union runs, read off
+ * {@link VIEW_METADATA_MEMBERS} (the union's member list by construction).
+ *
+ * [#19871] Deliberately NOT `z.input<typeof ViewMetadataSchema>`. That schema is a `z.preprocess`,
+ * whose input type is `unknown`, and its union's members are cast to `z.ZodTypeAny` where the
+ * union is built — so every type derived from the schema itself is `unknown`, and this name used to
+ * type-check any body at all. `view-metadata-type.test.ts` pins that `unknown` and an undeclared
+ * key are refused here, and that a body of each member still type-checks.
+ *
+ * A static type, not the door's verdict, in both directions: the door accepts bodies this type
+ * refuses (the preprocess removes the console's row `id`s, and three members strip undeclared
+ * top-level keys), and refuses bodies it admits — the identity precondition, the members'
+ * refinements, and a body that mixes keys of different members, because TypeScript checks an
+ * object literal's keys against the union as a whole and the container member's keys are all
+ * optional. `ViewMetadataSchema` remains the only judge.
+ */
+export type ViewMetadata = z.input<(typeof VIEW_METADATA_MEMBERS)[ViewMetadataBranch]>;
 /** Post-parse shape of {@link ViewMetadata} — defaults applied, transforms run (ADR-0122). */
 export type ViewMetadataParsed = z.infer<typeof ViewMetadataSchema>;
 export type ViewScope = z.input<typeof ViewScopeSchema>;