@@ -0,0 +1,40 @@
+---
+'@objectstack/spec': minor
+---
+
+fix(spec): the published type `ViewMetadata` names a `view` body instead of being `unknown` (#19871)
+
+Clause-②: no (narrowing)
+
+**BREAKING for TypeScript code that annotates with `ViewMetadata`**: a narrowing of a published
+TYPE, landing in the launch window as `minor` (the lockstep convention: the bump level is not the
+carrier, this banner and the disposition below are). The runtime accept set does not move at all:
+`ViewMetadataSchema` is unchanged, and a 44-body parse probe answers byte-identically before and
+after.
+
+`ViewMetadata` was declared as `z.input<typeof ViewMetadataSchema>`. That schema is a
+`z.preprocess`, whose input type is `unknown`, so the name documented as "any persisted view
+metadata body: container | ViewItem record | flattened overlay" type-checked any value at all,
+including bodies the schema refuses. It is now the union of the input types of
+`VIEW_METADATA_MEMBERS`, the four members the schema's union runs, so `unknown`, a non-object and a
+key no member declares are compile errors, and a body of each member still type-checks.
+
+**What still differs from the runtime verdict.** The type is the members' declared shape, not the
+door's answer. The door still accepts bodies the type refuses (it removes the console's row `id`s
+and three members strip undeclared keys), and still refuses bodies the type admits (the identity
+precondition, the members' refinements, and a body mixing keys of different members, which
+TypeScript checks against the union as a whole). `ViewMetadataSchema.safeParse` remains the only
+judge.
+
+**If your code stops compiling.** A value you annotated as `ViewMetadata` is not one of the four
+member shapes. Correct the body, or type a value that is still unvalidated as `unknown` and let
+`ViewMetadataSchema.safeParse` decide.
+
+`ViewMetadataParsed` is not changed by this release: it is still `unknown`.
+
+The `@objectstack/metadata` changelog entry for #19852 gives `ViewMetadata` being `unknown` as the
+reason a saved `view` file is written with no annotation; that reason is superseded here, and the
+outcome stands for another one: `ViewMetadata` is no longer the `z.input` type of
+`ViewMetadataSchema`, the schema `getMetadataTypeSchema('view')` binds.
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing authorable is removed, renamed or re-typed at runtime: no spec key, no export, no stored row moves, and every view body parses byte-identically, so `objectstack migrate meta` has nothing to reach. The only thing that moved is a TypeScript annotation, whose channel is the consumer's compiler. `type-surface-only` does not apply because this diff touches `packages/spec/**` (its predicate 2). -->
@@ -74,7 +74,7 @@ Serializers convert metadata objects to/from different file formats:
 
 - **JSONSerializer** — `.json` files with optional key sorting
 - **YAMLSerializer** — `.yaml`/`.yml` files (JSON_SCHEMA for security)
-- **TypeScriptSerializer** — the `typescript` / `javascript` formats (`.ts` / `.js`): a JSON document wrapped in a module, the file format `FilesystemLoader` writes and reads for those two formats (`typescript` is `FilesystemLoader.save()`'s default, so `MetadataManager.save()` routed to the filesystem loader writes `{rootDir}/{type}/{name}.ts`). It writes `export const metadata = { …JSON… };` then `export default metadata;`. A `typescript`-format file that `FilesystemLoader.save()` writes with the built-in serializer the package wires in also annotates that constant with the spec type of the item's metadata type, and imports it: `ServiceObject` from `@objectstack/spec/data` for an `object`, `Flow` from `@objectstack/spec/automation` for a `flow`, and so on. Each is exactly the `z.input` type of the schema `getMetadataTypeSchema()` resolves for that metadata type. A metadata type with no such spec type is written with no annotation and no import: `view` (its `ViewMetadata` type is `unknown`), `book`, `external_catalog`, or a plugin's own type. Only the loader knows the metadata type, so it picks the annotation through a package-internal function, and `TypeScriptSerializer.serialize()` called directly writes no annotation. A serializer wired in by hand (a custom one, a subclass that overrides `serialize()`, or a `TypeScriptSerializer` from the package's other entry point) is called through its own `serialize()`. It reads back the first `{ … }` block after the first `export const` (or, failing that, `export default`), which must be JSON: double-quoted keys and strings, no comments, no trailing commas, no functions. It is **not** an authoring shape: authored metadata such as a `*.object.ts` is written `ObjectSchema.create({ … })` (or `defineView()`, …), which this serializer never emits, and an authored file with unquoted keys is refused rather than read.
+- **TypeScriptSerializer** — the `typescript` / `javascript` formats (`.ts` / `.js`): a JSON document wrapped in a module, the file format `FilesystemLoader` writes and reads for those two formats (`typescript` is `FilesystemLoader.save()`'s default, so `MetadataManager.save()` routed to the filesystem loader writes `{rootDir}/{type}/{name}.ts`). It writes `export const metadata = { …JSON… };` then `export default metadata;`. A `typescript`-format file that `FilesystemLoader.save()` writes with the built-in serializer the package wires in also annotates that constant with the spec type of the item's metadata type, and imports it: `ServiceObject` from `@objectstack/spec/data` for an `object`, `Flow` from `@objectstack/spec/automation` for a `flow`, and so on. Each is exactly the `z.input` type of the schema `getMetadataTypeSchema()` resolves for that metadata type. A metadata type with no such spec type is written with no annotation and no import: `view` (`ViewMetadataSchema` is a `z.preprocess`, whose `z.input` type is `unknown`; `ViewMetadata` is declared instead as the union of the input types of the members that schema's union runs, so it is not that schema's `z.input` type), `book`, `external_catalog`, or a plugin's own type. Only the loader knows the metadata type, so it picks the annotation through a package-internal function, and `TypeScriptSerializer.serialize()` called directly writes no annotation. A serializer wired in by hand (a custom one, a subclass that overrides `serialize()`, or a `TypeScriptSerializer` from the package's other entry point) is called through its own `serialize()`. It reads back the first `{ … }` block after the first `export const` (or, failing that, `export default`), which must be JSON: double-quoted keys and strings, no comments, no trailing commas, no functions. It is **not** an authoring shape: authored metadata such as a `*.object.ts` is written `ObjectSchema.create({ … })` (or `defineView()`, …), which this serializer never emits, and an authored file with unquoted keys is refused rather than read.
 
 ### 4. Overlay / Customization System
 
 
@@ -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`,
 
@@ -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.
 
@@ -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);
+    });
+  }
+});
@@ -6352,8 +6352,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>;
Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@`
`12`	`12`	`* - a spec-valid body must type-check with no diagnostic at all;`
`13`	`13`	`* - the same body plus one undeclared key must fail with exactly TS2353. That`
`14`	`14`	* is what makes the annotation a check: a spec type that is `unknown` (as
`15`		- * `ViewMetadata` is) would pass the first file and the second.
	`15`	+ * `ViewMetadata` once was) would pass the first file and the second.
`16`	`16`	`*`
`17`	`17`	* `@objectstack/spec` is resolved the way a consumer of a saved file resolves
`18`	`18`	* it, through this package's `node_modules` and the `exports` map's `types`,