view.zod.ts

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

/**
 * View protocol schemas — the `view` metadata type and its three persisted body spellings.
 *
 * Covers the authoring surfaces (`defineView`, `defineViewItem`), the wire
 * doors Studio and the REST layer write through, and
 * {@link ViewMetadataSchema} — the union every persisted `view` body is judged
 * by.
 *
 * ## Name grammar depends on the body spelling
 *
 * {@link ViewMetadataSchema} is a union over three persisted body shapes, and
 * they do not share one `name` grammar. Which grammar applies is decided by the
 * shape of the body — something an author never names explicitly — so neither
 * failure direction below is discoverable from the key being written:
 *
 * | body spelling | recognised by | `name` is declared as | flat (undotted) name |
 * |:---|:---|:---|:---|
 * | standalone **ViewItem record** | a nested `config` | {@link ViewItemNameSchema} — `QUALIFIED_ITEM_NAME_PATTERN`, dot REQUIRED | **rejected**, located at `["name"]` |
 * | flattened runtime **overlay** | an inline view config; no `config`, no container slot | `z.string().optional()` — no grammar at all | accepted |
 * | `defineView` **container** | a container slot (`list` / `form` / `listViews` / `formViews`) | `z.string().optional()` on {@link ViewSchema} — no grammar at all | accepted, and normally IS flat |
 *
 * The two permissive rows are deliberate, not gaps left to tighten later:
 *
 * - A container's own name is the **bare object key**. ADR-0017 §3.2's
 *   dual-read loader registers the aggregated container under `<object>` and
 *   each expanded item under `<object>.<viewKey>`, so an object-scoped
 *   container is named `crm_lead` — a name with no dot to carry.
 * - An overlay's name is **stamped by the write path**, not authored:
 *   `normalizeViewMetadata` puts it on every view body at the single write
 *   chokepoint, and a personalization PUT inherits the identity of the entry it
 *   shadows.
 *
 * So both of the readings an author naturally forms are wrong:
 *
 * - *"the dot is mandatory on every view row"* — read off
 *   {@link ViewItemNameSchema} alone. It is not: overlay and container rows
 *   accept flat names, and rows in this repo legitimately use them
 *   (`case_grid`, `cases`, the container row `crm_lead`). Those rows are
 *   correct as written, not defects awaiting a dotted rewrite.
 * - *"flat names are fine generally"* — read off one of those flat-named rows.
 *   It is not: put the same name on a standalone ViewItem record and it is
 *   refused, on the one field the flat-named row told you to fill.
 *
 * This describes what the three shapes already do; it widens and narrows
 * nothing. The one item-name grammar itself lives in
 * `shared/identifiers.zod.ts` — grammar changes belong there, not here.
 */

import { z } from 'zod';
import { ProtectionSchema } from '../shared/protection.zod';
import { MetadataProtectionFields } from '../kernel/metadata-protection.zod';
import { strictObject, strictObjectError } from '../shared/strict-object';
import { SnakeCaseIdentifierSchema, QUALIFIED_ITEM_NAME_PATTERN } from '../shared/identifiers.zod';
import { ExpressionInputSchema } from '../shared/expression.zod';
import { normalizeVisibleWhen, VISIBILITY_STRICT_OPTIONS } from '../shared/visibility';
import { SELECT_OPTION_EDITABILITY_GUIDANCE, VISIBILITY_ONLY_STRICT_OPTIONS } from '../shared/editability-boundary';
// [#13855] The section → field-group reference form, shared with the
// `record:details` section shape (component.zod.ts) so one mixing rule serves
// both layout escape hatches.
import { SectionGroupKeySchema, sectionGroupReferenceRefinement } from '../shared/section-group-reference';
import { I18nLabelSchema, AriaPropsSchema } from './i18n.zod';
import { ChartTypeSchema } from './chart.zod';
import { SharingConfigSchema } from './sharing.zod';
import { retiredKey } from '../shared/retired-key';
import { FieldType, SelectOptionSchema } from '../data/field.zod';
import { BulkActionDefSchema } from './bulk-action.zod';

/**
 * HTTP Method Enum & HTTP Request Schema
 * Migrated to shared/http.zod.ts. Re-exported here for backward compatibility.
 */
import { HttpMethodSubsetSchema, HttpRequestSchema } from '../shared/http.zod';
import { lazySchema } from '../shared/lazy-schema';

/**
 * Shared history for this file (#4001).
 *
 * Views are the surface an author iterates on visually, which is exactly why a
 * dropped key hides here: the view still renders, just not the way it was
 * described. `FormFieldBaseSchema` / `FormSectionSchema` / `FormButtonConfig`
 * were closed years ago (ADR-0089 D3a); the other forty-odd shapes in this file
 * kept the posture those three were rescued from.
 */
const VIEW_HISTORY =
  'Until these shapes were closed an unknown key was dropped silently — the view still '
  + 'rendered, without whatever the key was meant to configure.';

export { HttpMethodSubsetSchema, HttpRequestSchema };

/**
 * [#4688] `HttpRequest` is RE-EXPORTED from its one declaration in
 * `shared/http.zod.ts` — never re-inferred here.
 *
 * The line this replaces was `export type HttpRequest = z.infer< typeof
 * HttpRequestSchema >` in the alias block at the bottom of this file. It looked
 * single-source: it inferred from the very schema object imported above, so the
 * resolved shape was identical. But it was a SECOND type declaration carrying
 * one name, and symbol identity — not shape — is what
 * `check:dual-source-exports` measures, and what an auto-import or a model
 * completion resolves by. That is how `./shared` and `./ui` came to name two
 * different declarations `HttpRequest` (the #4411 trap). A re-export keeps every
 * existing `import type { HttpRequest } from '@objectstack/spec/ui'` working
 * while leaving exactly one declaration that could ever diverge.
 */
export type { HttpRequest } from '../shared/http.zod';

/**
 * [#4691, renamed at #5832] The type of `HttpMethodSubsetSchema` is
 * `HttpMethodSubset`, RE-EXPORTED from its one declaration in
 * `shared/http.zod.ts`.
 *
 * `./ui` used to export that same 5-value type under the name `HttpMethod`
 * (`export type HttpMethod = z.infer< typeof HttpMethodSchema >`, in the alias
 * block at the bottom of this file). That name is already taken across the
 * package by a DIFFERENT declaration — `shared/http.zod.ts`'s 7-value
 * `z.enum([… 'HEAD', 'OPTIONS'])`, exported by `./shared` and `./api` — so one
 * name resolved to two incompatible types depending on the import path (the
 * #4411 trap; the last row of `dual-source-exports.baseline.json`).
 *
 * Converging by re-exporting `./shared`'s `HttpMethod` here — the fix #4688
 * used for `HttpRequest` — would have been WRONG: it silently widens `./ui`'s
 * type from 5 values to 7 while `HttpRequestSchema.method` still validates
 * against the 5-value subset. `method: 'HEAD'` would type-check and then throw
 * at `.parse()` — the type would start lying about the runtime. So the NAME is
 * dropped from `./ui` instead, and the 5-value type carries a name of its own.
 *
 * #4691 spelled that name `HttpMethodType`, which was merely the name left
 * over once `HttpMethod` was taken. #5832 renamed the whole trio to
 * `HttpMethodSubsetSchema` / `HttpMethodSubset` / `<category>/HttpMethodSubset`
 * because the CONST still collided one layer down: `schemaNameFromExportKey`
 * strips the `Schema` suffix, so `HttpMethodSchema` published as
 * `shared/HttpMethod` and overwrote the 7-value enum's own def.
 *
 * Re-exported here (rather than only left in `./shared`) so the shortest fix
 * for `import type { HttpMethod } from '@objectstack/spec/ui'` is also the
 * CORRECT one: TypeScript's "did you mean" points at `HttpMethodSubset` in the
 * same entry point, instead of tempting a path swap to `./shared`, where the
 * name `HttpMethod` does still exist and means the wider 7-value enum.
 */
export type { HttpMethodSubset } from '../shared/http.zod';

/**
 * View Data Source Configuration
 * Supports three modes:
 * 1. 'object': Standard Protocol - Auto-connects to ObjectStack Metadata and Data APIs
 * 2. 'api': Custom API - Explicitly provided API URLs
 * 3. 'value': Static Data - Hardcoded data array
 */
export const ViewDataSchema = lazySchema(() => z.discriminatedUnion('provider', [
  strictObject({
    surface: 'this `object` data source',
    history: VIEW_HISTORY,
    // `objectName` is the canonical spelling on the QUERY surface
    // (`data/query.zod.ts`); the view data source names it `object`, and an
    // author moving between the two writes the neighbouring word rather than a
    // typo edit distance could reach.
    // NOT aliased: a bare `name`. It is a real key on the view ITEM
    // (`ViewItemSchema.name`), so an author who wrote it here may have meant
    // the view's name, not the object's — and this campaign's own finding 7 is
    // that a confidently wrong prescription is worse than none.
    aliases: { objectName: 'object' },
  }, {
    provider: z.literal('object'),
    object: z.string().describe('Target object name'),
  }),
  strictObject({
    surface: 'this `api` data source',
    history: VIEW_HISTORY,
    // The HTTP verbs are the request BLOCKS' business (`read`/`write` each hold
    // an `HttpRequestSchema`), so an author who put the whole request inline is
    // pointed at the block that owns it rather than at a near-miss key.
    guidance: {
      url: 'Set the URL inside the request block: `read: { url, method }` (or `write: { … }`) — the data source itself declares only `read` / `write`.',
      method: 'Set the method inside the request block: `read: { url, method }` (or `write: { … }`).',
      fetch: 'Use `read` for the fetch request and `write` for the submit request.',
      submit: 'Use `write` for the submit request (and `read` for the fetch request).',
    },
  }, {
    provider: z.literal('api'),
    read: HttpRequestSchema.optional().describe('Configuration for fetching data'),
    write: HttpRequestSchema.optional().describe('Configuration for submitting data (for forms/editable tables)'),
  }),
  strictObject({
    surface: 'this `value` data source',
    history: VIEW_HISTORY,
    // `data`/`rows`/`records` are the words the surrounding surfaces use for a
    // row set; on this provider the static array is `items`.
    aliases: { data: 'items', rows: 'items', records: 'items', values: 'items' },
  }, {
    provider: z.literal('value'),
    items: z.array(z.unknown()).describe('Static data array'),
  }),
  /**
   * Schema-bound data source — used by standalone forms whose data is
   * shaped by a JSON Schema (or Zod-derived schema) rather than by an
   * ObjectQL object. Powers the metadata editor, action input dialogs,
   * and any Form that is not bound to a CRUD object.
   */
  strictObject({
    surface: 'this `schema` data source',
    history: VIEW_HISTORY,
    // `schemaId` and `schema` are one key apart in prose but not in edit
    // distance, and the pair is genuinely confusable: one NAMES a schema the
    // server resolves, the other INLINES it.
    aliases: { type: 'schemaId', metadataType: 'schemaId', jsonSchema: 'schema' },
  }, {
    provider: z.literal('schema'),
    /** Schema identifier (e.g. metadata type name "report"). Resolved at runtime against /meta entries. */
    schemaId: z.string().describe('Schema identifier — typically the metadata type name'),
    /** Optional inline JSON Schema; when omitted the runtime resolves schemaId from the server. */
    schema: z.record(z.string(), z.unknown()).optional().describe('Inline JSON Schema (Draft 2020-12). Optional when schemaId is resolvable.'),
  }),
]));

/**
 * Canonical filter operators for view filter rules.
 *
 * This is the SINGLE authoring vocabulary for `ViewFilterRule.operator`.
 * Exposing it as an enum (rather than a free `z.string()`) lets JSON-Schema
 * consumers — notably ObjectUI's SchemaForm — auto-render an operator
 * dropdown, and rejects genuinely unknown operators at parse time.
 *
 * Unary operators (`is_empty`, `is_not_empty`, `is_null`, `is_not_null`) take
 * no `value`. `before` / `after` are the date-friendly spellings of
 * `less_than` / `greater_than`; `between` expects a two-element `value` array.
 *
 * `icontains` (#8934) is the case-insensitive twin of `contains`: an ASCII-only
 * fold on both sides (#4706 Q1 = A — `café` does NOT match `CAFÉ`), comparand
 * LITERAL (`%`, `_` and regex metacharacters are ordinary characters). It
 * lowers to `$icontains`, which LIKE-escapes the comparand — it is NOT a
 * spelling of `ilike`/`$ilike`, which takes a raw LIKE pattern, and the two
 * must never be aliased onto each other (the #7536 boundary, restated on
 * `AST_OPERATOR_MAP` in `data/filter.zod.ts`). There is deliberately no
 * negative form: the `$` dialect has no `$notIcontains`, and this vocabulary
 * mirrors the executed set rather than widening it.
 *
 * Note: relative-date operators (`this_quarter`, `last_7_days`, …) are NOT
 * filter-rule operators — they are date-range presets and live on dashboard
 * date-range config (`DashboardFilterSchema.defaultRange`), not here.
 */
export const VIEW_FILTER_OPERATORS = [
  'equals', 'not_equals',
  'contains', 'not_contains', 'icontains',
  'starts_with', 'ends_with',
  'greater_than', 'less_than',
  'greater_than_or_equal', 'less_than_or_equal',
  'in', 'not_in',
  'is_empty', 'is_not_empty',
  'is_null', 'is_not_null',
  'before', 'after', 'between',
] as const;

export type ViewFilterOperator = (typeof VIEW_FILTER_OPERATORS)[number];

/**
 * The operators whose `value` is a LIST rather than a scalar (#6227).
 *
 * These are the authoring spellings that lower to `$in` / `$nin`
 * (`AST_OPERATOR_MAP`, `data/filter.zod.ts`), which
 * {@link https://github.com/objectstack-ai/objectstack/issues/5869 | the runtime
 * gate} requires to be arrays. Exported so a producer can ask the question the
 * schema asks instead of hard-coding its own list: `@object-ui`'s filter builder
 * decides `isMultiOperator` from a local `["in", "notIn"]` literal
 * (`components/src/custom/filter-builder.tsx`), a second dialect of exactly this
 * fact that is already one spelling adrift — `notIn` is an alias, not the
 * canonical member. One declared vocabulary, same reasoning as
 * {@link VIEW_FILTER_OPERATOR_ALIASES}.
 */
export const VIEW_FILTER_LIST_VALUE_OPERATORS = [
  'in', 'not_in',
] as const satisfies readonly ViewFilterOperator[];

/**
 * The operators whose `value` is a two-element `[min, max]` array (#6227).
 *
 * Separate from {@link VIEW_FILTER_LIST_VALUE_OPERATORS} because the check is
 * different in kind: membership takes ANY arity (`[]` included), a range takes
 * exactly two bounds.
 */
export const VIEW_FILTER_PAIR_VALUE_OPERATORS = [
  'between',
] as const satisfies readonly ViewFilterOperator[];

/**
 * Legacy operator spellings normalized to the canonical vocabulary above.
 *
 * These are historical shorthand (`eq`, `gt`) and camelCase (`notEquals`,
 * `greaterThan`) forms that older authoring tools and already-stored view
 * metadata may still carry. They are folded to canonical on parse so every
 * downstream consumer sees exactly one vocabulary — one strict contract, not
 * N dialects. Deprecated: new producers MUST emit the canonical forms; these
 * aliases are a migration bridge and may be dropped in a future major.
 *
 * `icontains` (#8934) deliberately has NO rows here: this table bridges
 * spellings that already live in stored metadata, and a canonical operator
 * born after the table has none — inventing "synonyms" for it would widen the
 * authoring surface rather than bridge a legacy one. Single-token canonicals
 * (`contains`, `in`, `between`) carry no camelCase/squashed folds for the same
 * reason: the folds exist per measured legacy spelling, not per operator.
 */
export const VIEW_FILTER_OPERATOR_ALIASES: Record<string, ViewFilterOperator> = {
  eq: 'equals',
  ne: 'not_equals', neq: 'not_equals', notequals: 'not_equals', notEquals: 'not_equals',
  notcontains: 'not_contains', notContains: 'not_contains',
  startswith: 'starts_with', startsWith: 'starts_with',
  endswith: 'ends_with', endsWith: 'ends_with',
  gt: 'greater_than', greaterthan: 'greater_than', greaterThan: 'greater_than',
  lt: 'less_than', lessthan: 'less_than', lessThan: 'less_than',
  gte: 'greater_than_or_equal', greaterorequal: 'greater_than_or_equal',
  greaterOrEqual: 'greater_than_or_equal', greaterThanOrEqual: 'greater_than_or_equal',
  lte: 'less_than_or_equal', lessorequal: 'less_than_or_equal',
  lessOrEqual: 'less_than_or_equal', lessThanOrEqual: 'less_than_or_equal',
  nin: 'not_in', notin: 'not_in', notIn: 'not_in',
  isempty: 'is_empty', isEmpty: 'is_empty',
  isnotempty: 'is_not_empty', isNotEmpty: 'is_not_empty',
  isnull: 'is_null', isNull: 'is_null',
  isnotnull: 'is_not_null', isNotNull: 'is_not_null',
};

/**
 * Fold a legacy operator spelling to its canonical form. Returns canonical
 * operators unchanged, maps known aliases, and returns unknown input verbatim
 * (so the enum's own validation reports it as invalid). Exported so producers
 * and renderers can normalize stored metadata against the SAME canonical map
 * the schema uses, instead of inventing a second dialect.
 */
export function normalizeFilterOperator(op: unknown): string {
  if (typeof op !== 'string') return op as string;
  if ((VIEW_FILTER_OPERATORS as readonly string[]).includes(op)) return op;
  return VIEW_FILTER_OPERATOR_ALIASES[op] ?? VIEW_FILTER_OPERATOR_ALIASES[op.toLowerCase()] ?? op;
}

// ───────────────────────────────────────────────────────────────────────────
// Write-time console decorations (#5074) — the mirror of `stripReadDecorations`
// ───────────────────────────────────────────────────────────────────────────
//
// `stripReadDecorations` (`kernel/metadata-read-decorations.ts`) exists because
// the READ path stamps keys onto a served document that were never part of it,
// so a served body is not a valid input to the schema that produced it. The
// console's row builders create the same problem from the other side, and this
// is that function's write-path twin.
//
// The producer is a React list key, not a protocol decision: the filter builder
// (`components/src/custom/filter-builder.tsx:228`, re-stamped on read-back at
// `plugin-view/src/config/view-config-utils.ts:146`/`:160`) and the sort builder
// (`components/src/custom/sort-builder.tsx:68`/`:94`) both stamp
// `id: crypto.randomUUID()` on every row they render. `saveMetaItem` validates
// the PUT body and persists the AUTHORED body verbatim, so those ids reach the
// wire and the store.
//
// ⚠️ Why a `.strip()` on the wire member cannot do this job — the #4001 批 18 /
// #5114 finding, and the reason this vocabulary exists at all: **`.strip()` does
// not recurse, any more than `.strict()` does.** Re-opening a union member
// re-opens its TOP level; every nested block is still reached through it at that
// block's own posture. `filter[]` and `sort[]` are nested blocks, so a top-level
// reopen leaves them 422ing the platform's own writes. Removing the decoration
// BEFORE validation is what makes the wire opening recursive-effective, and it
// is the only one of the two routes that does not require the authoring surface
// to declare a UI artifact (批 18 Q1: declaring `id` teaches an AI author to
// emit a UUID for a filter rule — a `??` fallback wearing a schema).
//
// Deliberately NOT solved by a second parallel schema tree: a hand-maintained
// wire twin of every carrier of `ViewFilterRuleSchema` is a second copy of the
// truth (PD#12's fork), and it rots silently the first time someone adds a new
// carrier. One declared vocabulary, applied at the wire door, covers every
// carrier that exists today and every one added later.

/** Keys the console stamps onto builder ROWS, which are therefore never authored. */
export const VIEW_CONSOLE_ROW_DECORATIONS = ['id'] as const;

/**
 * Keys whose array value holds console builder rows. Both are written by a
 * row-per-entry widget that needs a stable React key; neither element shape
 * declares `id`, on any surface, by design.
 */
const VIEW_DECORATED_ROW_CARRIERS: readonly string[] = ['filter', 'sort'];

/** Depth guard — a view body is a bounded document, not a general graph. */
const VIEW_DECORATION_MAX_DEPTH = 12;

/** The prescription an authored `id` gets on a row shape. Shared by both sites. */
const VIEW_CONSOLE_ROW_ID_GUIDANCE =
  '`id` is a console row key (the filter/sort builders stamp a `crypto.randomUUID()` '
  + 'per row for React) — it is not part of the authoring contract, and the write path '
  + 'removes it before validating. Delete it from authored metadata.';

function stripRowDecorations(value: unknown, isRow: boolean, depth: number): unknown {
  if (depth > VIEW_DECORATION_MAX_DEPTH || !value || typeof value !== 'object') return value;

  if (Array.isArray(value)) {
    let changed = false;
    const next = value.map((el) => {
      const out = stripRowDecorations(el, isRow, depth + 1);
      if (out !== el) changed = true;
      return out;
    });
    return changed ? next : value;
  }

  const dict = value as Record<string, unknown>;
  let next: Record<string, unknown> | undefined;

  if (isRow) {
    for (const k of VIEW_CONSOLE_ROW_DECORATIONS) {
      if (k in dict) {
        next ??= { ...dict };
        delete next[k];
      }
    }
  }

  for (const [k, v] of Object.entries(next ?? dict)) {
    const out = stripRowDecorations(v, VIEW_DECORATED_ROW_CARRIERS.includes(k), depth + 1);
    if (out !== v) {
      next ??= { ...dict };
      next[k] = out;
    }
  }

  return next ?? value;
}

/**
 * Remove {@link VIEW_CONSOLE_ROW_DECORATIONS} from the builder rows of a `view`
 * body, at every depth they occur — `filter[]` / `sort[]` under a flattened
 * overlay, under a ViewItem's `config`, under `userFilters.tabs[]`, under
 * `tabs[]`, and under any carrier added later.
 *
 * A **silent** removal, for the same reason `stripReadDecorations` is silent:
 * this is our own UI's decoration riding on a document that is otherwise exactly
 * what the author meant, so rejecting it would be hostile. It runs on the WIRE
 * door only ({@link ViewMetadataSchema}) — {@link defineViewItem} and the other
 * authoring doors keep rejecting the key by name, which is the whole point of
 * the split.
 *
 * Nothing is lost at rest: `saveMetaItem` persists the ORIGINAL body, so the
 * console still reads its own ids back.
 *
 * Returns the SAME reference when there is nothing to strip, so the common path
 * allocates nothing. Non-object inputs pass through — the schema owns those.
 */
export function stripViewConsoleDecorations(body: unknown): unknown {
  return stripRowDecorations(body, false, 0);
}

/** `string` / `number` / `an array of 3` / `null` … — the word the refusal uses. */
function describeFilterValue(value: unknown): string {
  if (value === null) return 'null';
  if (value === undefined) return 'no value';
  if (Array.isArray(value)) return `an array of ${value.length}`;
  return `a ${typeof value}`;
}

/**
 * A short, bounded rendering of the offending value.
 *
 * Bounded for the reason the runtime twin's `shapePreview` is: the value can be
 * arbitrarily large, and the message is for a human reading a refusal, not a
 * dump.
 */
function previewFilterValue(value: unknown): string {
  if (value === undefined) return '(omitted)';
  let text: string;
  try {
    text = JSON.stringify(value) ?? String(value);
  } catch {
    text = String(value);
  }
  return text.length > 40 ? `${text.slice(0, 39)}…` : text;
}

/**
 * [#6227] `value` must have the shape the rule's OPERATOR can execute.
 *
 * ## The two-stage failure this closes
 *
 * `{ field: 'stage', operator: 'not_in', value: 'won' }` — a set operator with a
 * scalar comparand — was a spec-VALID `ViewFilterRule`: `value` declared
 * `string | number | boolean | null | (string | number)[]` with no coupling to
 * `operator`, so every operator accepted every shape. The view published cleanly
 * and then failed at QUERY time, where #5869 / PR #6209 had already closed the
 * runtime half: `assertListComparandShapes` (`@objectstack/objectql`,
 * `filter-comparand-shape.ts`) refuses the lowered `{ stage: { $nin: 'won' } }`
 * with a named 400 `INVALID_FILTER`. Correct refusal, wrong moment — the author
 * is gone by then, and before #6209 the same shape was a 500. That file's own
 * module docblock names this schema as the reachable authoring source of the
 * defect.
 *
 * ## Why this mirrors the runtime gate EXACTLY, and refuses to go further
 *
 * The checks below are `assertListComparandShapes`' three constraints, one for
 * one: `$in`/`$nin` must be an array, `$between` must be a 2-array. Nothing else
 * is judged here, deliberately — #5685 already ruled on the opposite error, where
 * `FieldOperatorsSchema` declared `$gt` as `number | Date | FieldReference` while
 * every first-party producer put an ISO STRING there; the schema was ruled the
 * wrong side and widened to match the runtime. A publish-time gate refusing more
 * than the query path refuses would re-create that mismatch pointing the other
 * way, and would reject stored metadata that executes correctly today.
 * Specifically NOT refused, because the runtime does not refuse them:
 *
 * - **`in: []` / `not_in: []`.** An empty list is a legitimate declared predicate
 *   — "matches nothing" / "matches everything" — and the runtime gate says so in
 *   as many words. Arity is not this check's business for membership; only "is it
 *   a list at all".
 * - **A scalar operator carrying an array** (`equals: ['a','b']`). `equals`
 *   lowers to a bare `{ field: value }` deep-equality comparand
 *   (`convertComparison`), which every backend answers.
 * - **A string operator carrying a number** (`contains: 5`). Lowers to
 *   `$contains: 5`; no backend refuses it.
 * - **A unary operator carrying a value** (`is_empty: ''`). The null predicates
 *   take their direction from the operator NAME — `convertComparison` maps them
 *   to `{ $null: true|false }` and ignores the value position entirely — and the
 *   ObjectUI client deliberately sends a truthy PLACEHOLDER value for both
 *   `isnull` and `isnotnull`. Refusing it would break a live first-party producer
 *   to enforce nothing.
 *
 * ## Why `superRefine` and not `z.discriminatedUnion` (measured, not assumed)
 *
 * 1. **`z.discriminatedUnion` cannot read this discriminator — it does not
 *    construct.** `operator` is `z.preprocess(normalizeFilterOperator, z.enum(…))`
 *    — the alias fold that lets a stored `notIn` / `nin` / `gt` parse. Zod 4
 *    extracts a discriminator's literal values from the option's own def, and a
 *    preprocess wrapper hides them: building the union throws
 *    `Invalid discriminated union option at index "0"` before any parse happens.
 *    The alias fold is load-bearing ({@link VIEW_FILTER_OPERATOR_ALIASES} exists
 *    for stored metadata) and is not negotiable to buy a union.
 * 2. **A refinement adds no JSON-Schema structure.** Measured with
 *    `z.toJSONSchema` before and after: byte-identical output. `ui/ViewFilterRule`
 *    is a PUBLISHED def whose authorable key set is a ratchet of exactly three
 *    entries (`authorable-surface/ui.json`). A union fans that one def into N
 *    branches re-declaring the same three keys per branch — the phantom
 *    liveness-worklist inflation #7042 measured and refused for
 *    `ViewContainerWireSchema` one screen down — and ObjectUI's SchemaForm would
 *    stop rendering the single operator dropdown it renders today.
 * 3. **Error quality points at the defect.** A refinement emits ONE issue at path
 *    `['value']` naming the operator, the received shape and the expected one. A
 *    union emits every branch's failure and leads with the discriminator, i.e. it
 *    blames `operator` for a defect that is in `value`.
 *
 * In Zod 4 a refinement lives INSIDE the schema rather than wrapping it in a
 * `ZodEffects`, so `.shape` and the `ZodObject` class survive (measured) and
 * every carrier — `z.array(ViewFilterRuleSchema)` on `ListView.filter`, a tab
 * filter, `Page.filterBy`, a related-list filter and a lookup picker filter —
 * keeps working untouched.
 *
 * ## The wording is the runtime's wording (#5240)
 *
 * The leading sentence is kept verbatim from `nonListComparandError` /
 * `malformedRangeComparandError` so one condition keeps one wording across the
 * two moments it can be reported. The TAIL deliberately differs: the runtime's
 * closing fact is "the filter was NOT applied", which is false here — nothing
 * ran, the metadata is being refused — so this one prescribes the fix instead.
 */
function checkViewFilterRuleValueShape(
  rule: { field?: unknown; operator?: unknown; value?: unknown },
  ctx: z.RefinementCtx,
): void {
  // `operator` is read POST-parse, so it is already folded to canonical by
  // `normalizeFilterOperator`: a stored `notIn` is `not_in` here, and this check
  // never has to know the alias table.
  const operator = rule.operator as ViewFilterOperator;
  const value = rule.value;
  const field = typeof rule.field === 'string' ? rule.field : '<field>';

  const isList = (VIEW_FILTER_LIST_VALUE_OPERATORS as readonly string[]).includes(operator);
  const isPair = (VIEW_FILTER_PAIR_VALUE_OPERATORS as readonly string[]).includes(operator);

  if (isList) {
    if (Array.isArray(value)) return;
    ctx.addIssue({
      code: 'custom',
      path: ['value'],
      message:
        `Operator "${operator}" on field "${field}" requires an ARRAY of values. `
        + `Received ${describeFilterValue(value)} (${previewFilterValue(value)}). `
        + `"${operator}" tests membership of a list — write `
        + `${value === undefined ? '["…"]' : previewFilterValue([value])} for a single value, `
        + `or use ${operator === 'in' ? '"equals"' : '"not_equals"'} to compare against it. `
        + `An empty list [] is allowed and is a real predicate. This is refused at authoring `
        + `time because the query path refuses it too (400 INVALID_FILTER).`,
    });
    return;
  }

  if (!isPair) return;
  if (Array.isArray(value) && value.length === 2) return;
  ctx.addIssue({
    code: 'custom',
    path: ['value'],
    message:
      `Operator "${operator}" on field "${field}" requires a [min, max] value array. `
      + `Received ${describeFilterValue(value)} (${previewFilterValue(value)}). `
      + `A range needs exactly two bounds, in order. This is refused at authoring time `
      + `because the query path refuses it too (400 INVALID_FILTER).`,
  });
}

/**
 * View Filter Rule Schema
 * Standardized filter condition used in list views, tabs, and page-level filters.
 * Uses a declarative array-of-objects format: [{ field, operator, value }].
 *
 * ⚠️ [#5074] CLOSED — this is the authoring shape, and it rejects the console's
 * row `id`. #5114 had reopened it as a provisional hotfix, explicitly pending
 * this split; that hotfix is now retired rather than left standing.
 *
 * **Why the reopen was needed, and why it no longer is.** The filter builder
 * objectui renders stamps `id: crypto.randomUUID()` on every row it creates
 * (`components/src/custom/filter-builder.tsx:228`; stamped again when a stored
 * filter is read back into the builder —
 * `plugin-view/src/config/view-config-utils.ts:146`/`:160`). `saveMetaItem`
 * validates the PUT body and then persists the AUTHORED body verbatim, so that
 * `id` is on the wire and in the store. Closed *without* a wire route, this
 * shape turned every filter write carrying one into a 422 — measured on all
 * three paths, including the flattened personalization overlay that is the body
 * the console actually PUTs.
 *
 * The mechanism is the part worth carrying, and it is why a top-level reopen
 * could never have rescued this block: **`.strip()` does not recurse**, any more
 * than `.strict()` does. `ViewMetadataSchema` re-opens its wire members' TOP
 * level only, so a nested block closed here is still reached through those
 * members at full strictness. Same finding as `ListView.sort` at #4001 批 18
 * (#5070), one block over.
 *
 * `id` is still NOT declared here. It is a React list key, not protocol:
 * declaring it would put a UI artifact on the authorable surface and tell an AI
 * author to generate a UUID for a filter rule — a `??` fallback wearing a
 * schema. Instead the WIRE door removes it before validating, via the declared
 * {@link VIEW_CONSOLE_ROW_DECORATIONS} vocabulary and
 * {@link stripViewConsoleDecorations} — the write-path mirror of
 * `stripReadDecorations`, and the piece that makes the wire opening
 * recursive-effective where a `.strip()` cannot reach. So the authoring surface
 * stays exactly three keys and the console's own writes still parse.
 *
 * Recorded in three places: this JSDoc, `view-filter-rule-wire-id.test.ts`, and
 * the `ui/` row of `docs/audits/2026-07-unknown-key-strictness-ledger.md`.
 *
 * @example
 * ```ts
 * filter: [
 *   { field: 'status', operator: 'equals', value: 'active' },
 *   { field: 'close_date', operator: 'after', value: '2024-01-01' },
 *   { field: 'archived_at', operator: 'is_empty' },
 * ]
 * ```
 */
export const ViewFilterRuleSchema = lazySchema(() => strictObject({
  surface: 'this filter rule',
  history: VIEW_HISTORY,
  guidance: {
    id: VIEW_CONSOLE_ROW_ID_GUIDANCE,
  },
}, {
  /** Field name to filter on */
  field: z.string().describe('Field name to filter on'),
  /**
   * Filter operator (canonical vocabulary). Legacy shorthand/camelCase
   * spellings (`eq`, `gt`, `isNull`, …) are accepted and normalized to
   * canonical on parse.
   */
  operator: z.preprocess(normalizeFilterOperator, z.enum(VIEW_FILTER_OPERATORS))
    .describe('Filter operator'),
  /**
   * Filter value (optional for unary operators like is_empty, is_null).
   *
   * The accepted SHAPE is coupled to `operator` by
   * {@link checkViewFilterRuleValueShape} (#6227).
   */
  value: z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(z.union([z.string(), z.number()]))])
    .optional().describe(
      'Filter value. The accepted SHAPE depends on the operator: `in` / `not_in` take an '
      + 'array (any length, including []), `between` takes exactly [min, max], every other '
      + 'operator takes a scalar. The unary operators (is_empty / is_not_empty / is_null / '
      + 'is_not_null) take their direction from the operator name and ignore this key.',
    ),
}).superRefine(checkViewFilterRuleValueShape).describe('View filter rule'));

export type ViewFilterRule = z.input<typeof ViewFilterRuleSchema>;
/** Post-parse shape of {@link ViewFilterRule} — defaults applied, transforms run (ADR-0122). */
export type ViewFilterRuleParsed = z.infer<typeof ViewFilterRuleSchema>;

