docs(spec): record which calendar axis the #13817 guard gates — and which door carries the other (#17447)

* test(spec): pin the `type: 'calendar'` axis the #13817 guard does not gate

The #13817 cross-field check gates one axis — `appearance.allowedVisualizations`
includes 'calendar'. A view can also ask for a calendar by BEING one
(`type: 'calendar'`), and that axis parses CLEAN at all three doors. The
disposition was undocumented and so unreadable as a decision.

Measured at every door before writing a line: the axis is not unwatched, it is
carried by `checkViewCompleteness`'s VIEW_BINDING_BLOCKS at WARNING severity,
under the ADR-0078 §1 rubric the `page` note already cites. The two doors have
complementary coverage — the completeness check reads `type` only, the schema
check reads `allowedVisualizations` only.

Behaviour unchanged. Escalating the `type:` axis to a parse refusal would
refuse a shape 17.3.0 accepts, so it is a published-surface narrowing and a
separate ruling — the same disposition the `timeline` scope pin states.

Also pins that `viewType` is not a second spelling of `type`: refused as an
unknown key at the two authoring doors, and DROPPED at the `.strip()`ed overlay
write door, leaving the defaulted `type: 'grid'`.

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

* docs(changeset): the list-view calendar guard's axis scope (#16577)

`view.zod.ts` ships in `files[]` twice — as `src/**/*.zod.ts` and as the TSDoc
carried into `dist/*.d.ts` — so a docblock-only edit moves published bytes and
is not `skip-changeset`. Measured: the added prose greps in both
`dist/view.zod-*.d.ts` and `.d.mts`, positive control from the same docblock
hits the same two files, dark control zero.

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

---------

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

Author: os-bill

.changeset/listview-calendar-type-axis-scope-16577.md

