fix(spec): a flattened list overlay's type and columns carry the list shape's types

listOverlayPatchFields() read `type` and `columns` off ListViewShapeSchema
through a cast of its shape to a record of z.ZodTypeAny, which typed both
keys `unknown` on the list overlay member. So `{ object, viewKind: 'list',
columns: 42 }` type-checked as ViewMetadata, ViewMetadataParsed,
AssembledViewArtifact and AssembledViewArtifactParsed while that member
refuses it. The shape is now read as typed; the schemas are the same
objects, so no parse moves.

The item-4 TSDoc sentences on ViewMetadataParsed and
AssembledViewArtifactParsed no longer say the two keys are `unknown`, and
the pin that held them `unknown` is replaced by pins that they are typed,
with four refused-body probes and a runtime half. The changeset names the
fourth narrowing.

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

Author: claude

.changeset/19920-exported-types-remainder.md

@@ -2,19 +2,20 @@
 '@objectstack/spec': minor
 ---
 
-fix(spec): `JoinedReportBlock`, a ViewItem's `config` and a flattened overlay's `viewKind` carry the shapes their doors accept (#19920)
+fix(spec): `JoinedReportBlock`, a ViewItem's `config`, a flattened overlay's `viewKind` and a flattened list overlay's `type` / `columns` carry the shapes their doors accept (#19920)
 
 Clause-②: yes (narrowing)
 
 **BREAKING for TypeScript code that annotates with `JoinedReportBlock`, `Report`, `ReportParsed`, `ViewItem`, `ViewItemWire`, `ViewMetadata`, `ViewMetadataParsed`, `AssembledViewArtifact` or `AssembledViewArtifactParsed`, or that passes an unchecked value to `defineReport` / `defineViewItem`**: a narrowing of published TYPES, 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: no schema's parse, no value and no existing export changes. Three parsed-state type names are added (below); nothing is removed or renamed.
 
-Three places in the published types were wider than the doors that judge the same bodies, so values those doors refuse type-checked:
+Four places in the published types were wider than the doors that judge the same bodies, so values those doors refuse type-checked:
 
 - `JoinedReportBlock`: FROM `unknown` TO the input shape of `JoinedReportBlockSchema`. The schema was annotated `z.ZodTypeAny`, which erased its shape; it now carries its inferred type. The same erasure made every `blocks[]` element of `Report` / `ReportParsed` (and so of `defineReport`'s parameter) `unknown`; each is now a block.
 - A ViewItem's `config`: FROM `unknown` TO the arm's own config type, a `ListView` config on the `list` arm and a `FormView` config on the `form` arm. This holds on `ViewItem`, `ViewItemWire`, `defineViewItem`'s parameter and return, and the `viewItem` member of `ViewMetadata`, `ViewMetadataParsed`, `AssembledViewArtifact` and `AssembledViewArtifactParsed`. The arm builder took `config` as `z.ZodTypeAny`; it is now a generic parameter.
 - A flattened overlay member's `viewKind`: FROM `'list' | 'form'` on both members TO `'list'` on the list overlay and `'form'` on the form overlay, the one value each member accepts. A list-shaped body naming `viewKind: 'form'` used to type-check, through the list overlay member, as `ViewMetadata`, `ViewMetadataParsed`, `AssembledViewArtifact` and `AssembledViewArtifactParsed`.
+- A flattened list overlay's `type` and `columns`: FROM `unknown` TO the list view's own types, both optional: `type` one of the list view types, `columns` a field list. This holds on the list overlay member of `ViewMetadata`, `ViewMetadataParsed`, `AssembledViewArtifact` and `AssembledViewArtifactParsed`. The member read both keys off the list view shape through a cast that erased them, so `{ object, viewKind: 'list', columns: 42 }` type-checked as all four while that member refuses it.
 
-**If your code stops compiling.** A value you annotated with one of these names, or passed to `defineReport` / `defineViewItem`, is not the shape the door accepts: correct it, or type a value that is still unvalidated as `unknown` and let the schema's `safeParse` decide. A ViewItem's `config` must match its `viewKind`: a `ListView` config under `viewKind: 'list'`, a `FormView` config under `viewKind: 'form'`.
+**If your code stops compiling.** A value you annotated with one of these names, or passed to `defineReport` / `defineViewItem`, is not the shape the door accepts: correct it, or type a value that is still unvalidated as `unknown` and let the schema's `safeParse` decide. A ViewItem's `config` must match its `viewKind`: a `ListView` config under `viewKind: 'list'`, a `FormView` config under `viewKind: 'form'`. A flattened list overlay's `columns` is a field list and its `type` one of the list view types.
 
 The declared types of `JoinedReportBlockSchema`, `ViewItemSchema` and `ViewItemWireSchema` narrow with them, so `z.input` / `z.infer` of each is typed where it was `unknown` (or carried an `unknown` `config`). Typed, each schema's input and output now differ by its defaults, so three ADR-0122 parsed-state aliases are added beside the bare names: `JoinedReportBlockParsed`, `ViewItemParsed` and `ViewItemWireParsed`. Nothing is removed or renamed.
 

packages/spec/src/ui/assembled-views.zod.ts

@@ -122,9 +122,9 @@ export type AssembledViewArtifact = z.input<(typeof VIEW_METADATA_MEMBERS)[Exclu
  * [#19920] One default is applied by the parse but absent from this type, the one
  * `ViewMetadataParsed` (`view.zod.ts`) names: the flattened list overlay member declares `type`
  * without the list shape's `.default('grid')` and re-applies it in an `.overwrite()`, which
- * returns the member's own output type. So on that member `type` stays optional here (and, like
- * its `columns`, typed `unknown`), while every body it parses comes back with `type` set:
- * `'grid'` when the body named none.
+ * returns the member's own output type. So on that member `type` stays optional here (typed as
+ * the list shape's `type` enum), while every body it parses comes back with `type` set: `'grid'`
+ * when the body named none.
  */
 export type AssembledViewArtifactParsed = z.infer<(typeof VIEW_METADATA_MEMBERS)[Exclude<ViewMetadataBranch, 'container'>]>;
 

packages/spec/src/ui/view-overlay-viewkind-type.test.ts

@@ -2,8 +2,9 @@
 
 /**
  * [#19920] Each flattened overlay member's static `viewKind` is its own arm's literal: `'list'` on
- * the list overlay, `'form'` on the form overlay. And the list overlay's `type` default, which the
- * parse applies and the output type does not carry, is what the `ViewMetadataParsed` /
+ * the list overlay, `'form'` on the form overlay. The list overlay's `type` and `columns` carry the
+ * list shape's own types, not `unknown`. And the list overlay's `type` default, which the parse
+ * applies and the output type does not carry, is what the `ViewMetadataParsed` /
  * `AssembledViewArtifactParsed` TSDoc says it is.
  *
  * `flattenedViewOverlayFields(kind)` took `kind: 'list' | 'form'`, so `z.enum([kind])` widened to
@@ -12,6 +13,11 @@
  * `AssembledViewArtifactParsed`, while both doors refuse it (the list member: the arm mismatch; the
  * form member: `type` and `columns`). The function is now generic, so each member keeps its literal.
  *
+ * `listOverlayPatchFields()` read the list overlay's `type` and `columns` off the list shape
+ * through a cast to a record of `z.ZodTypeAny`, which typed both `unknown` on that member:
+ * `{ object, viewKind: 'list', columns: 42 }` type-checked as the same four union types while the
+ * list member refuses it. It now reads the shape as typed.
+ *
  * Two halves, judged by two programs (the `view-metadata-type.test.ts` shape):
  *
  * - The TYPE half is judged by `tsc -p tsconfig.test.json` (the package's `typecheck` script, via
@@ -70,17 +76,38 @@ const parsedMetadata: ViewMetadataParsed = { type: 'grid', columns: ['name'], ob
 void [listKindIn, listKindOut, formKindIn, formKindOut, listKindInForm, listKindOutForm, formKindInList, formKindOutList];
 void [artifact, parsedArtifact, metadata, parsedMetadata];
 
+// ── The list overlay's `type` and `columns` carry the list shape's types ─────────────────────
+
+type IsUnknown<T> = unknown extends T ? true : false;
+const typeAndColumnsAreTypedThere: [
+  IsUnknown<ListOverlayIn['type']>, IsUnknown<ListOverlayIn['columns']>,
+  IsUnknown<ListOverlayOut['type']>, IsUnknown<ListOverlayOut['columns']>,
+] = [false, false, false, false];
+const listOverlayPatchWithType: ListOverlayIn = { object: 'crm_lead', viewKind: 'list', type: 'kanban', columns: ['name'] };
+// @ts-expect-error -- the list overlay's `columns` is a field list, not a number.
+const listOverlayColumnsNumber: ListOverlayIn['columns'] = 42;
+// @ts-expect-error -- its `type` is the list shape's enum.
+const listOverlayTypeUnknown: ListOverlayIn['type'] = 'spreadsheet';
+// @ts-expect-error -- a list overlay whose `columns` is a number is no view artifact.
+const numericColumnsArtifact: AssembledViewArtifact = { object: 'crm_lead', viewKind: 'list', columns: 42 };
+// @ts-expect-error -- nor a parsed one.
+const numericColumnsParsedArtifact: AssembledViewArtifactParsed = { object: 'crm_lead', viewKind: 'list', columns: 42 };
+// @ts-expect-error -- nor a view body.
+const numericColumnsMetadata: ViewMetadata = { object: 'crm_lead', viewKind: 'list', columns: 42 };
+// @ts-expect-error -- nor a parsed one.
+const numericColumnsParsedMetadata: ViewMetadataParsed = { object: 'crm_lead', viewKind: 'list', columns: 42 };
+void [typeAndColumnsAreTypedThere, listOverlayPatchWithType, listOverlayColumnsNumber, listOverlayTypeUnknown];
+void [numericColumnsArtifact, numericColumnsParsedArtifact, numericColumnsMetadata, numericColumnsParsedMetadata];
+
 // ── The list overlay's `type` default: applied by the parse, absent from the output type ─────
 //
-// The TSDoc on `ViewMetadataParsed` / `AssembledViewArtifactParsed` says both things in words, and
-// these two lines compile only while each one holds. The day a change carries the `.overwrite()`
-// default into the output type, or types the member's `type` / `columns`, a line stops compiling
-// and the TSDoc sentences are then false: correct them with it.
+// The TSDoc on `ViewMetadataParsed` / `AssembledViewArtifactParsed` says this in words, and this
+// line compiles only while it holds. The day a change carries the `.overwrite()` default into the
+// output type, the line stops compiling and the TSDoc sentences are then false: correct them with
+// it.
 type IsOptionalKey<T, K extends keyof T> = {} extends Pick<T, K> ? true : false;
-type IsUnknown<T> = unknown extends T ? true : false;
 const typeIsOptionalOnListOverlayOutput: IsOptionalKey<ListOverlayOut, 'type'> = true;
-const typeAndColumnsAreUnknownThere: [IsUnknown<ListOverlayOut['type']>, IsUnknown<ListOverlayOut['columns']>] = [true, true];
-void [typeIsOptionalOnListOverlayOutput, typeAndColumnsAreUnknownThere];
+void [typeIsOptionalOnListOverlayOutput];
 
 describe('[#19920] the flattened overlay members keep their own viewKind literal', () => {
   it('the list-shaped `viewKind: "form"` body is refused by every door that judges it', () => {
@@ -91,6 +118,13 @@ describe('[#19920] the flattened overlay members keep their own viewKind literal
     expect(AssembledViewArtifactSchema.safeParse(body).success).toBe(false);
   });
 
+  it('a list overlay whose `columns` is a number is refused by every door that judges it', () => {
+    const body = { object: 'crm_lead', viewKind: 'list', columns: 42 };
+    expect(VIEW_METADATA_MEMBERS.listOverlay.safeParse(body).success).toBe(false);
+    expect(ViewMetadataSchema.safeParse(body).success).toBe(false);
+    expect(AssembledViewArtifactSchema.safeParse(body).success).toBe(false);
+  });
+
   it("a column-less list patch parses with `type: 'grid'`, which its output type leaves optional", () => {
     const patch = { object: 'crm_lead', viewKind: 'list', sort: [{ field: 'name', order: 'asc' }] };
     for (const door of [VIEW_METADATA_MEMBERS.listOverlay, ViewMetadataSchema, AssembledViewArtifactSchema]) {

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

@@ -5779,13 +5779,17 @@ const FORM_OVERLAY_COLUMNS_IS_A_COUNT =
  * {@link assertViewIdentity} records for the union's own door.
  */
 function listOverlayPatchFields() {
-  const shape = (ListViewShapeSchema as unknown as { shape: Record<string, z.ZodTypeAny> }).shape;
-  const type = shape.type as unknown as z.ZodDefault<z.ZodTypeAny>;
+  // [#19920] Read off the shape as typed, not through a cast to a record of
+  // `z.ZodTypeAny`: that cast erased both keys to `unknown` on this member, so
+  // `{ object, viewKind: 'list', columns: 42 }` type-checked as every union
+  // type read off {@link VIEW_METADATA_MEMBERS} while this member refuses it.
+  // The schemas are the same objects either way; only their static types move.
+  const shape = ListViewShapeSchema.shape;
   return {
-    columns: shape.columns!.optional(),
+    columns: shape.columns.optional(),
     // `.meta({ default })` keeps the served JSON Schema's `default: 'grid'`
     // byte-identical: the default is real, applied by the overwrite below.
-    type: type.unwrap().optional().meta({ default: LIST_OVERLAY_DEFAULT_TYPE }),
+    type: shape.type.unwrap().optional().meta({ default: LIST_OVERLAY_DEFAULT_TYPE }),
   };
 }
 
@@ -6791,10 +6795,9 @@ export type ViewMetadata = z.input<(typeof VIEW_METADATA_MEMBERS)[ViewMetadataBr
  * overlay member (`VIEW_METADATA_MEMBERS.listOverlay`) declares `type` without the list shape's
  * `.default('grid')`, so its checks can tell a column-less patch from a full config, and
  * re-applies the default in `.overwrite(applyListOverlayTypeDefault)`. An `.overwrite()` returns
- * the member's own output type, so on that member `type` stays optional here, while every body
- * that member parses comes back with `type` set: `'grid'` when the body named none. On that
- * member `type` and `columns` are also typed `unknown`: `listOverlayPatchFields` reads both off
- * the list shape through an untyped cast.
+ * the member's own output type, so on that member `type` stays optional here (typed as the list
+ * shape's `type` enum), while every body that member parses comes back with `type` set: `'grid'`
+ * when the body named none.
  */
 export type ViewMetadataParsed = z.infer<(typeof VIEW_METADATA_MEMBERS)[ViewMetadataBranch]>;
 export type ViewScope = z.input<typeof ViewScopeSchema>;