/**
 * Column Summary Function Schema
 * Aggregation function for column footer (Airtable-style column summaries)
 *
 * On a GROUPED list view the same declaration is the per-group HEADER summary
 * (#14556, ruling A on objectui#7189: grouping is server-side, so a group's
 * numbers are properties of the query, not of the fetched page). The header
 * is one aggregate query in the query AST's own vocabulary — `AggregationFunction`
 * (`data/query.zod.ts`), the vocabulary datasets already use, one and not two
 * (objectui#4576) — and this enum maps onto it in
 * `view-grouping-query.ts` (`COLUMN_SUMMARY_AGGREGATION`):
 *
 *   * `count` → a fieldless `count` (`COUNT(*)`, every row of the group — the
 *     group count itself), `count_unique` → `count_distinct`, and
 *     `sum` / `avg` / `min` / `max` → the same name; `none` declares nothing.
 *   * `count_filled` / `count_empty` / `percent_filled` / `percent_empty` map
 *     by DERIVATION (seat ruling on fork i, contract review of #14556): one
 *     `{ function: 'count', field }` node — `COUNT(field)`, the non-null count
 *     — rides the header row as `count_<field>`, and the four are computed
 *     from it and the group count by `deriveColumnSummary`: `count_filled` =
 *     `count_<field>`, `count_empty` = `count − count_<field>`,
 *     `percent_filled` = `count_<field> / count` (0 when the count is 0),
 *     `percent_empty` = `1 − percent_filled`. "Empty" is the SERVER's meaning
 *     on every face — the stored value is `null` (`aggregation-conformance`);
 *     the footer's client-side reading, which also treats `''` and `[]` as
 *     empty, is objectui's to converge under "one vocabulary".
 *
 * ⛔ Adding a member here without deciding its row in
 * `COLUMN_SUMMARY_AGGREGATION` is a type error by construction, so the table
 * cannot widen silently; a member whose row says "no counterpart" is refused
 * loudly by `compileListViewGroupQuery` (`NOT_IMPLEMENTED` / 501, with the
 * path of the summary) — none is in that state today.
 */
export const ColumnSummarySchema = lazySchema(() => z.enum([
  'none',
  'count',
  'count_empty',
  'count_filled',
  'count_unique',
  'percent_empty',
  'percent_filled',
  'sum',
  'avg',
  'min',
  'max',
]).describe(
  // The tracking card for the open mapping question is named in the JSDoc
  // above; `.describe()` prose reaches readers who cannot resolve an issue id.
  'Aggregation function for the column footer summary — and, on a grouped list view, the per-group '
  + 'header summary (server-side): count (COUNT(*), the group count), count_unique '
  + '(count_distinct), sum, avg, min, max map onto the query AST\'s AggregationFunction; '
  + 'count_filled, count_empty, percent_filled, percent_empty derive from one COUNT(field) node (the '
  + 'non-null count) and the group count — count_filled = COUNT(field), count_empty = count − COUNT(field), '
  + 'percent_filled = COUNT(field) / count (0 when count is 0), percent_empty = 1 − percent_filled. '
  + 'Server-side "empty" is null on every face; the footer\'s client-side reading of empty strings and '
  + 'empty arrays as empty is the renderer\'s to converge',
));

/**
 * Column Summary Configuration Schema
 *
 * The object form of `ListColumn.summary`. Use it when the footer aggregates a
 * field OTHER than the column's own — e.g. an `amount` column whose footer sums
 * `amount_in_base_currency`. The shorthand (`summary: 'sum'`) stays the common
 * case and always aggregates the column's own `field`.
 *
 * `type` reuses `ColumnSummarySchema`, so both forms share one aggregation
 * vocabulary and cannot drift apart.
 */
export const ColumnSummaryConfigSchema = lazySchema(() => strictObject({
  surface: 'this column summary configuration',
  history: VIEW_HISTORY,
}, {
  type: ColumnSummarySchema.describe('Aggregation function'),
  field: z.string().optional().describe('Field to aggregate (defaults to the column field)'),
}).describe('Column footer summary configuration'));

/**
 * Column Prefix Configuration Schema (Airtable-style compound cells)
 *
 * Renders a second field's value inline before the cell value — e.g. a status
 * badge in front of the record name — so a list can carry two signals in one
 * column without spending a second column on it.
 */
export const ColumnPrefixSchema = lazySchema(() => strictObject({
  surface: 'this column prefix',
  history: VIEW_HISTORY,
}, {
  field: z.string().describe('Field whose value renders before the cell value'),
  type: z.enum(['badge', 'text']).default('text').describe('How the prefix value is rendered'),
}).describe('Compound-cell prefix configuration'));

/**
 * List Column Configuration Schema
 * Detailed configuration for individual list view columns
 */
export const ListColumnSchema = lazySchema(() => strictObject({
  surface: 'this list column',
  history: VIEW_HISTORY,
}, {
  field: z.string().describe('Field name (snake_case)'),
  label: I18nLabelSchema.optional().describe('Display label override'),
  width: z.number().positive().optional().describe('Column width in pixels'),
  align: z.enum(['left', 'center', 'right']).optional().describe('Text alignment'),
  hidden: z.boolean().optional().describe('Hide column by default'),
  sortable: z.boolean().optional().describe('Allow sorting by this column'),
  resizable: z.boolean().optional().describe('Allow resizing this column'),
  wrap: z.boolean().optional().describe('Allow text wrapping'),
  type: z.string().optional().describe('Renderer type override (e.g., "currency", "date")'),

  /** Pinning (Airtable-style frozen columns) */
  pinned: z.enum(['left', 'right']).optional().describe('Pin/freeze column to left or right side'),

  /** Column Footer Summary (Airtable-style aggregation) */
  summary: z.union([ColumnSummarySchema, ColumnSummaryConfigSchema]).optional()
    .describe('Footer aggregation for this column — the function alone, or { type, field } to aggregate another field'),

  /** Compound cell (Airtable-style): render another field inline before the value */
  prefix: ColumnPrefixSchema.optional().describe('Field rendered inline before this cell value'),

  /** Interaction */
  link: z.boolean().optional().describe('Functions as the primary navigation link (triggers View navigation)'),
  action: z.string().optional().describe('Registered Action ID to execute when clicked'),
}));

/**
 * List View Selection Configuration
 */
export const SelectionConfigSchema = lazySchema(() => strictObject({
  surface: 'this selection configuration',
  history: VIEW_HISTORY,
}, {
  type: z.enum(['none', 'single', 'multiple']).default('none').describe('Selection mode'),
}));

/**
 * List View Pagination Configuration
 */
export const PaginationConfigSchema = lazySchema(() => strictObject({
  surface: 'this pagination configuration',
  history: VIEW_HISTORY,
}, {
  pageSize: z.number().int().positive().default(25).describe('Number of records per page'),
  pageSizeOptions: z.array(z.number().int().positive()).optional().describe('Available page size options'),
}));

/**
 * Row Height / Density Schema (Airtable-style)
 * Controls the visual density of rows in a list view.
 */
export const RowHeightSchema = lazySchema(() => z.enum([
  'compact',     // Minimal padding, single line
  'short',       // Reduced padding
  'medium',      // Default padding
  'tall',        // Extra padding, multi-line preview
  'extra_tall',  // Maximum padding, rich content preview
]).describe('Row height / density setting for list view'));

/**
 * Grouping Field Configuration
 * Defines a single grouping level for record grouping.
 *
 * `field` is one `groupBy` column of the group header query
 * ({@link GroupingConfigSchema}); the header row carries its RAW STORED value
 * under the field's own name — a lookup's group key is the referenced id, the
 * empty group's key is `null`. `order` and `collapsed` are presentation:
 * `EngineAggregateOptions` carries no `orderBy`, so the consumer sorts the
 * header rows (a set the size of the group count) and folds/unfolds them.
 */
export const GroupingFieldSchema = lazySchema(() => strictObject({
  surface: 'this grouping field',
  history: VIEW_HISTORY,
}, {
  field: z.string().describe('Field name to group by — one `groupBy` column of the group header query; the header row carries its raw stored value (null for the empty group)'),
  order: z.enum(['asc', 'desc']).default('asc').describe('Group sort order — applied by the consumer over the header rows (the aggregate query carries no orderBy)'),
  collapsed: z.boolean().default(false).describe('Collapse groups by default (presentation only)'),
}));

/**
 * Grouping Configuration Schema (Airtable-style)
 * Supports multi-level grouping for grid/gallery views.
 *
 * ## Grouping is SERVER-SIDE (#14556)
 *
 * Maintainer ruling A on objectui#7189 (2026-09-02): *the set of groups and
 * every number in a group header (the count and any per-group aggregation)
 * are properties of the query, not of the fetched page; rows inside a group
 * are paged.* Grouping the rows of one fetched window — what a grouped grid
 * did before this contract — rendered two headers (86, 14) or five
 * (31/31/30/7/1) for the same 186 rows in five units depending on row order,
 * and left the rows past the first window unreachable. That is the interim
 * state, not the contract.
 *
 * What the platform returns for a grouped list view, in the vocabulary the
 * query AST already declares (seat ruling: reuse, no new query shape):
 *
 * 1. **The group keys and every header number — ONE aggregate query**
 *    (`EngineAggregateOptions`, executed by `IDataEngine.aggregate`):
 *    `groupBy` = `fields[].field` in nesting order (multi-level grouping is
 *    a multi-column `groupBy`), `aggregations` = a `count` node (the group's
 *    TOTAL row count, alias `count`) plus the view's declared column
 *    summaries (`ListColumn.summary`, mapped onto `AggregationFunction` — see
 *    {@link ColumnSummarySchema}), `where` = the view's composed filter.
 *    One header row per group, keyed by the grouped fields' own names.
 * 2. **The rows inside a group — the EXISTING paged `find`**
 *    (`EngineQueryOptions`, `IDataEngine.find`) with the group's key
 *    predicate AND-ed into the same view filter, `limit` / `offset` per
 *    group (`$top` / `$skip` on the wire).
 * 3. No new engine verb, no new envelope.
 *
 * The checkable form of this contract is `view-grouping-query.ts` —
 * `compileListViewGroupQuery` (1) and `compileListViewGroupRowsQuery` (2),
 * pinned on the 186-row fixture: 86/61/31/7/1 regardless of row order.
 *
 * ## Known limits of the shape, recorded
 *
 *   * **Group keys are scalar-valued.** A header row carries, under each
 *     grouped field, one stored value — a lookup's referenced id, a select
 *     value, a number, a boolean, `null` for the empty group. A date /
 *     datetime grouping field groups per DISTINCT STORED INSTANT: there is
 *     no `dateGranularity` on a grouping field (the query AST's bucketed
 *     `groupBy` member form is not exposed here), so "by month" is not a
 *     list-view grouping today.
 *   * **Header cardinality is unbounded.** The header query answers one row
 *     per group, and `EngineAggregateOptions` carries neither `orderBy` nor
 *     `limit` — the existing door returns the whole grouped set and slices
 *     `limit` after aggregation. A high-cardinality grouping field therefore
 *     returns as many header rows as it has distinct values; bounding that is
 *     `orderBy` + `limit` on the aggregate verb, an engine-contract card of
 *     its own, never a change to `order`'s meaning.
 *
 * ## The door, and the follow-ons
 *
 * Both queries ride the data endpoint's EXISTING door: `POST
 * /data/:object/query` (`packages/rest/src/rest-server.ts`) → `protocol.findData`
 * (`packages/metadata-protocol/src/protocol.ts`), which routes a body carrying
 * `groupBy` / `aggregations` to `engine.aggregate` and answers `{ object,
 * records, total, hasMore }`; `client.data.query()` posts there and the RPC
 * face declares `method: 'aggregate'`. No new route, no new wire shape.
 * Follow-ons, in order: the platform half of #14556 pins that door on the
 * compiled queries (the 186-row fixture through the route, on driver-sql and
 * on the in-memory tier), then objectui#7189 (`plugin-grid` consumes the
 * header rows and stops grouping the page).
 */
export const GroupingConfigSchema = lazySchema(() => strictObject({
  surface: 'this grouping configuration',
  history: VIEW_HISTORY,
}, {
  fields: z.array(GroupingFieldSchema).min(1).describe('Fields to group by, in nesting order — the first entry is the outermost group and each later entry nests one level deeper (at least one field); the same order as the group header query\'s `groupBy`'),
}).describe(
  'Record grouping configuration — SERVER-SIDE: the set of groups and every number in a group '
  + 'header (the count and the per-column summaries) are properties of the query, not of the fetched page, '
  + 'answered by one aggregate query (`groupBy` = the fields in nesting order, `count` + the mapped column '
  + 'summaries, the view filter); rows inside a group are paged by the existing find with the group key '
  + 'AND-ed into the view filter. Compiled by `compileListViewGroupQuery` / `compileListViewGroupRowsQuery`',
));

/**
 * Gallery View Configuration (Airtable-style)
 * Configures card layout for gallery/card views.
 */
export const GalleryConfigSchema = lazySchema(() => strictObject({
  surface: 'this gallery configuration',
  history: VIEW_HISTORY,
}, {
  coverField: z.string().optional().describe('Attachment/image field to display as card cover'),
  coverFit: z.enum(['cover', 'contain']).default('cover').describe('Image fit mode for card cover'),
  cardSize: z.enum(['small', 'medium', 'large']).default('medium').describe('Card size in gallery view'),
  titleField: z.string().optional().describe('Field to display as card title'),
  visibleFields: z.array(z.string()).optional().describe('Fields to display on card body'),
}).describe('Gallery/card view configuration'));

/**
 * Timeline View Configuration (Airtable-style)
 * Configures timeline/chronological views.
 */
export const TimelineConfigSchema = lazySchema(() => strictObject({
  surface: 'this timeline configuration',
  history: VIEW_HISTORY,
}, {
  startDateField: z.string().describe('Field for timeline item start date'),
  endDateField: z.string().optional().describe('Field for timeline item end date'),
  titleField: z.string().describe('Field to display as timeline item title'),
  groupByField: z.string().optional().describe('Field to group timeline rows'),
  colorField: z.string().optional().describe('Field to derive each item color from (it names a field, not a color): the option color declared on that field for the record value, else the value itself when it already is a color literal (hex, rgb() or hsl()), else the timeline default marker color'),
  scale: z.enum(['hour', 'day', 'week', 'month', 'quarter', 'year']).default('week').describe('Default timeline scale'),
}).describe('Timeline view configuration'));

/**
 * View Sharing Configuration (Airtable-style)
 * Defines who can see and modify a view.
 */
export const ViewSharingSchema = lazySchema(() => strictObject({
  surface: 'this view sharing',
  history: VIEW_HISTORY,
}, {
  type: z.enum(['personal', 'collaborative']).default('collaborative').describe('View ownership type'),
  lockedBy: z.string().optional().describe('User who locked the view configuration'),
}).describe('View sharing and access configuration'));

/**
 * Row Color Configuration (Airtable-style)
 * Defines how rows are colored based on field values.
 */
export const RowColorConfigSchema = lazySchema(() => strictObject({
  surface: 'this row color configuration',
  history: VIEW_HISTORY,
}, {
  field: z.string().describe('Field whose value is looked up in the `colors` map below to pick a row colour (typically a select/status field). The map is what does the colouring — with no `colors`, no row is ever coloured, whatever this field holds. Author-time diagnostic `view/row-color-without-colors` reports that combination.'),
  colors: z.record(z.string(), z.string()).optional().describe('Map of field value to color (hex/token)'),
}).describe('Row color configuration based on field values'));

/**
 * Visualization Type Schema
 * Whitelist of visualization types the user can switch between.
 * Maps to Airtable's "Visualizations" setting in Appearance panel.
 */
export const VisualizationTypeSchema = lazySchema(() => z.enum([
  'grid',
  'kanban',
  'gallery',
  'calendar',
  'timeline',
  'gantt',
  'map',
  'chart',
  'tree',
]).describe('Visualization type that users can switch to'));

/**
 * User Actions Configuration Schema (Airtable Interface parity)
 * Controls which interactive actions are available to users in the view toolbar.
 * Each boolean toggles the corresponding toolbar element on/off.
 *
 * `group` / `hideFields` / `rowColor` adopted from objectui's legacy `show*`
 * fold (`SHOW_FLAG_TO_USER_ACTION` in normalize-list-view.ts; ruled Option A on
 * objectui#5435): the ListView toolbar already honoured all three, but no
 * spec-valid document could declare them, so the fold's own output failed the
 * save gate. The defaults asymmetry is LOAD-BEARING, copied from the renderer's
 * reads, not chosen here: `group` defaults ON (`ua?.group !== false`) like the
 * other core toolbar controls, while `hideFields` / `rowColor` default OFF
 * (`=== true`) — column hiding and row colouring are opt-in affordances.
 *
 * Name-collision note (same key NAME, different shape, on OTHER surfaces —
 * deliberate, each toggle is named after the config it gates): these three are
 * booleans HERE, while `rowColor` on the list view itself is a
 * {@link RowColorConfigSchema} (the colour rules this toggle exposes to users)
 * and `hideFields` on the record-details component is a `string[]` of field
 * names to omit. The describes below say which side of each pair this is.
 *
 * @see Airtable Interface → "User actions" panel
 */
export const UserActionsConfigSchema = lazySchema(() => strictObject({
  surface: 'this user actions configuration',
  history: VIEW_HISTORY,
}, {
  sort: z.boolean().default(true).describe('Allow users to sort records'),
  search: z.boolean().default(true).describe('Allow users to search records'),
  filter: z.boolean().default(true).describe('Allow users to filter records'),
  refresh: z.boolean().default(true).describe('Allow users to reload the view data from the backend without a full page reload'),
  rowHeight: z.boolean().default(true).describe('Allow users to toggle row height/density'),
  group: z.boolean().default(true).describe('Allow users to change record grouping from the toolbar. Toggle only — the grouping itself is configured in the view-level `grouping` block.'),
  addRecordForm: z.boolean().default(false).describe('Add records through a form instead of inline'),
  editInline: z.boolean().default(false).describe('Allow users to edit records inline — click a cell to edit it with the field\'s type-aware widget (the same control the form uses). Off by default: the list is read-only unless the author opts in.'),
  hideFields: z.boolean().default(false).describe('Allow users to hide/show fields from the toolbar (the affordance behind the view-level `hiddenFields` list). Boolean toggle — distinct from the record-details component\'s `hideFields`, which is an array of field names to omit. Off by default: column hiding is opt-in.'),
  rowColor: z.boolean().default(false).describe('Allow users to configure row colouring from the toolbar. Boolean toggle — the colour rules themselves live in the view-level `rowColor` block. Off by default: row colouring is opt-in.'),
  buttons: z.array(z.string()).optional().describe('Custom action button IDs to show in the toolbar'),
}).describe('User action toggles for the view toolbar'));

/**
 * Appearance Configuration Schema (Airtable Interface parity)
 * Controls visual presentation options for the view.
 *
 * @see Airtable Interface → "Appearance" panel
 */
export const AppearanceConfigSchema = lazySchema(() => strictObject({
  surface: 'this appearance configuration',
  history: VIEW_HISTORY,
}, {
  showDescription: z.boolean().default(true).describe('Show the view description text'),
  allowedVisualizations: z.array(VisualizationTypeSchema).optional()
    .describe('Whitelist of visualization types users can switch between (e.g. ["grid", "gallery", "kanban"])'),
}).describe('Appearance and visualization configuration'));

/**
 * View Tab Schema (Airtable Interface parity)
 * Defines a tab in a multi-tab view interface.
 * Each tab references a named list view and can be ordered, pinned, or set as default.
 *
 * @see Airtable Interface → "Tabs" panel
 */
export const ViewTabSchema = lazySchema(() => strictObject({
  surface: 'this view tab',
  history: VIEW_HISTORY,
}, {
  name: SnakeCaseIdentifierSchema.describe('Tab identifier (snake_case)'),
  label: I18nLabelSchema.optional().describe('Display label'),
  icon: z.string().optional().describe('Tab icon name'),
  view: z.string().optional().describe('Referenced list view name from listViews'),
  filter: z.array(ViewFilterRuleSchema).optional().describe('Tab-specific filter criteria'),
  order: z.number().int().min(0).optional().describe('Tab display order'),
  pinned: z.boolean().default(false).describe('Pin tab (cannot be removed by users)'),
  isDefault: z.boolean().default(false).describe('Set as the default active tab'),
  visible: z.boolean().default(true).describe('Tab visibility'),
}).describe('Tab configuration for multi-tab view interface'));

/**
 * User Filter Field Schema (ADR-0047)
 * One field exposed as a quick-filter control in the end-user filter bar.
 * Rendering details (widget, options) default to inference from the field
 * definition on the source object — authors only override when needed.
 *
 * @see Airtable Interface → "User filters" panel (Dropdowns element)
 */
export const UserFilterFieldSchema = lazySchema(() => strictObject({
  surface: 'this user filter field',
  history: VIEW_HISTORY,
}, {
  field: z.string().describe('Field name on the source object (must exist — checked by reference diagnostics)'),
  label: I18nLabelSchema.optional().describe('Display label override (defaults to the field label)'),
  type: z.enum(['select', 'multi-select', 'boolean', 'date-range', 'text']).optional()
    .describe('Filter control type. Omit to infer from the field definition'),
  options: z.array(strictObject({
    surface: 'this user filter option',
    history: VIEW_HISTORY,
    // Measured against the renderer that consumes these entries
    // (objectui `plugin-list/src/UserFilters.tsx` — `ResolvedOption`): it
    // declares exactly `label` / `value` / `color` plus a `count` it COMPUTES
    // from a data snapshot on every render. `count` is therefore not an
    // authoring key — an authored one is overwritten before it is read, which
    // is why it gets a wrong-layer prescription instead of being declared.
    guidance: {
      count: 'Per-option record counts are computed from the data, not authored. Set `showCount: true` on the filter FIELD to display them.',
    },
  }, {
    value: z.union([z.string(), z.number(), z.boolean()]).describe('Option value'),
    label: I18nLabelSchema.describe('Option label'),
    color: z.string().optional().describe('Option color token/hex'),
  })).optional().describe('Static options. Omit to derive from the field definition (select options / lookup records)'),
  showCount: z.boolean().optional().describe('Show per-option record counts'),
  defaultValues: z.array(z.union([z.string(), z.number(), z.boolean()])).optional()
    .describe('Pre-selected values when the view loads'),
}).describe('Quick-filter field configuration'));

/**
 * User Filters Schema (ADR-0047, Airtable Interface parity)
 * The end-user-facing quick-filter surface above a list. The author picks the
 * element style and which fields/presets are exposed; end users combine them
 * at runtime (session-scoped — selections never persist as metadata).
 *
 * Distinct from `ListView.filter` (the always-on base criteria) and from the
 * advanced filter builder (`userActions.filter` toggle).
 *
 * @see Airtable Interface → "User filters" panel (Elements: tabs / dropdowns)
 */
/**
 * CLOSED at **#5073** — the last shape #4001 批 18 left open in this file, and
 * the one that needed a protocol decision before strictness could touch it.
 *
 * ## Why it could not just be closed (the 批 18 blocker)
 *
 * objectui's renderer reads `config.allowAddTab` and renders an "add tab"
 * affordance from it (`packages/plugin-list/src/UserFilters.tsx:182` and
 * `:742`); its own `UserFiltersSchema` declared the key. The spec's did not —
 * and the difference between the two shapes was *exactly* that one key.
 *
 * That gap was not inert, because the metadata write path does NOT persist
 * `parsed.data`: `saveMetaItem` validates with `safeParse` and then stores the
 * ORIGINAL body verbatim, precisely so Studio-only auxiliary keys survive
 * (`metadata-protocol/src/protocol.ts`, "Validation policy"). So an authored
 * `allowAddTab` was stripped only from the parse RESULT, which is discarded —
 * the stored document kept it and the renderer read it. **The capability
 * worked.** Closing the shape without declaring the key would have converted a
 * working, shipped config into a 422 whose message named a key the author was
 * right to write — this campaign's finding 7 (the platform's own authority
 * steering an author into deleting something that worked), not the silent-strip
 * defect the campaign exists to kill.
 *
 * ## The resolution: promote, then close (maintainer adjudication, 2026-08-04)
 *
 * `allowAddTab` is DECLARED here (additive), so the capability is discoverable
 * from the contract — JSON Schema, Studio's SchemaForm and an AI author all see
 * it, instead of it living only in one React file. Then the shape closes, in
 * the same change, so there is no intermediate state where the key is declared
 * but neighbours still vanish silently. Rejected alternative: judging it an
 * objectui-only extension (`SANCTIONED_LOCAL`), which would have made
 * `packages/spec` and objectui two sources of truth for one contract — the
 * fork #2231's derive-by-reference unification exists to prevent (PD#12).
 *
 * ⚠️ Scope of the promotion, and its RESOLUTION (#5236 → #6961). At promotion
 * time `allowAddTab` was described as declaring only that the tab bar RENDERS
 * an add-tab affordance: the button objectui rendered carried no click handler,
 * so it was presentational, and the narrower wording was deliberate — a
 * contract promising "end users can add presets" would have advertised a
 * capability the runtime did not deliver (PD#10). The maintainer then ruled
 * **A1 — implement, session-scoped** (#5236, 2026-08-06), objectui#3926
 * delivered it (`packages/plugin-list/src/UserFilters.tsx` — naming popover,
 * snapshot of the applied filters, component state only, remove affordance on
 * the added tab), and the `.describe()` below was upgraded back to the real
 * semantics. The narrowing was the interim state the ruling closed, not the
 * contract: the key now promises the behaviour, and PD#10 is satisfied by the
 * delivery rather than by the hedge.
 *
 * ## What closing flips, and why that flip is wanted (批 6e's question)
 *
 * 批 6e left this open pending "does anything rely on the strip to NARROW a
 * page-shaped block?". It does, and the relier is in this file:
 * {@link ObjectUserFiltersSchema} is `UserFiltersSchema.omit({ tabs,
 * showAllRecords, allowAddTab })`, and `.omit()` inherits the base's posture,
 * so closing this base flips `object-list-view.test.ts`'s pin from "drops the
 * page-only keys" to "rejects" them. That flip is CORRECT and wanted: the CLI
 * lint (`packages/lint/src/validate-list-view-mode.ts`) already reports a
 * `tabs`-carrying `userFilters` on an object view, so the two doors used to
 * disagree — the bespoke guard warning while the schema silently dropped.
 * Closing makes them agree. See {@link ObjectUserFiltersSchema} for why that
 * inheritance is not left bare.
 */
export const UserFiltersSchema = lazySchema(() => strictObject({
  surface: 'these user filters',
  history: VIEW_HISTORY,
}, {
  // `toggle` is DEPRECATED (ADR-0047 §3.4a): it overlaps `tabs` (presets) and
  // `dropdown` (per-field values) without adding expressive power, needs
  // per-field defaultValues to be useful, and authoring tooling no longer
  // offers it (None / Tabs / Dropdown only). Kept in the enum so existing
  // configs keep rendering; do not author new `toggle` filters.
  element: z.enum(['dropdown', 'tabs', 'toggle']).default('dropdown')
    .describe('Filter control style: "dropdown" (per-field value selectors) or "tabs" (named presets). "toggle" is deprecated.'),
  fields: z.array(UserFilterFieldSchema).optional()
    .describe('Fields exposed as quick filters (dropdown/toggle elements)'),
  tabs: z.array(ViewTabSchema).optional()
    .describe('Named filter presets rendered as tabs (tabs element). Reuses ViewTabSchema'),
  showAllRecords: z.boolean().optional()
    .describe('Show an "All records" tab before the presets (tabs element)'),
  allowAddTab: z.boolean().optional()
    .describe('Let end users add their own tab after the presets (tabs element): the affordance asks for a name and snapshots the filters currently applied as a new tab. SESSION-SCOPED — an added tab lives only for the current mount, is never written back as metadata (ADR-0047), and carries a remove control the authored presets do not. Page lists only — object views use `listViews` for named presets'),
}).describe('End-user quick-filter configuration (Airtable "User filters" parity)'));

/**
 * Add Record Configuration Schema (Airtable Interface parity)
 * Configures the "Add Record" entry point for a list view.
 *
 * @see Airtable Interface → "+ Add record" button
 */
export const AddRecordConfigSchema = lazySchema(() => strictObject({
  surface: 'this add record configuration',
  history: VIEW_HISTORY,
}, {
  enabled: z.boolean().default(true).describe('Show the add record entry point'),
  position: z.enum(['top', 'bottom', 'both']).default('bottom').describe('Position of the add record button'),
  mode: z.enum(['inline', 'form', 'modal']).default('inline').describe('How to add a new record'),
  formView: z.string().optional().describe('Named form view to use when mode is "form" or "modal"'),
}).describe('Add record entry point configuration'));

/**
 * Kanban Settings
 */
export const KanbanConfigSchema = lazySchema(() => strictObject({
  surface: 'this kanban configuration',
  history: VIEW_HISTORY,
}, {
  groupByField: z.string().describe('Field to group columns by (usually status/select)'),
  summarizeField: z.string().optional().describe('Field to sum at top of column (e.g. amount)'),
  columns: z.array(z.string()).describe('Fields to show on cards'),
}));

/**
 * List Chart View Configuration (Airtable-style)
 * Configures aggregate chart visualizations (bar/line/pie/area/scatter)
 * when used as a `type: 'chart'` ListView. Distinct from the full-featured
 * `ChartConfigSchema` in `chart.zod.ts` (which is for embedded reports).
 */
export const ListChartConfigSchema = lazySchema(() => strictObject({
  surface: 'this list chart configuration',
  history: VIEW_HISTORY,
}, {
  /**
   * Narrowed from `ChartTypeSchema` with `.extract()` rather than retyped.
   * Same five members as before — this is a de-duplication, not a widening —
   * but a member renamed in the chart taxonomy now fails here at build time
   * instead of leaving a second list quietly disagreeing with the first.
   */
  chartType: ChartTypeSchema.extract(['bar', 'line', 'pie', 'area', 'scatter'])
    .default('bar').describe('Chart visualisation type'),
  /**
   * ADR-0021 — the semantic-layer `dataset` this chart binds to. Selects
   * dimensions/measures BY NAME so the chart's numbers stay consistent with
   * every other surface using the same dataset. This is the single author-facing
   * shape (the legacy inline `xAxisField` + `yAxisFields` + `aggregation` query
   * was removed in the cutover).
   */
  dataset: SnakeCaseIdentifierSchema.describe('Dataset name to bind (ADR-0021)'),
  /** Dimension names (from the dataset) for X / group / split. */
  dimensions: z.array(z.string()).optional().describe('Dimension names — X/group/split'),
  /** Measure names (from the dataset) for the value axis. */
  values: z.array(z.string()).min(1).describe('Measure names — Y (at least one)'),
}).describe('List chart view configuration'));

/**
 * Calendar Settings
 *
 * [#13817] `startDateField` is the ONLY required key — measured against the
 * one renderer (objectui `plugin-calendar/src/ObjectCalendar.tsx`): an explicit
 * `titleField` wins when present, and in its absence the event title resolves
 * through the ADR-0079 record display-name chain (`titleFormat` →
 * `displayNameField` → type-aware derivation → `"Untitled"`). Requiring
 * `titleField` here would demand more than the renderer reads — the exact
 * shape the #13748 ruling forbids ("do not require more than the renderer
 * actually needs"). The date has no such fallback: without `startDateField`
 * there is nothing truthful to place events by, which is what
 * {@link checkListViewCalendarVisualization} enforces cross-field.
 */
export const CalendarConfigSchema = lazySchema(() => strictObject({
  surface: 'this calendar configuration',
  history: VIEW_HISTORY,
}, {
  startDateField: z.string().describe('Field providing the event start date/time'),
  endDateField: z.string().optional().describe('Field providing the event end date/time (defaults to a single-day event)'),
  titleField: z.string().optional().describe('Field displayed as the event title. Omit to fall back to the record display name (ADR-0079 resolver chain)'),
  colorField: z.string().optional().describe('Field to derive each event color from (it names a field, not a color): the option color declared on that field for the record value, else the value itself when it already is a color literal (hex, rgb() or hsl()), else the calendar theme-aware palette color hashed from the value'),
}));

/**
 * Quick filter dimension for the Gantt toolbar.
 */
export const GanttQuickFilterSchema = lazySchema(() => strictObject({
  surface: 'this gantt quick filter',
  history: VIEW_HISTORY,
}, {
  field: z.string().describe('Record field / dot-path the dimension filters on'),
  label: z.string().optional().describe('Trigger label (falls back to the field label)'),
  options: z.array(z.union([
    z.string(),
    strictObject({
      surface: 'this gantt quick-filter option',
      history: VIEW_HISTORY,
      // Sibling contract: the user-filter option entry two blocks up spells the
      // display text `label` and the stored value `value`. Gantt's entry is the
      // same pair minus `color`, so the same near-misses apply.
      aliases: { text: 'label', title: 'label', name: 'label', key: 'value', id: 'value' },
    }, {
      value: z.union([z.string(), z.number()]),
      label: z.string().optional(),
    }),
  ])).optional().describe('Explicit option override for fixed enums'),
}));

/**
 * Gantt Settings
 *
 * Beyond the core timeline fields, the renderer supports a two-level
 * parent/child hierarchy (parentField/typeField), planned-vs-actual baselines,
 * dynamic grouping, a resource/workload view, hover tooltips and quick filters.
 *
 * CLOSED against unknown keys (#15469). This block used to end in
 * `.passthrough()` so renderer-ahead knobs could reach objectui's plugin-gantt
 * without a spec release. That window is shut: a `strictObject` applied and
 * then undone is two contracts on one surface (Prime Directive #12), and a
 * mistyped key (`colourField`) parsed green and rendered an uncoloured bar —
 * the exact silent class the calendar / timeline / map blocks already refuse.
 * The ten members the renderer read through the window
 * (`GANTT_CONFIG_EXTENSION_KEYS` in objectui `plugin-gantt/src/ObjectGantt.tsx`;
 * types from `GanttConfigExtensionFields` in `@object-ui/types/zod`, measured
 * at objectui pin `a472b07`) are declared below under "objectui-lifted
 * members", each at the type the renderer reads. A renderer knob now needs
 * its declaration here FIRST.
 */