@@ -0,0 +1,16 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): record which axis the list-view calendar guard gates — and which it does not (#16577)
+
+`checkListViewCalendarVisualization` gates ONE way of asking for a calendar: `appearance.allowedVisualizations` includes `'calendar'`. A view can also ask for one by BEING one — `type: 'calendar'` — and that axis parses CLEAN at all three doors (`ListViewSchema`, `ObjectListViewSchema`, `VIEW_METADATA_MEMBERS.listOverlay`). The disposition was correct but undocumented, so it read as an oversight rather than a decision.
+
+**No behaviour changes.** Every parse verdict at every door is byte-identical before and after; the diff is a TSDoc block on the exported check (which ships in `dist/*.d.ts` and in `src/**/*.zod.ts`) plus pins in `view.test.ts`.
+
+What the docblock now records, all of it measured rather than inferred:
+
+- The `type:` axis is **not unwatched**. It is carried by `checkViewCompleteness`'s `VIEW_BINDING_BLOCKS` (`kernel/functional-completeness.ts`) at **warning** severity, under the same ADR-0078 §1 rubric this file's `page` note already cites — refuse what renders NOTHING, warn what degrades. The two doors have complementary coverage: the completeness check reads `type` only and is blind to `allowedVisualizations`; this check reads `allowedVisualizations` only and is blind to `type`.
+- `viewType` is **not** a second spelling of `type`. The two authoring doors refuse it as an unknown key; the `.strip()`ed overlay write door (`PUT /api/v1/meta/view`) DROPS it, so the view parses as the defaulted `type: 'grid'` — an author who spells it reaches a grid, never a calendar.
+
+⛔ Escalating the `type:` axis to a parse refusal is deliberately NOT done here: it would refuse a shape 17.3.0 accepts, which is a published-surface narrowing and belongs to a ruling — the same disposition the `timeline` scope pin has stated since #13817.

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

@@ -52,6 +52,11 @@ import {
   originFileOf,
   originOf,
 } from '../../scripts/lib/export-origins-testkit';
+
+// [#16577] The door that carries the `type: '<layout>'` axis these view
+// schemas deliberately leave open — imported so the two-door split is asserted
+// from the side that can see both.
+import { checkViewCompleteness } from '../kernel/functional-completeness';
 describe('HttpMethodSubsetSchema', () => {
   it('should accept valid HTTP methods', () => {
     const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const;
@@ -3870,16 +3875,24 @@ describe("ListViewSchema — the `page` view type (#13216)", () => {
 // requires `calendar.startDateField` (ruled on #13748, option A; spec half)
 // ============================================================================
 
-describe("ListViewSchema — calendar in `appearance.allowedVisualizations` requires the `calendar:` block (#13817)", () => {
-  /** Walk `invalid_union` wrappers and return every issue, nested arms included. */
-  const flattenUnionIssues = (issues: z.ZodIssue[]): z.ZodIssue[] =>
-    issues.flatMap((i) => {
-      const nested = (i as unknown as { errors?: z.ZodIssue[][] }).errors;
-      return i.code === 'invalid_union' && Array.isArray(nested)
-        ? [i, ...flattenUnionIssues(nested.flat())]
-        : [i];
-    });
+/**
+ * Walk `invalid_union` wrappers and return every issue, nested arms included.
+ *
+ * Module-scoped (#16577) because two blocks need it: the #13817 refusals below
+ * and the `type: 'calendar'` scope pins further down. At the overlay door the
+ * union wraps a SHAPE failure in `invalid_union` with the per-arm truth nested
+ * one level down, so a search that reads only the top level finds nothing and
+ * reports it as "no such issue" rather than "issue is one level down".
+ */
+const flattenUnionIssues = (issues: z.ZodIssue[]): z.ZodIssue[] =>
+  issues.flatMap((i) => {
+    const nested = (i as unknown as { errors?: z.ZodIssue[][] }).errors;
+    return i.code === 'invalid_union' && Array.isArray(nested)
+      ? [i, ...flattenUnionIssues(nested.flat())]
+      : [i];
+  });
 
+describe("ListViewSchema — calendar in `appearance.allowedVisualizations` requires the `calendar:` block (#13817)", () => {
   // The same three doors the page-mount check runs at — the check is attached
   // at three separate points for the same zod-4 reason, and a missing
   // re-attachment is invisible (the door keeps accepting, which reads as "no
@@ -3956,3 +3969,112 @@ describe("ListViewSchema — calendar in `appearance.allowedVisualizations` requ
     expect(r.success).toBe(true);
   });
 });
+
+// ============================================================================
+// [#16577] The OTHER route to a calendar — `type: 'calendar'`. SCOPE PIN.
+//
+// #13817 gates ONE axis: `appearance.allowedVisualizations` includes
+// `'calendar'`. A view can also ask for a calendar by BEING one —
+// `type: 'calendar'` — and that axis is deliberately NOT gated here. The
+// disposition was undocumented and therefore unreadable as a decision; these
+// pins make it one, exactly as the `timeline` scope pin above does for the
+// other visualizations.
+//
+// ## Measured, at every door, before this block was written
+//
+// | body                                         | 3 schema doors | `checkViewCompleteness` |
+// |----------------------------------------------|----------------|-------------------------|
+// | `allowedVisualizations: ['calendar']`, no blk | REFUSED        | no finding              |
+// | `type: 'calendar'`, no `calendar:` block      | CLEAN          | **warning**             |
+//
+// So the axis is not unwatched — the two axes are carried by two doors with
+// complementary coverage, at two severities. The door that decides
+// `type: 'calendar'` is `checkViewCompleteness`'s `VIEW_BINDING_BLOCKS`
+// (`packages/spec/src/kernel/functional-completeness.ts`), which warns rather
+// than refuses under the ADR-0078 §1 rubric this file's `page` note already
+// cites: refuse what renders NOTHING, warn what degrades.
+//
+// ⛔ Whether that severity should be escalated for `calendar` is NOT ruled
+// here. #13748's own ruling says extensions of this guard are separate
+// findings to measure first, not riders — the same sentence the `timeline`
+// scope pin above records. Escalating would REFUSE a shape 17.3.0 accepts, so
+// it is a published-surface narrowing and belongs to a ruling, not to a pin.
+// ============================================================================
+
+describe("ListViewSchema — the `type: 'calendar'` axis is NOT gated by the #13817 check (#16577)", () => {
+  describe.each(viewDoorsCarryingPageMountCheck)('%s', (_label, parse) => {
+    it("ACCEPTS `type: 'calendar'` with no `calendar:` block — the axis #13817 does not gate", () => {
+      const r = parse({ type: 'calendar', columns: ['name'] });
+      expect(r.success, r.success === false ? JSON.stringify((r as unknown as { error: z.ZodError }).error.issues) : '').toBe(true);
+    });
+
+    // The asymmetry is the BLOCK schema's, not the guard's: writing the block
+    // is what makes `startDateField` required. Omitting the block skips that
+    // schema entirely, which is why the two rows above differ.
+    it("REFUSES `type: 'calendar'` + `calendar: {}` at `calendar.startDateField` — CalendarConfigSchema's own required key", () => {
+      const r = parse({ type: 'calendar', columns: ['name'], calendar: {} });
+      expect(r.success).toBe(false);
+      const flat = flattenUnionIssues((r as { error: z.ZodError }).error.issues);
+      const issue = flat.find((i) => i.path.join('.').endsWith('calendar.startDateField'));
+      expect(issue, JSON.stringify((r as { error: z.ZodError }).error.issues)).toBeDefined();
+    });
+  });
+
+  // The door that DOES carry this axis, named here so the split above is
+  // readable from either side. A change of severity there fails this pin.
+  it('is carried by `checkViewCompleteness` instead — at WARNING severity', () => {
+    const findings = checkViewCompleteness({ type: 'calendar', columns: ['name'] });
+    expect(findings).toHaveLength(1);
+    expect(findings[0]!.severity).toBe('warning');
+    expect(findings[0]!.path).toBe('calendar');
+  });
+
+  // The complement, and the reason neither door is redundant: the completeness
+  // check reads `type` only, so the axis #13817 gates is invisible to it.
+  it('and `checkViewCompleteness` does NOT see the allowedVisualizations axis', () => {
+    expect(checkViewCompleteness({
+      type: 'grid',
+      columns: ['name'],
+      appearance: { allowedVisualizations: ['grid', 'calendar'] },
+    })).toEqual([]);
+  });
+});
+
+// ============================================================================
+// [#16577] `viewType` is NOT a second spelling of `type` — measured, pinned.
+//
+// The finding that opened #16577 cited `viewType: 'calendar'` as a second way
+// in. At the spec's doors it is not one, and the two authoring doors and the
+// runtime write door disagree about HOW it fails — which is the part worth
+// pinning, because one of the two is a silent downgrade.
+// ============================================================================
+
+describe('ListViewSchema — `viewType` is not a spelling of `type` (#16577)', () => {
+  it('is an UNKNOWN key at the two authoring doors — refused, not aliased', () => {
+    for (const [label, parse] of [
+      ['ListViewSchema', (b: Record<string, unknown>) => ListViewSchema.safeParse(b)],
+      ['ObjectListViewSchema', (b: Record<string, unknown>) => ObjectListViewSchema.safeParse(b)],
+    ] as const) {
+      const r = parse({ viewType: 'calendar', columns: ['name'] });
+      expect(r.success, label).toBe(false);
+      const issue = (r as { error: z.ZodError }).error.issues.find((i) => i.code === 'unrecognized_keys');
+      expect(issue, `${label}: ${JSON.stringify((r as { error: z.ZodError }).error.issues)}`).toBeDefined();
+    }
+  });
+
+  // ⚠️ The overlay door is `PUT /api/v1/meta/view` — the only door a Studio
+  // tenant or an MCP/AI author has — and it is `.strip()`ed by design (it
+  // carries Studio's round-trip keys). So `viewType` is DROPPED there and the
+  // view parses as the defaulted `type: 'grid'`: an author who spells the
+  // retired alias gets a 200 and a grid, never a calendar. Pinned because the
+  // finding assumed the opposite, and because accepted-and-ignored is the
+  // failure mode this file's `VIEW_HISTORY` exists to record.
+  it("is STRIPPED at the overlay write door, leaving the defaulted `type: 'grid'`", () => {
+    const r = VIEW_METADATA_MEMBERS.listOverlay.safeParse({
+      object: 'crm_lead', viewKind: 'list', viewType: 'calendar', columns: ['name'],
+    });
+    expect(r.success).toBe(true);
+    expect((r as { data: Record<string, unknown> }).data).not.toHaveProperty('viewType');
+    expect((r as { data: { type?: unknown } }).data.type).toBe('grid');
+  });
+});

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

@@ -1746,6 +1746,27 @@ const VIEW_CALENDAR_ALLOWED_NEEDS_START_DATE =
  * another visualization has the same shape is a separate finding to measure
  * first, not a rider here (the #13748 ruling says so in those words).
  *
+ * ⚠️ [#16577] Scope, the OTHER axis: this check reads
+ * `appearance.allowedVisualizations` and NOT `type`. A view that asks for a
+ * calendar by BEING one — `type: 'calendar'` with no `calendar:` block —
+ * parses CLEAN at all three doors, measured. That is not an unwatched shape:
+ * it is the axis `checkViewCompleteness`'s `VIEW_BINDING_BLOCKS`
+ * (`../kernel/functional-completeness.ts`) carries, at WARNING, under the same
+ * ADR-0078 §1 rubric the `page` note above cites — refuse what renders
+ * NOTHING, warn what degrades. The two axes are covered by two doors with
+ * complementary coverage: the completeness check reads `type` only and is
+ * blind to `allowedVisualizations`, this check reads `allowedVisualizations`
+ * only and is blind to `type`. ⛔ Escalating the `type` axis to a refusal is
+ * NOT ruled: it would refuse a shape 17.3.0 accepts, so it is a
+ * published-surface narrowing and a separate finding — the same disposition
+ * the `timeline` sentence above states. Both halves are pinned in
+ * `view.test.ts`, so a change to either is a deliberate edit.
+ *
+ * ⚠️ [#16577] `viewType` is NOT a second spelling of `type` at any of these
+ * doors: the two authoring doors refuse it as an unknown key, and the
+ * `.strip()`ed overlay door DROPS it, so the view parses as the defaulted
+ * `type: 'grid'` — an author who spells it reaches a grid, never a calendar.
+ *
  * Attached with `.superRefine` at the same three doors as
  * {@link checkListViewPageMount}, for the same zod-4 reason (refinements block
  * `.omit()`/key-overwriting `.extend()`, so derived shapes re-attach): the