@wildo-ai/zod-decorators 1.1.4 → 1.1.6

package/dist/esm/zod-utils.shared.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { BooleanEditMode, EnumEditMode, NumberEditMode, StringEditMode } from './zod-decorators.types.js';
-import { DEFAULT_FOREIGN_KEY_DISPLAY_MODE, FileGenerationSource, FieldSchemaType, FormFieldComponent, RangeType, SCHEMA_METADATA, ZodDecorator } from './zod-decorators.types.js';
+import { BooleanEditMode, DisplayEmptyReason, EnumEditMode, EnumMultipleEditMode, NumberEditMode, StringEditMode } from './zod-decorators.types.js';
+import { DEFAULT_FOREIGN_KEY_DISPLAY_MODE, FileGenerationSource, FieldSchemaType, FormFieldComponent, RangeType, SCHEMA_METADATA, ZodDecorator, RequestDtoWriteSemantics } from './zod-decorators.types.js';
 import { z_range } from './zod-range.js';
 import { addDecorators, getMetadataRecursive } from './zod.module-override.js';
 // Type guard to check if a schema has Zod v4 internals
@@ -97,6 +97,84 @@ export function unwrapSchema(schema) {
             return schema;
     }
 }
+/**
+ * The same PATCH rule, one level down: inside a NESTED object field, a key the caller omits must not be
+ * re-materialised from its `.default()` either.
+ *
+ * `toPatchOptionalField` peels the OUTER default of a top-level field, but an object field's own keys
+ * kept theirs, so `{ privacy: { privacyLevel: 'minimal' } }` parsed to
+ * `{ privacy: { privacyLevel: 'minimal', consentedPurposes: [] } }` — a write the caller never made, which
+ * a downstream hook cannot tell apart from an explicit empty set (#534 review F1: a privacy-level change
+ * read as a consent withdrawal). Zod 4 applies a default even inside `.optional()`, so the default must
+ * be peeled, not wrapped.
+ *
+ * (`privacyLevel` itself was removed in #1280 — it was a stored preference nothing read. The example is
+ * kept in its original terms because it is the account of a defect that actually happened; the rule it
+ * motivates is about ANY nested key with a default, and is unchanged.)
+ *
+ * Scope, deliberately narrow:
+ * - nested PLAIN object fields, recursively, through `optional` / `nullable` wrappers only. An object
+ *   nested inside a union, discriminated union, record, intersection, pipe/transform, `readonly` or `lazy`
+ *   is NOT peeled and keeps re-materialising its defaults — narrower than it could be, never wrong;
+ * - an object carrying its own refinement is NOT peeled: a `.refine()` / `.superRefine()` may read a
+ *   defaulted key, and would see `undefined` (or throw) once that default stopped applying;
+ * - a nested key WITH a default becomes optional without it; a nested key WITHOUT one keeps its declared
+ *   optionality — a replaced nested object must still carry what it requires;
+ * - ARRAYS are left alone: an array element is sent whole, and its defaults describe a new element;
+ * - the object is rebuilt with Zod's own `clone(def)`, so `strict` / `catchall` and refinements survive;
+ *   decorator metadata AND `z.globalRegistry` metadata (`.describe()`, `.meta()` — what MCP tool input
+ *   schemas are generated from) are copied onto every rebuilt schema, and inner schemas are SHARED,
+ *   never mutated, so the source schema is untouched.
+ */
+function withoutNestedObjectDefaults(schema) {
+    const type = getZodType(schema);
+    if (type === 'optional' || type === 'nullable') {
+        const inner = getZodDefSchemaProperty(schema, 'innerType');
+        if (!inner)
+            return schema;
+        const rebuiltInner = withoutNestedObjectDefaults(inner);
+        if (rebuiltInner === inner)
+            return schema;
+        return copySchemaMetadata(schema, type === 'optional' ? rebuiltInner.optional() : rebuiltInner.nullable());
+    }
+    if (type !== 'object')
+        return schema;
+    const def = schema._zod.def;
+    if (Array.isArray(def.checks) && def.checks.length > 0)
+        return schema;
+    const shape = schema.shape;
+    const nextShape = {};
+    let changed = false;
+    for (const [key, field] of Object.entries(shape)) {
+        let next;
+        if (isZodDefault(field)) {
+            const peeled = getZodDefSchemaProperty(field, 'innerType');
+            next = peeled ? copySchemaMetadata(field, withoutNestedObjectDefaults(peeled).optional()) : field;
+        }
+        else {
+            next = withoutNestedObjectDefaults(field);
+        }
+        if (next !== field)
+            changed = true;
+        nextShape[key] = next;
+    }
+    if (!changed)
+        return schema;
+    const rebuilt = schema.clone({ ...def, shape: nextShape });
+    return copySchemaMetadata(schema, rebuilt);
+}
+/** Carry decorator metadata from a source wrapper onto a rebuilt one; the source is never mutated. */
+function copySchemaMetadata(source, target) {
+    const registered = z.globalRegistry.get(source);
+    if (registered && !z.globalRegistry.has(target))
+        z.globalRegistry.add(target, registered);
+    const metadata = source[SCHEMA_METADATA];
+    if (metadata) {
+        const record = target;
+        record[SCHEMA_METADATA] = { ...(record[SCHEMA_METADATA] ?? {}), ...metadata };
+    }
+    return target;
+}
 /**
  * Make a field OPTIONAL for a PATCH-style UPDATE DTO, peeling any OUTER
  * `.default()` wrapper first.
@@ -137,11 +215,13 @@ export function unwrapSchema(schema) {
 export function toPatchOptionalField(fieldSchema) {
     const admitsNullClear = fieldAdmitsAddedNullClear(fieldSchema);
     if (!isZodDefault(fieldSchema)) {
-        return admitsNullClear ? fieldSchema.nullable().optional() : fieldSchema.optional();
+        const nestedPatched = withoutNestedObjectDefaults(fieldSchema);
+        return admitsNullClear ? nestedPatched.nullable().optional() : nestedPatched.optional();
     }
-    const innerType = getZodDefSchemaProperty(fieldSchema, 'innerType');
-    if (!innerType)
+    const rawInnerType = getZodDefSchemaProperty(fieldSchema, 'innerType');
+    if (!rawInnerType)
         return fieldSchema.optional();
+    const innerType = withoutNestedObjectDefaults(rawInnerType);
     // A defaulted field is never null-clearable (see `fieldAdmitsAddedNullClear`), so the peeled
     // inner is made optional WITHOUT a nullable wrapper.
     const optionalInner = innerType.optional();
@@ -219,6 +299,69 @@ export function normalizeClearedRequestDtoValue(fieldSchema, value) {
 export function normalizeClearedMainSchemaValue(fieldSchema, value) {
     return normalizeClearedValue(fieldSchema, value, mainSchemaFieldIsClearable);
 }
+/**
+ * Mark an UPDATE request DTO object as written PATCH style (see `RequestDtoWriteSemantics`).
+ *
+ * The mark lives in the `SCHEMA_METADATA` bag because that bag is what every DTO rebuild carries
+ * across (network-boundary coercion, templatable-file stripping, nested-relationship extension). It
+ * is written COPY-ON-WRITE: rebuilds share one bag object between instances, so mutating it would
+ * mark schemas that were never PATCH roots.
+ */
+export function markPatchRequestDtoObject(schema) {
+    const record = schema;
+    record[SCHEMA_METADATA] = { ...(record[SCHEMA_METADATA] ?? {}), requestDtoWriteSemantics: RequestDtoWriteSemantics.PATCH };
+    return schema;
+}
+/**
+ * Does this object follow the PATCH write rule — absent key untouched, `null` clears?
+ *
+ * Looks through optional, nullable and default wrappers. A UNION answers `true` when ANY option is a
+ * PATCH object: a nested child's items are a union of an update branch (PATCH) and a create branch
+ * (written whole), and a field cannot tell which one it is in. `true` keeps the stricter rule, under
+ * which a required field stays unclearable; the other answer would let one read as clearable in the
+ * update branch, where clearing it would be a silent no-op.
+ */
+export function objectFollowsPatchWriteRule(schema) {
+    if (!schema)
+        return false;
+    const metadata = schema[SCHEMA_METADATA];
+    if (metadata?.requestDtoWriteSemantics === RequestDtoWriteSemantics.PATCH)
+        return true;
+    const type = getZodType(schema);
+    if (type === 'optional' || type === 'nullable' || type === 'default') {
+        const innerSchema = getZodDefSchemaProperty(schema, 'innerType');
+        return innerSchema ? objectFollowsPatchWriteRule(innerSchema) : false;
+    }
+    if (type === 'union') {
+        const options = getZodDefArrayProperty(schema, 'options');
+        return (options ?? []).some((option) => objectFollowsPatchWriteRule(option));
+    }
+    return false;
+}
+/**
+ * Is "clear it" meaningful for a field inside an object that is written WHOLE — an object value
+ * nested in a field, an array item, or a CREATE request DTO?
+ *
+ * The declaration answers it, exactly as on a main schema: absence or null allowed → clearable, required
+ * or defaulted → not. `requestDtoFieldIsClearable` ("accepts null") is the wrong question here: only a
+ * PATCH root's direct fields get a null admitted, so it reported every nested optional field
+ * unclearable, and an emptied nested address could never be saved (#989).
+ */
+export function valueObjectFieldIsClearable(fieldSchema) {
+    return mainSchemaFieldIsClearable(fieldSchema);
+}
+/**
+ * `normalizeClearedFieldValue` for a field inside an object written WHOLE. The cleared value is ABSENCE
+ * (`undefined`), or `null` only for a field that accepts null.
+ *
+ * Absence, because nothing else is safe there: the persistence layer removes only TOP-LEVEL cleared
+ * fields, so a `null` nested in a stored object would be persisted as `null` and then fail the main
+ * schema's `.optional()` on the next read.
+ */
+export function normalizeClearedValueObjectFieldValue(fieldSchema, value) {
+    const normalized = normalizeClearedValue(fieldSchema, value, valueObjectFieldIsClearable);
+    return normalized === null && !fieldSchema.safeParse(null).success ? undefined : normalized;
+}
 function normalizeClearedValue(fieldSchema, value, isClearable) {
     if (!isEmptyFieldGesture(value))
         return value;
@@ -380,9 +523,14 @@ export function isZodArray(schema) {
  * validate against. `reset_to_defaults` depended on exactly such a constraint to reject a request
  * naming no preference block, and without it the route answered HTTP 200 having written nothing.
  *
- * Native `.clone()` re-instantiates from the schema's own definition, so checks, error maps and
- * metadata survive by construction rather than by a copy loop that the next Zod version could
- * outgrow.
+ * Native `.clone()` re-instantiates from the schema's own definition, so checks and error maps
+ * survive by construction rather than by a copy loop that the next Zod version could outgrow.
+ *
+ * `z.globalRegistry` metadata (`.describe()`, `.meta()`) does NOT come with it: Zod links a clone to
+ * its source, which is how a clone inherits that metadata, only when no new definition is passed,
+ * and this always passes one. Measured, 2026-09-26: a billing-state `invoices` array lost its
+ * description to date coercion, so the API reference published it undescribed (#1625). It is copied
+ * explicitly below, without `id`, which names one schema and which Zod refuses to register twice.
  *
  * @param arraySchema - the array being rewritten. Returned untouched when it is not an array or
  *   carries no element, so callers do not need to pre-check.
@@ -396,7 +544,14 @@ export function withArrayElement(arraySchema, element) {
     if (!def) {
         return arraySchema;
     }
-    return arraySchema.clone({ ...def, element });
+    const rebuilt = arraySchema.clone({ ...def, element });
+    const registered = z.globalRegistry.get(arraySchema);
+    if (registered !== undefined && !z.globalRegistry.has(rebuilt)) {
+        const { id: _id, ...carried } = registered;
+        if (Object.keys(carried).length > 0)
+            z.globalRegistry.add(rebuilt, carried);
+    }
+    return rebuilt;
 }
 export function isZodOptional(schema) {
     return hasZodType(schema, 'optional');
@@ -571,6 +726,11 @@ export function getSchemaType(schema) {
     if (isPhoneSchema(schema)) {
         return FieldSchemaType.PHONE;
     }
+    // Check for address schemas (created by z_address()) — BEFORE the generic object case, which an
+    // address would otherwise fall into as a plain OBJECT with no field of its own (#561).
+    if (isAddressSchema(schema)) {
+        return FieldSchemaType.ADDRESS;
+    }
     // Check for versioned foreign key schemas (created by z_foreignKeyVersioned())
     if (isVersionedForeignKeySchema(schema)) {
         return FieldSchemaType.VERSIONED_FOREIGN_KEY;
@@ -618,7 +778,26 @@ export function getSchemaType(schema) {
                     return FieldSchemaType.UNKNOWN;
             }
         }
-        case 'date': return FieldSchemaType.DATE;
+        /*
+         * A `z.date()` is a DAY unless it declares itself a MOMENT.
+         *
+         * In Wildo a datetime is Date-based — an ISO-8601 string is a wire format for one, never the
+         * model — so `ZodDate` is the carrier for both "a day" (`dueDate`) and "a point in time"
+         * (`remindAt`). Nothing in the schema shape distinguishes them, which left `DATETIME`
+         * effectively unreachable: every date classified as `DATE`, so every one of them EDITED through
+         * the day picker and DISPLAYED through the day formatter, and a moment silently lost its hour
+         * on both surfaces while `FormFieldDateTime` and `DisplayFieldDateTime` sat unreachable.
+         *
+         * The declaration is what distinguishes them, and it already exists: `dateTimeUI()` is applyable
+         * to `ZodDate` precisely to say "this value carries a time of day". Reading it here means the
+         * two renderer dispatchers — which both key on this classification alone — pick the datetime
+         * pair without either of them learning a new rule.
+         *
+         * Scoped to the RENDERING classification on purpose: nothing in DTO building or persistence
+         * branches on `DATE` vs `DATETIME` (checked), so this changes which control a field gets and
+         * nothing about how its value is carried or stored.
+         */
+        case 'date': return getDateTimeUI(unwrapped) !== undefined ? FieldSchemaType.DATETIME : FieldSchemaType.DATE;
         case 'object': return FieldSchemaType.OBJECT;
         case 'array': return FieldSchemaType.ARRAY;
         case 'set': return FieldSchemaType.SET;
@@ -652,6 +831,210 @@ export function getSchemaType(schema) {
         default: return FieldSchemaType.UNKNOWN;
     }
 }
+/**
+ * Which classified schema types HOLD FIELDS — parts that are fields of the resource in their own right, each
+ * labelled, displayed and validated under its own dotted path (`privacy.consentedPurposes`) — as opposed to
+ * being ONE value whose parts belong to the value.
+ *
+ * A structured value is a Zod object too: `z_money()` is `{ amount, currency, decimals }`, `z_address()` is
+ * `{ line1, …, coordinates }`, every `z_range()` is `{ from, to }`. But its parts are not fields. The value's
+ * own component draws and names them (`LOW_LEVEL_FORM_FIELD_ADDRESS` carries `line1`, the money field reads the
+ * currency through `system_enums`), so the resource has exactly ONE word for the whole value — its field label —
+ * and no word for any part. Walking into a structured value as if it were a nested object is how the application
+ * labelling planner came to generate, translate and ship `fields.amount.amount`, `fields.amount.currency` and
+ * `fields.amount.decimals` for a money field no screen ever looked up (#1959).
+ *
+ * A `Record` over the whole enum rather than a list of either half, so a classification added tomorrow is a
+ * compile error here until someone decides which it is — the label walk, the labelling planner, the frontend
+ * label introspection and the validation summary all read this one answer through {@link isFieldContainerSchema}.
+ *
+ * `VERSIONED_OBJECT` holds fields: `versioned()` returns the application's own object with two hidden bookkeeping
+ * fields added, and the display renders it through the plain object branch, child field by child field.
+ */
+const FIELD_SCHEMA_TYPE_HOLDS_FIELDS = {
+    [FieldSchemaType.OBJECT]: true,
+    [FieldSchemaType.VERSIONED_OBJECT]: true,
+    [FieldSchemaType.STRING]: false,
+    [FieldSchemaType.NUMBER]: false,
+    [FieldSchemaType.BIGINT]: false,
+    [FieldSchemaType.BOOLEAN]: false,
+    [FieldSchemaType.ENUM]: false,
+    [FieldSchemaType.DATE]: false,
+    /*
+     * An ARRAY is not a container of FIELDS: its items are rows of one schema, and a walk that labels by field
+     * steps through it to the item (index-free) and asks this question of the ITEM. SET, TUPLE, RECORD and MAP
+     * are never walked for field labels at all.
+     */
+    [FieldSchemaType.ARRAY]: false,
+    [FieldSchemaType.SET]: false,
+    [FieldSchemaType.TUPLE]: false,
+    [FieldSchemaType.RECORD]: false,
+    [FieldSchemaType.MAP]: false,
+    [FieldSchemaType.TIME]: false,
+    [FieldSchemaType.DATETIME]: false,
+    [FieldSchemaType.RANGE_NUMBER]: false,
+    [FieldSchemaType.RANGE_DATE]: false,
+    [FieldSchemaType.RANGE_DATETIME]: false,
+    [FieldSchemaType.RANGE_TIME]: false,
+    [FieldSchemaType.RANGE_BIGDECIMAL]: false,
+    [FieldSchemaType.RANGE_MONEY]: false,
+    [FieldSchemaType.MONEY]: false,
+    [FieldSchemaType.BIGDECIMAL]: false,
+    [FieldSchemaType.CODE]: false,
+    [FieldSchemaType.FILE]: false,
+    [FieldSchemaType.DURATION]: false,
+    [FieldSchemaType.PHONE]: false,
+    [FieldSchemaType.ADDRESS]: false,
+    [FieldSchemaType.VERSIONED_FOREIGN_KEY]: false,
+    [FieldSchemaType.UNKNOWN]: false,
+};
+/**
+ * Does this schema HOLD FIELDS of the resource — so a walk that labels by field path descends into it — rather
+ * than being a scalar or a structured value whose parts are its own (money, address, duration, code, file, every
+ * range)? See {@link FIELD_SCHEMA_TYPE_HOLDS_FIELDS} for why the two are different and why the answer is read off
+ * {@link getSchemaType} rather than off a list of value types.
+ *
+ * Takes the schema as declared, wrappers included: `getSchemaType` recognises every structured value through its
+ * wrappers, so `z_money().optional()` answers `false` like `z_money()` does.
+ *
+ * @example
+ * isFieldContainerSchema(z.object({ city: z.string() })); // true — `address.city` is a field
+ * isFieldContainerSchema(z_address());                    // false — `line1` is the address's, not the resource's
+ */
+export function isFieldContainerSchema(schema) {
+    return FIELD_SCHEMA_TYPE_HOLDS_FIELDS[getSchemaType(schema)];
+}
+// =============================================================================
+// VALUE TYPE INFERENCE — the runtime twin of getSchemaType
+// =============================================================================
+/**
+ * An ISO-8601 DATETIME: a calendar date, a `T` (or the JSON-ish space form), a clock time, and an
+ * optional zone designator.
+ *
+ * The `T` is what makes this safe to recognise. No identifier, version, code or reference in this
+ * codebase's data has that shape, so a string matching it is a datetime with as much certainty as
+ * a declared schema would have given.
+ */
+const ISO_DATETIME_PATTERN = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})?$/;
+/** An ISO-8601 CALENDAR DATE and nothing else. */
+const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * Does this `YYYY-MM-DD` name a real day?
+ *
+ * `new Date('2026-02-30')` does not throw — it rolls over to 2 March — so a pattern match alone
+ * would accept a string that is shaped like a date and is not one. Round-tripping the parsed parts
+ * back out is what rejects it, and it is the difference between recognising dates and recognising
+ * things with four digits, a dash and some numbers.
+ */
+function namesARealCalendarDay(year, month, day) {
+    const parsed = new Date(Date.UTC(year, month - 1, day));
+    return parsed.getUTCFullYear() === year
+        && parsed.getUTCMonth() === month - 1
+        && parsed.getUTCDate() === day;
+}
+/**
+ * WHAT IS THIS VALUE, when no schema can say?
+ *
+ * The runtime twin of {@link getSchemaType}, and it exists for exactly one caller shape: a field
+ * declared `z.unknown()`. That is a DELIBERATE posture — an outbound webhook's `payload`, an
+ * integration's passthrough blob, a stored provider response — and the framework's answer used to
+ * be a single one: pretty-print everything as JSON into the code viewer. Faithful, and wrong for
+ * the common case, because most values inside such a payload are ordinary scalars. A name rendered
+ * as `"Ada"` in a monospace code block, a flag as `true`, a timestamp as a quoted ISO string: each
+ * is the value, and none of them is how that value reads anywhere else in the application.
+ *
+ * So when the schema cannot say, ask the value — and route a recognisable primitive to the
+ * formatter that primitive would have had if it HAD been declared.
+ *
+ * ## `undefined` is an answer, and the important one
+ *
+ * An object, an array, `null`, a function, a symbol — anything this cannot name — returns
+ * `undefined`, and the caller keeps the JSON rendering. That is the case the mechanism was built
+ * for and it is not being taken away; what changes is that scalars stop going through it.
+ *
+ * ## What is deliberately NOT inferred
+ *
+ * - **A number is never a date.** `1789903936618` is a plausible epoch and also a plausible id,
+ *   counter, amount or checksum, and there is nothing in the value to tell them apart. Guessing
+ *   would silently reformat every large integer in every opaque payload as a date in 2026.
+ * - **A numeric STRING stays a string.** `'42'` in a passthrough payload was sent as text by
+ *   whoever sent it; rendering it through the number formatter would apply grouping and locale
+ *   decimals to something that may be a code, a zip or a version segment.
+ * - **`true`/`false` as strings stay strings**, for the same reason.
+ * - **A bare `YYYY-MM-DD` IS taken as a date**, which is the one judgement call here. It is the
+ *   only shape in the list that something else could plausibly be, and the calendar round-trip
+ *   above is what keeps it from swallowing near-misses. In payload data this shape is a date
+ *   essentially always, and the cost of being wrong is a differently-formatted string rather than
+ *   a lost value.
+ *
+ * ## A string that CARRIES an object or array is that object, not a string
+ *
+ * The webhook `payload` named first above reaches the display SERIALIZED — a string whose content
+ * is a JSON object — and `typeof` alone reads it as a string. The first version of this function
+ * did exactly that, and the one case the mechanism promised to keep was the one it took away: the
+ * delivery-log payload rendered as a single raw line in a paragraph, found by
+ * `browser-settings-hub-webhooks` step 6 on its first run after this landed (#1411).
+ *
+ * So a string whose trimmed text opens with `{` or `[` AND parses to an object or array answers
+ * `undefined`, and keeps the JSON rendering — which already unwraps a string-wrapped value
+ * (`DisplayFieldJson`). The opening-character check keeps the parse off ordinary text, and the parse
+ * keeps prose that merely starts with a bracket ("[draft] …") a string.
+ *
+ * ## An author who disagrees has the existing escape hatch
+ *
+ * `displayComponent` is resolved BEFORE this is consulted, so a field that must always render as
+ * JSON says so and never reaches the inference.
+ */
+/**
+ * Does this string SERIALIZE an object or array? See "A string that CARRIES an object or array"
+ * on {@link inferFieldSchemaTypeFromValue}. A JSON scalar (`"42"`, `"true"`) deliberately does not
+ * count — those are the numeric and boolean strings that function keeps as strings on purpose.
+ */
+function carriesJsonStructure(text) {
+    const trimmed = text.trim();
+    const opener = trimmed.charAt(0);
+    if (opener !== '{' && opener !== '[')
+        return false;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return parsed !== null && typeof parsed === 'object';
+    }
+    catch {
+        return false;
+    }
+}
+export function inferFieldSchemaTypeFromValue(value) {
+    if (value instanceof Date) {
+        return FieldSchemaType.DATETIME;
+    }
+    switch (typeof value) {
+        case 'boolean':
+            return FieldSchemaType.BOOLEAN;
+        case 'bigint':
+            return FieldSchemaType.BIGINT;
+        case 'number':
+            // Including NaN and the infinities, deliberately: `JSON.stringify(NaN)` is the string
+            // `null`, so the JSON path would report a value that is not there. The number formatter
+            // renders them as themselves.
+            return FieldSchemaType.NUMBER;
+        case 'string':
+            break;
+        default:
+            return undefined;
+    }
+    const text = value;
+    if (carriesJsonStructure(text)) {
+        return undefined;
+    }
+    if (ISO_DATETIME_PATTERN.test(text) && !Number.isNaN(Date.parse(text))) {
+        return FieldSchemaType.DATETIME;
+    }
+    const dateParts = ISO_DATE_PATTERN.exec(text);
+    if (dateParts && namesARealCalendarDay(Number(dateParts[1]), Number(dateParts[2]), Number(dateParts[3]))) {
+        return FieldSchemaType.DATE;
+    }
+    return FieldSchemaType.STRING;
+}
 // =============================================================================
 // ZOD HELPER GETTER
 // =============================================================================
@@ -720,6 +1103,100 @@ export function getMergedObjectOrUnionShape(schema) {
     }
     return {};
 }