export const GanttConfigSchema = lazySchema(() => strictObject({
  surface: 'this gantt configuration',
  history: VIEW_HISTORY,
}, {
  startDateField: z.string().describe('Field providing the task start date'),
  endDateField: z.string().describe('Field providing the task end date'),
  titleField: z.string().describe('Field displayed as the task title'),
  progressField: z.string().optional().describe('Field providing the task completion percentage'),
  dependenciesField: z.string().optional().describe("Field listing the task's predecessor (dependency) record ids"),
  colorField: z.string().optional().describe('Field to derive each bar color from (it names a field, not a color): the option color declared on that field for the record value, else the value itself when it already is a color literal (hex, rgb() or hsl()), else a semantic color token derived from the value'),
  // Two-level hierarchy: a parent task id (summary bar) and a row type.
  parentField: z.string().optional().describe('Field holding the parent task id (builds the summary → step tree)'),
  typeField: z.string().optional().describe('Field whose value maps to task/summary/milestone'),
  // Planned-vs-actual reference bars.
  baselineStartField: z.string().optional().describe('Baseline (planned) start field'),
  baselineEndField: z.string().optional().describe('Baseline (planned) end field'),
  // Dynamic grouping: bucket leaf tasks under one synthesized summary per value.
  groupByField: z.string().optional().describe('Field to group leaf tasks by (synthesized summary rows)'),
  // Resource / workload view.
  resourceView: z.boolean().optional().describe('Render a per-resource workload histogram instead of the timeline'),
  assigneeField: z.string().optional().describe('Resource field to bucket load by (resource view)'),
  effortField: z.string().optional().describe('Per-task load units (resource view; default 1)'),
  capacity: z.number().optional().describe('Per-resource capacity ceiling; loads above this flag overload'),
  // Hover tooltip + quick filters.
  tooltipFields: z.array(z.union([
    z.string(),
    strictObject({
      surface: 'this gantt tooltip field',
      history: VIEW_HISTORY,
      // This entry is a closed `{ field, label }` pair — exactly the shape
      // objectui's `GanttView` tooltip resolver reads. 批 18 closed it while
      // the PARENT was still `.passthrough()`, because strictness is per
      // object, not per subtree (the nested hole 批 13 found on `responsive`);
      // #15469 closed the parent too, so the whole gantt block is now one
      // posture.
      aliases: { name: 'field', fieldName: 'field', text: 'label', title: 'label' },
    }, { field: z.string(), label: z.string().optional() }),
  ])).optional().describe('Fields to surface in the hover tooltip, in display order'),
  quickFilters: z.array(GanttQuickFilterSchema).optional().describe('Multi-select filter dropdowns rendered above the chart'),
  autoZoomToFilter: z.boolean().optional().describe('When true (default), filtering zooms the range to the filtered tasks'),
  // Timeline granularity. The member list is measured from the renderer
  // (objectui plugin-gantt GanttView.tsx: GanttViewMode / VIEW_MODES), not
  // invented here. No spec-side `.default()` on purpose: the renderer's
  // absence behaviour is not a constant — an omitted `viewMode` lets a
  // persisted layout seed the granularity before falling back to 'day', so a
  // materialized default would read as an explicit author choice and defeat
  // that seeding (same reasoning as the map block's defaultless `zoom`/`center`).
  viewMode: z.enum(['day', 'week', 'month', 'quarter', 'year']).optional().describe("Timeline granularity — one column per day/week/month/quarter/year (also the resource-view column granularity; renderer default 'day')"),
  // ── objectui-lifted members (#15469) ──────────────────────────────────────
  // The ten keys plugin-gantt read through the former `.passthrough()` window,
  // declared at the types objectui's `GanttConfigExtensionFields` carries (pin
  // a472b07) so the two authoring faces derive from ONE vocabulary. All
  // optional; each describe says what the renderer does with the key.
  borderColorField: z.string().optional().describe('Field carrying a per-task alert stroke color — any CSS color or semantic palette name (red, orange, …): the bar keeps its fill and gains an outline plus halo in that color (e.g. red for overdue, orange for due-soon; typically a server-computed alert field). Empty or null means no stroke'),
  lockField: z.string().optional().describe('Field marking a row view-only (truthy means locked): a locked bar cannot be dragged or resized, its progress cannot be dragged, no dependency can be drawn from it and its inline-edit and edit/delete menu entries are hidden — clicking it (open drawer, jump) still works. Independent of the global readOnly; freezes individual levels while siblings stay editable'),
  objectField: z.string().optional().describe("Field carrying the row's OWN object API name, for mixed-object trees (an api provider composing parent-object rows with child-object rows): the detail drawer and its full-page link follow each row's real object instead of the view's bound object. Empty or missing falls back to the bound object"),
  summaryExtent: z.enum(['children', 'self']).optional().describe("How a summary bar's span is computed. 'children' (renderer default) rolls the bar up from its children — min start, max end, duration-weighted progress — and ignores the record's own dates; 'self' renders the record's OWN start, end and progress and falls back to rollup only for records without dates (use it when the parent's schedule is authoritative, e.g. a shift plan whose work-order children are locked history)"),
  defaultCollapsedDepth: z.number().int().min(0).optional().describe('Auto-collapse tree nodes at or below this 0-indexed depth on first render (roots are depth 0): every node at that depth or deeper that has children starts folded; the user can still expand them. Omit to start fully expanded'),
  dependencyTypes: z.boolean().optional().describe('Whether the backing store persists dependency link TYPES (fs, ss, ff, sf); renderer default true. Set false when dependencies are bare predecessor ids: the link menu hides the type switcher (a switch would be silently reverted on refetch) and drag-created links are always finish-to-start'),
  timeZone: z.string().optional().describe("Business time zone, an IANA name such as 'Asia/Shanghai': the chart's calendar — shift bands, day columns, snapping, the today line, date labels — renders in this zone's wall time for every viewer instead of the browser's zone; persisted data stays real instants. An invalid name falls back to the browser zone with a console warning"),
  exportFileName: z.string().optional().describe("Base name for exported PNG and PDF files (e.g. the view's display label — the host's view schema often reaches the renderer stripped of label); falls back to the object schema label, then the object API name. A timestamp suffix is always appended"),
  interactions: strictObject({
    surface: 'this gantt interactions block',
    history: VIEW_HISTORY,
    aliases: { drag: 'move', dependencies: 'link', links: 'link' },
  }, {
    move: z.boolean().optional().describe('Bar and subtree dragging along the timeline (default true)'),
    resize: z.boolean().optional().describe('Edge resize grips that change a duration (default true)'),
    progress: z.boolean().optional().describe('The progress drag handle (default true)'),
    link: z.boolean().optional().describe('Dependency UI — the drag-to-link dots and the create/delete menu entries (default true)'),
  }).optional().describe('Per-interaction switches, each defaulting to true: allow bar moves but pin durations (resize: false), or keep the dependency UI read-only (link: false). They only narrow what readOnly and row locks already allow'),
  timeSegments: strictObject({
    surface: 'this gantt time-segments block',
    history: VIEW_HISTORY,
    aliases: { segments: 'bands', shifts: 'bands' },
  }, {
    dayStart: z.string().optional().describe("Clock time the shift-day begins, 'HH:mm' (24h); the day column starts here and runs 24h. Renderer default '00:00' (calendar day); for an 08:00 handover set '08:00'"),
    bands: z.array(strictObject({
      surface: 'this gantt shift band',
      history: VIEW_HISTORY,
      aliases: { name: 'label', title: 'label', from: 'start', to: 'end' },
    }, {
      key: z.string().optional().describe("Stable band id (e.g. 'day', 'night'); the renderer defaults to band plus the index"),
      label: z.string().describe('Display label for the band header (e.g. Day shift, Night shift)'),
      start: z.string().describe("Band start, 'HH:mm' (24h)"),
      end: z.string().describe("Band end, 'HH:mm'; when end is not after start the band crosses midnight"),
      color: z.string().optional().describe('Accent color (any CSS color) for the column tint'),
    })).describe('Ordered bands covering the 24h shift-day, beginning at dayStart'),
    showMidnight: z.boolean().optional().describe('Draw the dashed calendar-midnight (00:00) cue inside cross-midnight bands; renderer default true'),
  }).optional().describe('Shift segmentation for the day-mode timeline: splits each shift-day (starting at dayStart) into the configured bands — a two-tier header (date over band), per-band tints and drag/resize snapping to band boundaries. No shift concept is hardcoded; bands are pure config. Off when omitted'),
// Closed at #15469 (maintainer ruling A on the card, 2026-09-05): the
// renderer-ahead `.passthrough()` window that used to end this block is shut —
// an undeclared key is refused with the same named error the sibling view
// configs give, and a renderer knob is declared HERE before it is read.
}));

/**
 * Tree (tree-grid) Settings
 *
 * Renders a self-referencing object as an indented, expand/collapse tree-grid.
 * Flat records are nested via a single-parent pointer field (`parentField`).
 * Unlike a fixed-depth `grouping`, a tree handles arbitrary depth (org charts,
 * category trees, BOMs, nested comments). When `parentField` is omitted the
 * renderer auto-detects the object's `tree`/self-reference field.
 */
export const TreeConfigSchema = lazySchema(() => strictObject({
  surface: 'this tree configuration',
  history: VIEW_HISTORY,
}, {
  parentField: z.string().optional().describe('Single-parent pointer field (auto-detected from the object schema when omitted)'),
  labelField: z.string().optional().describe('Field rendered indented in the first column (defaults to "name")'),
  fields: z.array(z.string()).optional().describe('Additional fields rendered as flat columns alongside the label'),
  defaultExpandedDepth: z.number().int().min(0).optional().describe('Initial expansion depth (0 = roots only; omit = expand all)'),
// Closed at #15469 (same ruling as the gantt block above): the renderer-ahead
// `.passthrough()` window is shut. Measured before closing, at objectui pin
// a472b07: plugin-tree's `getTreeConfig` reads exactly the four keys declared
// here from the `tree` block — the undeclared read set was EMPTY, so the close
// declares nothing new and refuses only what no renderer ever read.
}));

/**
 * Map View Settings
 *
 * Configures the geospatial (`type: 'map'`) list view: which fields provide
 * marker coordinates and text, and the initial camera. The key set mirrors the
 * map renderer's documented config surface (objectui `plugin-map`, read by
 * `getMapConfig` in `ObjectMap.tsx` and documented in
 * `content/docs/plugins/plugin-map.mdx`) — every key here has a live read
 * there, and no renderer knob is admitted without one. Coordinates come from
 * either a `latitudeField`/`longitudeField` pair or a single combined
 * `locationField`; when no camera is declared the renderer fits the camera to
 * the queried records, which is why `zoom`/`center` carry no defaults — a
 * spec-side default would read as a declared camera and defeat that fit.
 *
 * Named `ListMapConfigSchema`, not `MapConfigSchema`: the `map` FLOW-NODE
 * config in `automation/builtin-node-config.zod.ts` already exports that name
 * (same collision, same resolution as `ListChartConfigSchema` vs the
 * `chart.zod.ts` `ChartConfigSchema`).
 *
 * Closed (strict) from the start: the map renderer's read set is itself closed
 * — it validates `schema.map` against a local zod schema with exactly these
 * keys, so an extra key here would be dropped there. The gantt / tree blocks
 * above used to be this file's two `.passthrough()` exceptions (renderer-ahead
 * knobs); #15469 closed both, so every view config block here now refuses an
 * unknown key the same way. Strict means a misspelling is a loud parse error
 * instead of a marker silently falling back to default field names.
 */
export const ListMapConfigSchema = lazySchema(() => strictObject({
  surface: 'this map configuration',
  history: VIEW_HISTORY,
}, {
  latitudeField: z.string().optional().describe('Field providing the marker latitude (used with longitudeField)'),
  longitudeField: z.string().optional().describe('Field providing the marker longitude (used with latitudeField)'),
  locationField: z.string().optional().describe('Field providing a combined location — a "lat,lng" string or a { lat, lng } object — as the alternative to the latitudeField/longitudeField pair'),
  titleField: z.string().optional().describe('Field displayed as the marker title (popup heading, mobile record card, and what the map search box matches on)'),
  descriptionField: z.string().optional().describe('Field displayed as the marker description'),
  zoom: z.number().min(1).max(20).optional().describe('Initial zoom level (1-20). Omit to let the renderer fit the camera to the queried records'),
  center: z.tuple([z.number(), z.number()]).optional().describe('Initial camera center as [latitude, longitude]. Omit to let the renderer fit the camera to the queried records'),
}).describe('Map view configuration'));

/**
 * Navigation Mode Enum
 * Defines how to navigate to the detail view from a list item.
 */
export const NavigationModeSchema = lazySchema(() => z.enum([
  'page',       // Navigate to a new route (default)
  'drawer',     // Open details in a side drawer/panel
  'modal',      // Open details in a modal dialog
  'split',      // Show details side-by-side with the list (master-detail)
  'popover',    // Show details in a popover (lightweight)
  'new_window', // Open in new browser tab/window
  'none'        // No navigation (read-only list)
]));

/**
 * Navigation Configuration Schema
 */
export const NavigationConfigSchema = lazySchema(() => strictObject({
  surface: 'this navigation configuration',
  history: VIEW_HISTORY,
}, {
  mode: NavigationModeSchema.default('page'),
  
  /** Target View Config */
  view: z.string().optional().describe('Name of the form view to use for details (e.g. "summary_view", "edit_form")'),
  
  /** Interaction Triggers */
  preventNavigation: z.boolean().default(false).describe('Disable standard navigation entirely'),
  openNewTab: z.boolean().default(false).describe('Force open in new tab (applies to page mode)'),
  
  /**
   * [#2578] Overlay size for a drawer/modal detail — coarse T-shirt buckets,
   * aligned with `FormView.modalSize` (`page` mode ignores it). `'auto'`
   * (default): the renderer derives the size from the object's field count and
   * clamps it to the client viewport, so AI writes nothing — it cannot know the
   * client width. Explicit buckets are a coarse, viewport-independent override.
   */
  size: z.enum(['auto', 'sm', 'md', 'lg', 'xl', 'full']).default('auto')
    .describe("Overlay size bucket for drawer/modal detail: 'auto' (default — renderer derives from field count + viewport; AI writes nothing) or a coarse override sm/md/lg/xl/full. Prefer this over the pixel `width`; page mode ignores it."),

  /**
   * @deprecated [#2578 → `size`] A pixel/percent width cannot be authored blind:
   * the author (often an AI) does not know the client viewport. Kept only as a
   * renderer fallback for pre-#2578 metadata; new metadata sets `size` (or omits
   * it for `auto`).
   */
  width: z.union([z.string(), z.number()]).optional().describe('[DEPRECATED → size] Pixel/percent width of the drawer/modal (e.g. "600px"). A pixel width cannot be chosen at authoring time without knowing the client viewport — use the `size` bucket.'),
}));

// `'pdf'` retirement prescription (#8010). Declared with `//` on purpose — the
// hook-body precedent's placement note applies here too: build-docs takes a
// file's first JSDoc per exported symbol, and this constant needs no doc page.
const LIST_VIEW_EXPORT_PDF_RETIRED =
  "'pdf' was removed from `view.exportOptions` formats in @objectstack/spec 17.0.0 "
  + '(PDF export itself was declined as NOT PLANNED) — no renderer has ever produced a PDF '
  + 'export: ObjectGrid dropped the declared format from the export menu with only a runtime '
  + "console.warn, so authoring it was a parse-clean no-op. Delete the value; the surviving "
  + "formats are 'csv', 'xlsx' and 'json'. "
  + 'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.';

/**
 * Export formats the platform actually delivers (#8010): `csv`/`json` on both
 * export paths, `xlsx` on the server stream only.
 *
 * `'pdf'` was REMOVED in 17 (#8010): PDF export was declined platform-side
 * (#1301 NOT_PLANNED), so the enum member was a declared-but-unrenderable
 * format whose only failure signal was a browser console line. This is an
 * enum-VALUE narrowing, so there is no `retiredKey()` tombstone to hang the
 * prescription on — the enum's own error map carries it
 * ({@link LIST_VIEW_EXPORT_PDF_RETIRED}), keyed on `issue.input` so that only
 * the value which used to be legal gets the "was removed" message (the
 * `HookBodyCapability` / `object.managedBy: 'system'` precedent).
 */
const ListViewExportFormatSchema = z.enum(['csv', 'xlsx', 'json'], {
  error: (issue) => (issue.input === 'pdf' ? LIST_VIEW_EXPORT_PDF_RETIRED : undefined),
});

/**
 * Object form of `view.exportOptions` (#8010, maintainer ruling 2026-08-12 —
 * option A). The declared key set is exactly what the only renderer reads,
 * measured on objectui `origin/main@878140b` (`ObjectGrid.tsx:1596–1642`):
 * `formats`, `maxRecords`, `includeHeaders`, `fileNamePrefix`, and the
 * previously UNDECLARED `streaming` opt-out — declared here so no
 * undeclared-but-read key survives the fix. Declaring anything more would be
 * capability surface with no reader; declaring less recreates the defect.
 */
const ListViewExportOptionsSchema = strictObject({
  surface: 'this export options block',
  history: VIEW_HISTORY,
}, {
  formats: z.array(ListViewExportFormatSchema).optional()
    .describe("Formats offered in the export menu (default: ['csv', 'json']). XLSX is delivered by the server stream only."),
  maxRecords: z.number().int().nonnegative().optional()
    .describe('Maximum number of records to export; 0 or absent = unlimited'),
  includeHeaders: z.boolean().optional()
    .describe('Include column headers in the exported file (default true)'),
  fileNamePrefix: z.string().optional()
    .describe('Download file name prefix — replaces the object label and suppresses the view label in the generated file name'),
  streaming: z.boolean().optional()
    .describe('Set false to force the client-side export path (csv/json only) instead of the server stream'),
});

/**
 * Loud top-level refusal for a retired `'pdf'` anywhere in `exportOptions`
 * (#8010). Without this, the prescription raised inside a union BRANCH is
 * buried in `invalid_union` sub-errors; with it, the union's own message IS
 * the prescription whenever the authored value — either spelling — declares
 * `'pdf'`. Every other union failure keeps zod's default message, with the
 * branch detail nested beneath it.
 */
const exportOptionsPdfUnionError = (issue: { input?: unknown }): string | undefined => {
  const input = issue.input;
  const declaresPdf = Array.isArray(input)
    ? input.includes('pdf')
    : (!!input && typeof input === 'object'
        && Array.isArray((input as { formats?: unknown }).formats)
        && ((input as { formats: unknown[] }).formats).includes('pdf'));
  return declaresPdf ? LIST_VIEW_EXPORT_PDF_RETIRED : undefined;
};

/**
 * [#13216] The `type: 'page'` mount refusals, in BOTH directions.
 *
 * `page` is the one member of the view `type` enum that renders nothing of its
 * own: every other member describes how to draw the object's ROWS, and degrades
 * to a wrong-but-visible list when its config block is missing (which is why
 * `checkViewCompleteness`'s `VIEW_BINDING_BLOCKS` treats those as WARNINGs — the
 * renderer falls back to literal default field names). A `page` view has no
 * rows to fall back to: without `pageName` there is no page to hand the page
 * renderer, so the view is not "degraded", it is empty. Nothing weaker than a
 * parse refusal is honest about that, and the refusal is why `page` is
 * deliberately absent from `VIEW_BINDING_BLOCKS` — see the note there.
 *
 * The reverse direction matters just as much and is the cheaper mistake to
 * make: `pageName` on a `grid` (or any non-`page`) view is accepted-and-ignored,
 * the failure mode this file's `VIEW_HISTORY` exists to record and the one that
 * reads as working to whoever authored it — human or model.
 *
 * ## Why `columns` is checked here and the other inert keys are not
 *
 * `columns` is the ONLY required key on {@link ListViewSchema}, so a `page` view
 * cannot be authored without writing one, and the only truthful value is `[]`.
 * Leaving that unchecked would mean the platform forces an author to write a
 * value and then ignores what they wrote. The optional type-specific blocks
 * (`kanban` on a grid view, `chart` on a tree view, …) are NOT checked, here or
 * anywhere: tolerating a stale optional block is this schema's standing
 * disposition, and narrowing it is a separate decision about every view type,
 * not a rider on this one.
 *
 * ⛔ `columns` is NOT made optional to spare the author the `[]`. The list and
 * form overlay arms of {@link ViewMetadataSchema} are told apart by exactly two
 * properties — "no required `columns`, disjoint `type` enum" — and the list arm
 * is tried FIRST, so an optional `columns` would let a flattened FORM overlay
 * that carries no explicit `type` match the LIST arm, default to `'grid'`, and
 * have its `sections` silently stripped by that arm's `.strip()`.
 */
const VIEW_PAGE_MOUNT_NEEDS_PAGE_NAME =
  "A `type: 'page'` view mounts a published page and has no rows of its own, so it needs to say "
  + 'WHICH page: declare `pageName`. Unlike every other view type there is no fallback rendering — '
  + "without it the view is blank. Shape: `{ type: 'page', pageName: '<page_name>', columns: [] }`.";

const VIEW_PAGE_NAME_NEEDS_PAGE_TYPE =
  "`pageName` is only read by a `type: 'page'` view (it names the published page that view mounts). "
  + 'On any other view type it is accepted and never applied — the view renders as its own type and '
  + "the page is never reached. Set `type: 'page'` to mount the page, or remove `pageName`.";

const VIEW_PAGE_MOUNT_HAS_COLUMNS =
  "A `type: 'page'` view renders the page named by `pageName`, not a column list — the declared "
  + 'columns are never read. `columns` is required on every list view, so write the empty list: '
  + '`columns: []`. (To show records in columns, use a row-rendering view type — `grid` and its '
  + 'siblings — or let the page itself declare the list it wants.)';

/**
 * The `type` ⇄ `pageName` binding check attached to {@link ListViewSchema}.
 *
 * Attached with `.superRefine` rather than being folded into the shape because
 * it is a relation BETWEEN two keys. Zod 4 attaches refinements to the schema
 * itself, so `.extend()` and `.omit()` carry it — which is what puts this check
 * on the flattened runtime overlay arm ({@link ViewMetadataSchema} member 3,
 * the door a Studio tenant or an MCP/AI author writes through) and on
 * {@link ObjectListViewSchema} (`objects[].listViews.*`) without a second copy.
 */
function checkListViewPageMount(
  view: { type?: string; pageName?: string; columns?: unknown },
  ctx: z.RefinementCtx,
): void {
  const isPageMount = view.type === 'page';
  const hasPageName = typeof view.pageName === 'string' && view.pageName.length > 0;

  if (isPageMount && !hasPageName) {
    ctx.addIssue({ code: 'custom', path: ['pageName'], message: VIEW_PAGE_MOUNT_NEEDS_PAGE_NAME });
  }
  if (!isPageMount && hasPageName) {
    ctx.addIssue({ code: 'custom', path: ['pageName'], message: VIEW_PAGE_NAME_NEEDS_PAGE_TYPE });
  }
  if (isPageMount && Array.isArray(view.columns) && view.columns.length > 0) {
    ctx.addIssue({ code: 'custom', path: ['columns'], message: VIEW_PAGE_MOUNT_HAS_COLUMNS });
  }
}

const VIEW_CALENDAR_ALLOWED_NEEDS_START_DATE =
  "`appearance.allowedVisualizations` includes 'calendar', so end users can switch this view to a "
  + 'calendar — but no `calendar:` block says which field supplies the event date. There is no '
  + 'truthful fallback: a date guessed by the renderer lands every record without that field on '
  + '"today", a plausible-looking, fully wrong screen. Declare `calendar: { startDateField: '
  + "'<date_field>' }` — only `startDateField` is required; the event title falls back to the "
  + "record display name (ADR-0079) — or remove 'calendar' from `allowedVisualizations`.";

/**
 * [#13817] The `appearance.allowedVisualizations` ⇄ `calendar` binding check —
 * ruled on #13748 (2026-08-31, option A "fix both halves"; this is the spec
 * half, objectui#7029 is the runtime half).
 *
 * A view declaring `appearance.allowedVisualizations: [... 'calendar']` with no
 * `calendar:` block used to parse clean; the switcher then rendered a clickable
 * calendar toggle, objectui invented `startDateField: 'due_date'`, and every
 * record without that field piled onto "today" (measured on hotcrm pinned at
 * `@objectstack/* 17.1.0` — all 9 leave requests on one cell). The renderer's
 * own refusal screen was unreachable because the synthesized config always
 * looked complete. Loud-over-silent: refuse at parse, naming the missing key.
 *
 * Only the block's `startDateField` is load-bearing — see the measurement note
 * on {@link CalendarConfigSchema} (it is that schema's one required key, so
 * requiring the block IS requiring `calendar.startDateField` and nothing more).
 *
 * ⚠️ Scope: `calendar` only — the measured defect. Whether `timeline` or
 * 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).
 *
 * 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
 * authoring terminal, `objects[].listViews.*`, and the flattened runtime
 * overlay arm — the door a Studio tenant or an MCP/AI author writes through.
 */
function checkListViewCalendarVisualization(
  view: { appearance?: { allowedVisualizations?: unknown } | null; calendar?: unknown },
  ctx: z.RefinementCtx,
): void {
  const allowed = view.appearance?.allowedVisualizations;
  if (!Array.isArray(allowed) || !allowed.includes('calendar')) return;
  if (view.calendar === undefined) {
    ctx.addIssue({
      code: 'custom',
      path: ['calendar'],
      message: VIEW_CALENDAR_ALLOWED_NEEDS_START_DATE,
    });
  }
}

/**
 * List View Schema (Expanded)
 * Defines how a collection of records is displayed to the user.
 *
 * **NAMING CONVENTION:**
 * View names (when provided) are machine identifiers and must be lowercase snake_case.
 * 
 * @example Standard Grid
 * {
 *   name: "all_active",
 *   label: "All Active",
 *   type: "grid",
 *   columns: ["name", "status", "created_at"],
 *   filter: [["status", "=", "active"]]
 * }
 * 
 * @example Kanban Board
 * {
 *   type: "kanban",
 *   columns: ["name", "amount"],
 *   kanban: {
 *     groupByField: "stage",
 *     summarizeField: "amount",
 *     columns: ["name", "close_date"]
 *   }
 * }
 */
/**
 * The unrefined SHAPE behind {@link ListViewSchema}, module-private.
 *
 * Split out for exactly one reason: zod 4 refuses `.omit()` on an object schema
 * that carries refinements (`".omit() cannot be used on object schemas
 * containing refinements"`, thrown at construction), and
 * {@link ObjectListViewSchema} is built by omitting `userFilters` from this
 * shape. So the shape stays refinement-free and BOTH terminals attach
 * {@link checkListViewPageMount} themselves — one check function, two
 * attachment points, no second copy of the rule.
 *
 * ⛔ Not exported, deliberately: a top-level EXPORTED schema binding mints a
 * new protocol def in `json-schema.manifest/` and a full set of ratcheted
 * `authorable-surface/` keys, so publishing this shape would duplicate every
 * `ui/ListView` key under a second name (the same argument
 * {@link VIEW_METADATA_MEMBERS} records for the union's members).
 */
const ListViewShapeSchema = lazySchema(() => strictObject({
  surface: 'this list view',
  history: VIEW_HISTORY,
  guidance: {
    // [#9933] Runtime-only overlay key, deliberately NOT declared here: this
    // is the AUTHORING shape, and column order/widths are per-user state the
    // console grid writes through the `view` metadata API (objectui's
    // `gridNonAuthorKeys` disposition). The overlay-validation face declares
    // it (`flattenedViewOverlayFields` / `viewItemWireFields`); an author who
    // writes it here gets this prescription instead of a bare typo suggestion.
    columnState: 'Column order/widths are per-user runtime personalization the console grid writes through the `view` metadata API — not authored metadata. Remove it from authored metadata.',
  },
}, {
  name: SnakeCaseIdentifierSchema.optional().describe('Internal view name (lowercase snake_case)'),
  label: I18nLabelSchema.optional(), // Display label override (supports i18n)
  type: z.enum([
    'grid',       // Standard Data Table
    'kanban',     // Board / Columns
    'gallery',    // Card Deck / Masonry
    'calendar',   // Monthly/Weekly/Daily
    'timeline',   // Chronological Stream (Feed)
    'gantt',      // Project Timeline
    'map',        // Geospatial
    'chart',      // Aggregate visualisation
    'tree',       // Self-referencing hierarchy (tree-grid)
    'page'        // Mount an already-published `page` — see `pageName` below
  ]).default('grid'),
  
  /** Data Source Configuration */
  data: ViewDataSchema.optional().describe('Data source configuration (defaults to "object" provider)'),
  
  /** Shared Query Config */
  columns: z.union([
    z.array(z.string()), // Legacy: simple field names
    z.array(ListColumnSchema), // Enhanced: detailed column config
  ]).describe('Fields to display as columns'),
  filter: z.array(ViewFilterRuleSchema).optional().describe('Filter criteria (JSON Rules)'),
  /**
   * Sort order. Prefer the structured `{ field, order }[]` form.
   *
   * @deprecated The bare string form (`"field desc"`) is legacy and retained
   * only for backward compatibility (it was the exact shape that crashed the
   * renderer in objectui#2601 — kept covered by a live fixture). Removal will
   * go through its own deprecation cycle; do not drop it here.
   */
  /**
   * ⚠️ [#5074] CLOSED — the entry is the authoring shape and rejects the
   * console's row `id`. 批 18 closed it, hit a live 422, and reverted (#5070);
   * that revert was explicitly provisional pending this split.
   *
   * The close carries `direction → order`, the #4721 alias for the identical
   * tuple: `{ field, direction: 'desc' }` used to parse to `{ field, order:
   * 'asc' }` — a silently REVERSED sort, which is the reason closing this entry
   * was worth doing at all.
   *
   * What made the first attempt a regression: `view-metadata-schema.test.ts`
   * pins `sort: [{ id, field, order }]` as *"the exact shape
   * normalizeViewMetadata persists on a console column-sort PUT"*, and `id` is
   * a UI row identity objectui stamps per row
   * (`components/src/custom/sort-builder.tsx:68`, `:94` —
   * `crypto.randomUUID()`), persisted verbatim because `saveMetaItem` stores the
   * original body. **`.strip()` on a wire member could not rescue it** — it
   * re-opens the TOP level only, and this is a nested block reached through that
   * member. See {@link stripViewConsoleDecorations}, which removes the
   * decoration on the wire door instead, at every depth.
   *
   * `id` is still NOT declared: it is a React list key, and declaring it would
   * put a UI artifact on the authorable surface and teach an AI author to emit
   * one (批 18 Q1, two-axis rejection on record).
   */
  sort: z.union([
    z.string(), //Legacy "field desc"
    z.array(strictObject({
      surface: 'this sort entry',
      history: VIEW_HISTORY,
      aliases: {
        // #4721: the same tuple under a different word. Edit distance cannot
        // reach it, and getting it wrong reverses the sort silently.
        direction: 'order',
      },
      guidance: {
        id: VIEW_CONSOLE_ROW_ID_GUIDANCE,
      },
    }, {
      field: z.string(),
      order: z.enum(['asc', 'desc'])
    }))
  ]).optional(),
  
  /** Search & Filter */
  searchableFields: z.array(z.string()).optional().describe('Fields enabled for search'),
  filterableFields: z.array(z.string()).optional().describe('Legacy shorthand for userFilters.fields — bare field names enabled for end-user filtering. Prefer userFilters'),

  /** User Filters (ADR-0047, Airtable Interface parity) */
  userFilters: UserFiltersSchema.optional()
    .describe('End-user quick-filter bar: dropdown/toggle fields or tab presets. Omit to let the renderer derive filters from select/boolean fields'),

  /** Grid Features */
  resizable: z.boolean().optional().describe('Enable column resizing'),
  // `striped` / `bordered` — tombstoned at the bottom of this shape with
  // `virtualScroll` (#7176, pass-through-only; see the retired block below).
  compactToolbar: z.boolean().optional().describe('Collapse Group/Color/Density/Hide-fields into a single View settings popover'),

  /** Selection */
  selection: SelectionConfigSchema.optional().describe('Row selection configuration'),

  /** Navigation / Interaction */
  navigation: NavigationConfigSchema.optional().describe('Configuration for item click navigation (page, drawer, modal, etc.)'),

  /** Pagination */
  pagination: PaginationConfigSchema.optional().describe('Pagination configuration'),

  /** Type Specific Config */
  kanban: KanbanConfigSchema.optional().describe('Kanban-board configuration — applies when the view renders as a kanban layout'),
  calendar: CalendarConfigSchema.optional().describe('Calendar configuration — applies when the view renders as a calendar layout'),
  gantt: GanttConfigSchema.optional().describe('Gantt-timeline configuration — applies when the view renders as a gantt layout'),
  gallery: GalleryConfigSchema.optional(),
  timeline: TimelineConfigSchema.optional(),
  chart: ListChartConfigSchema.optional(),
  map: ListMapConfigSchema.optional().describe('Map configuration — applies when the view renders as a map layout'),
  tree: TreeConfigSchema.optional().describe('Tree/hierarchy configuration — applies when the view renders as a tree layout'),

  /**
   * The published `page` a `type: 'page'` view mounts.
   *
   * Named `pageName` because that is what a page reference is already called on
   * every other surface that carries one — `PageNavItemSchema.pageName` in
   * `app.zod.ts`, the collection it resolves against (`stack.pages`), and the
   * lint rule that resolves it (`nav-target-unresolved`). A second spelling for
   * the same reference would split the one thing an author has to learn.
   *
   * Grammar is {@link SnakeCaseIdentifierSchema} — the SAME schema
   * `PageSchema.name` is declared with — rather than the bare `z.string()`
   * the nav item uses, so the set of values this key accepts is exactly the set
   * of strings that could name a page. A `pageName` outside that grammar names
   * nothing that can exist, and saying so at parse is cheaper than resolving it
   * against a collection. (The nav item stays a bare string: its targets may be
   * `${…}`-interpolated at render time, which a view mount has no path to.)
   *
   * Existence of the target is a separate question with its own answers, on the
   * doors that can see the collection: `defineStack`'s `validateCrossReferences`
   * (build-time, throws) and `validateViewPageRefs` in `@objectstack/lint`
   * (the CLI commands and the runtime publish gate).
   */
  pageName: SnakeCaseIdentifierSchema.optional().describe(
    "Published page this view mounts — required when `type: 'page'`, and refused on every other view type. "
    + 'Rendering is delegated to the existing page renderer; the page keeps its own `assignedProfiles` audience.',
  ),

  /** View Metadata (Airtable-style view management) */
  description: I18nLabelSchema.optional().describe('View description for documentation/tooltips'),
  sharing: ViewSharingSchema.optional().describe('View sharing and access configuration'),

  /** Row Height / Density (Airtable-style) */
  rowHeight: RowHeightSchema.optional().describe('Row height / density setting'),

  /** Record Grouping (Airtable-style) — server-side, see {@link GroupingConfigSchema} (#14556). */
  grouping: GroupingConfigSchema.optional().describe('Group records by one or more fields — server-side: the groups and their header numbers come from an aggregate query over the whole filtered set, rows within a group are paged (see GroupingConfigSchema)'),

  /** Row Color (Airtable-style) */
  rowColor: RowColorConfigSchema.optional().describe('Color rows based on field value'),

  /** Field Visibility & Ordering per View (Airtable-style) */
  hiddenFields: z.array(z.string()).optional().describe('Fields to hide in this specific view'),
  fieldOrder: z.array(z.string()).optional().describe('Explicit field display order for this view'),

  /** Row & Bulk Actions */
  rowActions: z.array(z.string()).optional().describe('Actions available for individual row items'),
  bulkActions: z.array(z.string()).optional().describe('Actions available when multiple rows are selected'),
  bulkActionDefs: z.array(BulkActionDefSchema).optional().describe(
    'Rich bulk action definitions (schema-driven, executed via BulkActionDialog). Use a def for a '
    + "mass data-plane mutation ('update' with a `patch` / 'delete') that no action expresses, or for "
    + "an `operation: 'custom'` + `execution: 'aggregate'` entry that dispatches the "
    + 'action it NAMES once for the whole selection — the renderer injects `params._selectedIds: '
    + 'string[]` (read that on the server, not `recordId`) so a single call can produce one aggregate '
    + 'artifact (zip of QR codes, merged PDF, batch print). Aggregate results are all-or-nothing: a '
    + 'handler that cannot cover the whole selection must reject, and per-row retry is replaced by '
    + 're-running the action. `batchSize` does not apply (the call is never chunked); set `maxRecords` '
    + "on defs whose server work is expensive. For the PER-RECORD dispatch use `bulkActions: ['<name>']` "
    + 'instead — the bare-string form, promoted with the action\'s own label, params and `visible`; a '
    + "'custom' def without `execution: 'aggregate'` has no dispatcher and is refused at parse time"
    + '. Toolbar url/api actions can also interpolate the current selection via '
    + '`${ctx.selection.ids}` / `${ctx.selection.count}`.',
  ),

  /** Conditional Formatting */
  conditionalFormatting: z.array(strictObject({
    surface: 'this conditional formatting rule',
    history: VIEW_HISTORY,
    // `visibleWhen` is the ADR-0089 spelling for a predicate on view/page, so
    // an author borrowing it here is using a neighbouring surface's correct
    // word — the `visibleWhen → visible` category #3746 named, not a typo.
    aliases: { when: 'condition', expression: 'condition', visibleWhen: 'condition', rule: 'condition', styles: 'style', css: 'style' },
    // `rowColor` is a real, DIFFERENT capability on the same view; pointing a
    // colour-only author at the block that already does it beats making them
    // hand-write a style map.
    guidance: {
      color: 'Row colouring by field value has its own block — see `rowColor` on this list view. To set a CSS colour from a predicate, put it in `style`: `{ condition, style: { color: "#b91c1c" } }`.',
    },
  }, {
    condition: ExpressionInputSchema.describe('Predicate (CEL) to evaluate.'),
    style: z.record(z.string(), z.string()).describe('CSS styles to apply when condition is true'),
  })).optional().describe('Conditional formatting rules for list rows'),

  /** Inline Edit */
  inlineEdit: z.boolean().optional().describe('Allow inline editing of records directly in the list view'),

  /** Export */
  // Object form adopted at #8010 (maintainer ruling 2026-08-12 — option A):
  // the spec published a bare format array while the only renderer (objectui
  // ObjectGrid) read `exportOptions.formats` — no declaration was both
  // type-legal and functional. The object form is now the contract; the legacy
  // bare array stays accepted and LIFTS to `{ formats: [...] }` at parse
  // (z.input keeps both spellings, z.output is the object form only).
  // `'pdf'` left the format enum in the same change (#1301 NOT_PLANNED) — the
  // enum error map and the union error above carry the prescription.
  exportOptions: z.union([
    z.array(ListViewExportFormatSchema).transform((formats) => ({ formats })), // Legacy: bare format array
    ListViewExportOptionsSchema,
  ], { error: exportOptionsPdfUnionError }).optional().describe(
    'Export configuration for the list toolbar export menu: `{ formats?, maxRecords?, includeHeaders?, fileNamePrefix?, streaming? }`. '
    + 'A bare format array is the legacy spelling and lifts to `{ formats: [...] }` at parse.',
  ),

  /** User Actions (Airtable Interface parity) */
  userActions: UserActionsConfigSchema.optional().describe('User action toggles for the view toolbar'),

  /** Appearance (Airtable Interface parity) */
  appearance: AppearanceConfigSchema.optional().describe('Appearance and visualization configuration'),

  /** Tabs (Airtable Interface parity) */
  tabs: z.array(ViewTabSchema).optional().describe('Tab definitions for multi-tab view interface'),

  /** Add Record (Airtable Interface parity) */
  addRecord: AddRecordConfigSchema.optional().describe('Add record entry point configuration'),

  /** Record Count Display (Airtable Interface parity) */
  showRecordCount: z.boolean().optional().describe('Show record count at the bottom of the list'),

  /** Advanced: Allow Printing (Airtable Interface parity) */
  allowPrinting: z.boolean().optional().describe('Allow users to print the view'),

  /** Empty State */
  emptyState: strictObject({
    surface: 'this empty state',
    history: VIEW_HISTORY,
    // `description`/`text`/`subtitle` are the words the neighbouring empty-state
    // vocabularies use for the secondary line; here it is `message`.
    aliases: { description: 'message', text: 'message', subtitle: 'message', heading: 'title', label: 'title', image: 'icon' },
    // The add-record entry point is a real, separate block on this same view —
    // an author wiring a CTA into the empty state is reaching for it.
    guidance: {
      action: 'The empty state renders text only. Configure the "add record" entry point in the `addRecord` block on this list view.',
      button: 'The empty state renders text only. Configure the "add record" entry point in the `addRecord` block on this list view.',
    },
  }, {
    title: I18nLabelSchema.optional(),
    message: I18nLabelSchema.optional(),
    icon: z.string().optional(),
  }).optional().describe('Empty state configuration when no records found'),

  /** ARIA accessibility attributes */
  aria: AriaPropsSchema.optional().describe('ARIA accessibility attributes for the list view'),

  // `responsive` / `performance` REMOVED (#3896 audit close-out): authorable
  // and inert — no renderer in either repo read them (re-grepped 2026-07-16,
  // objectui@fb35e48; ledger: dead).
  responsive: retiredKey(
    '`view.responsive` was removed in @objectstack/spec 17.0.0 (audit close-out) — ' +
    'no renderer ever read it; the grid is responsive by its own layout rules. Delete the key. ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.',
  ),
  performance: retiredKey(
    '`view.performance` was removed in @objectstack/spec 17.0.0 (audit close-out) — ' +
    'no renderer or runtime read it; list-view performance tuning was never implemented. ' +
    'Delete the key. ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.',
  ),

  // `striped` / `bordered` / `virtualScroll` REMOVED (#7176, ADR-0049
  // enforce-or-remove; maintainer ruling 2026-08-10). Every measured reader was
  // a forwarding copy — react spec-bridge → plugin-list → plugin-view/app-shell
  // — and the chain ends at ObjectGrid, which never spells any of the three:
  // copy-without-apply is dead in effect. Per the ruling, if objectui wants one
  // of these as real behavior, that is an implementation card filed first, and
  // the key stays retired pending it.
  striped: retiredKey(
    '`view.striped` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — ' +
    'every measured reader only copied it forward and no renderer ever applied it, so authoring ' +
    'it was a parse-clean no-op. There is no authorable striped-rows switch; delete the key. ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.',
  ),
  bordered: retiredKey(
    '`view.bordered` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — ' +
    'every measured reader only copied it forward and no renderer ever applied it (the grid frame ' +
    "is the renderer's own constant, not authorable). Delete the key. " +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.',
  ),
  virtualScroll: retiredKey(
    '`view.virtualScroll` was removed in @objectstack/spec 17.0.0 (ADR-0049 enforce-or-remove) — ' +
    'every measured reader only copied it forward and no grid ever virtualized off it; authoring ' +
    'it was a parse-clean no-op. Delete the key; large datasets page via `pagination`. ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.',
  ),
}));

/**
 * List View Schema (Expanded) — {@link ListViewShapeSchema} plus the
 * `type: 'page'` ⇄ `pageName` binding check and the
 * `allowedVisualizations` ⇄ `calendar` binding check. See that shape for why
 * shape and checks are separate bindings, and {@link checkListViewPageMount} /
 * {@link checkListViewCalendarVisualization} for what each check refuses.
 */
export const ListViewSchema = lazySchema(() =>
  ListViewShapeSchema
    .superRefine(checkListViewPageMount)
    .superRefine(checkListViewCalendarVisualization));

/**
 * [#12868] Form-view select option — {@link SelectOptionSchema} minus the
 * per-option `default` key (maintainer-ruled narrowing, 2026-08-28, on the
 * objectui#6263 analysis; disposition 甲).
 *
 * `SelectOptionSchema` serves two surfaces, and only ONE of them reads
 * `default`:
 *
 * - **Object-field options** (`Field.select.options`): `default` is ENFORCED —
 *   `applyFieldDefaults` falls back to the option marked `default: true` when
 *   the field declares no `defaultValue` (#7246 ruling, PR #7388; `defaultValue`
 *   wins when both are declared). That face keeps the key, its alias rows
 *   (`isDefault`/`selected` → `default`) and its precedence pin, untouched.
 * - **Form-view options** (this shape): the key parsed clean and nothing read
 *   it — the engine's insert-path fallback consults the OBJECT definition's
 *   options, never a form view's, and no form renderer seeds a value from it
 *   (measured on objectui#6263: all three consuming controls drop it). A second
 *   default contract on the console was explicitly declined in the #7246
 *   ruling's rider, so the ADR-0049 declared-but-unenforced key is narrowed OUT
 *   of this face only.
 *
 * Derived structurally from `SelectOptionSchema.shape` (an Omit, not a copy) so
 * the two faces cannot drift apart key-by-key: every key the object-field
 * option shape gains or loses is gained or lost here too, minus exactly
 * `default`. The alias table is the object face's minus the two rows that
 * pointed at the removed key; those spellings move to `guidance`, because an
 * alias row must name a key the shape accepts (`alias-integrity.test.ts`) and
 * suggesting a key the schema refuses is the `triggerPhrases` failure shape
 * `shared/strict-object.ts` documents. The census that gates this narrowing
 * (issue #12868, part of the ruling) measured ZERO occurrences of
 * `default`/`isDefault`/`selected` inside form-view options across this tree,
 * the example apps and the published `*.form.ts` corpus, with the instrument's
 * positive control hitting the 40+ enforced object-field usages.
 *
 * The protocol-18 conversion `form-view-option-default-removed` strips the key
 * from stored sources; the guidance below carries the author-facing
 * prescription.
 */
export const FormSelectOptionSchema = lazySchema(() => {
  // An Omit at the SHAPE level: reuse every property schema by reference,
  // drop exactly `default`. (`.omit()` would also work, but building through
  // `strictObject` is what registers this surface's own aliases/guidance with
  // the alias-integrity audit instead of inheriting the object face's.)
  const { default: _objectFaceOnly, ...formOptionShape } = SelectOptionSchema.shape;
  return strictObject({
    surface: 'this form-view select option',
    history:
      'Until the FormView vocabulary got its own option shape these keys were judged by the '
      + 'shared object-field option schema, so `default` parsed clean here while nothing on the '
      + 'form path read it.',
    // The object face's alias table minus the two rows that pointed at
    // `default` — an alias must prescribe a key the shape accepts, and those
    // two spellings are answered by `guidance` below instead.
    aliases: { text: 'label', name: 'label', title: 'label', key: 'value', id: 'value', colour: 'color', visible: 'visibleWhen', showWhen: 'visibleWhen' },
    guidance: {
      default:
        '`options[].default` on a form-view field was removed from the FormView vocabulary in '
        + '@objectstack/spec 18 (ADR-0049 declared-but-unenforced) — on this surface the key '
        + 'parsed clean and nothing read it: the insert-path default falls back to the OBJECT '
        + "definition's option list, never a form view's, and no form renderer seeds a value "
        + 'from it. Delete the key. Declare the pre-selected choice on the object definition '
        + 'instead — field-level `defaultValue`, or `default: true` on that field\'s own '
        + '`options` entry (both enforced there, with `defaultValue` winning when both are '
        + 'declared). Run `os migrate meta --from 17` to list the mechanical edits for existing '
        + 'sources; apply them by hand.',
      isDefault:
        '`isDefault` is an object-field spelling: an OBJECT field\'s option list answers it with '
        + 'a rename to `default`, which is enforced there. Form-view options accept neither '
        + 'spelling — declare the pre-selected choice on the object definition (field-level '
        + '`defaultValue`, or `default: true` on that field\'s own `options` entry).',
      selected:
        '`selected` is an object-field spelling: an OBJECT field\'s option list answers it with '
        + 'a rename to `default`, which is enforced there. Form-view options accept neither '
        + 'spelling — declare the pre-selected choice on the object definition (field-level '
        + '`defaultValue`, or `default: true` on that field\'s own `options` entry).',
    },
    // Same editability boundary as the object face (#8201): an option is
    // offered or withheld, never shown-but-unselectable.
    guidanceSets: [SELECT_OPTION_EDITABILITY_GUIDANCE],
  }, formOptionShape).describe(
    'Form-view select option — the object-field option shape minus the per-option `default` key '
    + '(declare the pre-selected choice on the object definition: field-level `defaultValue`, or '
    + "`default: true` on that field's own `options` entry).",
  );
});

/**
 * Non-recursive half of {@link FormFieldSchema} — every key except the
 * recursive `fields`.
 *
 * Split out so the recursion can be TYPED. `z.lazy()` needs an explicit
 * annotation to break the circular inference, and the `z.ZodType<any>` this
 * schema used to carry made `FormField` resolve to `any` for every consumer
 * (#4171): a precise 30-key contract silently reduced to a type that constrains
 * nothing, with no compile error anywhere to say so. Inferring the base and
 * closing the recursive loop in the type instead keeps the keys derived from the
 * schema — the `QueryAST` pattern in `data/query.zod.ts`.
 *
 * Still `lazySchema`-wrapped: splitting the literal out of the exported schema's
 * factory would otherwise have moved its construction back to module load, which
 * is the allocation `lazySchema` exists to defer.
 */
/**
 * [#4001 批 18] Deliberately still a BARE `z.object` — and the ledger row for
 * this site is a measurement artifact, not open surface.
 *
 * Two reasons were recorded; #6619 retired one of them and left the other
 * standing, which is why the posture here did not move with the fold:
 *
 * 1. **The posture here was never the live one.** This base is module-private
 *    and has exactly ONE consumer, {@link FormFieldSchema}, which applies
 *    `.strict()` after extending it (ADR-0089 D3a). An unknown form-field key
 *    is already rejected at the only door; the ledger reads `strip` because it
 *    counts the BASE, and the base is not a door. Still true — and it is why
 *    this site takes `strictObjectError` rather than `strictObject`: the fold
 *    is a change to what the message can SAY, and closing this shape as a side
 *    effect would have been an acceptance change smuggled in with it.
 * 2. ~~It already carries a bespoke error map.~~ **Retired by #6619.** The
 *    ADR-0089 map that resolves the `visibleWhen` / `visibility` pair is no
 *    longer bespoke: it is `VISIBILITY_STRICT_OPTIONS`, a shared `strictObject`
 *    options fragment whose prescription rides the template's set-keyed
 *    `guidance` channel. `strictObjectError` builds exactly the map
 *    `strictObject` would and registers the surface with
 *    `alias-integrity.test.ts` — the audit this site used to sit outside — with
 *    the shape left open for the extension to close.
 *
 * `extraKeys: ['fields']` is the base/extension boundary the helper documents:
 * the candidate list is read from THIS shape, and `fields` is declared one
 * level up by the extension that also closes it, so naming it here is what
 * keeps `feilds` pointing at `fields` instead of at `field`.
 *
 * Spelled as a literal `z.object(shape, { error: strictObjectError(…) })`
 * rather than through a wrapper on purpose: the strictness ledger's AST reader
 * (`scripts/lib/strictness-ledger.ts`) recognises the `z.object(` idiom and
 * counts this site's OPEN posture — the row `ui/view.zod.ts` carries as its
 * one `authorable` strip site. A wrapper would hide the site from the
 * instrument entirely, which is a gate going quiet, not a posture change.
 *
 * The nested `keyField` block below IS converted: strictness does not recurse,
 * so a closed parent said nothing about it.
 */
/**
 * [#7467] Public-lookup opt-in for a lookup / `master_detail` / `user` field on
 * an ANONYMOUS public form.
 *
 * This block GATES the REST public-lookup capability: `GET
 * /forms/:slug/lookup/:field` answers a picker search only for a field whose
 * form declaration carries `publicPicker`. Without it the route answers `403
 * LOOKUP_NOT_PUBLIC` — loud by design (#3022), so a misconfigured form is a
 * visible refusal rather than a silently empty picker. The public-form resolve
 * route enforces the same opt-in from the other side: an undeclared
 * lookup/master_detail/user field is stripped from the rendered sections, so an
 * anonymous form can never expose unrestricted record search by accident.
 *
 * Until #7467 this key was ENFORCED but declared nowhere — the mirror image of
 * ADR-0049's "declared ≠ enforced": `FormFieldSchema` is strict (ADR-0089 D3a),
 * so every authoring path refused a form carrying a picker and the capability
 * was unreachable. Declaring it is the maintainer-ruled direction (option 1 of
 * that card's fork).
 *
 * Every key below mirrors a read the route actually performs
 * (`packages/rest/src/rest-server.ts`, `GET /forms/:slug/lookup/:field`
 * handler), and NOTHING else: this block opens an unauthenticated search
 * surface, so the schema deliberately admits no option the route does not
 * enforce. The route's own hard bounds are encoded rather than restated in
 * prose — `displayFields` beyond the first 5 are never projected (the route
 * slices), a `maxResults` above 50 is never honored (the route clamps), so
 * authoring either is refused here instead of silently meaning less than it
 * says. Anonymous visitors can search but cannot paginate (`offset` is pinned
 * to 0 server-side), which is what keeps a leaked endpoint from enumerating
 * the table.
 *
 * @example Opt a lookup field into the public picker
 * { field: 'owner', publicPicker: { displayFields: ['name'], maxResults: 10 } }
 */
export const FormFieldPublicPickerSchema = lazySchema(() => strictObject({
  surface: 'this public picker configuration',
  history: VIEW_HISTORY,
}, {
  /**
   * Projection: the fields returned for each picker row (plus `id`), and the
   * search target — the visitor's `q` is matched with `contains` against the
   * FIRST entry. The route projects at most 5 and defaults to `['name']` when
   * omitted, so more than 5 (or an empty list) is refused here rather than
   * silently truncated / silently replaced.
   */
  displayFields: z.array(z.string()).min(1).max(5).optional().describe(
    'Fields projected into each picker result (with `id`); the visitor\'s search matches '
    + '`contains` on the first entry. At most 5 (the route projects no more); omitted → [\'name\'].',
  ),
  /**
   * Per-request result cap. The route clamps to a hard ceiling of 50 and
   * defaults to 20; anonymous visitors cannot paginate, so this bounds what a
   * single request can pull. Values the route would never honor (0, negatives,
   * fractions, > 50) are refused at authoring time.
   */
  maxResults: z.number().int().min(1).max(50).optional().describe(
    'Maximum rows a lookup returns (default 20, hard ceiling 50 — the route clamps; anonymous '
    + 'visitors cannot paginate past it).',
  ),
  /**
   * Static pre-filter, ANDed ahead of the visitor's search predicate. Same
   * rule dialect as every other view filter (`ViewFilterRuleSchema`) — the
   * route composes these rows with its own `{ field, operator: 'contains',
   * value: q }` search row in one filters list.
   */
  filter: z.array(ViewFilterRuleSchema).optional().describe(
    'Static pre-filter rows ANDed ahead of the visitor\'s search (e.g. only active records are '
    + 'searchable). Same `{ field, operator, value }` dialect as list-view filters.',
  ),
  /**
   * Referenced-object override. Omitted, the route resolves the target from
   * the field definition on the parent object (`reference`); set it only when
   * that resolution is wrong for this form.
   *
   * `reference` is the key `FieldSchema` accepts — `referenceTo` is only a
   * rejected alias it lists so a failed parse can offer a rename hint, so an
   * author following the old spelling of this sentence had their whole object
   * metadata refused at parse.
   */
  object: z.string().optional().describe(
    'Referenced-object override for the picker search; omitted → resolved from the `reference` '
    + 'key on the field definition.',
  ),
}).describe('Public-lookup opt-in: enables GET /forms/:slug/lookup/:field for this field on an anonymous public form (without it the route answers 403 LOOKUP_NOT_PUBLIC).'));

/** Authoring shape of {@link FormFieldPublicPickerSchema}. */
export type FormFieldPublicPicker = z.input<typeof FormFieldPublicPickerSchema>;
/** Post-parse shape of {@link FormFieldPublicPicker} — filter-rule operator aliases folded (ADR-0122). */
export type FormFieldPublicPickerParsed = z.infer<typeof FormFieldPublicPickerSchema>;

const FormFieldBaseSchema = lazySchema(() => {
  const shape = {
  /** Field name (snake_case) */
  field: z.string().describe('Field name (snake_case)'),
  
  /** Field type — reuses Data.FieldType. When set, widget is auto-inferred (can be overridden). */
  type: FieldType.optional().describe('Field type (auto-infers widget if omitted)'),
  
  /**
   * Select/multiselect options — only needed when type=select/multiselect/radio/checkboxes.
   *
   * [#12868] `FormSelectOptionSchema`, not `SelectOptionSchema`: the form-view
   * face refuses the per-option `default` key the object-field face enforces —
   * see the narrowed schema's docblock for the ruling and the census.
   */
  options: z.array(FormSelectOptionSchema).optional().describe('Options for select/multiselect/radio/checkboxes fields (per-option `default` is not accepted here — declare the pre-selected choice on the object definition)'),
  
  /** Reference object for lookup/master_detail fields */
  reference: z.string().optional().describe('Target object name for lookup/master_detail fields'),

  /**
   * [#7467] Public-lookup opt-in (lookup / master_detail / user fields on an
   * anonymous public form). Gates `GET /forms/:slug/lookup/:field` — absent,
   * the route answers 403 LOOKUP_NOT_PUBLIC (loud by design, #3022) and the
   * resolve route strips the field from the rendered sections. See
   * {@link FormFieldPublicPickerSchema}.
   */
  publicPicker: FormFieldPublicPickerSchema.optional().describe(
    'Opt this field into the anonymous public-form lookup picker (GET /forms/:slug/lookup/:field). '
    + 'Without it the route answers 403 LOOKUP_NOT_PUBLIC and the field is stripped from the '
    + 'rendered public form.',
  ),
  
  /** Text constraints */
  // #12174 — the form-field row's constraint keys converge on the value shape
  // #11566/#11949 (lengths) and #8321 (precision/scale) landed on the object
  // field surface: a character length is a positive integer and a digit count
  // a non-negative one, so `maxLength: 0`, `minLength: -5` and `scale: 2.5`
  // are refused at authoring instead of flowing to the renderer (objectui
  // reads every one of these keys off the form row: the spec bridge
  // `form-view.ts` mapField and plugin-form `sectionFields.ts` copy all six
  // onto the runtime field, FormPage merges `override.maxLength` onto the
  // input, and the fields package builds validation rules from them —
  // `maxLength: 0` reached the DOM as an input that accepts nothing).
  // Deliberately NO type-conditional gate here, unlike the object-field
  // superRefine (BOUNDED_STRING_FIELD_TYPES): a form row references an object
  // field by name and usually omits `type`, so the referenced field's type is
  // not visible to this schema at parse time — a gate firing only when the
  // optional presentational `type` override happens to be authored would make
  // strictness depend on an unrelated key. Value shape is checkable here;
  // key placement is the object field's own schema's job.
  maxLength: z.number().int().min(1).optional().describe('Maximum character length (positive integer; for text/textarea/email/url/phone)'),
  minLength: z.number().int().min(1).optional().describe('Minimum character length (positive integer; `minLength: 0` is refused — express "no minimum" by omitting the key)'),

  /** Number constraints */
  min: z.number().optional().describe('Minimum value (for number/currency/percent/slider)'),
  max: z.number().optional().describe('Maximum value'),
  precision: z.number().int().min(0).optional().describe('Total digits (non-negative integer; for number/currency)'),
  scale: z.number().int().min(0).optional().describe('Decimal places (non-negative integer)'),
  
  /** Multi-value flag */
  multiple: z.boolean().optional().describe('Allow multiple values (for select/lookup/file/image)'),
  
  /** UI overrides */
  label: I18nLabelSchema.optional().describe('Display label override'),
  placeholder: I18nLabelSchema.optional().describe('Placeholder text'),
  helpText: I18nLabelSchema.optional().describe('Help/hint text'),
  readonly: z.boolean().optional().describe('Read-only override'),
  immutable: z.boolean().optional().describe('Editable on create, locked once the record exists (e.g. machine names).'),
  required: z.boolean().optional().describe('Required override'),
  hidden: z.boolean().optional().describe('Hidden override'),
  colSpan: z.number().int().min(1).max(4).optional().describe('[legacy — prefer `span`] Absolute column span (1-4). Fragile when the column count is derived per surface (mobile 1 / modal 2 / page 3-4): a fixed span only lines up at the width the author imagined. The renderer clamps it to the current column count. Prefer `span`.'),
  /**
   * [#2578] Relative field width — decoupled from the (often auto-derived)
   * column count, so it stays correct at 1/2/3/4 columns.
   */
  span: z.enum(['auto', 'full']).default('auto').describe("Relative field width. 'auto' (default — omit it): the renderer sizes the field from its widget type × the current column count (wide widgets like textarea/richtext/json/file/subform take the whole row). 'full': whole row at any column count. Prefer this over the absolute `colSpan`."),

  /** Custom widget override — only needed when auto-inference is insufficient */
  widget: z.string().optional().describe('Custom widget/component name (overrides type-based inference)'),

  /** For `code` fields: source language (e.g. 'javascript', 'sql', 'json', 'typescript', 'expression', 'cel'). Drives syntax highlighting. */
  language: z.string().optional().describe('Code editor language (for type=code)'),

  /**
   * For `record`-typed fields only. Declares how the map key is sourced,
   * displayed, and validated when an admin creates a new entry.
   *
   * The same identifier is also stored as `name` on the inner value (so
   * `record.fields[k].name === k`). Most callers can omit this and accept
   * the defaults: `{ field: 'name', label: 'Name', regex: /^[a-z_][a-z0-9_]*$/, immutable: true }`.
   *
   * See ADR-0007 (record form field type).
   */
  keyField: strictObject({
    surface: 'this record key field',
    history: VIEW_HISTORY,
    // The enclosing form field IS strict (ADR-0089 D3a `.strict()` on
    // `FormFieldSchema`), but strictness does not recurse — this nested block
    // kept dropping keys silently inside a closed parent, the same nested hole
    // 批 13 measured on `responsive`.
    aliases: { key: 'field', name: 'field', pattern: 'regex', placeHolder: 'placeholder', help: 'helpText', hint: 'helpText' },
  }, {
    field: z.string().default('name').describe('Property name that holds the key inside each item (defaults to "name")'),
    label: I18nLabelSchema.optional().describe('Display label for the key column'),
    placeholder: I18nLabelSchema.optional().describe('Placeholder when entering a new key'),
    helpText: I18nLabelSchema.optional().describe('Help text under the key input'),
    /** Validation pattern serialised as a regex source string (no flags). */
    regex: z.string().optional().describe('JS regex source string the key must match (no flags)'),
    /** Renamable after creation? Defaults to false — keys are usually identifiers. */
    immutable: z.boolean().default(true).describe('If true, the key is read-only after creation'),
  }).optional().describe('Key column config for record-typed fields'),

  dependsOn: z.string().optional().describe('Parent field name for cascading'),
  /**
   * Conditional-visibility predicate (CEL) — the field is shown only when TRUE
   * (ADR-0089, canonical `*When` name). Binding root depends on the surface:
   * runtime record forms bind `record` (plus `previous`, the saved record, and
   * `parent` for master-detail line items); metadata-editing forms
   * (`*.form.ts`) bind the row under edit as `data`.
   *
   * ## `current_user` DOES bind here — client-side, and only under a host that
   * publishes a scope (objectui#6010)
   *
   * The form renderer passes the host shell's predicate scope into
   * `evalFieldPredicate` / `resolveFieldRuleState` (`@object-ui/core`) as their
   * `extra` scope, so a field-level predicate resolves `current_user` and its
   * ADR-0068 D1 aliases (`user`, `ctx.user`, `os.user`) alongside `record` +
   * `previous` + `parent`. The root really was unbound here (#6146) and this
   * block said so for as long as that held; objectui#6010 bound it, and the
   * text above is a re-measurement rather than a relaxation of anything.
   *
   * Two limits the binding does **not** remove — both fail in the direction an
   * author will not notice:
   *
   * 1. ⚠️ **This is a rendering rule, never authorization.** Nothing
   *    server-side evaluates a form-view field `visibleWhen`: the write path
   *    evaluates field `readonlyWhen` / `requiredWhen` and per-option
   *    `visibleWhen`, and that is the whole list. A role test written here
   *    hides a control and protects no data — the record still carries the
   *    value and every other read surface still returns it. To withhold a field
   *    by role, declare field-level security on a permission set, which the
   *    server enforces.
   * 2. ⚠️ **The scope belongs to the HOST, so it is empty wherever no host
   *    publishes one.** The console's public form route (`/f/:slug`) is mounted
   *    outside any provider deliberately — an anonymous visitor has no
   *    principal — so `current_user` is unbound there, the predicate faults,
   *    and visibility's fallback is `true`: the field the test was meant to
   *    hide is shown to everyone. The authed standalone route (`/forms/:name`)
   *    publishes the session principal and binds normally.
   *
   * `current_user` is bound for **per-option** `visibleWhen` as well, through a
   * different evaluator (`resolveCascadingOptions` against the same host scope,
   * ADR-0068 / objectui#2284) — and that surface the rule validator ALSO
   * enforces on write, which is why it stays the destination for a user-gated
   * *choice* rather than a user-gated field.
   *
   * **Inside a repeater, `data` is the ROW, not the whole document** (#6254).
   * A sub-field of a `type: 'record'` / repeater field is rendered with its own
   * activation — the metadata form renderer evaluates each sub-field predicate
   * as `evaluatePredicate(spec.visibleOn, { data: row })` — so `data.type`
   * means *this row's* `type`, which is what a per-entry rule wants. The root
   * is still spelled `data` at every depth: there is no implicit row scope, so
   * a BARE identifier (`type == 'formula'`) is unbound and the predicate faults
   * open, showing the field for every row — the same fail-open direction the
   * `current_user` note above describes, arriving from the other end. Prefix
   * every reference with `data.` whether the field sits at the top level or
   * inside a repeater.
   *
   * ⛔ **No `features.*` on any form-view predicate — refused at parse**
   * (ruled 2026-08-27, objectui#6262). Unlike the two fault-open notes above,
   * this one is ENFORCED: see {@link checkFormViewPredicateFeaturesRoot} for
   * the ruling and the scanner.
   */
  visibleWhen: ExpressionInputSchema.optional().describe("Visibility predicate (CEL) — field shown only when TRUE. Root: `record` (+ `previous`, `parent`) in runtime forms, or `data` in metadata forms. `current_user` (and the ADR-0068 aliases `user` / `ctx.user` / `os.user`) resolves here — CLIENT-SIDE only: nothing server-side evaluates a form-view field `visibleWhen`, so a role test here hides the control and protects no data (declare permission-set field-level security for that), and on the public `/f/:slug` route no host publishes a scope, so the root is unbound and the predicate faults open. No `features.*` on ANY form-view predicate — refused at parse (ruled 2026-08-27): the root is unbound on the standalone form routes (`/forms/:name`, `/f/:slug`) and the predicate would fault open there. Inside a repeater `data` is the ROW, but it is still spelled `data` — a bare identifier is unbound and faults open too. e.g. P`record.priority == 'urgent'`"),
  /** @deprecated ADR-0089 — use `visibleWhen`. Accepted and normalized to `visibleWhen` at parse. */
  visibleOn: ExpressionInputSchema.optional().describe('[DEPRECATED → `visibleWhen`] Visibility predicate (CEL). Normalized to `visibleWhen` at parse.'),
  disclosure: z.enum(['inline', 'popover']).optional().describe('Composite rendering: inline bordered box (default) or a summary line + gear popover (progressive disclosure).'),
  };
  return z.object(shape, {
    error: strictObjectError({
      ...VISIBILITY_STRICT_OPTIONS,
      // #8202 — this shape names ITSELF. The shared table's `'this view/page
      // schema'` was harmless while all three of its consumers answered a key
      // the same way; since #7887 they answer `disabled` in two contradictory
      // ways on purpose (the rename below on a field, the boundary
      // prescription on a section / page component), and the contradiction is
      // only coherent if the message says which shape refused the key. A
      // per-shape string is by definition not something a table shared by
      // three shapes can carry, so it is filed here — the same placement rule
      // #8199 drew for the prescription itself.
      surface: 'this form field',
      extraKeys: ['fields'],
      // The one member of the `visibleWhen` family that can answer `disabled`
      // with a key of its own (#7832). `VISIBILITY_STRICT_OPTIONS` is shared
      // with `FormSectionSchema` and `PageComponentSchema`, and neither of those
      // declares a read-only or disabled slot, so this row belongs HERE rather
      // than in the shared table — filed there it would name a key two of its
      // three surfaces do not accept. `visible` / `showWhen` need nothing: they
      // match `VISIBILITY_KEY_PATTERN` and are already answered by the shared
      // ADR-0089 prescription, which consumes the key before the rename channel
      // is consulted, so an alias for either would be dead on arrival.
      //
      // #7887 filed the OTHER half of that split from the same reasoning and in
      // the same direction: the two sibling shapes now carry an editability
      // BOUNDARY prescription (`shared/editability-boundary.ts`), and it is
      // filed on those two rather than shared, because a `disabled`-matching
      // guidanceSet on THIS table would consume the key before the rename below
      // ever runs — killing the one pointer that is correct here, and turning
      // `alias-integrity.test.ts`'s #7889 reachability check red. The two
      // decisions are one rule read from both ends: the shared table may only
      // carry what is true of all three surfaces.
      aliases: { disabled: 'readonly' },
    }, shape),
  });
});

/**
 * A parsed form field — the TYPE half of {@link FormFieldSchema}.
 *
 * `visibleOn` is absent by construction: ADR-0089 D2 folds it into
 * `visibleWhen` at the schema boundary, so it is accepted on input and never
 * present on output.
 */
export type FormField = Omit<z.infer<typeof FormFieldBaseSchema>, 'visibleOn'> & {
  /**
   * Sub-fields for `composite` / `repeater` / `record` types — declares
   * the inner shape of an embedded sub-object (composite), each row of
   * an embedded sub-object array (repeater), or each entry of a name-keyed
   * map (record). Recursive: any of the three can nest.
   *
   * Use `lookup` / `master_detail` instead when the children are independent
   * records with their own IDs in a separate object/table.
   */
  fields?: FormField[];
};

/**
 * The authoring shape of a form field — the INPUT half of
 * {@link FormFieldSchema} (#4195).
 *
 * Differs from {@link FormField} in both directions, which is exactly why it
 * has to be declared: `span` is `.default('auto')` so it is optional here and
 * required there, and the deprecated `visibleOn` is accepted here and stripped
 * by the ADR-0089 D2 transform before it reaches the output.
 *
 * Without this, `z.input<typeof FormFieldSchema>` was `unknown` — so a form
 * section's `fields` were unchecked at every authoring site.
 */
export type FormFieldInput = z.input<typeof FormFieldBaseSchema> & {
  /** Sub-fields for composite/repeater/record types. Recursive. */
  fields?: FormFieldInput[];
};

/**
 * Form Field Configuration Schema
 * Detailed configuration for individual form fields.
 *
 * Reuses Data.FieldType and related constraints from the Data protocol to avoid duplication.
 * The `type` field auto-infers widget rendering; explicit `widget` overrides are only needed
 * for custom components.
 *
 * @example Auto-inferred select widget
 * { field: 'status', type: 'select', options: [{ label: 'Open', value: 'open' }] }
 *
 * @example Lookup field with reference
 * { field: 'account_id', type: 'lookup', reference: 'account', label: 'Account' }
 *
 * @example Custom widget override
 * { field: 'filter', widget: 'filter-builder' }
 */
export const FormFieldSchema: z.ZodType<FormField, FormFieldInput> = lazySchema(() =>
  FormFieldBaseSchema.extend({
    fields: z.array(z.lazy(() => FormFieldSchema)).optional()
      .describe('Sub-fields for composite/repeater/record types'),
  }).strict().transform(normalizeVisibleWhen));