+/**
+ * The key a union of OBJECTS is discriminated by — the declared one, or the one a plain `z.union` carries
+ * structurally. `undefined` when the schema is not a union, or is a plain union no key discriminates.
+ *
+ * ## Why a plain union needs an answer
+ *
+ * `z.discriminatedUnion(key, …)` records its key; `z.union([V1, V2])` does not, even when every member
+ * declares the same key as a literal and those literals never collide — which is exactly how a versioned
+ * record is written (`schemaVersion: z.literal(1)` / `z.literal(2)`). Such a union IS discriminated; only
+ * the spelling differs. Measured 2026-09-14 on the compliance programme's `documentationRequirements`
+ * items (`z.union([V1, V2])`): the display resolved no member, so every item rendered an em-dash, and the
+ * label walk collected no field inside them, so `governanceScope.subjectKind` could not be worded
+ * anywhere (#1022).
+ *
+ * The real instance is one step less regular than that: V1 predates `schemaVersion` and does not declare it
+ * at all, while V2 declares `z.literal(2)`. Both are `z.strictObject`s, so V1 REJECTS any value carrying the
+ * key — its absence is as decisive as a literal.
+ *
+ * ## The inference, and why it cannot guess
+ *
+ * A key discriminates a plain union only when EVERY option is an object and, for that key:
+ *
+ * 1. every member either declares it as a bare `z.literal`, or omits it AND is strict (`z.strictObject`,
+ *    whose catchall is `never`) — a non-strict member that omits the key would also accept a value carrying it;
+ * 2. the declared literal values are pairwise DISJOINT across members;
+ * 3. at least one member declares it, and at most ONE member omits it.
+ *
+ * Under those conditions a value selects at most one member — by its literal, or by carrying no value for the
+ * key (the one member that omits it) — so resolving by it is exact, the same guarantee
+ * `z.discriminatedUnion` enforces at construction. Keys are tried in authoring order across the members, so
+ * the answer is deterministic. A union that fails every key answers `undefined`, and callers keep treating
+ * it as undiscriminated.
+ *
+ * One function, so the label walk (`collectResourceLabelFieldEntries`), the application label deciders and
+ * the display ({@link resolveDiscriminatedUnionVariant}) agree about which unions have members at all.
+ */
+export function getUnionDiscriminatorKey(schema) {
+    if (!isZodUnion(schema))
+        return undefined;
+    const declared = getZodDefStringProperty(schema, 'discriminator');
+    if (declared)
+        return declared;
+    const options = (getZodDefArrayProperty(schema, 'options') ?? []);
+    if (options.length < 2)
+        return undefined;
+    if (!options.every((option) => isZodTypeAny(option) && isZodObject(option)))
+        return undefined;
+    const members = options;
+    const memberShapes = members.map((member) => getZodObjectShape(member));
+    const candidateKeys = [...new Set(memberShapes.flatMap((shape) => Object.keys(shape)))];
+    for (const key of candidateKeys) {
+        const seenValues = new Set();
+        let declaringMembers = 0;
+        let omittingMembers = 0;
+        const discriminates = memberShapes.every((shape, index) => {
+            const keySchema = shape[key];
+            if (!keySchema) {
+                omittingMembers += 1;
+                return omittingMembers <= 1 && isStrictZodObject(members[index]);
+            }
+            if (!isZodLiteral(keySchema))
+                return false;
+            const literalValues = getZodDefArrayProperty(keySchema, 'values') ?? [];
+            if (literalValues.length === 0 || literalValues.some((literalValue) => seenValues.has(literalValue)))
+                return false;
+            for (const literalValue of literalValues)
+                seenValues.add(literalValue);
+            declaringMembers += 1;
+            return true;
+        });
+        if (discriminates && declaringMembers > 0)
+            return key;
+    }
+    return undefined;
+}
+/** A `z.strictObject` — its catchall is `never`, so it rejects every key its shape does not declare. */
+function isStrictZodObject(schema) {
+    const catchall = getZodDefSchemaProperty(schema, 'catchall');
+    return catchall !== undefined && getZodType(catchall) === 'never';
+}
+/**
+ * The OBJECT members of a union that {@link getUnionDiscriminatorKey} discriminates — declared or plain —
+ * in authoring order; `[]` for anything else. Pass the UNWRAPPED schema.
+ *
+ * For a declared discriminated union the non-object options are filtered out, as
+ * `AutomatedLayoutFrontendUtils.getDiscriminatedUnionObjectOptions` does; a plain union has none (the
+ * inference requires every option to be an object).
+ */
+export function getUnionObjectMembers(schema) {
+    if (!getUnionDiscriminatorKey(schema))
+        return [];
+    const options = (getZodDefArrayProperty(schema, 'options') ?? []);
+    return options.filter((option) => isZodTypeAny(option) && isZodObject(option));
+}
 /**
  * Resolve the ONE variant of a discriminated union that a given value belongs to.
  *
@@ -729,22 +1206,28 @@ export function getMergedObjectOrUnionShape(schema) {
  * which variant this is, so the shape can be exactly that variant's, with no fields belonging to
  * the alternatives the value did not choose.
  *
+ * The discriminator is {@link getUnionDiscriminatorKey}'s: declared, or carried structurally by a plain
+ * `z.union` (#1022 — a versioned record's items). For such a plain union a value carrying NO discriminator
+ * belongs to the one strict member that omits the key, when there is one; for a declared discriminated union
+ * it belongs to none.
+ *
  * Returns `null` when the schema is not a discriminated union, when the value carries no
- * discriminator, or when no variant matches it — all three are "this caller cannot narrow", and a
- * caller that renders should say nothing rather than guess a variant.
+ * discriminator its union can place, or when no variant matches it — all three are "this caller cannot
+ * narrow", and a caller that renders should say nothing rather than guess a variant.
  */
 export function resolveDiscriminatedUnionVariant(schema, value) {
-    if (!isDiscriminatedUnion(schema))
-        return null;
     if (typeof value !== 'object' || value === null)
         return null;
-    const discriminator = getZodDefStringProperty(schema, 'discriminator');
+    const discriminator = getUnionDiscriminatorKey(schema);
     if (!discriminator)
         return null;
     const discriminatorValue = value[discriminator];
-    if (discriminatorValue === undefined)
-        return null;
     const options = (getZodDefArrayProperty(schema, 'options') ?? []);
+    if (discriminatorValue === undefined) {
+        if (getZodDefStringProperty(schema, 'discriminator'))
+            return null;
+        return options.find((option) => isZodObject(option) && getZodObjectShape(option)[discriminator] === undefined) ?? null;
+    }
     for (const option of options) {
         if (!isZodObject(option))
             continue;
@@ -786,6 +1269,33 @@ export function getZodDefArrayProperty(schema, property) {
     const value = def?.[property];
     return isArray(value) ? value : undefined;
 }
+/**
+ * The payload of one entry of a schema's `checks` array.
+ *
+ * A CHECK IS ITSELF A ZOD INTERNAL, which is the whole reason this helper exists. Its own fields
+ * live at `check._zod.def`, not on the check object, and they are keyed by a `check` discriminator
+ * (`min_length`, `greater_than`, `string_format`, …) rather than by the Zod 3 `kind` property.
+ *
+ * Three readers in this file — {@link getStringFormat}, {@link getStringConstraints} and
+ * {@link getNumberConstraints} — walked `checks` and read `check.kind`, which is `undefined` for
+ * every check Zod 4 produces. None of them threw; each returned an empty answer, so a string with
+ * `.max(120)` reported no maximum, a number with `.min(1)` reported no minimum, and `z.email()`
+ * reported no format. Every consumer degraded silently: an `<input>` with no `maxLength`, no `min`,
+ * and `type="text"` where `type="email"` was intended.
+ */
+function getZodCheckDefinition(check) {
+    if (typeof check !== 'object' || check === null)
+        return undefined;
+    const internals = check._zod;
+    if (typeof internals === 'object' && internals !== null && 'def' in internals) {
+        const definition = internals.def;
+        if (typeof definition === 'object' && definition !== null)
+            return definition;
+    }
+    // A check authored as a plain object (or a future Zod shape that flattens the payload) is read
+    // directly rather than skipped — the discriminator lookup below tolerates a miss.
+    return check;
+}
 export function getZodDefStringProperty(schema, property) {
     const def = getZodDef(schema);
     const value = def?.[property];
@@ -955,34 +1465,82 @@ export function getShowWhenParams(schema) {
     const metadata = getCustomFieldMetadata(schema);
     return metadata[ZodDecorator.SHOW_WHEN];
 }
+// =============================================================================
+// Enhanced Primitive Helpers
+// =============================================================================
+// ------------------------------------------------------------
+// STRING SCHEMA UTILITIES
+// ------------------------------------------------------------
+/**
+ * Keep the TIGHTER of two bounds a schema declares, so several constraints compose the way the
+ * validator composes them: every lower bound must be cleared, so the highest governs, and every
+ * upper bound must be respected, so the lowest does.
+ *
+ * `undefined` means "nothing declared yet" and always loses, which is what makes these safe to fold
+ * over a checks array in any order.
+ */
+function tightestLowerBound(current, candidate) {
+    return current === undefined ? candidate : Math.max(current, candidate);
+}
+function tightestUpperBound(current, candidate) {
+    return current === undefined ? candidate : Math.min(current, candidate);
+}
 /**
- * Get string format from schema checks (email, url, etc.)
+ * The format a string schema declares — `email`, `url`, `datetime`, … — or `null` for a plain one.
+ *
+ * Zod 4 expresses a format TWO ways and both are read here, because an author picks between them
+ * freely and the rendered field must not depend on which they chose:
+ *
+ *   - a dedicated schema type (`z.email()`, `z.iso.datetime()`) carries `def.format` and no checks;
+ *   - a chained refinement (`z.string().email()`) carries a `string_format` CHECK whose own
+ *     definition names the format.
+ *
+ * `ipv4` and `ipv6` both answer `'ip'`: this vocabulary exists to choose an input type and a
+ * display treatment, and those are the same for either family.
  */
 export function getStringFormat(schema) {
     const unwrapped = unwrapSchema(schema);
     if (getZodType(unwrapped) !== 'string') {
         return null;
     }
-    const checks = getZodDefArrayProperty(unwrapped, 'checks') ?? [];
-    for (const check of checks) {
-        if (typeof check !== 'object' || check === null)
+    const declared = getZodDefStringProperty(unwrapped, 'format');
+    const fromDeclaration = normalizeStringFormat(declared);
+    if (fromDeclaration)
+        return fromDeclaration;
+    for (const check of getZodDefArrayProperty(unwrapped, 'checks') ?? []) {
+        const definition = getZodCheckDefinition(check);
+        if (definition?.check !== 'string_format')
             continue;
-        const kind = check.kind;
-        switch (kind) {
-            case 'email': return 'email';
-            case 'url': return 'url';
-            case 'uuid': return 'uuid';
-            case 'cuid': return 'cuid';
-            case 'cuid2': return 'cuid2';
-            case 'ulid': return 'ulid';
-            case 'regex': return 'regex';
-            case 'datetime': return 'datetime';
-            case 'time': return 'time';
-            case 'ip': return 'ip';
-        }
+        const fromCheck = normalizeStringFormat(definition.format);
+        if (fromCheck)
+            return fromCheck;
     }
     return null;
 }
+/**
+ * Zod's format name → this vocabulary. Unknown names answer `null` rather than being passed
+ * through, because every consumer switches on {@link StringFormat} and an unrecognised value would
+ * fall to a default anyway — but as a widened type, which is how a format nobody handles ends up
+ * silently typed as one that is handled.
+ */
+function normalizeStringFormat(value) {
+    switch (value) {
+        case 'email': return 'email';
+        case 'url': return 'url';
+        case 'uuid': return 'uuid';
+        case 'cuid': return 'cuid';
+        case 'cuid2': return 'cuid2';
+        case 'ulid': return 'ulid';
+        case 'regex': return 'regex';
+        case 'datetime': return 'datetime';
+        case 'time': return 'time';
+        // Both IP families answer the same thing — see the note on `getStringFormat`.
+        case 'ip':
+        case 'ipv4':
+        case 'ipv6': return 'ip';
+        default: return null;
+    }
+}
 /**
  * Get min/max length constraints from string schema
  */
@@ -991,24 +1549,32 @@ export function getStringConstraints(schema) {
     if (getZodType(unwrapped) !== 'string') {
         return {};
     }
-    const checks = getZodDefArrayProperty(unwrapped, 'checks') ?? [];
     const result = {};
-    for (const check of checks) {
-        if (typeof check !== 'object' || check === null)
-            continue;
-        const kind = check.kind;
-        const value = check.value;
-        if (typeof value !== 'number')
+    // Zod 4 keys these by a `check` discriminator and names the bound after the constraint
+    // (`minimum` / `maximum` / `length`), where Zod 3 used `kind` plus a shared `value`.
+    //
+    // Bounds ACCUMULATE toward the tightest rather than being assigned, because a schema may carry
+    // several and the last one authored is not the one that governs. `z.string().min(3).nonempty()`
+    // is ordinary authoring — a business floor plus a sanity floor — and assigning would report
+    // `minLength: 1` for a schema that rejects `"ab"`. The same reasoning the truncation and the
+    // exclusive-bound branches already follow: a hint looser than the schema invites a value the
+    // server refuses, which is worse than no hint at all.
+    for (const check of getZodDefArrayProperty(unwrapped, 'checks') ?? []) {
+        const definition = getZodCheckDefinition(check);
+        if (!definition)
             continue;
-        if (kind === 'min') {
-            result.minLength = value;
+        const minimum = definition.minimum;
+        const maximum = definition.maximum;
+        const exactLength = definition.length;
+        if (definition.check === 'min_length' && typeof minimum === 'number') {
+            result.minLength = tightestLowerBound(result.minLength, minimum);
         }
-        if (kind === 'max') {
-            result.maxLength = value;
+        if (definition.check === 'max_length' && typeof maximum === 'number') {
+            result.maxLength = tightestUpperBound(result.maxLength, maximum);
         }
-        if (kind === 'length') {
-            result.minLength = value;
-            result.maxLength = value;
+        if (definition.check === 'length_equals' && typeof exactLength === 'number') {
+            result.minLength = tightestLowerBound(result.minLength, exactLength);
+            result.maxLength = tightestUpperBound(result.maxLength, exactLength);
         }
     }
     return result;
@@ -1025,29 +1591,66 @@ export function getNumberConstraints(schema) {
     if (type !== 'number' && type !== 'int') {
         return {};
     }
-    const checks = getZodDefArrayProperty(unwrapped, 'checks') ?? [];
     const result = {};
-    // int type in Zod v4
     if (type === 'int') {
         result.isInt = true;
         result.step = 1;
     }
+    // Zod 4 names a bound by DIRECTION rather than by role — `greater_than` / `less_than`, each
+    // carrying an `inclusive` flag — where Zod 3 had `min` / `max`. Integer-ness is a `number_format`
+    // check (`z.number().int()`) or the schema type itself (`z.int()`), never a `kind: 'int'`.
+    //
+    // Read INTEGER-NESS FIRST, in its own pass, because an exclusive bound cannot be translated
+    // without knowing it — see below.
+    //
+    // It arrives the same TWO ways a string format does, and both must be read: `z.number().int()`
+    // adds a `number_format` CHECK, while `z.int()` is its own schema type carrying `def.format` and
+    // no checks at all. Reading only the check left `z.int()` — the shorter and more idiomatic
+    // spelling — reporting no integer constraint and therefore no step.
+    const declaredNumberFormat = getZodDefStringProperty(unwrapped, 'format');
+    if (typeof declaredNumberFormat === 'string' && declaredNumberFormat.includes('int')) {
+        result.isInt = true;
+        result.step = 1;
+    }
+    const checks = getZodDefArrayProperty(unwrapped, 'checks') ?? [];
     for (const check of checks) {
-        if (typeof check !== 'object' || check === null)
-            continue;
-        const kind = check.kind;
-        const value = check.value;
-        if (kind === 'min' && typeof value === 'number') {
-            result.min = value;
-        }
-        if (kind === 'max' && typeof value === 'number') {
-            result.max = value;
-        }
-        if (kind === 'int') {
+        const definition = getZodCheckDefinition(check);
+        if (definition?.check === 'number_format' && typeof definition.format === 'string' && definition.format.includes('int')) {
             result.isInt = true;
             result.step = 1;
         }
-        if (kind === 'multipleOf' && typeof value === 'number') {
+    }
+    for (const check of checks) {
+        const definition = getZodCheckDefinition(check);
+        if (!definition)
+            continue;
+        const value = definition.value;
+        if (typeof value !== 'number')
+            continue;
+        const inclusive = definition.inclusive === true;
+        if (definition.check === 'greater_than') {
+            // An EXCLUSIVE bound has no HTML equivalent: `min` is inclusive, so writing the raw value
+            // would ADMIT a number the schema rejects — `z.number().positive()` becoming `min="0"` and
+            // accepting zero. On an integer the next representable value is exact, so it translates; on a
+            // float there is no honest answer and the constraint is left unstated rather than stated
+            // wrongly. A field with no hint still validates; a field with a wrong hint invites a value
+            // the server refuses.
+            //
+            // And for the same reason the result ACCUMULATES toward the tightest bound instead of being
+            // assigned: `z.number().int().min(5).positive()` carries two lower bounds, and taking the
+            // last would report `min: 1` for a schema that rejects 1 through 4.
+            if (inclusive)
+                result.min = tightestLowerBound(result.min, value);
+            else if (result.isInt)
+                result.min = tightestLowerBound(result.min, value + 1);
+        }
+        if (definition.check === 'less_than') {
+            if (inclusive)
+                result.max = tightestUpperBound(result.max, value);
+            else if (result.isInt)
+                result.max = tightestUpperBound(result.max, value - 1);
+        }
+        if (definition.check === 'multiple_of') {
             result.step = value;
         }
     }
@@ -1065,17 +1668,14 @@ export function getNumberConstraints(schema) {
 export function getEnumValues(schema) {
     const unwrapped = unwrapSchema(schema);
     const type = getZodType(unwrapped);
-    // Handle string literal types (z.literal("value")) - return single value as array
-    // Only string literals are treated as enums (for select fields)
-    // In Zod v4, literal values are stored in def.values as an array
+    // A string literal is a vocabulary — usually of one value (`z.literal('value')`), and in Zod 4
+    // legitimately of several (`z.literal(['a', 'b'])`), which stores every value in `def.values`.
+    // EVERY string value is the vocabulary: reading only `values[0]` planned and worded one value of a
+    // multi-value discriminator and rendered every other member's row raw (#1096). Non-string literals
+    // (numbers, booleans, null) are not select-field vocabularies and contribute nothing.
     if (type === 'literal') {
-        const values = getZodDefProperty(unwrapped, 'values');
-        const literalValue = values?.[0];
-        // Only string literals are valid enum values
-        if (typeof literalValue === 'string') {
-            return [literalValue];
-        }
-        return [];
+        const values = getZodDefProperty(unwrapped, 'values') ?? [];
+        return values.filter((value) => typeof value === 'string');
     }
     // Handle union types - combine enum values from all options
     // This handles cases like z.union([z.enum(A), z.enum(B)])
@@ -1386,7 +1986,23 @@ export function getArrayItemSchema(schema) {
     return element ?? null;
 }
 /**
- * Get min/max constraints for array
+ * How many items an array schema admits — `z.array(x).min(1).max(3)`.
+ *
+ * READS ZOD 4, and did not until 2026-09-20: it looked for `def.minLength` / `def.maxLength`
+ * carrying a `{ value }` object, which is the ZOD 3 shape. Zod 4 puts array bounds in `def.checks`
+ * under a `check` discriminator (`min_length` / `max_length` / `length_equals`) with the bound
+ * named after the constraint, exactly as the string reader above already handles. So this returned
+ * `{}` for every array ever declared — measured, all three of `.min(1).max(2)`, `.max(1)` and no
+ * bound at all answered the same thing.
+ *
+ * The cost was silent and total: an author could write `.max(3)` on a multi-select and get no
+ * limit, no disabled options and no hint, with the only enforcement left at submit — and the one
+ * control that read this looked, in its source, exactly like a control that honoured it.
+ *
+ * Bounds ACCUMULATE toward the tightest, for the same reason the string reader states: a schema
+ * may carry several (`.min(1).nonempty()` is ordinary authoring) and the last one authored is not
+ * the one that governs. A hint looser than the schema invites a value the server refuses, which is
+ * worse than no hint at all.
  */
 export function getArrayConstraints(schema) {
     const unwrapped = unwrapSchema(schema);
@@ -1394,17 +2010,23 @@ export function getArrayConstraints(schema) {
         return {};
     }
     const result = {};
-    const minLength = getZodDefProperty(unwrapped, 'minLength');
-    const maxLength = getZodDefProperty(unwrapped, 'maxLength');
-    if (minLength && typeof minLength === 'object' && 'value' in minLength) {
-        const value = minLength.value;
-        if (typeof value === 'number')
-            result.minLength = value;
-    }
-    if (maxLength && typeof maxLength === 'object' && 'value' in maxLength) {
-        const value = maxLength.value;
-        if (typeof value === 'number')
-            result.maxLength = value;
+    for (const check of getZodDefArrayProperty(unwrapped, 'checks') ?? []) {
+        const definition = getZodCheckDefinition(check);
+        if (!definition)
+            continue;
+        const minimum = definition.minimum;
+        const maximum = definition.maximum;
+        const exactLength = definition.length;
+        if (definition.check === 'min_length' && typeof minimum === 'number') {
+            result.minLength = tightestLowerBound(result.minLength, minimum);
+        }
+        if (definition.check === 'max_length' && typeof maximum === 'number') {
+            result.maxLength = tightestUpperBound(result.maxLength, maximum);
+        }
+        if (definition.check === 'length_equals' && typeof exactLength === 'number') {
+            result.minLength = tightestLowerBound(result.minLength, exactLength);
+            result.maxLength = tightestUpperBound(result.maxLength, exactLength);
+        }
     }
     return result;
 }
@@ -1412,7 +2034,21 @@ export function getArrayConstraints(schema) {
 // RECORD/MAP SCHEMA UTILITIES
 // ------------------------------------------------------------
 /**
- * Get the value schema from a record schema
+ * Get the value schema from a record schema.
+ *
+ * A record's keys are DATA rather than declared fields, so it has no `shape` and
+ * {@link getObjectShape} correctly answers `null` for one. What a consumer still needs is the
+ * single schema every entry's value shares — enough to render each entry through the ordinary
+ * field dispatch instead of as raw text.
+ *
+ * That is not hypothetical: `FieldSchemaType.RECORD` had no display branch at all until
+ * 2026-09-18, so a record field fell through `DisplayValueDispatcher` to its "unsupported type"
+ * chip and rendered an ERROR over data that was fully present — measured on four settings panes
+ * (an organization's `Limits` and `Limit overrides`, and SSO's `Domain verification status` on
+ * both the organization and application surfaces). This function existed the whole time; the
+ * display simply never called it.
+ *
+ * Unwraps first, so an `.optional()` / `.default()` / `.nullable()` record answers like a bare one.
  */
 export function getRecordValueSchema(schema) {
     const unwrapped = unwrapSchema(schema);
@@ -1422,6 +2058,59 @@ export function getRecordValueSchema(schema) {
     const valueSchema = getZodDefSchemaProperty(unwrapped, 'valueType');
     return valueSchema ?? null;
 }
+/**
+ * The KEY schema of a RECORD, or `null` when the schema is not a record — {@link getRecordValueSchema}'s twin.
+ *
+ * A record's keys are data, but they can still belong to a named vocabulary: an organization's `limits` is keyed by
+ * limit identifiers, declared `z.record(z.string().systemEnum('Limit'), …)`, and a display reads each key's word
+ * through the vocabulary the key schema names (#1851) instead of printing the identifier.
+ *
+ * Unwraps first, like {@link getRecordValueSchema}.
+ */
+export function getRecordKeySchema(schema) {
+    const unwrapped = unwrapSchema(schema);
+    if (getZodType(unwrapped) !== 'record') {
+        return null;
+    }
+    const keySchema = getZodDefSchemaProperty(unwrapped, 'keyType');
+    return keySchema ?? null;
+}
+/**
+ * The element schema of a SET, or `null` when the schema is not a set.
+ *
+ * Sibling of {@link getRecordValueSchema} and {@link getMapSchemas}, and added for the same reason
+ * that one records: `FieldSchemaType.SET` classified correctly and had no display branch, so a set
+ * field fell through `DisplayValueDispatcher` to its "unsupported type" chip and rendered an ERROR
+ * over data that was fully present. A set is an ARRAY without order or duplicates, so its element
+ * schema is the only thing a renderer needs to treat it as one.
+ *
+ * Unwraps first, so an `.optional()` / `.default()` / `.nullable()` set answers like a bare one.
+ */
+export function getSetValueSchema(schema) {
+    const unwrapped = unwrapSchema(schema);
+    if (getZodType(unwrapped) !== 'set') {
+        return null;
+    }
+    return getZodDefSchemaProperty(unwrapped, 'valueType') ?? null;
+}
+/**
+ * The positional item schemas of a TUPLE, or `null` when the schema is not a tuple.
+ *
+ * A tuple differs from an array in exactly one way that matters to a renderer: each POSITION has
+ * its own schema, so the items cannot share one element type. Returning the list lets a display
+ * branch pair `value[i]` with `items[i]` and render each position as the type it actually is,
+ * rather than formatting the whole tuple as text.
+ *
+ * Unwraps first, like its siblings.
+ */
+export function getTupleItemSchemas(schema) {
+    const unwrapped = unwrapSchema(schema);
+    if (getZodType(unwrapped) !== 'tuple') {
+        return null;
+    }
+    const items = getZodDefProperty(unwrapped, 'items');
+    return Array.isArray(items) ? items : null;
+}
 /**
  * Get the key and value schemas from a map schema
  */
@@ -1869,6 +2558,45 @@ export function getUniqueFieldParams(schema) {
         return { scope: 'global', sparse: true }; // Default params from original getUniqueParams
     return value;
 }
+/**
+ * The NAME of the field an object schema marks as its primary key, or `undefined`.
+ *
+ * ## Why this is not `resourceFieldIdentifier`
+ *
+ * A resource has two different id-shaped names and they are not interchangeable:
+ *
+ *  - `resourceFieldIdentifier` (`organizationSsoConfigId`, `todoId`) is the URL PARAMETER name. It
+ *    appears in routes and in contextual parameters. A response payload does not generally carry it.
+ *  - the PRIMARY KEY field (`_id`) is what the row calls its own identity, and is what a payload
+ *    actually contains.
+ *
+ * Conflating them is a real defect rather than a hypothetical one. `ResourceAutomaticDisplayer`'s
+ * READ-bootstrap fallback — the path that exists so a row without an id in its URL can still be
+ * identified once its data arrives — read `data[resourceFieldIdentifier]`. For an ordinary resource
+ * the fallback never runs (the id is in the URL, so the earlier branch returns), and for a
+ * CONTEXT-ADDRESSED SINGLETON, which is the only shape that needs it, the key is absent from the
+ * payload and the lookup yields `undefined`.
+ *
+ * Measured 2026-09-19 on the running application: `organizationSsoConfig` loads
+ * `["_id", "enforcement", "domains", …]` while the fallback asked for `organizationSsoConfigId`. So
+ * the resource id stayed undefined after a successful READ, the mutation manager could not attach
+ * (it is keyed on that id), and `canInlineEdit` was false — which is why every settings singleton in
+ * the product was silently read-only, and why declaring `inlineEditable` on one would have changed
+ * nothing.
+ *
+ * Returns the FIRST field marked `.isPrimaryKey()`. A schema declaring several is malformed; a
+ * schema declaring none — a DTO projection, a nested object — yields `undefined`, and every caller
+ * treats that as "no id", which is the safe reading.
+ */
+export function getPrimaryKeyFieldName(schema) {
+    const shape = getZodObjectShape(schema);
+    for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+        if (isPrimaryKeyField(fieldSchema)) {
+            return fieldName;
+        }
+    }
+    return undefined;
+}
 /**
  * Check if a schema field has the isPrimaryKey decorator (recursive traversal through wrappers).
  */
@@ -2140,6 +2868,30 @@ export function getDurationConstraints(schema) {
         allowedUnits: metadata.allowedUnits,
     };
 }
+/**
+ * Check if a schema is an address schema (created by z_address()).
+ * Detects by the presence of addressConfig in SCHEMA_METADATA, on the schema or its unwrapped inner schema.
+ */
+export function isAddressSchema(schema) {
+    return getAddressMetadata(schema) !== undefined;
+}
+/**
+ * Get the address metadata from a schema, or undefined when it is not an address schema.
+ */
+export function getAddressMetadata(schema) {
+    const schemaMetadata = schema[SCHEMA_METADATA];
+    if (schemaMetadata?.addressConfig?.isAddress === true) {
+        return schemaMetadata.addressConfig;
+    }
+    const unwrapped = unwrapSchema(schema);
+    if (unwrapped !== schema) {
+        const unwrappedMetadata = unwrapped[SCHEMA_METADATA];
+        if (unwrappedMetadata?.addressConfig?.isAddress === true) {
+            return unwrappedMetadata.addressConfig;
+        }
+    }
+    return undefined;
+}
 /**
  * Check if a schema is a phone schema (created by z_phone()).
  * Detects by the presence of phoneConfig in SCHEMA_METADATA.
@@ -2489,6 +3241,18 @@ const ENUM_EDIT_MODE_BY_FORM_COMPONENT = {
     [FormFieldComponent.SELECT]: EnumEditMode.SELECT,
     [FormFieldComponent.RADIO_GROUP]: EnumEditMode.RADIO,
 };
+/**
+ * The MULTIPLE-selection twin of the map above, for the other `edit` axis an author can use.
+ *
+ * `CHECKBOX_GROUP` is deliberately absent from the single-select map — the test
+ * `does NOT map CHECKBOX_GROUP onto an enum mode` pins that, because a checkbox group is an
+ * array-of-enum control and has no single-select meaning. It belongs HERE, where it does, and it
+ * is the only member: `FormFieldComponent` has no `COMBOBOX`, which is why the searchable multi
+ * had to borrow `EnumEditMode.COMBOBOX` before this vocabulary existed.
+ */
+const ENUM_MULTIPLE_EDIT_MODE_BY_FORM_COMPONENT = {
+    [FormFieldComponent.CHECKBOX_GROUP]: EnumMultipleEditMode.CHECKBOX,
+};
 const NUMBER_EDIT_MODE_BY_FORM_COMPONENT = {
     [FormFieldComponent.INPUT]: NumberEditMode.INPUT,
     [FormFieldComponent.SLIDER]: NumberEditMode.SLIDER,
@@ -2517,6 +3281,21 @@ export function resolveEnumEditMode(schema) {
     const component = getFormFieldComponent(schema);
     return (component !== undefined ? ENUM_EDIT_MODE_BY_FORM_COMPONENT[component] : undefined) ?? EnumEditMode.SELECT;
 }
+/**
+ * Resolve the shape an ARRAY OF ENUM VALUES edits as.
+ *
+ * Takes the ELEMENT schema, which is where `enumUI()` lives. The default is CHECKBOX and not the
+ * single vocabulary's SELECT: a checkbox group is the one multiple control that says "any number
+ * of these" without the reader having to open it first, and it is what an undeclared enum array
+ * has always rendered as.
+ */
+export function resolveEnumMultipleEditMode(itemSchema) {
+    const declared = getEnumUI(itemSchema)?.edit?.multipleEditMode;
+    if (declared !== undefined)
+        return declared;
+    const component = getFormFieldComponent(itemSchema);
+    return (component !== undefined ? ENUM_MULTIPLE_EDIT_MODE_BY_FORM_COMPONENT[component] : undefined) ?? EnumMultipleEditMode.CHECKBOX;
+}
 /** Resolve the shape a number field edits as, honoring both edit axes. */
 export function resolveNumberEditMode(schema) {
     const declared = getNumberUI(schema)?.edit?.editMode;
@@ -2641,11 +3420,140 @@ export function isNotEditableForOperation(schema, operation) {
     return false;
 }
 /**
- * Check if a schema has inline editable configuration.
- * Reads from `{primitive}UI.display.inlineEditable`.
+ * The readable stand-in for an unresolvable foreign key, taken from the record that HOLDS it.
+ *
+ * Returns the value of the sibling named by `foreignKeyUI.display.labelFallbackField`, or
+ * `undefined` when the field declares none, the record is absent, or the sibling is empty. Every
+ * caller treats `undefined` as "fall through to the id", which is the behaviour before this existed
+ * — so a field that declares nothing renders exactly as it did.
+ *
+ * Non-string siblings are refused rather than coerced: a label is text, and `String(someObject)`
+ * would put `[object Object]` on screen, which is worse than the id it replaced.
+ */
+export function resolveForeignKeyLabelFallback(schema, record) {
+    if (!schema || !record)
+        return undefined;
+    const fallbackField = getForeignKeyUIDisplay(schema)?.labelFallbackField;
+    if (!fallbackField)
+        return undefined;
+    const raw = record[fallbackField];
+    return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
+}
+/**
+ * WHY this field has nothing to show — see {@link DisplayEmptyReason}.
+ *
+ * `isCollectionEmptiness` is supplied by the CALL SITE, because only the renderer knows which kind
+ * of emptiness it met: the dispatcher reaches its empty branches separately for a null scalar, a
+ * zero-length array, a keyless object and an entryless record. Re-deriving that from the value here
+ * would be a second, weaker answer to a question the caller has already answered exactly — and it
+ * would get `[]` on a field whose schema says OBJECT wrong.
+ *
+ * The remaining split is `.excludeFromUpdate()`: a field the UPDATE contract strips is one the
+ * operator cannot fill, so its emptiness is the system's to resolve, not theirs. That predicate is
+ * the same one {@link isEligibleForLayoutDefaultInlineEdit} uses to decide whether to offer a
+ * control, which is what keeps the two answers consistent: a field that gets no control also does
+ * not get a word inviting input.
+ */
+export function resolveDisplayEmptyReason(schema, isCollectionEmptiness) {
+    if (isCollectionEmptiness)
+        return DisplayEmptyReason.NONE;
+    if (schema && isExcludedFromUpdate(schema))
+        return DisplayEmptyReason.NOT_PROVIDED;
+    return DisplayEmptyReason.NOT_SET;
+}
+/**
+ * The component label key that words a given empty reason.
+ *
+ * One named mapping rather than a ternary at each of the dispatcher's four empty branches — the
+ * shape `.claude/rules/invariant-call-site-enumeration.md` exists to refuse. It is TOTAL over the
+ * vocabulary (`Record<DisplayEmptyReason, string>`), so a reason added tomorrow is a compile error
+ * here rather than a silent fallthrough to the generic word.
+ *
+ * `noValue` is deliberately KEPT as the NOT_SET key rather than renamed. It is already declared,
+ * already realised in every application's generated tree, and already the right words for that
+ * case; renaming it would restale every label unit in every application to say the same thing.
+ */
+export const DISPLAY_EMPTY_REASON_LABEL_KEYS = {
+    [DisplayEmptyReason.NOT_SET]: 'noValue',
+    [DisplayEmptyReason.NONE]: 'noValueNone',
+    [DisplayEmptyReason.NOT_PROVIDED]: 'noValueNotProvided',
+};
+/**
+ * Does this field DECLARE that it is inline-editable?
+ *
+ * Reads `{primitive}UI.display.inlineEditable`, which is `boolean | {…}`.
+ *
+ * ## `false` means FALSE — corrected 2026-09-19
+ *
+ * This used to be `inlineEditable != null`, so an authored `inlineEditable: false` answered TRUE
+ * and the field was routed to `DisplayFieldEditable` exactly like an opted-IN one. There,
+ * `getInlineEditableParams` returns `undefined` for `false` and the component falls back to
+ * `DEFAULT_INLINE_EDIT_PARAMS` — so the explicit opt-out produced the DEFAULT inline editor. An
+ * author writing `false` got the opposite of what they asked for, with nothing to grep for.
+ *
+ * Nothing in the repository authored `false` at the time of the fix (measured: zero occurrences
+ * across `engine/`, `platform/` and both dogfood applications), so no behaviour changed on the day.
+ * What changed is that the opt-out became REAL, which is what
+ * {@link ResourceLayoutInlineEditDefault} needs: a layout-level default is only safe if a single
+ * field can decline it.
  */
 export function hasInlineEditableDecorator(schema) {
-    return getFieldUIDisplayConfig(schema)?.inlineEditable != null;
+    return getFieldUIDisplayConfig(schema)?.inlineEditable != null
+        && getFieldUIDisplayConfig(schema)?.inlineEditable !== false;
+}
+/**
+ * Has this field explicitly DECLINED inline editing?
+ *
+ * Distinct from `!hasInlineEditableDecorator(schema)`, and the distinction is the whole point of
+ * the layout-level default: a field that says nothing is a candidate for the default, while a field
+ * that says `false` has opted out and must stay read-only even under a layout that turns the
+ * default on.
+ */
+export function declinesInlineEdit(schema) {
+    return getFieldUIDisplayConfig(schema)?.inlineEditable === false;
+}
+/**
+ * Would a layout whose `defaultInlineEdit` is on make THIS field editable in place?
+ *
+ * The predicate is derived from what the field already declares about itself, rather than from a
+ * hand-kept list of editable field names — so a field added to a settings schema tomorrow is
+ * covered without anyone remembering to add it, and a field that is not writable is never offered a
+ * control that would fail on save.
+ *
+ * A field qualifies when ALL of these hold:
+ *
+ *  - it has not DECLINED (`inlineEditable: false`) — an explicit author decision outranks a default;
+ *  - it is not `.excludeFromUpdate()` — the UPDATE DTO strips it, so a control here would collect a
+ *    value the server silently discards. That is worse than no control, because the row appears to
+ *    save and does not;
+ *  - it is not `.isHidden()` for display — a field nobody may read is not a field anybody may write.
+ *
+ * ## The primary key needs no clause of its own — measured, not assumed
+ *
+ * An `isPrimaryKey(schema)` guard was written here first, on the reasoning that an identity is not a
+ * setting. It is UNREACHABLE: `.isPrimaryKey()` already reports `isHiddenForDisplay() === true`, so
+ * the hidden clause below decides every primary key before a dedicated clause could. Deleting it
+ * left all ten pins green, which is how it was found.
+ *
+ * It is removed rather than kept "for safety". An unreachable guard is not defence in depth — it is
+ * an untested claim that reads like coverage (`.claude/rules/invariant-call-site-enumeration.md`
+ * #19, #25), and the next author would have reasonably assumed it was load-bearing. The N/A is
+ * stated here instead. If a primary key ever stops being hidden for display, this is the paragraph
+ * that has to be re-read.
+ *
+ * Note what is deliberately NOT tested: the field's TYPE. A boolean, a string, an enum and an array
+ * are all legitimately editable in place, and the display dispatcher already routes each to the
+ * right control (`DisplayFieldEditableArray` for arrays, the switch fast-path for booleans). Adding
+ * a type filter here would silently re-narrow what the layout author asked for.
+ */
+export function isEligibleForLayoutDefaultInlineEdit(schema) {
+    if (declinesInlineEdit(schema))
+        return false;
+    if (isExcludedFromUpdate(schema))
+        return false;
+    if (isHiddenForDisplay(schema))
+        return false;
+    return true;
 }
 /**
  * Get the resolved inline editable params from `{primitive}UI.display.inlineEditable`.
@@ -2907,7 +3815,11 @@ export function serializeZodSchema(schema, seen = new Set()) {
             const literalValues = (getZodDefArrayProperty(inner, 'values') ?? [getZodDefProperty(inner, 'value')])
                 .filter((entry) => entry !== undefined && entry !== null);
             const value = literalValues[0];
-            return withOptionals(withMeta({ type: 'literal', value }), optional, nullable);
+            // A multi-value literal (`z.literal(['a', 'b'])`) carries EVERY value it admits (#1106): serialized
+            // as `value: 'a'` alone it round-tripped as `z.literal('a')` and refused `b`. `value` stays the first
+            // entry for the single-value case every reader already understands; `values` is present only when
+            // there is more than one, and the deserializer prefers it.
+            return withOptionals(withMeta({ type: 'literal', value, ...(literalValues.length > 1 ? { values: literalValues } : {}) }), optional, nullable);
         }
         case 'enum': {
             // In Zod 4, both z.enum() and z.enum() use type 'enum'
@@ -3068,7 +3980,9 @@ export function deserializeZodSchema(desc) {
                 return applyOptionalNullable(s, d);
             }
             case 'literal': {
-                const s = applyMetadata(z.literal(d.value), d.metadata);
+                // `values` is the whole admitted set of a multi-value literal (#1106); `value` alone is a single one.
+                const literalValues = d.values;
+                const s = applyMetadata(z.literal((literalValues && literalValues.length > 1 ? literalValues : d.value)), d.metadata);
                 return applyOptionalNullable(s, d);
             }
             case 'enum': {