/**
 * Form Layout Section
 *
 * Closed under ADR-0089 D3a, and — since #6619 — closed with the SHARED
 * template rather than a bespoke map. #4001 skipped this shape because
 * converting it meant re-expressing `strictVisibilityError` as `guidance`, and
 * `guidance` could not express a family of keys; #6619 gave the channel a
 * set-keyed form and the conversion became the same one call every other closed
 * shape in this package makes. The `.transform()` that folds
 * `visibleOn` → `visibleWhen` is unchanged and still runs after the parse.
 *
 * ## A section gates VISIBILITY, not editability (#7887 — boundary, not gap)
 *
 * There is no `disabled`, `readonly` or `readonlyWhen` on a section, and that is
 * a **deliberate boundary** ruled on 2026-08-12, not a slot nobody got round to
 * adding: **editability lives on fields.** A section decides whether its fields
 * are *shown* (`visibleWhen`, plus `collapsible` / `collapsed` for how); whether
 * a shown field can be *edited* is the field's own `readonly` /
 * {@link FormFieldSchema.readonlyWhen}, enforced by the field renderer that owns
 * the input. Nothing in the platform reads a section-level read-only flag, so
 * declaring one would ship the ADR-0049 declared-but-unenforced shape this repo
 * is retiring elsewhere.
 *
 * Writing one anyway stays a loud parse error — unchanged — and since #7887 that
 * error carries `EDITABILITY_BOUNDARY_KEYS`' prescription naming the field-level
 * keys, so the author is redirected instead of merely refused. To make a whole
 * section non-editable, mark its fields `readonly`; to make it conditionally
 * non-editable, give each field a `readonlyWhen` predicate.
 */
export const FormSectionSchema = lazySchema(() => strictObject({
  ...VISIBILITY_ONLY_STRICT_OPTIONS,
  // #8202 — see the note at `FormFieldBaseSchema`'s options: the boundary
  // prescription this table carries tells the author to move an editability
  // key to "the form field(s) inside", and the field's own message tells them
  // to rename it in place. The reader can only tell which answer is theirs if
  // the rejection names the shape, so each of the three shapes names itself.
  surface: 'this form section',
  // [#13855] Both are the author reaching for the field-group reference form
  // with the word a neighbouring surface uses: the object declares
  // `fieldGroups`, and a field points back with `group`. Neither is a typo edit
  // distance reaches. Spread the inherited table first so nothing it carries is
  // dropped by re-declaring the key.
  aliases: {
    ...VISIBILITY_ONLY_STRICT_OPTIONS.aliases,
    fieldGroup: 'group',
    groupKey: 'group',
  },
}, {
  /**
   * Stable identifier for translation lookup. snake_case convention.
   * When provided, translation bundles can target this section's `label`
   * and `description` via `metadataForms.<type>.sections.<name>`.
   * Optional for backward-compat with sections that only have a `label`.
   */
  name: z.string().optional().describe('Stable section identifier for i18n lookup (snake_case)'),
  label: I18nLabelSchema.optional(),
  description: z.string().optional().describe('Optional description rendered under the section header.'),
  collapsible: z.boolean().default(false),
  collapsed: z.boolean().default(false),
  /**
   * Conditional-visibility predicate (CEL) — the whole section is shown only
   * when TRUE (ADR-0089, canonical `*When` name). Same per-layer binding root as
   * {@link FormFieldSchema.visibleWhen}: `record` (+ `previous`, `parent`) in
   * runtime forms, `data` in metadata-editing forms.
   *
   * ## `current_user` DOES bind here — client-side, and only under a host that
   * publishes a scope (objectui#6110 + #6111)
   *
   * This block said "no `current_user` at section level" (#6146) for as long as
   * that held, and it held for TWO reasons, both since discharged. The console
   * form renderer now reads the host shell's predicate scope and threads it into
   * `isSectionVisible` (objectui#6110), where it used to pass `undefined`; and
   * the object-view chain no longer drops the key before a renderer sees it —
   * `ObjectForm` / `SplitForm` / `ModalForm` / `DrawerForm` copy the authored
   * `visibleWhen` onto the `section-divider` pseudo-field and the SDUI form
   * renderer evaluates that pseudo-field's predicate with the same scope bound
   * (objectui#6111). So a section predicate resolves `current_user` and its
   * ADR-0068 D1 aliases (`user`, `ctx.user`, `os.user`) alongside `record` +
   * `previous` + `parent`. The text above is a re-measurement of a claim that
   * was true when it was written, not a relaxation of anything.
   *
   * The two limits {@link FormFieldSchema.visibleWhen} records apply here
   * verbatim — both fail in the direction an author will not notice:
   *
   * 1. ⚠️ **This is a rendering rule, never authorization.** Nothing
   *    server-side evaluates a form-view section `visibleWhen` — nor a field
   *    one: the write path evaluates field `readonlyWhen` / `requiredWhen` and
   *    per-option `visibleWhen`, and that is the whole list. A role test written
   *    here hides a group of controls and protects no data — the record still
   *    carries every value in the section and every other read surface still
   *    returns them. To withhold a field by role, declare field-level security
   *    on a permission set, which the server enforces.
   * 2. ⚠️ **The scope belongs to the HOST, so it is empty wherever no host
   *    publishes one.** The console's public form route (`/f/:slug`) is mounted
   *    outside any provider deliberately — an anonymous visitor has no
   *    principal — so `current_user` is unbound there, the predicate faults,
   *    and visibility's fallback is `true`: the section the test was meant to
   *    hide is shown to everyone. The authed standalone route (`/forms/:name`)
   *    publishes the session principal and binds normally.
   *
   * ⛔ No `features.*` either — that one is
   * refused at parse (ruled 2026-08-27, objectui#6262; see
   * {@link checkFormViewPredicateFeaturesRoot}).
   */
  visibleWhen: ExpressionInputSchema.optional().describe('Visibility predicate (CEL) — section shown only when TRUE. Root: `record` (+ `previous`, `parent`) in runtime forms, or `data` in metadata forms. `current_user` (and the ADR-0068 aliases `user` / `ctx.user` / `os.user`) resolves here too — CLIENT-SIDE only: nothing server-side evaluates a form-view section `visibleWhen`, so a role test here hides the controls and protects no data (declare permission-set field-level security for that), and on the public `/f/:slug` route no host publishes a scope, so the root is unbound and the predicate faults open. No `features.*` on ANY form-view predicate — refused at parse (ruled 2026-08-27): unbound on the standalone form routes, where the predicate would fault open.'),
  /** @deprecated ADR-0089 — use `visibleWhen`. Accepted and normalized to `visibleWhen` at parse. */
  visibleOn: ExpressionInputSchema.optional().describe('[DEPRECATED → `visibleWhen`] Visibility predicate (CEL). Hides the whole section when false. Normalized to `visibleWhen` at parse.'),
  columns: z.union([
    z.enum(['1', '2', '3', '4']),
    z.literal(1),
    z.literal(2),
    z.literal(3),
    z.literal(4),
  ]).default(1).transform(val => (typeof val === 'string' ? parseInt(val) : val) as 1 | 2 | 3 | 4),
  /**
   * Which pane of a split form this section renders in (`type: 'split'` only —
   * any other form type rejects the key at parse, see the FormViewSchema
   * refinement). Placement is explicit and PER SECTION so it survives
   * reordering: with the old first-vs-rest positional rule the assignment was
   * invisible in the metadata, and an edit that reordered sections silently
   * moved them across the divider. Defaults by position when omitted: the
   * first section renders in `primary`, every other section in `secondary`
   * (exactly the legacy rule, so keyless metadata keeps its layout).
   */
  pane: z.enum(['primary', 'secondary']).optional().describe(
    "Split pane this section renders in (split forms only; a parse error elsewhere). Omitted → first section 'primary', others 'secondary'.",
  ),
  /**
   * [#13855] Reference a declared field GROUP instead of enumerating members —
   * the delta form ruled 2026-08-31 (maintainer: 「直接处理b」).
   *
   * `{ group: 'contact_info' }` inherits the bound object's `fieldGroups` entry
   * with that key: its members (every visible field whose `Field.group` points
   * at it, in field-declaration order) and its own presentation (label,
   * description, `collapse`, `visibleWhen`, and the drop when the group has no
   * visible members) all come from `deriveFieldGroupLayout` (ADR-0085 §5). The
   * section restates none of it — see {@link sectionGroupReferenceRefinement}
   * for the mixing rule, and for why the keys the group owns are refused beside
   * `group` rather than given a precedence.
   *
   * Existence is NOT a parse question: the key names something on a DIFFERENT
   * schema, so it follows the `UserFilterFieldSchema.field` precedent — parse
   * takes any well-formed key, and `form-section-group-unknown`
   * (`@objectstack/lint`) reports one that resolves to no declared group.
   *
   * ⛔ Not on a wizard step — refused by the {@link FormViewSchema} refinement,
   * for the reason #13704 refused the step keys themselves: a group carries
   * `visibleWhen` and `collapse`, and a wizard step has no slot for either.
   */
  group: SectionGroupKeySchema.optional().describe(
    'Field group key (snake_case) whose members and presentation this section inherits, from the bound object\'s `fieldGroups` (ADR-0085 §5 `deriveFieldGroupLayout`). Mutually exclusive with `fields`, and with every key the group itself declares (`name`, `label`, `description`, `collapsible`, `collapsed`, `visibleWhen`/`visibleOn`). Not valid on a wizard step. Must name a declared group — checked by reference diagnostics.',
  ),
  /**
   * The section's members, enumerated.
   *
   * Optional since #13855 — and optional ONLY in the sense that `group` is the
   * other way to declare the same fact. A section carrying neither is refused
   * (see {@link sectionGroupReferenceRefinement}), so no section reaches a
   * renderer without a member source, which is what the previously-required key
   * guaranteed.
   */
  fields: z.array(z.union([
    z.string(), // Legacy: simple field name
    FormFieldSchema, // Enhanced: detailed field config
  ])).optional(),
}).superRefine(sectionGroupReferenceRefinement({
  surface: 'this form section',
  // Exactly the keys `deriveFieldGroupLayout` fills from the group. `name` is
  // in the list because the derived section's `key` IS the group key, which is
  // already this surface's i18n anchor (`metadataForms.<type>.sections.<name>`)
  // — a second name would give one section two lookup identities. `visibleOn`
  // rides along because this refinement runs BEFORE the `.transform` that folds
  // it onto `visibleWhen`, so the deprecated spelling must be named here or it
  // would be the one way to smuggle a section-level predicate past the rule.
  //
  // NOT in the list, deliberately: `columns` and `pane`. Those are how THIS
  // form lays the section out and the group declares nothing about them, so
  // there is no second source to create.
  derivedKeys: ['name', 'label', 'description', 'visibleWhen', 'visibleOn'],
  // `collapsible` / `collapsed` carry `.default(false)`, so an authored `false`
  // is already indistinguishable from the default by the time this runs — the
  // same asymmetry #13704 records for the wizard step keys, and it costs
  // nothing: `false` declares exactly what a group with `collapse: 'none'`
  // delivers. Only `true` declares presentation the group owns.
  trueOnlyDerivedKeys: ['collapsible', 'collapsed'],
})).transform(normalizeVisibleWhen));

/**
 * A single form action button (submit / cancel / reset): visibility + label.
 * Leaf of the {@link FormViewSchema} `buttons` block (#2998).
 * `.strict()` per ADR-0089 D3a so a typo'd key errors instead of vanishing.
 */
export const FormButtonConfigSchema = lazySchema(() => strictObject({
  surface: 'this form button configuration',
  history: VIEW_HISTORY,
}, {
  show: z.boolean().optional().describe('Whether the button is rendered (renderer default applies when omitted)'),
  label: I18nLabelSchema.optional().describe('Button label (i18n-capable; renderer default when omitted)'),
}).strict());
export type FormButtonConfig = z.input<typeof FormButtonConfigSchema>;

/** An object that may carry the `groups` alias beside canonical `sections`. */
type WithFormSectionAlias = { sections?: unknown; groups?: unknown };

/**
 * Fold the legacy `groups` alias onto the canonical `sections` and drop
 * `groups` from the output (#6926) — the whole-array counterpart of
 * `normalizeVisibleWhen`.
 *
 * ## What this makes true
 *
 * `groups` was declared with the inline comment *"Legacy support -> alias to
 * sections"* since the schema existed, and nothing in this repo ever performed
 * the fold. The alias was honored exactly ONE boundary downstream, inside the
 * renderer (objectui `spec-bridge/bridges/form-view.ts` `spec.sections ??
 * spec.groups`, and `plugin-form/ObjectForm.tsx`'s full legacy fold, shipped by
 * objectui#2545 because a `groups`-only spec had rendered nothing). Every
 * framework consumer that is NOT that renderer read `sections` only — so the
 * same authored form rendered in the console and degraded on the REST
 * public-form routes. Folding at the producer makes the declared alias true for
 * every consumer of a parsed form at once, instead of teaching each consumer a
 * second key to read (the lenient-consumer shape this package rejects).
 *
 * ## Precedence: `sections` wins
 *
 * Deliberately the renderer's own rule (`spec.sections ?? spec.groups`), so no
 * form that renders today changes what it renders. `??` treats an EMPTY array
 * as present, and so does this: `{ sections: [], groups: [...] }` folds to
 * `sections: []`, matching the renderer rather than inventing a merge.
 *
 * ⚠️ The two objectui folds disagree on exactly that input, and this rule picks
 * the PRIMARY path's answer. `spec-bridge/bridges/form-view.ts` uses `??`, so
 * an empty `sections` wins; `plugin-form/ObjectForm.tsx` gates on
 * `!folded.sections?.length`, so there the alias wins when `sections` is empty.
 * An alias is consulted when the canonical key is ABSENT — a fallback-on-empty
 * is a lenient-consumer accommodation, which is the shape this fold exists to
 * remove. Also note ObjectForm's fold rewrites sub-keys (`title` → `label`,
 * `defaultCollapsed` → `collapsed`): that is a renderer-local shape adaptation,
 * NOT spec semantics. This fold is `FormSectionSchema` → `FormSectionSchema`,
 * verbatim, with no sub-key rewriting.
 *
 * ## Why `.overwrite()` and not `.transform()` (measured, #6926)
 *
 * Both fold identically at parse. `.transform()` returns a `ZodPipe`, and this
 * schema is consumed as an OBJECT in two places in this file that a pipe breaks:
 * {@link FormViewOverlayWireSchema} builds the flattened form-overlay union
 * member with `FormViewSchema.extend(...)` (a pipe has no `.extend`), and
 * {@link selectViewMetadataBranch} reads `._zod.def.shape.type` through
 * `overlayTypeValues` — which a pipe answers with an EMPTY set, i.e. a silent
 * mis-dispatch rather than an error. Splitting into an object schema plus a
 * piped export would require re-applying the fold on the overlay branch by
 * hand, which is the re-transcription that lets two doors disagree.
 *
 * `.overwrite()` is zod 4's "transform that does not change the type", which is
 * precisely what a `FormSectionSchema[]` → `FormSectionSchema[]` alias fold is.
 * It keeps the schema a `ZodObject`, and `.extend()` INHERITS the check, so the
 * fold reaches every parse door with one declaration: `FormViewSchema` itself,
 * `ViewSchema.form` / `.formViews.*`, both `ViewItemSchema` form arms, and the
 * flattened `formOverlay` member of `ViewMetadataSchema`. The cost is that the
 * INFERRED output type still declares `groups?` even though a parsed form never
 * carries it; the runtime contract is the enforced one. (Narrowing the exported
 * `FormViewParsed` by hand is not the fix — ADR-0122's gate requires it to read
 * `z.infer<typeof FormViewSchema>` verbatim.)
 *
 * Deliberately NOT exported: it is an implementation detail of this one schema,
 * and a public fold helper is an invitation to fold a second time somewhere
 * else. Export it if and when a pre-parse door is ruled to need the same fold
 * (see "What this does NOT reach").
 *
 * ## Ordering: the `pane` refinement above still sees `groups`
 *
 * Checks run in attachment order, so the `.superRefine` is evaluated BEFORE
 * this fold and keeps reporting a misplaced `pane` at the path the author
 * actually wrote (`groups.0.pane`, not `sections.0.pane`). Attaching the fold
 * first would have re-pathed that message onto a key the author never typed.
 *
 * ## What this does NOT reach
 *
 * Only PARSED forms. Pre-parse consumers still see the authored key and are
 * right to: `packages/lint`'s view rules walk authored sources
 * (`validate-form-layout.ts`, `validate-visibility-predicates.ts`), and a
 * `sys_metadata` row saved through `saveMetaItem` is persisted VERBATIM (the
 * save validates and then discards `parsed.data` on purpose) and re-read
 * through the ADR-0087 stored-row conversion chain, which is not a zod parse.
 * The alias therefore stays legal at input — this fold narrows output, never
 * acceptance.
 */
function foldFormGroupsIntoSections<T extends WithFormSectionAlias>(
  input: T,
): Omit<T, 'groups'> {
  if (input.groups === undefined) return input as Omit<T, 'groups'>;
  const { groups, ...rest } = input;
  // `sections` wins when present — including when it is an empty array, which
  // is what the renderer's `??` does and therefore what authored forms already
  // render.
  if (rest.sections !== undefined) return rest as Omit<T, 'groups'>;
  return { ...rest, sections: groups } as Omit<T, 'groups'>;
}

/**
 * `submitBehavior: { kind: 'redirect' }` — the ruled shape of `url` (#7496,
 * maintainer ruling of 2026-08-11).
 *
 * ## What was ruled, and why the schema is where it lands
 *
 * objectui's `FormPage` performs a **verbatim redirect** on this value, and
 * objectui#4190 dead-ended asking what the value may be: nothing in this
 * package said whether it was a path, an address, or a template, so the
 * consumer could not be hardened without inventing the contract. The ruling
 * picked the narrowest shape with measured pull:
 *
 *  1. **relative paths only** — an absolute URL is refused. This is the
 *     open-redirect face: the post-submit target is authored metadata, and
 *     AI-authored metadata is exactly where an `https://` someone else chose
 *     gets copied in. Refusing the scheme form at the authoring door is a
 *     structural fix; escaping or allowlisting it at the consumer is not.
 *  2. **interpolation only from declared record fields**, every interpolated
 *     value **URL-escaped** when the redirect is built.
 *  3. a **verbatim redirect on the resolved relative path IS the intended
 *     consumption** — so the value that reaches `window.location.assign` is
 *     this string with its tokens substituted, and nothing else.
 *
 * Widening (e.g. an allowlist of absolute origins) waits for measured demand.
 *
 * ## Why `{{record.<field>}}` and not a fourth dialect
 *
 * The token spelling is not invented here: it is the ADR-0032 §3 double-brace
 * text template, whose variable scope is the CEL scope (`{{record.x}}` — see
 * `shared/expression.zod.ts`, `tmpl`). It is narrowed twice against that
 * dialect, because a redirect target has a much smaller honest scope than a
 * notification body: only the `record.` root is accepted (the record just
 * submitted is all the post-submit moment has), and only a **flat** field
 * segment, spelled with the same grammar `object.fields` keys are declared
 * under (`/^[a-z_][a-z0-9_]*$/`, `data/object.zod.ts`). A token that could
 * never name a field is refused here rather than substituted into a URL.
 *
 * ## What this refine can and cannot decide
 *
 * Parse time knows the *string*; it does not know the *object*. So the shape
 * (relative-only, token grammar, no smuggling) is enforced here, and whether
 * `{{record.foo}}` names a field this form's object actually declares is for
 * the layer that holds both — the reference-integrity family in
 * `@objectstack/lint`, which already resolves field references against object
 * declarations. Enforcing half loudly beats enforcing none.
 */
// The ruling is #7496 on the tracker — internal readers get the id here; the
// customer-facing sentence carries the date only, which is what a refused
// author can act on.
const SUBMIT_REDIRECT_RULING = 'ruled 2026-08-11';

/** The ONE interpolation `submitBehavior.url` accepts. Global — used to strip. */
const SUBMIT_REDIRECT_URL_TOKEN_RE = /\{\{record\.[a-z_][a-z0-9_]*\}\}/g;

/**
 * A leading `scheme:` — `https:`, but equally `javascript:` and `data:`, which
 * are the same refusal for a stronger reason.
 */
const URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;

/**
 * Whitespace and C0/DEL controls. Browsers **strip** leading control characters
 * and whitespace before resolving a URL, so any check that merely looks at
 * `raw[0]` can be walked past by prefixing one; refusing them outright is what
 * makes the leading-`/` rule mean what it reads like.
 */
const URL_SMUGGLE_RE = /[\s\u0000-\u001f\u007f]/;

/**
 * Validate a `submitBehavior: { kind: 'redirect' }` `url` against the ruling.
 * Returns the author-facing refusal, or `undefined` when the value conforms.
 *
 * Ordered most-specific first: an author who wrote `https://example.com/thanks`
 * is told about the open-redirect rule, not that their string lacks a `/`.
 */
function checkSubmitRedirectUrl(raw: string): string | undefined {
  if (raw === '') {
    return 'A `redirect` submit behavior needs a `url` — an empty string is not a destination. '
      + `Write the in-app path the submitter should land on, e.g. \`/thanks\` (${SUBMIT_REDIRECT_RULING}).`;
  }

  if (URL_SCHEME_RE.test(raw)) {
    return '`submitBehavior.url` accepts a RELATIVE path only, and this is an absolute URL '
      + `(${SUBMIT_REDIRECT_RULING}). A post-submit redirect that can leave the app is an open `
      + 'redirect, so the scheme form is refused at the authoring door rather than sanitized at the '
      + 'renderer. Write the in-app path instead — `/thanks`, not `https://example.com/thanks`. '
      + 'To send the browser OUT of the app deliberately, that is an app navigation item '
      + "(`{ type: 'url', url }`), which is declared for external addresses.";
  }

  if (raw.startsWith('//')) {
    return '`submitBehavior.url` accepts a RELATIVE path only, and a leading `//` is '
      + `protocol-relative — the browser reads \`//example.com/thanks\` as ANOTHER ORIGIN despite `
      + `the leading slash (${SUBMIT_REDIRECT_RULING}). Use a single leading slash for an in-app `
      + 'path; for a deliberate external link use an app navigation item (`{ type: \'url\', url }`).';
  }

  if (raw.includes('\\')) {
    return '`submitBehavior.url` must not contain a backslash — browsers normalise `\\` to `/` '
      + 'while resolving, so `/\\example.com` navigates off-origin exactly like `//example.com` '
      + `and would walk straight past the relative-only rule (${SUBMIT_REDIRECT_RULING}). `
      + 'Write the path with forward slashes; percent-encode a backslash that is genuinely part of '
      + 'a path segment (`%5C`).';
  }

  if (URL_SMUGGLE_RE.test(raw)) {
    return '`submitBehavior.url` must not contain whitespace or control characters — browsers strip '
      + 'them before resolving, so a leading one hides what the address really starts with and '
      + `defeats the relative-only rule (${SUBMIT_REDIRECT_RULING}). Percent-encode a space that `
      + 'belongs in the path (`%20`).';
  }

  // Braces are checked before the leading-`/` rule only in the sense that a
  // malformed token is reported on its own terms; the leading `/` is still
  // required, and a token therefore cannot open the path.
  const withoutTokens = raw.replace(SUBMIT_REDIRECT_URL_TOKEN_RE, '');
  if (withoutTokens.includes('{') || withoutTokens.includes('}')) {
    const offender = withoutTokens.match(/\{\{?[^{}]*\}?\}?/)?.[0] ?? '{';
    return '`submitBehavior.url` interpolates ONLY declared record fields, spelled '
      + `\`{{record.field_name}}\` — \`${offender}\` is not that shape (${SUBMIT_REDIRECT_RULING}). `
      + 'The record just submitted is the whole scope a post-submit redirect has, and the field '
      + 'segment takes the same lowercase snake_case grammar fields are declared under. Every '
      + 'interpolated value is URL-escaped when the redirect is built, so a token is a value in the '
      + 'path or query — never a way to add path structure.';
  }

  if (!raw.startsWith('/')) {
    return '`submitBehavior.url` must start with `/` — a document-relative path like `thanks` '
      + 'resolves against whichever console route the form happened to be opened from, so one form '
      + `lands in different places depending on how it was reached (${SUBMIT_REDIRECT_RULING}). `
      + 'Write the rooted in-app path: `/thanks`.';
  }

  return undefined;
}

/**
 * ## Form-view predicates may not name the `features.*` scope root
 *
 * Ruled 2026-08-27 on objectui#6262 (maintainer, decision-inbox batch 2 —
 * option B, vocabulary narrowing): **form views may not name `features.*` in
 * predicates**, and the exclusion is declared and enforced HERE, at the
 * authoring/publish door, with a loud rejection.
 *
 * ### Why the root is excluded rather than wired up
 *
 * A form view is one authored artifact served on two kinds of route, and
 * `features.*` got two different verdicts from the same predicate text:
 *
 * - inside an app (`/apps/:appName/*`) the `features` scope root resolves
 *   against the real auth-config flags (`GET /api/v1/auth/config`);
 * - on the console's standalone form routes (`/forms/:name`, public
 *   `/f/:slug`) no app context exists, the root is UNBOUND, the predicate
 *   faults — and `visibleWhen`'s fault fallback is `true`, so the field or
 *   section a feature flag was meant to hide is shown to **everyone**.
 *
 * That is a fail-OPEN asymmetry on an access-shaped key. It was measured
 * before being ruled on (objectui#6262, 2026-08-25, re-verified at dispatch):
 * ZERO authored `features.*` form-view predicates exist across
 * apps/examples/content, against an 18-hit positive control on authored
 * `visibleWhen` predicates generally — so the honest fix is to narrow the
 * vocabulary at the door, not to build an auth-config fetch + pre-load
 * semantics on a route with zero consumers.
 *
 * ### Exactly this surface, nothing else
 *
 * The exclusion covers every predicate a FORM VIEW carries: section-level
 * `visibleWhen`, field-level `visibleWhen` (including sub-fields of
 * composite/repeater/record fields at any depth), and per-option
 * `visibleWhen` on options authored inline in the form view. App-context
 * predicate surfaces (`action.visible`, bulk-action `visible`, page/app
 * predicates) keep `features.*` exactly as before — those render only where
 * the root is bound.
 *
 * ### What the scanner can and cannot decide
 *
 * Parse time sees the CEL *source string*. The scanner strips string literals
 * (so `"features"` inside quoted text cannot false-positive) and then looks
 * for `features` in ROOT position — not preceded by `.` or an identifier
 * character — so `record.features_enabled` and `record.features.x` (a record
 * field that happens to be named `features`) stay legal. An AST-only envelope
 * (`{ dialect, ast }`, no `source`) is opaque at this layer and passes — the
 * authoring shape is the source string, and build emits the AST from sources
 * this gate has already accepted.
 */
// The ruling is objectui#6262 on the tracker — internal readers get the id
// here; the customer-facing sentence carries the date only.
const FORM_VIEW_FEATURES_RULING = 'ruled 2026-08-27';

/** CEL string literals (both quote styles, with escapes) — stripped before the root scan. */
const CEL_STRING_LITERAL_RE = /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g;

/**
 * `features` in root position: start-of-source or a non-identifier,
 * non-member-access character before it, and no identifier character after —
 * catches `features.x`, `features['x']`, bare `features` and `has(features.x)`
 * while leaving `record.features` (member access) and `features_enabled`
 * (longer identifier) alone.
 */
const FEATURES_ROOT_RE = /(?:^|[^.\w])features(?![\w])/;

/**
 * Scan one parsed form-view predicate (an {@link Expression} envelope — the
 * bare-string shorthand is already normalized by the time a refinement sees
 * it) for the excluded `features.*` root. Returns the author-facing refusal,
 * or `undefined` when the predicate conforms.
 */
function checkFormViewPredicateFeaturesRoot(predicate: unknown): string | undefined {
  if (predicate === null || typeof predicate !== 'object') return undefined;
  const { dialect, source } = predicate as { dialect?: unknown; source?: unknown };
  if (dialect !== 'cel' || typeof source !== 'string') return undefined;
  if (!FEATURES_ROOT_RE.test(source.replace(CEL_STRING_LITERAL_RE, ''))) return undefined;
  return 'Form-view predicates may not name the `features.*` scope root '
    + `(${FORM_VIEW_FEATURES_RULING}). A form view also renders on routes with no app context `
    + '(the console\'s standalone `/forms/:name` and the public `/f/:slug`), where `features` is '
    + 'UNBOUND: the predicate faults and `visibleWhen` fails OPEN, so the field or section a '
    + 'feature flag was meant to hide is shown to everyone. Gate by record state instead '
    + '(`record.*`), or put the feature-gated surface on an app page or action — the surfaces '
    + 'where `features.*` stays bound.';
}

/** The subset of a parsed form field the `features.*` root scan reads. */
type FormFieldPredicateCarrier = {
  visibleWhen?: unknown;
  options?: ReadonlyArray<{ visibleWhen?: unknown } | null | undefined>;
  fields?: ReadonlyArray<string | FormFieldPredicateCarrier | null | undefined>;
};

/**
 * Walk one form-view field (and its sub-fields, and its inline options) and
 * report every predicate naming the excluded `features.*` root. Legacy
 * bare-string field entries carry no predicate and are skipped.
 */
function refineFormFieldFeaturesRoot(
  field: string | FormFieldPredicateCarrier | null | undefined,
  path: ReadonlyArray<string | number>,
  ctx: z.RefinementCtx,
): void {
  if (field === null || field === undefined || typeof field === 'string') return;
  const refusal = checkFormViewPredicateFeaturesRoot(field.visibleWhen);
  if (refusal) ctx.addIssue({ code: 'custom', path: [...path, 'visibleWhen'], message: refusal });
  field.options?.forEach((option, optionIndex) => {
    const optionRefusal = checkFormViewPredicateFeaturesRoot(option?.visibleWhen);
    if (optionRefusal) {
      ctx.addIssue({
        code: 'custom',
        path: [...path, 'options', optionIndex, 'visibleWhen'],
        message: optionRefusal,
      });
    }
  });
  field.fields?.forEach((sub, subIndex) => {
    refineFormFieldFeaturesRoot(sub, [...path, 'fields', subIndex], ctx);
  });
}

/**
 * Form View Schema
 * Defines the layout for creating or editing a single record.
 *
 * @example Simple Sectioned Form
 * {
 *   type: "simple",
 *   sections: [
 *     {
 *       label: "General Info",
 *       columns: 2,
 *       fields: ["name", "status"]
 *     },
 *     {
 *       label: "Details",
 *       fields: ["description", { field: "priority", widget: "rating" }]
 *     }
 *   ]
 * }
 */
export const FormViewSchema = lazySchema(() => strictObject({
  surface: 'this form view',
  history: VIEW_HISTORY,
  // [#13704] `steps` is the word the wizard's own vocabulary teaches (and the
  // deleted fake tutorial taught) — a guidance-refusal with the ruled spelling
  // (#13622 T1, 2026-08-31: ⛔ never an accepted alias; the `groups` alias is
  // history being paid down, not a precedent). The #5099-family shape: the
  // unknown-key rejection itself carries the prescription.
  guidance: {
    steps: 'A wizard\'s steps are its `sections` — there is no `steps` key. '
      + 'Write `type: \'wizard\'` with `sections: [{ label, fields: [...] }, …]`: '
      + 'each section renders as one gated step, and array order is step order.',
  },
}, {
  type: z.enum([
    'simple',  // Single column or sections
    'tabbed',  // Tabs
    'wizard',  // Step by step
    'split',   // Side-by-side resizable panes; sections placed via `section.pane`
    'drawer',  // Side panel
    'modal'    // Dialog
  ]).default('simple'),

  // --- Presentation options (per `type` variant). These mirror what the
  // ObjectForm component accepts so the protocol declares them; all optional. ---
  /** Field layout within the form body. */
  layout: z.enum(['vertical', 'horizontal', 'inline', 'grid']).optional().describe('Field layout direction'),
  /** Number of columns for the form body (grid/multi-column layouts). */
  columns: z.number().int().min(1).optional().describe('Number of columns for the form body'),
  /** Optional form title / description (for embedded or standalone forms). */
  title: z.string().optional().describe('Form title'),
  description: z.string().optional().describe('Form description'),
  /** Tabbed (`type: 'tabbed'`). */
  defaultTab: z.string().optional().describe('Initially active tab (tabbed forms)'),
  tabPosition: z.enum(['top', 'bottom', 'left', 'right']).optional().describe('Tab strip position (tabbed forms)'),
  /**
   * Wizard (`type: 'wizard'`) — the step-sequenced form variant. Ruled contract
   * (#13622 proposal D4–D8, maintainer 2026-08-31 「同意」; renderer semantics
   * measured in that proposal against objectui's WizardForm):
   *
   * - **Sections ARE the steps, and array order IS step order (D8).** There is
   *   no `steps:` key (refused with a prescription — see this surface's
   *   `guidance`) and no `order` key: an integer beside the array would be a
   *   second source of truth that a reordering edit silently contradicts.
   * - **The step gate is the DEFAULT semantics of the type (D4).** With
   *   `allowSkip` absent/false, step N+1 opens only after step N submits and
   *   passes validation; going back, and re-entering completed steps, is always
   *   free. `allowSkip: true` grants **navigation freedom, not a validation
   *   exemption** — the final submit still re-validates every step's declared
   *   fields and returns the author to the first failing step. The gate is a
   *   UI admission rule, **never authorization**: nothing server-side evaluates
   *   it, and the server re-validates the submitted record in both modes.
   * - **Per-step validation binds ONLY the existing field-level vocabulary
   *   (D6)**: `required` / `requiredWhen` / `readonlyWhen` / per-option
   *   `visibleWhen`, evaluated by the same canonical rule engine the plain form
   *   renderer and the server share. There is no step-level `ValidationRule`
   *   binding — cross-field/script rules stay write-time vocabulary the server
   *   enforces at final submit.
   * - **Progress is DERIVED state (D5).** Each step's completed / current /
   *   upcoming / invalid standing derives from the gate; `showStepIndicator`
   *   is the only authorable progress surface — no progress object, no
   *   percentages, no custom step-state text.
   * - **Wizard steps carry no predicate slot and do not collapse (D2).**
   *   `visibleWhen` (and its deprecated `visibleOn` alias) and
   *   `collapsible` / `collapsed: true` on a wizard section are refused at
   *   parse — see the superRefine below; it is the spec-door upgrade of
   *   objectui#6237's ruled `FormSectionConfig` split ("WizardForm steps =
   *   No"). A wizard with absent/empty `sections` is refused too (D7): it used
   *   to silently render as a plain simple form.
   */
  allowSkip: z.boolean().optional().describe(
    'Wizard step-gate opt-out: allow entering a later step without submitting the one before it. '
    + 'Navigation freedom, NOT a validation exemption — the final submit still re-validates every '
    + 'step and returns to the first failing one. Default (absent/false): steps unlock in array '
    + 'order as each prior step submits validly. UI admission only, never authorization.',
  ),
  showStepIndicator: z.boolean().optional().describe(
    'Show the wizard step indicator (renderer default: shown). Step progress '
    + '(completed/current/upcoming/invalid) is derived from the step gate — this boolean is the '
    + 'only authorable progress surface.',
  ),
  /** Split (`type: 'split'`). */
  splitDirection: z.enum(['horizontal', 'vertical']).optional().describe('Split orientation (split forms)'),
  splitSize: z.number().optional().describe('Primary split panel size, % (split forms)'),
  splitResizable: z.boolean().optional().describe('Whether the split is resizable (split forms)'),
  /** Drawer (`type: 'drawer'`). */
  drawerSide: z.enum(['top', 'bottom', 'left', 'right']).optional().describe('Drawer side (drawer forms)'),
  /** @deprecated [#2578 → `modalSize` / size buckets] A pixel width can't be authored blind (unknown client viewport); the renderer derives width from content + viewport. */
  drawerWidth: z.string().optional().describe('[DEPRECATED → size buckets] Drawer width, e.g. "480px". A pixel width cannot be chosen without knowing the client viewport — the renderer derives it.'),
  /** Modal (`type: 'modal'`). */
  modalSize: z.enum(['sm', 'default', 'lg', 'xl', 'full']).optional().describe('Modal size (modal forms)'),

  /**
   * Data Source Configuration. NOT removed in the #3896 sweep despite the
   * ledger's dead verdict — the removal attempt broke the build and thereby
   * re-verified the entry: `defineForm` (below) writes
   * `data: { provider: 'schema', schemaId }` onto EVERY metadata form, and
   * `metadata-protocol` serves it to the metadata-admin pipeline. The
   * record-form provider values (`object`/`api`/`value`) may still be
   * unread — that is a narrower value-subset audit, not a key removal.
   */
  data: ViewDataSchema.optional().describe('Data source configuration (defaults to "object" provider)'),

  sections: z.array(FormSectionSchema).optional(), // For simple layout
  /**
   * Legacy alias of {@link FormViewSchema.sections} — accepted at INPUT, folded
   * onto `sections` at parse (#6926), and therefore never present in a parsed
   * form. See {@link foldFormGroupsIntoSections} for the fold and why it lives
   * here rather than in each consumer.
   */
  groups: z.array(FormSectionSchema).optional().describe(
    '[LEGACY ALIAS → `sections`] Accepted for back-compat and folded onto `sections` at parse; `sections` wins when both are present. Prefer `sections`.',
  ),

  /**
   * Inline child collections (master-detail). When present, the standard
   * create/edit form for this object renders as a master-detail form — the
   * object's own fields on top, an editable grid per child collection below,
   * persisted together in ONE atomic transaction — with no bespoke page. Each
   * entry needs only `childObject`; the relationship FK and grid columns are
   * derived from the child object's metadata (override via
   * `relationshipField` / `columns`).
   */
  subforms: z.array(strictObject({
    surface: 'this subform',
    history: VIEW_HISTORY,
    // `object` is the word every OTHER block on this surface uses for an object
    // name (`ViewDataSchema.object`, `ViewItemSchema.object`), so writing it
    // here is an author being consistent — not making a typo.
    aliases: {
      object: 'childObject', childObjectName: 'childObject', child: 'childObject',
      foreignKey: 'relationshipField', relationField: 'relationshipField', parentField: 'relationshipField',
      fields: 'columns', label: 'title', sumField: 'amountField', rollupField: 'totalField',
    },
  }, {
    childObject: z.string().describe('Child object whose records are entered inline'),
    relationshipField: z.string().optional().describe('FK on the child pointing back to the parent (auto-detected when omitted)'),
    columns: z.array(z.any()).optional().describe('Editable grid columns (derived from the child object when omitted)'),
    amountField: z.string().optional().describe('Numeric child column summed for the running total'),
    totalField: z.string().optional().describe('Parent field to receive the rolled-up sum'),
    title: z.string().optional().describe('Section title'),
    addLabel: z.string().optional().describe('Add-row button label'),
    minRows: z.number().optional(),
    maxRows: z.number().optional(),
  })).optional().describe('Inline master-detail child collections'),

  // `defaultSort` REMOVED (#3896 audit close-out): no reader in either repo —
  // related lists sort by their OWN list view's sort, never by this.
  defaultSort: retiredKey(
    '`form.defaultSort` was removed in @objectstack/spec 17.0.0 (audit close-out) — ' +
    'nothing read it: a related list inside a form sorts by its own list view\'s `sort`. ' +
    'Delete the key and set the sort on the related list view instead. ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.',
  ),

  /** Public form sharing configuration */
  sharing: SharingConfigSchema.optional().describe('Public sharing configuration for this form'),

  /**
   * What happens after a successful submit.
   *
   * The default when this is omitted is **mode-aware**, not a single fixed
   * kind (ruled 2026-08-10 on #7245): the public `/_console/f/:slug` path
   * defaults to `thank-you` — there is no record an anonymous submitter is
   * allowed to read back, so a confirmation panel is all there is to show.
   * The internal `/_console/forms/:name` path — where `type: 'form'` actions
   * send operators — defaults to redirecting to the record that was just
   * created, since an operator who just created a record belongs on that
   * record. An explicit `submitBehavior` always wins, in either mode.
   *
   * - `thank-you` — show a confirmation panel
   * - `redirect` — send the browser to a URL
   * - `continue` — reset the form so another response can be entered
   * - `next-record` — advance to the next record (internal queues only)
   */
  // ⚠️ `discriminatedUnion`, not `union` — deliberately, and it is the closing
  // that forces the choice. A plain `z.union` of four STRICT members reports a
  // bad key as `invalid_union` carrying four sub-errors, one per member, and
  // #5014 measured that the renderers flatten those to a bare "Invalid input" —
  // so the prescription this campaign exists to deliver would never reach the
  // author. Discriminating on the `kind` literal that is already there picks
  // the ONE intended member and reports its message verbatim. No input changes
  // shape: every member already required its own `kind` literal.
  submitBehavior: z.discriminatedUnion('kind', [
    strictObject({
      surface: 'this `thank-you` submit behavior',
      history: VIEW_HISTORY,
      aliases: { heading: 'title', text: 'message', body: 'message', description: 'message' },
    }, {
      kind: z.literal('thank-you'),
      title: z.string().optional(),
      message: z.string().optional(),
    }),
    strictObject({
      surface: 'this `redirect` submit behavior',
      history: VIEW_HISTORY,
      // `delay` / `delayMS` are one keystroke and one capital from `delayMs`;
      // the unit is in the name, so a bare `delay` is genuinely ambiguous and
      // gets pointed at the spelled-out key rather than silently dropped.
      aliases: { delay: 'delayMs', delayMS: 'delayMs', timeout: 'delayMs', to: 'url', href: 'url', target: 'url' },
    }, {
      kind: z.literal('redirect'),
      // The ruled shape — see `checkSubmitRedirectUrl` above for what each
      // refusal defends and why the refine, not the consumer, is where it
      // lands. `z.string()` stays the type on purpose: the consumption ruled in
      // is a verbatim redirect on the resolved path, so this key must keep
      // arriving at the renderer as the string the author wrote (an
      // `Expression` envelope would change what `FormPage` reads).
      url: z.string()
        .superRefine((raw, ctx) => {
          const refusal = checkSubmitRedirectUrl(raw);
          if (refusal) ctx.addIssue({ code: 'custom', message: refusal });
        })
        .describe(
          'Where the browser goes after a successful submit. Ruled 2026-08-11: '
          + '(1) RELATIVE paths only — it must start with `/`, and absolute or protocol-relative '
          + 'URLs are refused, which is what closes the open-redirect face; '
          + '(2) interpolation ONLY from declared record fields, spelled `{{record.field_name}}`, '
          + 'and every interpolated value is URL-escaped when the redirect is built; '
          + '(3) a verbatim redirect on the resolved relative path is the intended consumption. '
          + "To send the browser OUT of the app, use an app navigation item (`{ type: 'url', url }`) instead.",
        ),
      delayMs: z.number().int().min(0).optional(),
    }),
    strictObject({
      surface: 'this `continue` submit behavior',
      history: VIEW_HISTORY,
      // `continue` resets the form and takes no options; an author configuring
      // confirmation text wanted the `thank-you` kind instead.
      guidance: {
        title: 'The `continue` behavior takes no options — it just resets the form. For a confirmation panel use `{ kind: "thank-you", title, message }`.',
        message: 'The `continue` behavior takes no options — it just resets the form. For a confirmation panel use `{ kind: "thank-you", title, message }`.',
      },
    }, { kind: z.literal('continue') }),
    strictObject({
      surface: 'this `next-record` submit behavior',
      history: VIEW_HISTORY,
      guidance: {
        title: 'The `next-record` behavior takes no options — it advances to the next record. For a confirmation panel use `{ kind: "thank-you", title, message }`.',
        message: 'The `next-record` behavior takes no options — it advances to the next record. For a confirmation panel use `{ kind: "thank-you", title, message }`.',
      },
    }, { kind: z.literal('next-record') }),
  // The `url` describe below carries the ruling in full, but it reaches only
  // the generated JSON Schema: the references page renders a union as one type
  // expression, so a member's inner key gets no row of its own. The headline
  // therefore rides HERE, where the reference table does have a row (#7496).
  ]).optional().describe(
    "Post-submit behavior. On the `redirect` arm, `url` is relative-only and interpolates "
    + 'only declared record fields as `{{record.field_name}}`, URL-escaped (ruled 2026-08-11).',
  ),

  /**
   * Structured action-button config: per-button visibility + label for
   * `submit` / `cancel` / `reset`. The spec home for the flat renderer-invented
   * keys ObjectUI's `ObjectForm` used to read (`showSubmit`/`submitText`/
   * `showCancel`/`cancelText`/`showReset`) — now consumed: `ObjectForm` folds
   * `buttons.*` down onto those flat props at render (framework#1894, #2998),
   * with the flat keys kept only as deprecated back-compat. Authoring `buttons`
   * takes effect; a stale flat key still wins where explicitly set.
   */
  buttons: z.object({
    submit: FormButtonConfigSchema.optional().describe('Submit button'),
    cancel: FormButtonConfigSchema.optional().describe('Cancel button'),
    reset: FormButtonConfigSchema.optional().describe('Reset button'),
  }).strict().optional()
    .describe('Form action-button visibility & labels; folded onto the flat renderer props by ObjectUI ObjectForm.'),

  /**
   * Initial field values for create-mode forms, keyed by field machine name —
   * the spec home for ObjectUI's renderer-invented `initialValues`. Consumed:
   * `ObjectForm` folds `defaults` into its create-mode initial values at render
   * (framework#1894, #2998); an explicit `initialValues` (e.g. URL prefill)
   * still wins.
   */
  defaults: z.record(z.string(), z.unknown()).optional()
    .describe('Initial field values for create-mode forms (folded into ObjectUI ObjectForm initial values;).'),

  // `aria` REMOVED from the FORM view (#3896 audit close-out): no form
  // renderer applied it (plugin-form/SchemaForm never read schema.aria) — an
  // ACCESSIBILITY claim that is merely accepted is false compliance, the
  // requiresConfirmation shape.
  aria: retiredKey(
    '`form.aria` was removed in @objectstack/spec 17.0.0 (audit close-out) — no form ' +
    'renderer ever applied it, so declared ARIA attributes silently did not reach the DOM. ' +
    'Delete the key. The form renderer emits its own semantic markup; report gaps as ' +
    'renderer issues rather than per-view attribute overrides. ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.',
  ),
}).superRefine((view, ctx) => {
  // `section.pane` is split-only vocabulary. On any other form type it would
  // be a silent no-op — the worst failure mode for authored (and especially
  // AI-authored) metadata, where "accepted but ignored" reads as working.
  // Reject it loudly at parse instead. `.extend()` keeps this check (zod 4
  // attaches refinements to the schema), so the flattened runtime-overlay
  // variant in ViewMetadataSchema enforces it too.
  //
  // ⚠️ This refinement runs BEFORE the `.overwrite()` fold — see
  // {@link foldFormGroupsIntoSections} — so every check here must keep
  // reading BOTH buckets (`sections` AND the legacy `groups` alias).
  for (const [key, sections] of [['sections', view.sections], ['groups', view.groups]] as const) {
    sections?.forEach((section, index) => {
      if (view.type !== 'split' && section?.pane != null) {
        ctx.addIssue({
          code: 'custom',
          path: [key, index, 'pane'],
          message:
            `\`pane\` places a section in a split pane and is only valid on \`type: 'split'\` ` +
            `form views (this form is '${view.type}'). Remove the key or change the form type.`,
        });
      }
      // The `features.*` scope-root exclusion (ruled 2026-08-27, objectui#6262
      // — see {@link checkFormViewPredicateFeaturesRoot}): every predicate
      // this form view carries — section-level, field-level at any depth,
      // per-option — is refused when it names the root that is unbound on the
      // standalone form routes. Runs on every form `type`, split included.
      const sectionRefusal = checkFormViewPredicateFeaturesRoot(section?.visibleWhen);
      if (sectionRefusal) {
        ctx.addIssue({ code: 'custom', path: [key, index, 'visibleWhen'], message: sectionRefusal });
      }
      section?.fields?.forEach((field, fieldIndex) => {
        refineFormFieldFeaturesRoot(field, [key, index, 'fields', fieldIndex], ctx);
      });
      // [#13704] Wizard steps carry no predicate slot and do not collapse —
      // objectui#6237's ruled `FormSectionConfig` split ("WizardForm steps =
      // No"), upgraded from a renderer fact to a parse refusal (#13622 D2/T2,
      // ruled 2026-08-31). Breadth is ruled NARROW: exactly this step-key
      // family — no per-type presentation-key matrix.
      //
      // Post-parse observability decides the spellings checked here:
      // `FormSectionSchema` folds `visibleOn` → `visibleWhen` (its
      // `.transform(normalizeVisibleWhen)`) before this refinement runs, so
      // one check answers both spellings (the message says so, since the
      // reported path can only name the canonical key). `collapsible` /
      // `collapsed` carry `.default(false)`, so an authored `false` is
      // indistinguishable from the default here — and needs no refusal: it
      // declares exactly the behavior a wizard delivers. Only `true` declares
      // behavior a wizard step does not have.
      if (view.type === 'wizard' && section != null) {
        if (section.visibleWhen != null) {
          ctx.addIssue({
            code: 'custom',
            path: [key, index, 'visibleWhen'],
            message:
              '`visibleWhen` on a wizard step is refused: wizard steps carry no predicate slot '
              + '— steps are entered in array order behind the step gate, '
              + 'never conditionally. Put the predicate on the fields inside the step, or use a '
              + "`simple`/`tabbed` form for section-level visibility. (The deprecated `visibleOn` "
              + 'alias folds into `visibleWhen` and is refused the same way.)',
          });
        }
        for (const collapseKey of ['collapsible', 'collapsed'] as const) {
          if (section[collapseKey] === true) {
            ctx.addIssue({
              code: 'custom',
              path: [key, index, collapseKey],
              message:
                `\`${collapseKey}\` on a wizard step is refused: wizard steps do not collapse — `
                + 'the wizard shows exactly the current step. Remove the key; collapsible '
                + 'grouping belongs to `simple`/`tabbed` sections.',
            });
          }
        }
        // [#13855] The field-group REFERENCE form is refused on a wizard step
        // for the same reason the two refusals above exist, one layer back: a
        // `fieldGroups` entry carries `visibleWhen` and `collapse`, and
        // `deriveFieldGroupLayout` passes both through to the derived section.
        // Accepting `group` here would hand a wizard step exactly the predicate
        // and collapse state #13704 just finished refusing — reached through
        // the object's declaration instead of the step's own keys, so the
        // refusals above would report clean while the behaviour arrived anyway.
        // The section schema cannot see the group (that is cross-schema), so
        // the honest answer at parse is to refuse the reference on this form
        // type, not to guess what the group declares.
        //
        // Deliberately the CONSERVATIVE direction: a wizard step whose group
        // declares neither key is legal metadata this refuses today, and
        // allowing it later (once the renderer half lands and a ruling covers a
        // derived predicate on a step) is additive.
        if (section.group != null) {
          ctx.addIssue({
            code: 'custom',
            path: [key, index, 'group'],
            message:
              '`group` on a wizard step is refused: a field group carries `visibleWhen` and '
              + '`collapse`, and `deriveFieldGroupLayout` passes both through to the section it '
              + 'derives — neither of which a wizard step has a slot for (steps are entered in '
              + 'array order behind the step gate, and the wizard shows exactly the current step). '
              + 'Enumerate the step with `fields: [...]`, or use a `simple`/`tabbed` form to '
              + 'inherit the group.',
          });
        }
      }
    });
  }
  // [#13704] A wizard must declare its steps (#13622 D7, ruled 2026-08-31).
  // Before this refusal, `type: 'wizard'` with absent/empty `sections`
  // silently fell back to plain simple rendering (objectui RecordFormPage's
  // conditional spread + ObjectForm's `sections?.length` guard) — the
  // accepted-but-ignored shape. ⛔ No "at least 2 steps" floor: a one-step
  // wizard is legal and renders.
  //
  // Scoped to the doors where the body claims to be a COMPLETE authored form
  // view (`ViewSchema.form` / `formViews`, the ViewItem config arms). The
  // flattened runtime-overlay member (`FormViewOverlayWireSchema` =
  // `.extend(flattenedViewOverlayFields()).strip()`) is exempt: an overlay is
  // a partial patch over a shadowed registry entry — `{ type: 'wizard' }`
  // beside the required `object`+`viewKind` binding, with `sections` supplied
  // by the base view, is its load-bearing round-trip shape (#7025 pins that
  // membership; moving it needs its own ruling, per #7741's precedent). The
  // extension's required `viewKind` is the structural marker of that door: on
  // THIS strict shape the key can never be present (unknown keys are refused
  // before acceptance), so reading it distinguishes the doors mechanically.
  // The step-KEY refusals above run on every door on purpose — they fire only
  // on a key the author wrote, which is never a partial-overlay artifact.
  if (view.type === 'wizard' && typeof (view as { viewKind?: unknown }).viewKind !== 'string') {
    // Mirror `foldFormGroupsIntoSections`' precedence exactly (`sections`
    // wins even when empty), and report at the bucket the author wrote —
    // canonical `sections` when neither bucket is present.
    const steps = view.sections !== undefined ? view.sections : view.groups;
    if (steps === undefined || steps.length === 0) {
      const authoredKey =
        view.sections !== undefined ? 'sections' : view.groups !== undefined ? 'groups' : 'sections';
      ctx.addIssue({
        code: 'custom',
        path: [authoredKey],
        message:
          "A `type: 'wizard'` form view must declare its steps: `"
          + authoredKey + '` is ' + (steps === undefined ? 'absent' : 'empty')
          + ', and the wizard would silently render as a plain simple form. Declare at least one '
          + 'step — `sections: [{ label, fields: [...] }]`; sections ARE the steps, in array order.',
      });
    }
  }
}).overwrite(foldFormGroupsIntoSections));

/**
 * Object-scoped user filters (ADR-0047 amendment, framework #2679 / objectui #2338).
 *
 * A {@link UserFiltersSchema} restricted to the styles that make sense on an object
 * list view: `dropdown` (per-field value chips — the Airtable "quick filter" pills)
 * and the deprecated `toggle`. The `tabs` element and its two companions
 * (`showAllRecords`, `allowAddTab`) are OMITTED because an object view's saved-view
 * switcher (`ViewTabBar`) already owns the tab-bar role — a `tabs` user-filter would
 * render a second, conflicting tab bar. Need named presets on an object? Use
 * `listViews` (each becomes a segmented tab).
 *
 * ## Why this carries its OWN error map instead of inheriting the base's (#5073)
 *
 * The shape is still DERIVED — `.omit()` off {@link UserFiltersSchema}, so a key
 * added upstream flows in rather than being re-transcribed (#2231). What is not
 * inherited is the unknown-key message, and that is deliberate: `.omit()` keeps the
 * base's `strictObject` error map, whose `knownKeys` were read from the base's shape
 * — which still contains the three omitted keys. Measured before this was written:
 * an author who typed `tab` on an object view got *"Did you mean `tab` → `tabs`?"*,
 * a suggestion to write the one key this surface refuses, and a bare `tabs` was
 * rejected with no prescription at all. Both are the campaign's finding 7 — the fix
 * signposting the way into the failure it exists to kill — and #5073 is the change
 * that turned these keys from silently-dropped into rejected, so the message is this
 * change's own responsibility. Rebuilding the map over the OMITTED shape drops the
 * three keys out of the suggestion pool, and `guidance` gives each the pointer the
 * CLI lint (`packages/lint/src/validate-list-view-mode.ts`) already carries.
 */
export const ObjectUserFiltersSchema = lazySchema(() => strictObject({
  surface: 'these object user filters',
  history: VIEW_HISTORY,
  guidance: {
    tabs: '`tabs` presets are page-only: an object view\'s tab bar is its saved-view switcher (ViewTabBar), and a second one would collide. Define each preset as a named entry under the object\'s `listViews` instead — every one renders as a segmented tab.',
    showAllRecords: '`showAllRecords` configures the page-only `tabs` element. On an object view the default list view already is the "all records" entry; use `listViews` for the named presets beside it.',
    allowAddTab: '`allowAddTab` configures the page-only `tabs` element. An object view\'s tab bar is the saved-view switcher (ViewTabBar), which owns its own add control.',
  },
}, {
  ...UserFiltersSchema.omit({ tabs: true, showAllRecords: true, allowAddTab: true }).shape,
  element: z.enum(['dropdown', 'toggle']).default('dropdown')
    .describe('Filter control style on object views: "dropdown" (per-field value chips). "toggle" is deprecated. "tabs" is page-only — use `listViews` for named presets.'),
}));

/**
 * ADR-0047 "views" mode — an object's default list + named list views.
 *
 * Structurally a {@link ListViewSchema} whose `userFilters` is narrowed to
 * {@link ObjectUserFiltersSchema}: `dropdown` value chips are allowed (ADR-0047
 * amendment, framework #2679), but the page-only `tabs` preset bar is not — that
 * belongs to a page list (`InterfaceListPage`, "filters" mode), because an object
 * view's only tab-bar nav is the `ViewTabBar`. The narrowed schema makes a `tabs`
 * user-filter untypable at author time (tsc); the CLI `validate` list-view-mode rule
 * reports it pre-parse. See objectui #2338.
 */
export const ObjectListViewSchema = lazySchema(() =>
  ListViewShapeSchema.omit({ userFilters: true })
    .extend({ userFilters: ObjectUserFiltersSchema.optional() })
    // Derived from the UNREFINED shape (zod 4 refuses `.omit()` on a refined
    // object), so the binding checks are re-attached here rather than
    // inherited. Dropping these lines would leave `objects[].listViews.*` —
    // the ADR-0047 authoring surface — as the one door where a `page` view
    // with no `pageName`, or a calendar-enabled view with no `calendar:`
    // block, parses clean.
    .superRefine(checkListViewPageMount)
    .superRefine(checkListViewCalendarVisualization));

/**
 * [#4001/#7741] The wrap remedy, ONE prose source for two doors: the container's
 * unknown-key guidance (the build/authoring door below) and the inline overlay
 * arms' missing-binding refusals (the runtime write door —
 * {@link flattenedViewOverlayFields}). The ruling on #7741 (2026-08-12) requires
 * the write door to reuse the build path's existing guidance — 「写门的拒绝复用
 * build 路径已有的 guidance」 — so the sentence is shared rather than forked into
 * a second copy that would drift on the first rewording.
 */
const VIEW_WRAP_REMEDY =
  'Wrap it: `defineView({ list: { type, data, columns, … } })`, or name it — '
  + '`defineView({ listViews: { my_view: { … } } })`.';

/**
 * Master View Schema
 * Can define multiple named views.
 */
/**
 * View Container Schema
 * Aggregates all view definitions for a specific object or context.
 *
 * @example
 * {
 *   list: { type: "grid", columns: ["name"] },
 *   form: { type: "simple", fields: ["name"] },
 *   listViews: {
 *     "all": { label: "All", filter: [] },
 *     "my": { label: "Mine", filter: [["owner", "=", "{current_user_id}"]] }
 *   }
 * }
 */
export const ViewSchema = lazySchema(() => strictObject({
  surface: 'this view container',
  history: VIEW_HISTORY,
  // The one mistake this shape actually sees: a FLAT list view written where a
  // CONTAINER goes. `defineView` has guarded it since the container was
  // introduced, with a comment saying why — "`ViewSchema` strips unknown
  // top-level keys, so a flat list view would parse to an empty container".
  // Another bespoke guard built to work around silent stripping, and like every
  // other one this campaign has found, it covered ONE door: `defineView`. The
  // metadata door (Studio, the API, an agent) got the empty container in
  // silence. Closing the shape covers both; the guard stays for the case strict
  // cannot see — `defineView({})`, an empty container with no unknown keys at
  // all, which is still zero views registered.
  //
  // `name`, `label` and `object` are NOT in this list, and the first draft had
  // all three — wrongly. A container carries its own identity and its object
  // binding: `saveMetaItem` sends the name, artifact-shipped containers do
  // (`service-ai/ai_traces`), the validation sweep injects it, and a
  // stack-level `views: [...]` entry needs `object` to say which object it
  // belongs to (this file's own note on `ObjectListViewSchema` calls the
  // container "view definitions for a specific object", and `getViewsByObject()`
  // is what reads that binding). Tombstoning them rejected shapes the platform
  // itself writes.
  //
  // The list below is what survived an EMPIRICAL check rather than a confident
  // one: every container literal in the repo was scanned for these nine keys,
  // and only `name` / `label` / `object` ever appear on one. That check should
  // have come before the guidance, not after three CI failures — a guidance
  // entry is a claim about the schema, and claims need verifying like code.
  guidance: Object.fromEntries(
    ['type', 'columns', 'data', 'viewKind', 'filters', 'sort']
      .map((k) => [k, `\`${k}\` belongs to a single VIEW, not to the container. ${VIEW_WRAP_REMEDY} The container's own keys are \`list\`, \`form\`, \`listViews\`, \`formViews\`.`]),
  ),
}, {
    // Item identity. The container is a registered metadata item, so the door
    // supplies these — declared for the same reason `translation` needed them
    // (#4001 batch 5): undeclared, they were stripped, and the metadata door
    // quietly discarded an item's own name on the way through.
    // No grammar, and that is the ADR-0017 §3.2 dual-read talking: the
    // container is registered under the BARE object key, so its own name is
    // `crm_lead` — flat by construction, where a standalone ViewItem record
    // must be `crm_lead.<viewKey>`. Stated once in this module's header block.
    name: z.string().optional().describe('Item name — supplied by the metadata door; for an object-scoped container it is the object name.'),
    label: I18nLabelSchema.optional().describe('Human-readable label shown in metadata lists.'),
    object: z.string().optional().describe('Object this container binds to — how a stack-level `views: [...]` entry says which object its views belong to; read by `getViewsByObject()` / `GET /meta/view?object=`.'),
    list: ObjectListViewSchema.optional(), // Default list view (views mode — dropdown userFilters allowed, no tabs; ADR-0047)
    form: FormViewSchema.optional(), // Default form view
    listViews: z.record(z.string(), ObjectListViewSchema).optional().describe('Additional named list views (views mode — dropdown userFilters allowed, no tabs; ADR-0047)'),
    formViews: z.record(z.string(), FormViewSchema).optional().describe('Additional named form views'),
  /**
   * ADR-0010 §3.7 — Package-level protection envelope. Package
   * authors declare lock policy here; the loader translates it
   * into the private `_lock` envelope at registration time and
   * strips this block before persistence. See
   * `shared/protection.zod.ts`.
   */
  protection: ProtectionSchema.optional().describe(
    'Package author protection block — lock policy for this view.',
  ),

  // ADR-0010 — runtime protection envelope (internal — set by loader).
  ...MetadataProtectionFields,

}));

/**
 * Type-safe factory for creating view definitions.
 *
 * Validates the config at creation time using Zod `.parse()`, and rejects a
 * container that defines no views: `ViewSchema` strips unknown top-level keys,
 * so a *flat* list view (`{ name, label, type, columns, ... }`) would parse to
 * an empty container — zero views register and the Console silently renders
 * nothing. Failing here surfaces that authoring mistake at build time.
 *
 * @example
 * ```ts
 * const taskViews = defineView({
 *   list: {
 *     type: 'grid',
 *     data: { provider: 'object', object: 'task' },
 *     columns: ['subject', 'status', 'priority', 'due_date'],
 *   },
 *   form: {
 *     type: 'simple',
 *     sections: [{ label: 'Details', fields: [{ field: 'subject' }] }],
 *   },
 * });
 * ```
 */
export function defineView(config: z.input<typeof ViewSchema>): ViewParsed {
  const parsed = ViewSchema.parse(config);
  const viewCount =
    (parsed.list ? 1 : 0) +
    (parsed.form ? 1 : 0) +
    Object.keys(parsed.listViews ?? {}).length +
    Object.keys(parsed.formViews ?? {}).length;
  if (viewCount === 0) {
    throw new Error(
      'defineView: the container defines no views — nothing registers and no view appears in the Console. '
      + 'Declare at least one of `list`, `form`, `listViews`, `formViews`. '
      + 'If you passed a flat list view ({ name, label, type, columns, ... }), wrap it: '
      + 'defineView({ list: { type, data, columns, ... } }).'
    );
  }
  return parsed;
}

// ───────────────────────────────────────────────────────────────────────────
// Independent View Item model (Object has-many View)
// ───────────────────────────────────────────────────────────────────────────
//
// The {@link ViewSchema} *container* above aggregates every view of an object
// into one document. That model cannot express runtime-authored views (a user
// adding "My high-value leads" at runtime cannot append to a developer's source
// file), and it forces multiple distinct views into a single designer.
//
// {@link ViewItemSchema} promotes each named view to a first-class, independently
// addressable entity bound to its object by a foreign key. The object↔view
// switcher is then a *query* (`getViewsByObject`) rather than embedded storage —
// mirroring Airtable / Salesforce / Notion, where a table/object has-many views.
//
// `defineView` is retained as authoring sugar: the backend loader expands an
// aggregated document into N ViewItems at registration time, so existing
// `*.view.ts` files and the published spec keep working unchanged.

/**
 * Qualified view-item identity: `<object>.<viewKey>` — dotted snake_case
 * segments, e.g. `crm_lead.pipeline`. Globally unique, and the object can be
 * recovered from the prefix, so the registry key never collides across objects.
 *
 * The dot-REQUIRED arity of the platform's one item-name grammar
 * (`QUALIFIED_ITEM_NAME_PATTERN`, `shared/identifiers.zod.ts` — #12194): same
 * segment source as `MetadataItemNameSchema`, which the metadata publish door
 * enforces with the qualifier optional. Grammar changes belong there, not here.
 */
export const ViewItemNameSchema = z
  .string()
  .regex(
    QUALIFIED_ITEM_NAME_PATTERN,
    'View item name must be a dotted snake_case qualified name, e.g. "crm_lead.pipeline".',
  )
  .describe('Globally-unique view id, `<object>.<viewKey>`.');

/**
 * Identity layer for a view item — its visibility scope and ownership.
 *
 * - `package`  — shipped from `*.view.ts` source / an installed package.
 *                Not deletable (reinstall restores it); customisable via an
 *                override layer; hideable from the switcher.
 * - `shared`   — authored at runtime, visible org-wide. Creating one is gated
 *                by the `view.manageShared` capability.
 * - `personal` — authored at runtime, scoped to `owner`. Any user with read
 *                access to the object may create one.
 *
 * Named `scope` (not `provenance`) to avoid colliding with the loader-set
 * `_provenance` envelope field, which tracks a different axis
 * (package | org | env-forced).
 */
export const ViewScopeSchema = z
  .enum(['package', 'shared', 'personal'])
  .describe('View identity layer: package | shared | personal.');

/** Discriminator for the kind of view a {@link ViewItemSchema} carries. */
export const ViewKindSchema = z
  .enum(['list', 'form'])
  .describe('Whether `config` is a ListView (list family) or a FormView.');

/**
 * Fields shared by every independent view item, regardless of kind. Returned
 * as a raw Zod shape so it composes into each discriminated-union member
 * without forcing eager schema construction.
 */
function viewItemBaseShape() {
  return {
    // The dot is REQUIRED here and NOWHERE ELSE in the `view` family — the
    // overlay and container spellings declare an ungrammared `name`. The
    // three-way rule, and both directions it is misread in, are stated once in
    // this module's header block.
    name: ViewItemNameSchema,
    object: z
      .string()
      .describe('Bound object name — the foreign key used to aggregate views.'),
    label: I18nLabelSchema.optional().describe('Display label (supports i18n).'),
    isDefault: z
      .boolean()
      .optional()
      .describe("Whether this is the object's default view in the switcher."),
    order: z
      .number()
      .int()
      .optional()
      .describe("Sort order within the object's view switcher / left rail."),
    scope: ViewScopeSchema.optional().describe(
      'Identity layer (defaults to `package` for source-loaded views).',
    ),
    owner: z
      .string()
      .optional()
      .describe('Owner user id — set when `scope` is `personal`.'),
    hidden: z
      .boolean()
      .optional()
      .describe('Hidden from the switcher (per-user / per-org declutter).'),
    /**
     * Package author protection block — same envelope as {@link ViewSchema};
     * the loader translates it into the private `_lock` envelope.
     */
    protection: ProtectionSchema.optional().describe(
      'Package author protection block — lock policy for this view.',
    ),
    // ADR-0010 — runtime protection envelope (internal — set by loader).
    ...MetadataProtectionFields,
  };
}

/**
 * Independent View Item — a single named view bound to one object.
 *
 * Discriminated on `viewKind`: a `list` item carries a {@link ListViewSchema}
 * config (grid / kanban / calendar / …), a `form` item carries a
 * {@link FormViewSchema} config.
 *
 * @example
 * ```ts
 * const pipeline = defineViewItem({
 *   name: 'crm_lead.pipeline',
 *   object: 'crm_lead',
 *   viewKind: 'list',
 *   label: 'Pipeline',
 *   config: {
 *     type: 'kanban',
 *     data: { provider: 'object', object: 'crm_lead' },
 *     columns: ['name', 'stage', 'amount'],
 *   },
 * });
 * ```
 */
/**
 * One arm of the ViewItem discriminated union, as a raw shape.
 *
 * Both postures below are built from THIS function, so the authoring gate and
 * the wire member cannot drift into two transcriptions of one contract (#2231's
 * derive-by-reference; the fork PD#12 exists to prevent). The two differ in
 * exactly two ways, both visible at the call site: the unknown-key posture, and
 * the round-trip keys the wire arm additionally declares.
 */
function viewItemArmShape<K extends 'list' | 'form'>(viewKind: K, config: z.ZodTypeAny) {
  return {
    viewKind: z.literal(viewKind),
    config,
    ...viewItemBaseShape(),
  };
}

/**
 * [#9933] The per-user column layout the console's grid persists through the
 * `view` metadata door — an **explicitly runtime-only overlay key**, admitted
 * where overlays are validated and deliberately NOT authorable.
 *
 * Modeled on what the write actually sends (measured on objectui#5233's
 * os-dev-report and `ObjectGridColumnState` in objectui's
 * `plugin-grid/src/ObjectGrid.tsx`): `onColumnStateChange` emits
 * `{ order?: string[]; widths?: Record<string, number> }` — the merged result
 * of a column reorder and a resize — and `persistViewPatch` PUTs it as the
 * `columnState` key of a personalization overlay. Until this key was declared,
 * a `columnState`-only patch carried no key any {@link ViewMetadataSchema}
 * member declared, so {@link assertViewIdentity} refused the body ("no
 * recognized `view` key") and the write 422'd — the ruled patch-only write
 * (objectstack#7494 comment 5261754173) could not land. It survived only
 * inside the fat write's copied base, i.e. laundered past validation.
 *
 * Posture decisions, both deliberate:
 *  - **Not `.strict()`**: the console owns the internals of this per-user
 *    state (objectui's `gridNonAuthorKeys` ruling, 2026-08-18), so a future
 *    console key here must not 422 against an older server. The two known
 *    keys are typed; unknown inner keys parse (and `saveMetaItem` stores the
 *    original body verbatim anyway).
 *  - **Not exported, not on {@link ListViewSchema}**: exporting would mint a
 *    protocol def / authorable-surface entries, and declaring it on the
 *    authoring shape would bless hand-authoring a payload the product writes
 *    on the user's behalf. Author-writability is a DIFFERENT spec change,
 *    explicitly out of #9933's scope; the authoring doors keep rejecting the
 *    key by name (see `VIEW_ITEM_SURFACE.guidance` and `ListViewSchema`'s
 *    `guidance`).
 *
 * Declared ABOVE the ViewItem section on purpose: `viewItemWireFields()` reads
 * it, and under `OS_EAGER_SCHEMAS=1` every `lazySchema` factory runs at module
 * init in file order — a `const` declared below its first eager reader is a
 * TDZ `ReferenceError` at import time (the `strict-object.ts` docblock carries
 * the measured incident).
 */
const ViewColumnStateSchema = z.object({
  order: z.array(z.string()).optional()
    .describe('Column order as field names, leftmost first (runtime-only per-user state — written by the console grid, never authored).'),
  widths: z.record(z.string(), z.number()).optional()
    .describe('Column widths in pixels, keyed by field name (runtime-only per-user state — written by the console grid, never authored).'),
}).describe(
  'Runtime-only personalization overlay key: the per-user column layout (order/widths) the console grid '
  + 'persists through the `view` metadata API. NOT authorable — authoring doors reject it by name; do not write it in metadata source.',
);

/** The authoring surface `defineViewItem` and Studio's create form are judged by. */
const VIEW_ITEM_SURFACE = {
  surface: 'this view item',
  history: VIEW_HISTORY,
  guidance: {
    // The failure this close exists for (#5074): one letter, and the author got
    // a ViewItem with NO view configuration that parsed clean.
    confg: 'Did you mean `config`? A ViewItem carries its whole view definition under `config`.',
    // Wire keys, named so the rejection tells an author where they belong
    // instead of leaving them to guess.
    isPinned: 'Pinning is per-user Studio state, not authored metadata — the console writes it through the `view` metadata API. Remove it from authored metadata.',
    sortOrder: 'Switcher position is per-user Studio state, not authored metadata — use `order` for the authored default. Remove it from authored metadata.',
    // [#9933] Runtime-only overlay key — same disposition as the two above.
    columnState: 'Column order/widths are per-user runtime personalization the console grid writes through the `view` metadata API — not authored metadata. Remove it from authored metadata.',
  },
} as const;

/**
 * [#5074] The AUTHORING gate — strict. Split from the wire member it used to be.
 *
 * Until #5074 one schema wore two contracts. It is what {@link defineViewItem}
 * parses and what objectui's view-create form validates `createBuildBody`'s
 * output against (`app-shell/src/views/metadata-admin/view-create-body.test.ts`)
 * — an authoring door that genuinely wants strict. It was ALSO the first member
 * of {@link ViewMetadataSchema}, the union `saveMetaItem` validates every
 * persisted `view` body against — a wire role that genuinely needs Studio's
 * round-trip keys through.
 *
 * Traced end to end rather than inferred, and the trace is why the split was
 * necessary rather than cosmetic. objectui's "pin this view" control calls
 * `dataSource.updateView(object, id, { isPinned })`
 * (`app-shell/src/views/ObjectView.tsx:882`), and `updateView`
 * (`data-objectstack/src/index.ts:2801`) GETs the stored item and PUTs
 * `{ ...current, ...partial }`. For a standalone ViewItem record `current`
 * carries `viewKind` AND `config`, so the merged body matches member 1 — the
 * flattened-overlay members are excluded by their `config: z.undefined()` guard
 * — and it arrives carrying `isPinned`, which the authoring shape does not
 * declare. That body is now judged by {@link ViewItemWireSchema} instead.
 *
 * What closing this buys, in the words of the ruling that ordered it:
 * `defineViewItem({ name, object, viewKind, confg: {…} })` — one letter wrong —
 * used to strip the typo and hand back a ViewItem with **no view configuration
 * at all**, parsed clean. That is #1535's `workflows: [...]` replayed on the
 * surface with the highest author density in the file.
 */
export const ViewItemSchema = lazySchema(() =>
  z.discriminatedUnion('viewKind', [
    strictObject(VIEW_ITEM_SURFACE, viewItemArmShape('list', ListViewSchema.describe('List-family view configuration.'))),
    strictObject(VIEW_ITEM_SURFACE, viewItemArmShape('form', FormViewSchema.describe('Form view configuration.'))),
  ]),
);

/**
 * Auxiliary Studio round-trip keys, given an explicit DECLARED home on the wire
 * variant (#5074) instead of living implicitly on "the member nobody closed".
 *
 * These are per-user switcher state the console writes through the `view`
 * metadata API and reads back; `saveMetaItem` persists the body verbatim, so
 * they are on the wire and in the store. They are deliberately declared HERE and
 * not on {@link ViewItemSchema}: an author who writes `isPinned` in a `*.view.ts`
 * gets a named rejection pointing at `order`, while the console's own PUT parses.
 */
function viewItemWireFields() {
  return {
    isPinned: z.boolean().optional()
      .describe('Studio round-trip: view pinned in the switcher (per-user state, written by the console — not authored).'),
    sortOrder: z.number().int().optional()
      .describe('Studio round-trip: position within the switcher (per-user state, written by the console — not authored).'),
    // [#9933] Same disposition as the two keys above: per-user state the
    // console writes through the `view` metadata API. `updateView` PUTs
    // `{ ...current, ...partial }`, so on a standalone ViewItem record the
    // key arrives at THIS member's top level; declaring it validates the
    // shape where `.strip()` used to let it ride through unchecked.
    columnState: ViewColumnStateSchema.optional()
      .describe('Studio round-trip: per-user column order/widths (runtime-only state, written by the console grid — not authored)'),
  };
}

/**
 * [#5074] The WIRE variant of {@link ViewItemSchema} — member 1 of
 * {@link ViewMetadataSchema}, re-opened with `.strip()`.
 *
 * Exactly the pattern the two flattened members below already use
 * (`ListViewSchema.extend(flattenedViewOverlayFields()).strip()`), reached one
 * member further. `z.discriminatedUnion` cannot be `.extend()`ed, so the two
 * postures share {@link viewItemArmShape} rather than a `.extend()` chain —
 * derive-by-reference either way, one shape, two doors.
 *
 * `.strip()` covers the TOP level only. Nested console decorations
 * (`config.filter[].id`, `config.sort[].id`) are handled by
 * {@link stripViewConsoleDecorations} on the wire door — see that function for
 * why a recursive strip is the piece a posture flip cannot provide.
 */
export const ViewItemWireSchema = lazySchema(() =>
  z.discriminatedUnion('viewKind', [
    z.object({
      ...viewItemArmShape('list', ListViewSchema.describe('List-family view configuration.')),
      ...viewItemWireFields(),
    }).strip(),
    z.object({
      ...viewItemArmShape('form', FormViewSchema.describe('Form view configuration.')),
      ...viewItemWireFields(),
    }).strip(),
  ]),
);

/**
 * Type-safe factory for an independent {@link ViewItem}.
 *
 * Validates the config at creation time using Zod `.parse()`.
 *
 * @example
 * ```ts
 * const allLeads = defineViewItem({
 *   name: 'crm_lead.all',
 *   object: 'crm_lead',
 *   viewKind: 'list',
 *   isDefault: true,
 *   config: { type: 'grid', data: { provider: 'object', object: 'crm_lead' }, columns: ['name'] },
 * });
 * ```
 */
export function defineViewItem(config: z.input<typeof ViewItemSchema>): ViewItem {
  return ViewItemSchema.parse(config);
}

// ───────────────────────────────────────────────────────────────────────────
// Canonical persisted-`view`-body schema (the runtime metadata-type schema)
// ───────────────────────────────────────────────────────────────────────────
//
// #3095 — the `view` metadata type maps to THIS schema in
// `metadata-type-schemas.ts` (both the save-time 422 validator and the
// read-time `computeMetadataDiagnostics` badge consult it). A single
// container schema ({@link ViewSchema}) is a NO-OP for two of the three shapes
// a `view` body actually carries at runtime: Zod strips unknown keys, so a
// standalone {@link ViewItemSchema} record ({ name, object, viewKind, config })
// and a console personalization overlay (raw view config + inherited identity)
// both parse to `{}` — silently "valid" while their `config` is never checked.
//
// The three legitimate runtime shapes, each validated GENUINELY here:
//
//   1. `defineView` aggregate **container** — at least one of
//      `list`/`form`/`listViews`/`formViews`. An empty container is rejected
//      (it registers zero views; mirrors the {@link defineView} guard).
//   2. Standalone **ViewItem record** — `{ viewKind, config, … }`; the nested
//      `config` is validated against ListView/FormView.
//   3. **Flattened runtime overlay** — a raw ListView/FormView config at the
//      top level plus optional identity fields (`viewKind`/`object`/`label`,
//      inherited from the shadowed registry entry by `normalizeViewMetadata`;
//      see #2555). This is what a personalization PUT (column sort, inline
//      edit, …) sends. Discriminated from a record by the ABSENCE of a nested
//      `config`, and from a container by the ABSENCE of container slots — the
//      structural guards below make those exclusions explicit so a malformed
//      record/container can never be rescued by this lenient branch.
//
// Auxiliary Studio round-trip keys (`isPinned`, `sortOrder`, …) ride along on
// the shapes Studio actually round-trips, matching the "persist the payload
// verbatim" contract in `saveMetaItem` (it validates but stores the original
// item). ⚠️ [#5074] The line that used to stand here said "all four members
// strip-parse (no `.strict()`)". It was true when written, then half-false and
// half-load-bearing (批 18 measured it), and is now replaced by the split. As
// it stands, measured:
//
//   • member 1 is `ViewItemWireSchema` — the `.strip()` WIRE variant of
//     `ViewItemSchema`. The authoring schema of the same shape is strict and
//     lives at its own name; this is the body `updateView` PUTs for a
//     standalone ViewItem record, and `isPinned`/`sortOrder` are DECLARED on it
//     rather than surviving because nobody closed the member.
//   • member 2 (the container) IS strict. `ViewSchema` was closed by an earlier
//     batch, so `{ list: …, isPinned: true }` 422s. Not a regression: nothing
//     sends it. `updateView` unwraps a container to its inner list config
//     (`if (current?.list) current = current.list`) before merging, so a
//     container body never reaches this union carrying an aux key.
//   • members 3 and 4 are the flattened overlays, `.strip()` and saying so.
//
// ⚠️ All three `.strip()`s re-open the TOP level ONLY — `.strip()` no more
// recurses than `.strict()` does. The nested console decorations
// (`filter[].id`, `sort[].id`) are removed by `stripViewConsoleDecorations`
// BEFORE the union runs, which is what makes the wire opening
// recursive-effective and what let `ViewFilterRuleSchema` / `ListView.sort`
// close for authoring. Anyone closing a member here must re-run that trace,
// not re-read this comment.
//
// [#5599] …and the cost of that opening, before the identity precondition
// below existed: member 4 both `.strip()`s AND declares no required key
// (`FormViewSchema.type` even carries a `'simple'` default), so it matched
// ANY object. `{ nope: 1 }` did not merely pass — it passed as a *view*,
// reduced to `{ type: 'simple' }`, and `saveMetaItem` (which persists the
// ORIGINAL body, not the parse output) wrote `{"nope":1,"name":"…"}` into
// `sys_metadata` as an ACTIVE view overlay. The read path then re-parsed the
// same body through the same schema and badged it `_diagnostics.valid: true`
// (#5598), so Studio agreed. `view` was the one common overlay type whose
// declared write-path spec gate (ADR-0005 §Validation) could be bypassed by
// an arbitrary body — Prime Directive #10's "declared ≠ enforced", one layer
// above the object schemas #4001 closed: at union-MEMBER SELECTION, not at
// any single member. The fix is a precondition, NOT a strictness flip on the
// members — see {@link assertViewIdentity} and {@link viewMetadataVocabulary}.
//
// [#7741] The residue that precondition deliberately let through — a body that
// DOES speak view vocabulary (`{ type: 'grid', columns: […] }`) but names no
// object to attach to — was the same defect one layer further in: accepted,
// persisted, badged valid, served by nothing. Closed at the members this time
// (ruled direction B, 2026-08-12): the two flattened overlay arms now REQUIRE
// `object` + `viewKind` — the exact pair the object-bound read paths filter on
// — with located refusals that reuse the container door's wrap guidance. The
// precondition's bar (speaks the vocabulary at all) and the members' bar
// (bound enough to be servable) are different questions and stay in their own
// stages; a baseline-shadowing personalization PUT arrives here already bound
// because `normalizeViewMetadata` inherits identity before validation (#2555).

/**
 * [#7741] The located refusals the two inline overlay arms give a body that
 * arrives at the runtime write door without its object binding.
 *
 * Why these are REQUIRED rather than optional (maintainer ruling, 2026-08-12,
 * direction B): every object-bound read path matches a stored view row on
 * `object` AND `viewKind` — `GET /meta/view?object=` (rest-server.ts) and
 * `getViewsByObject()` (metadata-manager.ts) both filter
 * `v.viewKind && v.object === obj` — so an inline config missing either is
 * stored, badged `valid: true`, and then served by nothing: `expandViewContainer`
 * never sees it (it is not a container) and the switcher never lists it. The
 * ruling: 「一个无法展开、无法被任何读路径服务的行,不允许被存储并盖上
 * `valid:true`」. Both fields, not `object` alone, because the pair is what the
 * measured serving filter requires — a row bound by `object` but missing
 * `viewKind` is exactly as invisible to the switcher as the card's repro.
 *
 * The platform's own personalization writes are unaffected: `saveMetaItem`
 * normalizes before it validates, and `viewIdentityPatch`
 * (`@objectstack/metadata-protocol`, #2555) inherits `viewKind`/`object`/`label`
 * from the registry entry the overlay shadows — an expanded ViewItem always
 * carries both — so a console pin/sort/hide PUT on a REAL view reaches this
 * schema already bound. The body that arrives unbound is the one with no entry
 * to inherit from: a new name authored inline, i.e. the dead row this closes.
 *
 * Draft and active alike, by the same ruling — the schema is mode-agnostic on
 * purpose: 「draft 与 active 同样适用 …… 现在没有这个证据,不预留」.
 */
const INLINE_VIEW_OBJECT_REQUIRED =
  'This inline view config names no `object`, so the saved row could never be served: '
  + '`GET /meta/view?object=…` and the view switcher match stored views on `object` + `viewKind`, '
  + 'and a row missing them is registered yet renders nowhere. '
  + 'Bind it — add `object: "<object_name>"` and `viewKind: "list" | "form"` — or save a ViewItem '
  + 'record (`{ name, object, viewKind, config: { … } }`), or make it a container. '
  + VIEW_WRAP_REMEDY;

const INLINE_VIEW_KIND_REQUIRED =
  'This inline view config names no `viewKind`, so the saved row could never be served: '
  + '`GET /meta/view?object=…` and the view switcher match stored views on `object` + `viewKind`, '
  + 'and a row missing them is registered yet renders nowhere. '
  + 'Bind it — add `viewKind: "list" | "form"` alongside `object` — or save a ViewItem record '
  + '(`{ name, object, viewKind, config: { … } }`), or make it a container. '
  + VIEW_WRAP_REMEDY;

/**
 * Identity + structural-guard fields layered onto the two "flattened runtime
 * overlay" members. The `config`/`list`/`form`/`listViews`/`formViews` guards
 * pin those keys to `undefined`: a body carrying any of them is a record or a
 * container, not a flattened overlay, so it must be validated by the dedicated
 * member instead of slipping through here with its real payload stripped away.
 *
 * [#7741] `object` and `viewKind` are REQUIRED on these two members — see the
 * refusal constants above for the measured reason and the ruling. The rest of
 * the identity fields stay optional: they are display/round-trip state, not
 * what any read path filters on.
 */
function flattenedViewOverlayFields() {
  return {
    // No grammar, deliberately: the write path stamps this name rather than an
    // author writing it, so a flat overlay name is legal here while the SAME
    // string is refused by `viewItemBaseShape()`'s `ViewItemNameSchema`. The
    // per-spelling rule is stated once in this module's header block.
    name: z.string().optional().describe('Save name / qualified view id (stamped by the write path).'),
    object: z
      .string({ error: (issue) => (issue.input === undefined ? INLINE_VIEW_OBJECT_REQUIRED : undefined) })
      .describe(
        'Bound object name — REQUIRED on an inline view config: the object-bound read paths '
        + '(`GET /meta/view?object=`, the view switcher) match on `object` + `viewKind`, so an unbound '
        + 'row can never be served. Inherited from the shadowed entry on personalization PUTs.',
      ),
    viewKind: z
      .enum(ViewKindSchema.options, {
        error: (issue) => (issue.input === undefined ? INLINE_VIEW_KIND_REQUIRED : undefined),
      })
      .describe(
        'View family — REQUIRED on an inline view config: half of the `object` + `viewKind` '
        + 'pair the object-bound read paths match on. Inherited from the shadowed entry on '
        + 'personalization PUTs.',
      ),
    label: I18nLabelSchema.optional().describe('Display label (inherited from the shadowed entry —).'),
    // [#9933] Runtime-only overlay key — declared HERE (the overlay-validation
    // face) and on `viewItemWireFields()`, never on an authoring shape. This is
    // what lets a `columnState`-only personalization patch through the
    // identity precondition (the vocabulary is derived from the members' keys)
    // AND gets its inner shape genuinely validated instead of ridden past
    // `.strip()` unchecked.
    columnState: ViewColumnStateSchema.optional(),
    isDefault: z.boolean().optional(),
    order: z.number().int().optional(),
    scope: ViewScopeSchema.optional(),
    owner: z.string().optional(),
    hidden: z.boolean().optional(),
    protection: ProtectionSchema.optional(),
    ...MetadataProtectionFields,
    // Structural guards — a flattened overlay is neither a record nor a container.
    config: z.undefined().optional(),
    list: z.undefined().optional(),
    form: z.undefined().optional(),
    listViews: z.undefined().optional(),
    formViews: z.undefined().optional(),
  };
}

/**
 * True when a `view` container defines at least one view. The bare
 * {@link ViewSchema} accepts `{}` (every slot optional), which would let an
 * empty overlay pass validation and register nothing — the same footgun
 * {@link defineView} rejects at authoring time.
 */
function containerHasAView(v: unknown): boolean {
  if (!v || typeof v !== 'object') return false;
  const c = v as Record<string, unknown>;
  return Boolean(
    c.list ||
    c.form ||
    (c.listViews && typeof c.listViews === 'object' && Object.keys(c.listViews).length > 0) ||
    (c.formViews && typeof c.formViews === 'object' && Object.keys(c.formViews).length > 0),
  );
}

/**
 * [#5599] The keys the WRITE PATH itself puts on a `view` body, which therefore
 * cannot be evidence that the author sent a view.
 *
 * `saveMetaItem` normalizes before it validates. `normalizeViewMetadata`
 * (`@objectstack/metadata-protocol`) stamps `name` onto **every** view body at
 * the single write chokepoint — it exists precisely to guarantee one — and, when
 * the overlay shadows a registry entry, `viewIdentityPatch` inherits `viewKind`,
 * `object` and `label` from it (#2555). A key present on 100% of the bodies
 * reaching the gate has zero discriminating power: counting `name` as evidence
 * would leave this precondition unable to reject anything on the write path at
 * all — which is the one path #5599 is about, since `{ nope: 1 }` arrives at the
 * schema as `{ nope: 1, name: 'garbage_view' }`, exactly the body the issue
 * reports as persisted.
 *
 * So the bar is *shape*, not identity — which is how the ruling worded it too.
 * A body may be very lean, but it must say something about what the view IS; a
 * body of these keys alone says only which view it is attached to.
 *
 * Exported so the producer side can be pinned against it: `normalizeViewMetadata`
 * must never stamp a key that is not listed here, or that key silently becomes
 * evidence again and re-opens this hole. That pin lives with the producer, in
 * `metadata-protocol`'s `view-write-path-identity.test.ts`.
 */
export const VIEW_WRITE_PATH_IDENTITY_KEYS: ReadonlySet<string> = new Set([
  'name',
  'viewKind',
  'object',
  'label',
]);

/**
 * [#5599] Every top-level key ANY member of {@link ViewMetadataSchema} declares,
 * MINUS {@link VIEW_WRITE_PATH_IDENTITY_KEYS} — the vocabulary the identity
 * precondition judges "is this a `view` at all?" against.
 *
 * **Derived from the members, never hand-listed.** A literal array here would be
 * a second declaration of the union's own surface, and the two would drift on
 * the first member that grows a key — the precondition would then reject a body
 * the union accepts, which is a 422 on a shape the platform itself writes. So it
 * walks the members' Zod defs instead: objects contribute their `shape` keys,
 * unions recurse into their options (member 1 is a discriminated union of two
 * arms), and wrappers (`.refine()`, `.strip()`, pipes) are unwrapped. Adding a
 * key to any arm widens this set in the same edit, with no bookkeeping.
 *
 * Computed once, on first parse rather than at schema-construction time: the
 * members are {@link lazySchema} proxies whose factories run on first `_zod`
 * touch, and deriving eagerly would force every view schema in the file to
 * materialise as a side effect of this module loading (ADR-0089 D3a).
 */
function collectDeclaredTopLevelKeys(schema: unknown, into: Set<string>, depth = 0): void {
  const def = (schema as { _zod?: { def?: Record<string, unknown> } } | undefined)?._zod?.def;
  if (!def || depth > 6) return;
  if (def.type === 'object') {
    for (const key of Object.keys((def.shape ?? {}) as object)) into.add(key);
    return;
  }
  if (def.type === 'union') {
    for (const option of (def.options ?? []) as unknown[]) collectDeclaredTopLevelKeys(option, into, depth + 1);
    return;
  }
  // `.refine()` keeps the object def; these cover pipes / wrappers defensively.
  for (const hop of ['innerType', 'in', 'out', 'schema'] as const) {
    if (def[hop]) collectDeclaredTopLevelKeys(def[hop], into, depth + 1);
  }
}

/**
 * [#5599] The precondition's predicate half, extracted (#6391) so
 * {@link diagnoseViewMetadata} can ask the SAME question the parse path asks
 * without having to recognise the issue text the other half writes.
 *
 * True for anything this precondition does not judge (non-objects, arrays —
 * left to the union, which already rejects them) and for any object carrying at
 * least one key some member declares that the write path did not stamp itself.
 */
function speaksViewVocabulary(body: unknown): boolean {
  if (typeof body !== 'object' || body === null || Array.isArray(body)) return true;
  const vocabulary = viewMetadataVocabulary();
  return Object.keys(body as Record<string, unknown>).some((key) => vocabulary.has(key));
}

/**
 * [#5599] The minimal identity precondition, run BEFORE the four-arm union.
 *
 * A `view` body must speak the `view` vocabulary — carry at least one key some
 * member declares that the write path did not stamp itself
 * ({@link VIEW_WRITE_PATH_IDENTITY_KEYS}). That is the whole bar, deliberately:
 * it rejects bodies that are **not a view at all** (`{ nope: 1 }`, `{}`,
 * `{ id: 'x' }`, and identity with no content) while making no judgement about
 * whether the view is *complete* — which is what keeps it compatible with every
 * lean shape the platform round-trips. A pin PUT (`{ isPinned: true }`), a hide
 * PUT (`{ hidden: true }`), a reorder (`{ sortOrder: 3 }`) and a column-sort PUT
 * all carry declared non-identity keys and are unaffected *by this precondition*
 * ([#7741] the UNION may still refuse the baseline-less ones — an overlay with
 * no shadowed entry to inherit `object`/`viewKind` from now fails the members'
 * binding requirement, which is the ruled behaviour, and the refusal is the
 * members' located guidance rather than this precondition's).
 *
 * "Complete" is deliberately NOT the bar, and the distinction is the whole
 * reason this is safe: `{ isPinned: true }` is not a renderable view either, but
 * it is unambiguously a *view operation*, and 422-ing the platform's own writes
 * would be a worse defect than the one being fixed.
 *
 * **Why a precondition and not a required floor on member 4.** Giving the form
 * arm a required key (the other candidate fix) would 422 the flattened overlays
 * Studio writes, whose required-ness nobody has measured; the ruling on #5599
 * took this route and deferred that one explicitly. This route also leaves every
 * arm's `.strip()` untouched — the round-trip capability #5074 traced and
 * documented is load-bearing and is not what was broken. What was broken is that
 * an arm which strips AND requires nothing is a wildcard for the whole union, so
 * the fix belongs one level up, at the union's door.
 *
 * **Why it lives in the existing `z.preprocess` stage.** `/api/v1/meta/types/view`
 * serves `z.toJSONSchema()` of this schema to Studio's SchemaForm, and both pins
 * (`view-metadata-schema.test.ts`, `view-authoring-wire-split.test.ts`) require a
 * four-member `anyOf` in the OUTPUT *and* INPUT directions. Adding a stage to the
 * pipe (`z.unknown().superRefine(…).pipe(union)`) satisfies the output direction
 * and silently degrades the input one to `{}` — the form would render nothing.
 * Reporting through the preprocess's own `ctx` changes no types, so the emitted
 * `anyOf` is byte-identical. It also short-circuits: `z.NEVER` aborts the pipe,
 * so a rejected body yields ONE named issue instead of that issue plus four
 * `invalid_union` branches for arms that were never the point.
 */
function assertViewIdentity(body: unknown, ctx: z.RefinementCtx): boolean {
  // Non-objects and arrays are left to the union, which already rejects them —
  // this precondition answers "which object is not a view", nothing else.
  if (typeof body !== 'object' || body === null || Array.isArray(body)) return true;
  if (speaksViewVocabulary(body)) return true;
  const keys = Object.keys(body as Record<string, unknown>);
  // Report the two halves separately. Lumping them together would call `name`
  // "unrecognized", which is false and would send an author to fix the wrong
  // key: `name` is declared, it is just discounted as evidence.
  const identity = keys.filter((key) => VIEW_WRITE_PATH_IDENTITY_KEYS.has(key));
  const unknown = keys.filter((key) => !VIEW_WRITE_PATH_IDENTITY_KEYS.has(key));
  const quote = (list: string[], cap = 5) =>
    `${list.slice(0, cap).map((k) => `\`${k}\``).join(', ')}${list.length > cap ? ', …' : ''}`;
  ctx.addIssue({
    code: 'custom',
    path: [],
    message:
      'Not a `view` body: no recognized `view` key. Expected at least one of a container slot ' +
      '(`list` / `form` / `listViews` / `formViews`), a ViewItem record (`viewKind` + `config`), ' +
      'or an inline view config (`type`, `columns`, `sections`, `filter`, …). ' +
      (keys.length === 0 ? 'Received `{}`.' : 'Received ') +
      (unknown.length > 0 ? `unrecognized ${unknown.length === 1 ? 'key' : 'keys'} ${quote(unknown)}` : '') +
      (unknown.length > 0 && identity.length > 0 ? ', and ' : '') +
      (identity.length > 0
        ? `only identity fields (${quote(identity)}) — these say which view this attaches to, ` +
          'not what the view is, and the write path stamps them itself'
        : '') +
      (keys.length === 0 ? '' : '.'),
  });
  return false;
}

// ───────────────────────────────────────────────────────────────────────────
// [#6391] The union's members, named and published
// ───────────────────────────────────────────────────────────────────────────
//
// Measured from the consumer side (objectui#3606 / PR objectui#3624, against
// `@objectstack/spec` 17.0.0-rc.5): a consumer that has to turn a
// `ViewMetadataSchema` failure back into per-field diagnostics had exactly two
// routes, and both couple to spec internals. It could index the nested
// `invalid_union` `errors[]` BY MEMBER POSITION — position is an internal
// detail nobody promised, so objectui pinned it with a CANARY test that rings
// on every reorder — or it could re-declare each member itself, which is a
// deeper coupling still and was measured and rejected there.
//
// The cause was never the union: member 1 was already the exported
// `ViewItemWireSchema`, and a consumer could reference THAT contractually. The
// other three were inline expressions with no name, so member 2 was merely
// "shaped like `ViewSchema`" — key-for-key identical, behaviourally identical,
// and NOT the same object, which is precisely the difference between a contract
// and a resemblance.
//
// So the members get names, the union is built FROM those names (the identity
// is guaranteed by construction, not maintained by hand), and a branch-naming
// diagnostic entry point sits beside them so a consumer never has to know the
// order at all — {@link diagnoseViewMetadata}.
//
// The names are published as ONE export — {@link VIEW_METADATA_MEMBERS}, keyed
// by branch — rather than as three individual `…Schema` consts, and that is a
// decision rather than a style: a top-level exported schema binding mints a new
// protocol def (`ui/ViewContainerWire`, …) in `json-schema.manifest/` and, for
// anything with a derivable object shape, a full set of keys in the ratcheted
// `authorable-surface/`. The container member's 15 keys ARE `ui/View`'s 15
// keys — duplicating them there would add 15 phantom authorable properties to
// the ADR-0049 liveness worklist for a wire door nobody authors against. The
// record gives a consumer the same contractual handle
// (`VIEW_METADATA_MEMBERS.container`) with none of that.
//
// ⛔ What this deliberately does NOT do: convert the union to
// `z.discriminatedUnion`. That was the filer's other option, and it would move
// the ACCEPTANCE face — a discriminated union refuses an unknown discriminant
// outright where this union falls through all four members, and several of
// these shapes have no discriminant key at all (a flattened overlay may carry
// nothing but `columns`). The dispatch below is therefore a DIAGNOSTIC
// dispatch: it names the branch a failure belongs to, and decides nothing about
// whether the body is accepted. `ViewMetadataSchema` remains the only judge.

/**
 * [#6391] Member 2 of {@link ViewMetadataSchema} — a non-empty `defineView`
 * container. Published as `VIEW_METADATA_MEMBERS.container`.
 *
 * `ViewSchema` itself accepts `{}` (every slot optional), which would register
 * zero views; the refinement is what makes this member "a container that
 * actually defines a view" — see {@link containerHasAView}. It is published
 * because that refinement, not `ViewSchema`, is what the union holds: a
 * consumer selecting "the container branch" needs the object the union is
 * actually going to run, or its diagnosis diverges from the platform's on
 * exactly the empty-container case.
 */
const ViewContainerWireSchema = lazySchema(() =>
  ViewSchema.refine(containerHasAView, {
    message:
      'A view container must define at least one of `list`, `form`, `listViews`, or `formViews`.',
  }),
);

/**
 * [#6391] Member 3 of {@link ViewMetadataSchema} — a flattened runtime LIST
 * overlay: an inline `ListView` config at the top level plus the optional
 * identity/round-trip fields a personalization PUT carries. Published as
 * `VIEW_METADATA_MEMBERS.listOverlay`.
 *
 * `.strip()` is load-bearing, not leftover. `.extend()` INHERITS strictness, so
 * closing `ListViewSchema` for authoring (#4001) silently made this overlay
 * strict too — and this member exists precisely to carry Studio's auxiliary
 * round-trip keys (`isPinned`, `sortOrder`, …) that `saveMetaItem` persists
 * verbatim. Strict here is a 422 on a shape the platform itself writes. The
 * ledger names this as the trap to watch while batching: a response-side
 * extension of an authoring schema must strip back, or an upstream field
 * addition becomes a crash.
 *
 * [#7741] `object` + `viewKind` are required on this arm (and its form
 * sibling) — see {@link flattenedViewOverlayFields} for the ruling and the
 * measured serving filter that decides exactly this pair.
 */
const ListViewOverlayWireSchema = lazySchema(() =>
  // [#13216] Built from {@link ListViewShapeSchema}, not {@link ListViewSchema}:
  // `flattenedViewOverlayFields()` re-declares `name` and `label`, and zod 4
  // refuses to overwrite a key on an object that carries refinements. So the
  // binding checks are re-attached AFTER `.strip()` instead of inherited — this
  // is the runtime write door (`PUT /api/v1/meta/view`), the one an MCP/AI
  // author reaches, so it is the last place the refusals may go missing.
  // `viewDoorsCarryingPageMountCheck` in `view.test.ts` fails if any of the
  // three attachment points is dropped.
  ListViewShapeSchema.extend(flattenedViewOverlayFields()).strip()
    .superRefine(checkListViewPageMount)
    .superRefine(checkListViewCalendarVisualization),
);

/**
 * [#6391] Member 4 of {@link ViewMetadataSchema} — a flattened runtime FORM
 * overlay, published as `VIEW_METADATA_MEMBERS.formOverlay`. Same construction
 * and the same `.strip()` rationale as {@link ListViewOverlayWireSchema}; the
 * list member is tried first, and a flattened form (no required `columns`,
 * disjoint `type` enum) then matches here.
 */
const FormViewOverlayWireSchema = lazySchema(() =>
  FormViewSchema.extend(flattenedViewOverlayFields()).strip(),
);

/**
 * [#6391] The branch names of {@link ViewMetadataSchema}'s union, in
 * declaration order.
 *
 * The order is still the union's evaluation order — that has not changed and is
 * observable — but a consumer no longer has to *encode* it: it can ask for a
 * branch by name via {@link VIEW_METADATA_MEMBERS}, or let
 * {@link diagnoseViewMetadata} name the branch for it.
 */
export const VIEW_METADATA_BRANCHES = ['viewItem', 'container', 'listOverlay', 'formOverlay'] as const;

/** [#6391] One branch of {@link ViewMetadataSchema}'s union, by name. */
export type ViewMetadataBranch = (typeof VIEW_METADATA_BRANCHES)[number];

/**
 * [#6391] Branch name → the schema {@link ViewMetadataSchema}'s union actually
 * holds for that branch.
 *
 * This record IS the union's member list: the schema below is built by mapping
 * {@link VIEW_METADATA_BRANCHES} over it, so "member N is the published schema"
 * is guaranteed by construction rather than by two declarations agreeing. Add a
 * member here and it is in the union, named, in one edit.
 *
 * The values are {@link lazySchema} proxies, so naming them costs no eager
 * materialisation (ADR-0089 D3a) — reading this record does not build a single
 * view schema.
 */
export const VIEW_METADATA_MEMBERS = {
  // 1. Standalone ViewItem record — nested config validated genuinely, and the
  //    WIRE variant, so Studio's round-trip keys have a declared home.
  viewItem: ViewItemWireSchema,
  // 2. Non-empty defineView container.
  container: ViewContainerWireSchema,
  // 3/4. Flattened runtime overlay — inline ListView / FormView config + identity.
  listOverlay: ListViewOverlayWireSchema,
  formOverlay: FormViewOverlayWireSchema,
} as const satisfies Record<ViewMetadataBranch, z.ZodTypeAny>;

/**
 * [#5599] The `view` vocabulary, derived once from the members on first use.
 *
 * Hoisted out of {@link ViewMetadataSchema}'s factory closure (#6391) so
 * {@link diagnoseViewMetadata} can consult the SAME derivation the parse path
 * consults. Two copies of this rule would be two answers to "is this a view
 * body at all?", and the diagnostic one would be the wrong one.
 *
 * Still computed on first call rather than at module load: the members are
 * {@link lazySchema} proxies whose factories run on first `_zod` touch, and
 * deriving eagerly would force every view schema in the file to materialise as
 * a side effect of this module loading (ADR-0089 D3a).
 */
let viewVocabularyCache: Set<string> | undefined;
function viewMetadataVocabulary(): Set<string> {
  if (!viewVocabularyCache) {
    const vocabulary = new Set<string>();
    for (const branch of VIEW_METADATA_BRANCHES) {
      collectDeclaredTopLevelKeys(VIEW_METADATA_MEMBERS[branch], vocabulary);
    }
    // Identity the write path supplies is not evidence of shape — see
    // `VIEW_WRITE_PATH_IDENTITY_KEYS` for why this subtraction is the
    // difference between closing #5599 and only appearing to.
    for (const key of VIEW_WRITE_PATH_IDENTITY_KEYS) vocabulary.delete(key);
    viewVocabularyCache = vocabulary;
  }
  return viewVocabularyCache;
}

/**
 * [#6391] The `type` values that tell the two flattened overlay branches apart.
 *
 * `ListViewSchema.type` and `FormViewSchema.type` are disjoint enums — the
 * property the union's own comment already relies on ("a flattened form (no
 * required `columns`, disjoint `type` enum) then matches the form member"). Read
 * off the schemas rather than re-listed, so a new view type cannot make the
 * dispatch disagree with the members.
 */
function overlayTypeValues(schema: z.ZodTypeAny): ReadonlySet<string> {
  const shape = (schema as unknown as { _zod?: { def?: { shape?: Record<string, unknown> } } })
    ._zod?.def?.shape;
  const values = (shape?.type as { _zod?: { values?: Set<unknown> } } | undefined)?._zod?.values;
  return new Set([...(values ?? [])].filter((v): v is string => typeof v === 'string'));
}

/**
 * [#6391] Which branch of {@link ViewMetadataSchema} a body CLAIMS to be, by
 * its structural discriminants — or `null` when nothing in the body settles it.
 *
 * This is the "select the member by body" entry the filer asked for, and it
 * encodes exactly the discriminants the members themselves already declare:
 *
 * - a nested `config` means a ViewItem record — both overlay members pin
 *   `config: z.undefined()` precisely to exclude that shape;
 * - a container slot (`list` / `form` / `listViews` / `formViews`) means a
 *   container — both overlay members pin those `undefined` too;
 * - otherwise the body is a flattened overlay, and `viewKind` (when the write
 *   path inherited one — #2555) or the disjoint `type` enums say which family.
 *
 * ⚠️ A `null` answer is not a rejection and a non-`null` one is not an
 * acceptance. This function decides which branch is worth EXPLAINING; whether
 * the body parses is `ViewMetadataSchema`'s answer and only its answer.
 */
export function selectViewMetadataBranch(body: unknown): ViewMetadataBranch | null {
  if (typeof body !== 'object' || body === null || Array.isArray(body)) return null;
  const b = body as Record<string, unknown>;
  if (b.config !== undefined) return 'viewItem';
  if (b.list !== undefined || b.form !== undefined || b.listViews !== undefined || b.formViews !== undefined) {
    return 'container';
  }
  if (b.viewKind === 'form') return 'formOverlay';
  if (b.viewKind === 'list') return 'listOverlay';
  if (typeof b.type === 'string') {
    if (overlayTypeValues(FormViewSchema).has(b.type)) return 'formOverlay';
    if (overlayTypeValues(ListViewSchema).has(b.type)) return 'listOverlay';
  }
  return null;
}

/**
 * [#7510] What a branch reports once {@link focusClaimedBranch} has taken its
 * own complaint off the table.
 *
 * The shape is chosen, not decorative: `code: 'invalid_type'` at path `[]` is
 * exactly the "this branch only says the value is the wrong KIND" shape that
 * every consumer of a failed union in this repo already drops before ranking —
 * `isKindMismatchOnly` in `shared/error-map.zod.ts`, in `metadata-protocol`'s
 * `zodIssuesToMetadataIssues`, and in `rest`'s `zodIssuesToFields`, one
 * predicate written three times. So a muted branch does not become a quieter
 * competitor for the reader's attention; it leaves the competition, and the
 * branch the body actually claims is what remains to be rendered.
 *
 * The message still has to be true if some future consumer prints it anyway,
 * so it says what happened (this is not the branch the body claims) and where
 * the diagnosis is (the branch that is).
 */
function unclaimedBranchIssue(
  branch: ViewMetadataBranch,
  claimed: ViewMetadataBranch,
  input: unknown,
): z.core.$ZodIssue {
  return {
    code: 'invalid_type',
    expected: 'object',
    input,
    path: [],
    message:
      `Not the \`${branch}\` branch — this body reads as \`${claimed}\`, `
      + `so that branch carries the diagnosis.`,
  } as z.core.$ZodIssue;
}

/**
 * [#7510] Focus a FAILED `ViewMetadataSchema` union on the branch the body
 * claims, so the branch that got furthest is the one whose prescription the
 * author reads.
 *
 * ## The defect this closes
 *
 * Measured through the real write path (`saveMetaItem` → this union) on
 * `origin/main` @ `9051802`: a form ViewItem whose field carries an unknown
 * `publicPicker` subkey is correctly refused, and the message the author gets
 * is the CONTAINER branch's —
 *
 * ```
 * <root>: Unrecognized key(s) on this view container: `viewKind`, `config`.
 *   • `viewKind` belongs to a single VIEW, not to the container. Wrap it: …
 * ```
 *
 * — a confident, detailed prescription to restructure a container that was
 * correct all along, with the word the author actually mistyped appearing
 * nowhere. Not a `publicPicker` quirk: any ViewItem-branch failure whose
 * top-level issue is not itself an `unrecognized_keys` reproduces it (#7510
 * measured four — a picker subkey, an unknown form-field key, a bad field enum,
 * a typo'd column summary — all four surfaced the container text).
 *
 * The cause is a tie the shared ranking cannot break on content it can see. It
 * ranks a branch by `[issue count, carries an unrecognized_keys]`, and on such
 * a body the container branch reports exactly ONE root `unrecognized_keys`
 * (`viewKind`, `config` are not container keys) while the ViewItem branch
 * reports exactly ONE nested `invalid_union` — the real key sits one level
 * further down, inside it, where the tiebreak does not look. One issue each,
 * and the unknown-key bonus hands it to the branch that understood the body
 * least.
 *
 * ## Why the fix is here and not in the ranking
 *
 * The ranking is shared by every union in the repo and is right about unions in
 * general; what it lacks is what only this file knows — which branch this body
 * IS. That answer already exists here, as {@link selectViewMetadataBranch}, and
 * {@link diagnoseViewMetadata} has been giving objectui the branch-correct
 * reading from it since #6391. The union's own error path was the one door that
 * did not consult it, which is why Studio's 422 and `diagnoseViewMetadata`
 * could describe the same body two different ways. Now they cannot: one rule,
 * one source, both doors.
 *
 * ## What it does and does not touch
 *
 * ⛔ **Not a gate.** A `$ZodCheck` runs after the union has already reached its
 * verdict, and this one only ever REPLACES entries inside an existing
 * `invalid_union` issue's `errors` — it never adds an issue, never removes one,
 * and returns without touching anything when the parse succeeded. The
 * accept/reject verdict of every input is therefore the union's, byte for byte,
 * by construction rather than by test (and pinned anyway, over the 42-body
 * corpus in `view-union-diagnostics.test.ts`).
 *
 * `when: () => true` is what lets it run at all: a check is skipped by default
 * once parsing has produced aborting issues, which is precisely the state this
 * one exists to describe. It is a declared field of `$ZodCheckDef`, not a
 * reach into zod's internals.
 *
 * Three things deliberately stay exactly as they were:
 *
 * - **The `errors` array keeps its length and its ORDER.** A muted branch is
 *   replaced in place, not filtered out, so a positional consumer (objectui's
 *   canary read `errors[2]`) still finds branch 2 where branch 2 was.
 * - **The wrapper itself is untouched.** Whether zod emits the
 *   `invalid_union` wrapper or returns a lone non-aborted branch's issues
 *   verbatim is decided in `handleUnionResults` before any check runs, so
 *   nothing about the envelope's shape or issue codes moves.
 * - **An unclaimed body is left alone.** When no discriminant settles the claim
 *   (`selectViewMetadataBranch` → `null`) the ranking keeps the case, exactly as
 *   {@link diagnoseViewMetadata} keeps it (`candidates = claimed ? [claimed] :
 *   all`). A genuinely bad CONTAINER claims `container`, so the #4001 guidance
 *   text that made this defect visible is also what a real container failure
 *   still gets.
 */
function focusClaimedBranch(): z.core.$ZodCheck<unknown> {
  const check = new z.core.$ZodCheck({ check: 'custom', when: () => true }) as z.core.$ZodCheck<unknown>;
  check._zod.check = (payload) => {
    if (payload.issues.length === 0) return;
    const claimed = selectViewMetadataBranch(payload.value);
    if (claimed === null) return;

    for (let index = 0; index < payload.issues.length; index += 1) {
      const issue = payload.issues[index] as { code?: string; errors?: readonly z.core.$ZodIssue[][] };
      if (issue?.code !== 'invalid_union' || !Array.isArray(issue.errors)) continue;
      // Defensive: the branch↔position mapping below is only meaningful for
      // THIS union's own issue. A nested union that bubbled up unwrapped would
      // have a different arity, and renaming its branches would be a lie.
      if (issue.errors.length !== VIEW_METADATA_BRANCHES.length) continue;

      payload.issues[index] = {
        ...(payload.issues[index] as object),
        errors: issue.errors.map((branchIssues, position) => {
          const branch = VIEW_METADATA_BRANCHES[position]!;
          return branch === claimed
            ? branchIssues
            : [unclaimedBranchIssue(branch, claimed, payload.value)];
        }),
      } as typeof payload.issues[number];
    }
  };
  return check;
}

/** [#6391] The result of {@link diagnoseViewMetadata}. */
export type ViewMetadataDiagnosis =
  | { success: true; branch: ViewMetadataBranch; data: ViewMetadataParsed }
  | { success: false; branch: ViewMetadataBranch | null; issues: readonly z.core.$ZodIssue[] };

/**
 * [#6391] Explain a `view` body the way a consumer needs it explained: with the
 * failing BRANCH named and that branch's own per-field issues, flat.
 *
 * The problem this closes, measured in objectui#3624: `ViewMetadataSchema`
 * failing produces ONE root `invalid_union` issue with the per-field truth
 * buried in nested `errors[]`, addressable only by member position. Here the
 * position never appears — the caller gets `branch: 'listOverlay'` and the list
 * overlay's own issues, with real field paths.
 *
 * Three outcomes, and the middle one is the one worth reading twice:
 *
 * 1. **The body parses.** `ViewMetadataSchema` accepted it; the branch reported
 *    is the first member that accepts it.
 * 2. **The body is not a `view` at all** (#5599's identity precondition —
 *    `{ nope: 1 }`, `{}`, identity keys only). `branch` is `null` and the
 *    issues are the precondition's own. Naming a branch here would be a lie:
 *    the union never ran, and pointing the author at "the form overlay" would
 *    send them to fix a shape they were not writing.
 * 3. **The body claims a branch and that branch rejects it.** `branch` names
 *    it, `issues` are that member's, resolved against the body's own paths.
 *    When no discriminant settles the claim, every member is tried and the one
 *    complaining LEAST is reported — the same "fewest issues wins" ranking
 *    `selectUnionBranches` (`shared/error-map.zod.ts`) already uses for this
 *    family, so one mistake gets one prescription across every surface.
 *
 * ⛔ **Acceptance is not decided here.** This function delegates the verdict to
 * `ViewMetadataSchema` and only ever explains a verdict it did not make: if the
 * schema accepts, this reports success no matter what the branch dispatch
 * thinks. Pinned in `view-union-diagnostics.test.ts`.
 */
export function diagnoseViewMetadata(body: unknown): ViewMetadataDiagnosis {
  const parsed = ViewMetadataSchema.safeParse(body);
  const stripped = stripViewConsoleDecorations(body);

  if (parsed.success) {
    const accepting = VIEW_METADATA_BRANCHES.find(
      (branch) => VIEW_METADATA_MEMBERS[branch].safeParse(stripped).success,
    );
    // The union accepted, so some member did; `selectViewMetadataBranch` is the
    // fallback only for the impossible case, never the primary answer.
    return { success: true, branch: accepting ?? selectViewMetadataBranch(stripped) ?? 'viewItem', data: parsed.data };
  }

  // (2) The identity precondition short-circuited the pipe with `z.NEVER`, so
  // the union never ran and there is no branch to name. Detected by re-running
  // the precondition's own predicate rather than by pattern-matching its issue
  // text — same rule, one source.
  if (!speaksViewVocabulary(body)) {
    return { success: false, branch: null, issues: parsed.error.issues };
  }

  const claimed = selectViewMetadataBranch(stripped);
  const candidates = claimed ? [claimed] : [...VIEW_METADATA_BRANCHES];
  let best: { branch: ViewMetadataBranch; issues: readonly z.core.$ZodIssue[] } | undefined;
  for (const branch of candidates) {
    const result = VIEW_METADATA_MEMBERS[branch].safeParse(stripped);
    // A member that accepts what the union rejected cannot happen (the union is
    // exactly these members), but if it ever did, reporting zero issues under a
    // `success: false` would be the worst possible answer — so skip it.
    if (result.success) continue;
    if (!best || result.error.issues.length < best.issues.length) {
      best = { branch, issues: result.error.issues };
    }
  }
  return best
    ? { success: false, branch: best.branch, issues: best.issues }
    : { success: false, branch: claimed, issues: parsed.error.issues };
}

/**
 * Canonical schema for ANY persisted `view` metadata body — the schema the
 * `view` type registers in `metadata-type-schemas.ts`. A union over the three
 * runtime shapes (see the block comment above), so save-time validation and
 * read-time diagnostics finally see through `ViewItem`/personalization bodies
 * instead of stripping them to `{}` (#3095).
 *
 * `z.toJSONSchema()` emits this as an `anyOf` of the four members, which the
 * `/api/v1/meta/types/view` endpoint serves to Studio's SchemaForm. That still
 * holds through the #5074 `z.preprocess` wrapper — a pipe converts to its
 * output side, so the top level is still an `anyOf` of four. Pinned in
 * `view-metadata-schema.test.ts` and `view-authoring-wire-split.test.ts`,
 * because the endpoint is what feeds every generated view form.
 *
 * [#5074] The `z.preprocess` is the WIRE door's decoration strip — see
 * {@link stripViewConsoleDecorations}. It runs once, ahead of every member, so
 * the openness this union needs reaches nested blocks that a member-level
 * `.strip()` can never reach.
 *
 * [#5599] That same stage now also carries the identity precondition — see
 * {@link assertViewIdentity} for why the check has to live here rather than as
 * an extra pipe stage, and why it is a precondition rather than a required floor
 * on member 4.
 */
export const ViewMetadataSchema = lazySchema(() => {
  // [#6391] The members ARE {@link VIEW_METADATA_MEMBERS}, read in
  // {@link VIEW_METADATA_BRANCHES} order. Built by mapping rather than
  // re-listed, so "the published schema is the member the union runs" cannot
  // drift into "the published schema resembles it" — the exact gap objectui had
  // to bridge with a canary test.
  const members = VIEW_METADATA_BRANCHES.map((branch) => VIEW_METADATA_MEMBERS[branch]);

  return z.preprocess(
    (body, ctx) => (assertViewIdentity(body, ctx) ? stripViewConsoleDecorations(body) : z.NEVER),
    // [#7510] The `.check()` rides the UNION rather than the pipe, so the body
    // it reads is the stripped one the members were actually judged against —
    // the same input `diagnoseViewMetadata` claims a branch from. It changes no
    // verdict; see {@link focusClaimedBranch}.
    z.union(members as unknown as readonly [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]])
      .check(focusClaimedBranch()),
  );
});

// ───────────────────────────────────────────────────────────────────────────
// defineView container → ViewItem expansion (shared by every loader)
//
// `defineView({ list, form, listViews, formViews })` aggregates an object's
// views into one document. Each registration path that ingests such a
// container (the ObjectQL engine boot loop AND the metadata HMR plugin) must
// expand it into N independent ViewItems registered under `<object>.<viewKey>`,
// so each view is individually addressable and `getViewsByObject()` can rebuild
// the switcher. The original container is ALSO kept under the bare `<object>`
// key for backward-compatible reads. This logic lives in `@objectstack/spec`
// (depended on by both objectql and metadata) so the two loaders cannot drift.

/** A ViewItem materialised from an aggregated container (always `package`). */
export interface ExpandedViewItem {
  name: string;
  object: string;
  viewKind: 'list' | 'form';
  label?: unknown;
  config: any;
  isDefault?: boolean;
  order: number;
  scope: 'package';
  /** Non-blocking expansion diagnostics (MetadataValidationResult wire shape).
   *  Present only when the item's name had to be rewritten to avoid a
   *  collision — loaders surface `warnings` in their boot/HMR logs and
   *  Studio can badge the view. */
  _diagnostics?: { valid: boolean; warnings: Array<{ path: string; message: string }> };
}

/** True when a raw view artifact still uses the aggregated container shape
 *  (and is not already an independent ViewItem, which carries `viewKind`). */
export function isAggregatedViewContainer(item: any): boolean {
  if (!item || typeof item !== 'object') return false;
  if (item.viewKind) return false; // already an independent ViewItem
  return Boolean(item.list || item.form || item.listViews || item.formViews);
}

/** Structural signature used to collapse a container's default `list`/`form`
 *  with a redundant `listViews`/`formViews` restatement of the same view (the
 *  common "default == listViews.all" authoring pattern). */
function viewSignature(v: any): string {
  if (!v || typeof v !== 'object') return '';
  try {
    return JSON.stringify({ type: v.type ?? null, label: v.label ?? null, columns: v.columns ?? null });
  } catch {
    return '';
  }
}

/** Allocate a collision-free `<object>.<key>` name within one expansion. */
function uniqueViewName(base: string, used: Set<string>): string {
  let name = base;
  let i = 2;
  while (used.has(name)) name = `${base}_${i++}`;
  used.add(name);
  return name;
}

/** Stamp a rename warning on an expanded item whose `<object>.<key>` name was
 *  already taken (e.g. `formViews.default` vs the implicit default `list`).
 *  The rename itself is kept for backward compatibility — this makes it LOUD:
 *  loaders log the warning and Studio can render it, so authors discover that
 *  references to the requested name (form action `target`s, navigation
 *  `viewName`s) resolve to a DIFFERENT view. */
function stampRenameWarning(item: ExpandedViewItem, requestedName: string): void {
  if (item.name === requestedName) return;
  item._diagnostics = {
    valid: true,
    warnings: [{
      path: 'name',
      message:
        `View key collision: '${requestedName}' is already registered by another view in this `
        + `defineView container (list and form views share one '<object>.<key>' namespace, and the `
        + `default 'list' implicitly claims '<object>.default'). This ${item.viewKind} view was `
        + `renamed to '${item.name}'. References targeting '${requestedName}' — form action `
        + `targets, navigation viewNames — will resolve to the OTHER view. Rename the view key `
        + `to something unique to remove this warning.`,
    }],
  };
}

function cloneViewConfig(v: any): any {
  try {
    return structuredClone(v);
  } catch {
    return JSON.parse(JSON.stringify(v));
  }
}

/**
 * A view-key collision detected while expanding one `defineView` container.
 *
 * List and form views share a single `<object>.<key>` namespace during
 * expansion (see {@link expandViewContainer}), and the default `list`
 * implicitly claims `<object>.default`. When a later view competes for a name
 * already taken, it is renamed (`<object>.<key>` → `<object>.<key>_2`) to keep
 * the runtime registry key unique. That rename is a silent footgun: references
 * to the requested name (form action `target`s, navigation `viewName`s) resolve
 * to the OTHER view. The build-time view-ref lint turns each collision into a
 * hard error so the author fixes the key instead of shipping a broken reference.
 */
export interface ViewKeyCollision {
  /** The `<object>.<key>` name that was already registered by an earlier view. */
  requested: string;
  /** The disambiguated name the colliding view was renamed to (e.g. `…_2`). */
  renamedTo: string;
  /** Which family the renamed (losing) view belongs to. */
  viewKind: 'list' | 'form';
  /** The raw author-supplied key that collided. */
  key: string;
}

/** Result of {@link expandViewContainerWithDiagnostics}. */
export interface ExpandViewResult {
  items: ExpandedViewItem[];
  collisions: ViewKeyCollision[];
}

/**
 * Expand an aggregated view container into independent ViewItems, ALSO reporting
 * every name collision that forced a rename.
 *
 * List family: `listViews` entries first (keys taken from the author), then the
 * default `list` — deduped by structural signature so a `listViews.all` that
 * merely restates `list` collapses into one item. The view matching the
 * declared default is flagged `isDefault`. Form family: `formViews` entries,
 * then the default `form`.
 *
 * Collisions are captured at the exact points the shared `used` set forces a
 * rename, so the diagnostic can never drift from the expansion it describes.
 */
export function expandViewContainerWithDiagnostics(object: string, container: any): ExpandViewResult {
  const out: ExpandedViewItem[] = [];
  const collisions: ViewKeyCollision[] = [];
  const used = new Set<string>();
  let order = 0;

  // ---- list family ----
  const listSigToName = new Map<string, string>();
  const listViews =
    container.listViews && typeof container.listViews === 'object' ? container.listViews : {};
  for (const [k, v] of Object.entries<any>(listViews)) {
    if (!v || typeof v !== 'object') continue;
    const requested = `${object}.${k}`;
    const name = uniqueViewName(requested, used);
    if (name !== requested) collisions.push({ requested, renamedTo: name, viewKind: 'list', key: k });
    listSigToName.set(viewSignature(v), name);
    const item: ExpandedViewItem = { name, object, viewKind: 'list', label: v.label, config: cloneViewConfig(v), order: order++, scope: 'package' };
    stampRenameWarning(item, requested);
    out.push(item);
  }
  const defaultList = container.list;
  let defaultListName: string | undefined;
  if (defaultList && typeof defaultList === 'object') {
    const dup = listSigToName.get(viewSignature(defaultList));
    if (dup) {
      defaultListName = dup; // already represented by a named listViews entry
    } else {
      const key = typeof defaultList.name === 'string' && defaultList.name ? defaultList.name : 'default';
      const requested = `${object}.${key}`;
      const name = uniqueViewName(requested, used);
      if (name !== requested) collisions.push({ requested, renamedTo: name, viewKind: 'list', key });
      const item: ExpandedViewItem = { name, object, viewKind: 'list', label: defaultList.label, config: cloneViewConfig(defaultList), order: order++, scope: 'package' };
      stampRenameWarning(item, requested);
      out.push(item);
      defaultListName = name;
    }
  }
  if (!defaultListName && out.length) defaultListName = out[0].name;
  for (const item of out) {
    if (item.viewKind === 'list' && item.name === defaultListName) item.isDefault = true;
  }

  // ---- form family ----
  const formStart = out.length;
  const formSigSeen = new Set<string>();
  const formViews =
    container.formViews && typeof container.formViews === 'object' ? container.formViews : {};
  for (const [k, v] of Object.entries<any>(formViews)) {
    if (!v || typeof v !== 'object') continue;
    const requested = `${object}.${k}`;
    const name = uniqueViewName(requested, used);
    if (name !== requested) collisions.push({ requested, renamedTo: name, viewKind: 'form', key: k });
    formSigSeen.add(viewSignature(v));
    const item: ExpandedViewItem = { name, object, viewKind: 'form', label: v.label, config: cloneViewConfig(v), order: order++, scope: 'package' };
    stampRenameWarning(item, requested);
    out.push(item);
  }
  const defaultForm = container.form;
  let defaultFormName: string | undefined;
  if (defaultForm && typeof defaultForm === 'object' && !formSigSeen.has(viewSignature(defaultForm))) {
    const key = typeof defaultForm.name === 'string' && defaultForm.name ? defaultForm.name : 'form';
    const requested = `${object}.${key}`;
    const name = uniqueViewName(requested, used);
    if (name !== requested) collisions.push({ requested, renamedTo: name, viewKind: 'form', key });
    const item: ExpandedViewItem = { name, object, viewKind: 'form', label: defaultForm.label, config: cloneViewConfig(defaultForm), order: order++, scope: 'package' };
    stampRenameWarning(item, requested);
    out.push(item);
    defaultFormName = name;
  }
  if (!defaultFormName && out.length > formStart) defaultFormName = out[formStart].name;
  for (let i = formStart; i < out.length; i++) {
    if (out[i].name === defaultFormName) out[i].isDefault = true;
  }

  return { items: out, collisions };
}

/**
 * Expand an aggregated view container into independent ViewItems.
 *
 * Thin wrapper over {@link expandViewContainerWithDiagnostics} that discards the
 * collision diagnostics — the shape every runtime loader consumes. Behaviour is
 * unchanged: colliding names are still renamed so the registry key stays unique.
 */
export function expandViewContainer(object: string, container: any): ExpandedViewItem[] {
  return expandViewContainerWithDiagnostics(object, container).items;
}

/**
 * Type-safe factory for a standalone {@link FormView} bound to a JSON Schema
 * rather than to an ObjectQL object.
 *
 * Use this for forms that edit **metadata** (e.g. `report.form.ts`,
 * `dashboard.form.ts`), **action inputs**, or **flow screens** — anywhere the
 * data shape is described by a Zod-derived JSON Schema instead of an Object
 * field set.
 *
 * The returned FormView is validated at definition time; the runtime form
 * renderer (`@object-ui/plugin-form`) inspects `data.provider === 'schema'`
 * and pulls field metadata from the resolved JSON Schema instead of from
 * ObjectQL.
 *
 * @example
 * ```ts
 * export const reportForm = defineForm({
 *   schemaId: 'report',
 *   type: 'tabbed',
 *   sections: [
 *     { label: 'Basics', columns: 2, fields: [
 *       { field: 'name' },
 *       { field: 'label' },
 *       { field: 'objectName', widget: 'ref:object' },
 *       { field: 'type' },
 *     ]},
 *     { label: 'Columns', fields: [{ field: 'columns', widget: 'master-detail' }] },
 *     { label: 'Advanced', collapsible: true, collapsed: true, fields: [
 *       { field: 'filter', widget: 'filter-builder' },
 *       { field: 'chart', widget: 'chart-config' },
 *     ]},
 *   ],
 * });
 * ```
 */
export function defineForm(
  config: Omit<z.input<typeof FormViewSchema>, 'data'> & { schemaId: string },
): FormViewParsed {
  const { schemaId, ...rest } = config;
  return FormViewSchema.parse({
    ...rest,
    data: { provider: 'schema', schemaId },
  });
}

export type View = z.input<typeof ViewSchema>;
/** Post-parse shape of {@link View} — defaults applied, transforms run (ADR-0122). */
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>;
/** 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>;
export type ViewKind = z.input<typeof ViewKindSchema>;
export type ListView = z.input<typeof ListViewSchema>;
/** Post-parse shape of {@link ListView} — defaults applied, transforms run (ADR-0122). */
export type ListViewParsed = z.infer<typeof ListViewSchema>;
export type FormView = z.input<typeof FormViewSchema>;
/** Post-parse shape of {@link FormView} — defaults applied, transforms run (ADR-0122). */
export type FormViewParsed = z.infer<typeof FormViewSchema>;
export type FormSection = z.input<typeof FormSectionSchema>;
/** Post-parse shape of {@link FormSection} — defaults applied, transforms run (ADR-0122). */
export type FormSectionParsed = z.infer<typeof FormSectionSchema>;
/** Authoring shape of {@link FormSelectOptionSchema} — the object-field option minus `default` (#12868). */
export type FormSelectOption = z.input<typeof FormSelectOptionSchema>;
/** Post-parse shape of {@link FormSelectOption} — defaults applied, transforms run (ADR-0122). */
export type FormSelectOptionParsed = z.infer<typeof FormSelectOptionSchema>;
export type ListColumn = z.input<typeof ListColumnSchema>;
/** Post-parse shape of {@link ListColumn} — defaults applied, transforms run (ADR-0122). */
export type ListColumnParsed = z.infer<typeof ListColumnSchema>;
// `FormField` is declared next to FormFieldSchema — it IS that schema's
// annotation, so it cannot be inferred back out of it (#4171).
export type SelectionConfig = z.input<typeof SelectionConfigSchema>;
/** Post-parse shape of {@link SelectionConfig} — defaults applied, transforms run (ADR-0122). */
export type SelectionConfigParsed = z.infer<typeof SelectionConfigSchema>;
export type NavigationConfig = z.input<typeof NavigationConfigSchema>;
/** Post-parse shape of {@link NavigationConfig} — defaults applied, transforms run (ADR-0122). */
export type NavigationConfigParsed = z.infer<typeof NavigationConfigSchema>;
export type PaginationConfig = z.input<typeof PaginationConfigSchema>;
/** Post-parse shape of {@link PaginationConfig} — defaults applied, transforms run (ADR-0122). */
export type PaginationConfigParsed = z.infer<typeof PaginationConfigSchema>;
export type ViewData = z.input<typeof ViewDataSchema>;
/** Post-parse shape of {@link ViewData} — defaults applied, transforms run (ADR-0122). */
export type ViewDataParsed = z.infer<typeof ViewDataSchema>;
// `HttpRequest` is NOT inferred here — it is re-exported from its single
// declaration in `shared/http.zod.ts` next to the schema re-export at the top of
// this file (#4688). Re-adding `= z.infer<typeof HttpRequestSchema>` below would
// re-create the dual-source row this change removed, even though the inferred
// shape is identical.
//
// `HttpMethod` is not declared here either — and is no longer exported from
// `./ui` at all (#4691). It used to be `= z.infer<typeof HttpMethodSchema>`,
// the 5-value UI subset, while `./shared` and `./api` export a DIFFERENT,
// 7-value declaration under that same name. Re-exporting theirs would widen
// this entry's type past what `HttpRequestSchema.method` actually validates, so
// the name was dropped instead; the 5-value type is re-exported as
// `HttpMethodSubset` at the top of this file (`HttpMethodType` until #5832),
// where the full rationale lives.
export type ColumnSummary = z.input<typeof ColumnSummarySchema>;
export type ColumnSummaryConfig = z.input<typeof ColumnSummaryConfigSchema>;
export type ColumnPrefix = z.input<typeof ColumnPrefixSchema>;
/** Post-parse shape of {@link ColumnPrefix} — defaults applied, transforms run (ADR-0122). */
export type ColumnPrefixParsed = z.infer<typeof ColumnPrefixSchema>;
export type RowHeight = z.input<typeof RowHeightSchema>;
export type GroupingConfig = z.input<typeof GroupingConfigSchema>;
/** Post-parse shape of {@link GroupingConfig} — defaults applied, transforms run (ADR-0122). */
export type GroupingConfigParsed = z.infer<typeof GroupingConfigSchema>;
export type GalleryConfig = z.input<typeof GalleryConfigSchema>;
/** Post-parse shape of {@link GalleryConfig} — defaults applied, transforms run (ADR-0122). */
export type GalleryConfigParsed = z.infer<typeof GalleryConfigSchema>;
export type TimelineConfig = z.input<typeof TimelineConfigSchema>;
/** Post-parse shape of {@link TimelineConfig} — defaults applied, transforms run (ADR-0122). */
export type TimelineConfigParsed = z.infer<typeof TimelineConfigSchema>;
export type ListChartConfig = z.input<typeof ListChartConfigSchema>;
/** Post-parse shape of {@link ListChartConfig} — defaults applied, transforms run (ADR-0122). */
export type ListChartConfigParsed = z.infer<typeof ListChartConfigSchema>;
export type ViewSharing = z.input<typeof ViewSharingSchema>;
/** Post-parse shape of {@link ViewSharing} — defaults applied, transforms run (ADR-0122). */
export type ViewSharingParsed = z.infer<typeof ViewSharingSchema>;
export type RowColorConfig = z.input<typeof RowColorConfigSchema>;
export type VisualizationType = z.input<typeof VisualizationTypeSchema>;
export type UserActionsConfig = z.input<typeof UserActionsConfigSchema>;
/** Post-parse shape of {@link UserActionsConfig} — defaults applied, transforms run (ADR-0122). */
export type UserActionsConfigParsed = z.infer<typeof UserActionsConfigSchema>;
export type AppearanceConfig = z.input<typeof AppearanceConfigSchema>;
/** Post-parse shape of {@link AppearanceConfig} — defaults applied, transforms run (ADR-0122). */
export type AppearanceConfigParsed = z.infer<typeof AppearanceConfigSchema>;
export type ViewTab = z.input<typeof ViewTabSchema>;
/** Post-parse shape of {@link ViewTab} — defaults applied, transforms run (ADR-0122). */
export type ViewTabParsed = z.infer<typeof ViewTabSchema>;
export type UserFilterField = z.input<typeof UserFilterFieldSchema>;
export type UserFilters = z.input<typeof UserFiltersSchema>;
/** Post-parse shape of {@link UserFilters} — defaults applied, transforms run (ADR-0122). */
export type UserFiltersParsed = z.infer<typeof UserFiltersSchema>;
export type AddRecordConfig = z.input<typeof AddRecordConfigSchema>;
/** Post-parse shape of {@link AddRecordConfig} — defaults applied, transforms run (ADR-0122). */
export type AddRecordConfigParsed = z.infer<typeof AddRecordConfigSchema>;
export type CalendarConfig = z.input<typeof CalendarConfigSchema>;
export type GanttConfig = z.input<typeof GanttConfigSchema>;
export type GanttQuickFilter = z.input<typeof GanttQuickFilterSchema>;
export type KanbanConfig = z.input<typeof KanbanConfigSchema>;
export type ListMapConfig = z.input<typeof ListMapConfigSchema>;
export type NavigationMode = z.input<typeof NavigationModeSchema>;
export type TreeConfig = z.input<typeof TreeConfigSchema>;
export type ViewItemName = z.input<typeof ViewItemNameSchema>;