@wildo-ai/zod-decorators 1.0.1 → 1.1.0

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { ForeignKeyDisplayMode, FieldSchemaType, FormFieldComponent, RangeType, SCHEMA_METADATA, ZodDecorator } from './zod-decorators.types.js';
+import { 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 { 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
@@ -96,6 +97,238 @@ export function unwrapSchema(schema) {
             return schema;
     }
 }
+/**
+ * Make a field OPTIONAL for a PATCH-style UPDATE DTO, peeling any OUTER
+ * `.default()` wrapper first.
+ *
+ * PATCH semantics: a field the caller OMITS must be left untouched. A field
+ * declared `z.number().default(0)` breaks this — Zod re-materialises `0` for the
+ * absent key on every parse, so the derived `$set` silently CLOBBERS the stored
+ * value with the default. (Live defect: a webhook delivery row's `attemptCount`
+ * counter was reset to `0` by every status transition that did not set it, so
+ * the retry cap `attemptCount >= MAX_ATTEMPTS` was never reached and dead
+ * deliveries retried forever.)
+ *
+ * It is ALSO where the framework's field-CLEARING contract is admitted onto the wire. An optional
+ * field additionally gains a `.nullable()` wrapper here, so a caller can distinguish the two
+ * PATCH intents that an absent key alone cannot express:
+ *
+ * - key ABSENT  → leave the stored value untouched (classic PATCH semantics, above);
+ * - value NULL  → this field has no value (clear it).
+ *
+ * Eligibility is decided by `fieldAdmitsAddedNullClear` — notably NOT by `isOptional()`, which
+ * would wrongly admit `.default()` fields. Required fields keep rejecting `null`. The wrapper is
+ * added INSIDE the optional (`ZodOptional<ZodNullable<…>>`) so the outer type stays `optional` for
+ * every consumer that introspects it.
+ *
+ * Behaviour:
+ * - Non-default fields: `fieldSchema.optional()`, plus a `.nullable()` wrapper when the field is
+ *   optional and does not already accept null.
+ * - Default-wrapped fields: the outer `ZodDefault` is peeled, the inner schema
+ *   (keeping `.int()` / `.min()` / refinements) is made optional, and any
+ *   decorator metadata attached to the default wrapper (e.g.
+ *   `.default(0).isSummaryField()`) is carried onto the resulting optional so
+ *   `getMetadataRecursive` is unchanged. The inner schema is SHARED, never
+ *   mutated, so the source schema is left intact.
+ *
+ * Defaults remain correct for CREATE (a new row gets them) — this transform is
+ * for the UPDATE DTO only.
+ */
+export function toPatchOptionalField(fieldSchema) {
+    const admitsNullClear = fieldAdmitsAddedNullClear(fieldSchema);
+    if (!isZodDefault(fieldSchema)) {
+        return admitsNullClear ? fieldSchema.nullable().optional() : fieldSchema.optional();
+    }
+    const innerType = getZodDefSchemaProperty(fieldSchema, 'innerType');
+    if (!innerType)
+        return fieldSchema.optional();
+    // A defaulted field is never null-clearable (see `fieldAdmitsAddedNullClear`), so the peeled
+    // inner is made optional WITHOUT a nullable wrapper.
+    const optionalInner = innerType.optional();
+    const defaultWrapperMetadata = fieldSchema[SCHEMA_METADATA];
+    if (defaultWrapperMetadata) {
+        const optionalRecord = optionalInner;
+        const existing = optionalRecord[SCHEMA_METADATA] ?? {};
+        optionalRecord[SCHEMA_METADATA] = {
+            ...existing,
+            ...defaultWrapperMetadata,
+        };
+    }
+    return optionalInner;
+}
+/**
+ * The value an edit control should contribute to form state, once a "the user emptied this field"
+ * gesture has been normalised into the framework's single CLEARED representation.
+ *
+ * # Why a normalisation step has to exist at all
+ *
+ * An HTML form control cannot express "no value". The platform defines a form entry's value as a
+ * string (or a `File`), and assigning `null` to `input.value` is coerced to `""` at the DOM
+ * boundary. So a user clearing a text box produces `''`, a user clearing a date picker produces
+ * `undefined`, and neither of those is a wire representation of "clear this field". Left alone they
+ * produce three different wrong outcomes: `''` fails a refined schema outright (a colour or phone
+ * field could never be emptied once set), `''` passes a plain string schema and PERSISTS an empty
+ * string as a second, redundant "no data" value, and `undefined` is dropped by `JSON.stringify` so
+ * the clear silently never reaches the server at all.
+ *
+ * # What it normalises TO, and why not `undefined`
+ *
+ * Always `null`, never `undefined`. React Hook Form reserves `undefined` to mean "fall back to
+ * defaultValue" and documents that calling `onChange` with it is not valid, so `undefined` is not a
+ * representable field value there. `null` is the value RHF itself prescribes for a cleared field,
+ * and it is the one sentinel that survives every downstream seam: the submission path keeps it, the
+ * section-save path keeps it, and `JSON.stringify` keeps it.
+ *
+ * # Where this must be called
+ *
+ * At the ONE place a control's change reaches form state, before the value is handed to both the
+ * form library and the autosave queue. Normalising later (at submit) is too late — validation has
+ * already rejected the empty string — and normalising only for validation is the documented Formik
+ * defect, where the schema validates a value the server never receives.
+ *
+ * # What it deliberately leaves alone
+ *
+ * - **Fields that cannot be cleared** — a required field, or one whose declaration otherwise
+ *   rejects null. Their empty value is returned untouched so validation still fails with the normal
+ *   message rather than being silently rewritten.
+ * - **Password and OTP inputs** — an empty password box conventionally means "unchanged", never
+ *   "remove the credential". Removing a secret must be an explicit destructive action, not a blank
+ *   field.
+ * - **Any non-empty value**, including `0` and `false`, which are values rather than absences.
+ *
+ * # Two entry points, because the caller's schema decides the question
+ *
+ * A form validates the operation's REQUEST DTO; inline edit on a display surface only ever holds
+ * the resource's MAIN schema. Those two answer "can this be cleared?" differently and cannot be
+ * told apart by shape, so the caller picks the entry point matching what it holds — see
+ * `requestDtoFieldIsClearable` for why merging them is unsound. This is the REQUEST-DTO one.
+ *
+ * @param fieldSchema - the field as it appears on the operation's request DTO.
+ * @param value - the raw value the control emitted.
+ * @returns `null` when the gesture is a clear on a clearable field; otherwise `value` unchanged.
+ */
+export function normalizeClearedRequestDtoValue(fieldSchema, value) {
+    return normalizeClearedValue(fieldSchema, value, requestDtoFieldIsClearable);
+}
+/**
+ * `normalizeClearedFieldValue` for a caller holding the resource's MAIN schema — inline edit on a
+ * display surface, and any edit control reasoning about its own declared field.
+ *
+ * Same contract, different question asked of the schema. See `mainSchemaFieldIsClearable`.
+ */
+export function normalizeClearedMainSchemaValue(fieldSchema, value) {
+    return normalizeClearedValue(fieldSchema, value, mainSchemaFieldIsClearable);
+}
+function normalizeClearedValue(fieldSchema, value, isClearable) {
+    if (!isEmptyFieldGesture(value))
+        return value;
+    const editMode = getStringUI(fieldSchema)?.edit?.editMode;
+    if (editMode === StringEditMode.PASSWORD || editMode === StringEditMode.OTP)
+        return value;
+    if (!isClearable(fieldSchema))
+        return value;
+    return null;
+}
+/**
+ * Is "clear it" a meaningful instruction for this field, as declared on an UPDATE REQUEST DTO?
+ *
+ * On a request DTO the answer is exactly "does it accept null", because `toPatchOptionalField` adds
+ * a nullable wrapper to the clearable fields and to no others.
+ *
+ * **This must never be asked of a MAIN-schema field, and its sibling must never be asked of a DTO
+ * field.** The two schemas cannot be told apart by shape, and each answers only its own question
+ * correctly:
+ *
+ * - On a DTO, PATCH semantics make EVERY field optional, so a required field is shape-identical to
+ *   an optional one. "Declares absence" is therefore meaningless here and would report every
+ *   required field clearable.
+ * - On a main schema, an `.optional()` field does NOT accept null, so "accepts null" would report
+ *   every ordinary optional field un-clearable.
+ *
+ * Merging them into one permissive predicate looks convenient and is unsound in the first
+ * direction: it silently made required fields clearable, which a pin caught.
+ */
+export function requestDtoFieldIsClearable(fieldSchema) {
+    return fieldSchema.safeParse(null).success;
+}
+/**
+ * Is "clear it" a meaningful instruction for this field, as declared on a resource's MAIN schema?
+ *
+ * Here the author's own declaration is the answer: a field that may be absent (`.optional()`) or
+ * explicitly null (`.nullish()`) can be cleared; a required or defaulted one cannot. Read the
+ * warning on `requestDtoFieldIsClearable` before using either.
+ */
+export function mainSchemaFieldIsClearable(fieldSchema) {
+    return fieldSchema.safeParse(null).success || fieldAdmitsAddedNullClear(fieldSchema);
+}
+/**
+ * Is this value an edit control's way of saying "the user emptied me"?
+ *
+ * The three shapes are the three the framework's controls actually emit: `''` from the string,
+ * enum and number families, `undefined` from the date/time family, and `null` from a control that
+ * has already been normalised (so re-normalising is idempotent).
+ */
+function isEmptyFieldGesture(value) {
+    return value === '' || value === undefined || value === null;
+}
+/**
+ * Should an UPDATE DTO ADD a `.nullable()` wrapper to this field so a caller can CLEAR it?
+ *
+ * This is the eligibility half of the framework's field-clearing contract. The wire rule is
+ * JSON-Merge-Patch shaped and has exactly one meaning: an ABSENT key leaves the stored value
+ * untouched, and an explicit `null` means "this field has no value". The repository write boundary
+ * then derives the STORAGE representation from the field's own declaration — `$unset` / SQL NULL
+ * for a field whose schema rejects null, a stored null for one authored `.nullish()`.
+ *
+ * Three declarations must be told apart, and the distinction is not the one `isOptional()` draws:
+ *
+ * - **Optional (`.optional()`, `.nullish()`)** — the author said this field may have no value, so
+ *   clearing it is meaningful. ELIGIBLE.
+ * - **Required (`z.string()`)** — no "no value" state exists. NOT eligible: `null` must keep
+ *   failing validation, which is also what the industry guidance prescribes (a field that cannot be
+ *   deleted answers 400 rather than silently ignoring the instruction).
+ * - **Defaulted (`.default('x')`)** — `isOptional()` reports TRUE for these because the *input* may
+ *   be omitted, but the *output* type is non-optional: the schema guarantees a value is always
+ *   present, and the READ path validates against that guarantee. Clearing one would persist an
+ *   absence the resource's own main schema rejects, turning the next read into a 500. NOT eligible,
+ *   and this is precisely why this predicate exists instead of reusing `isOptional()`.
+ *
+ * A field that ALREADY accepts null (authored `.nullable()` / `.nullish()`) is reported `false` —
+ * not because it cannot be cleared, but because nothing needs adding: it accepts `null` on its own,
+ * and re-wrapping would emit a redundant nullable in the generated JSON Schema / OpenAPI document.
+ *
+ * @param fieldSchema - the field as declared on the resource's main schema.
+ * @returns `true` only when a nullable wrapper must be ADDED for the field to be clearable.
+ */
+export function fieldAdmitsAddedNullClear(fieldSchema) {
+    // A default makes the OUTPUT non-optional — see the JSDoc above. Checked first because
+    // `ZodDefault` wraps an inner schema that is frequently optional-looking.
+    if (isZodDefault(fieldSchema))
+        return false;
+    if (!declaresAbsenceAsAValidState(fieldSchema))
+        return false;
+    // Already null-accepting (`.nullable()` / `.nullish()`): clearable without any addition.
+    return !fieldSchema.safeParse(null).success;
+}
+/**
+ * Does this field's declaration allow the value to be ABSENT (i.e. accept `undefined`)?
+ *
+ * Deliberately NOT `isOptional()`: that helper answers "may the user omit this input?", which is
+ * true for `.default()` fields, whereas this answers "may this field legitimately hold no value?",
+ * which is false for them. Merging the two is what would make a defaulted field clearable.
+ */
+function declaresAbsenceAsAValidState(fieldSchema) {
+    if (isZodDefault(fieldSchema))
+        return false;
+    if (isZodOptional(fieldSchema))
+        return true;
+    const type = getZodType(fieldSchema);
+    if (type === 'nullable' || type === 'pipe' || type === 'readonly' || type === 'catch') {
+        const innerSchema = getZodDefSchemaProperty(fieldSchema, 'innerType') ?? getZodDefSchemaProperty(fieldSchema, 'in');
+        return innerSchema ? declaresAbsenceAsAValidState(innerSchema) : false;
+    }
+    return false;
+}
 // =============================================================================
 // ZOD TYPE DETECTION HELPERS
 //
@@ -132,6 +365,39 @@ export function isZodObject(schema) {
 export function isZodArray(schema) {
     return hasZodType(schema, 'array');
 }
+/**
+ * The same array schema with a different ELEMENT, keeping everything else it carries.
+ *
+ * Use this instead of `z.array(newElement)` whenever an existing array is being rewritten.
+ * A fresh `z.array()` is a brand-new schema that carries none of the original's own checks, so
+ * every authored `.min()` / `.max()` / `.length()` / `.nonempty()` is silently dropped — the
+ * rewritten schema still parses, just without the constraint the author declared. That is
+ * invisible to types and to any test that only feeds it valid data.
+ *
+ * It cost real time to find: all FOUR DTO-boundary walkers (templatable-file stripping,
+ * network-boundary coercion, backend-only stripping, summary-field extraction) rebuilt arrays this
+ * way, so an authored array constraint never reached the schema the controller and the repository
+ * 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.
+ *
+ * @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.
+ * @param element - the replacement element schema.
+ */
+export function withArrayElement(arraySchema, element) {
+    if (!isZodArray(arraySchema)) {
+        return arraySchema;
+    }
+    const def = arraySchema._zod?.def;
+    if (!def) {
+        return arraySchema;
+    }
+    return arraySchema.clone({ ...def, element });
+}
 export function isZodOptional(schema) {
     return hasZodType(schema, 'optional');
 }
@@ -421,6 +687,39 @@ export function getZodObjectShape(schema) {
     const shape = getObjectShape(schema);
     return shape ?? {};
 }
+/**
+ * Field shape of an object schema OR a discriminated union, merged across ALL
+ * variants. Unlike {@link getZodObjectShape} (which returns `{}` for a union),
+ * this walks the union's variant options and merges their shapes, so callers that
+ * need the full field set of a polymorphic resource — FK/ObjectId discovery,
+ * field-access checks, etc. — see every variant's fields instead of nothing.
+ *
+ * For a field present in multiple variants the FIRST occurrence wins (variants
+ * share the common base fields, so the common shape is identical across them).
+ * Returns `{}` for non-object, non-union schemas.
+ */
+export function getMergedObjectOrUnionShape(schema) {
+    if (isZodObject(schema)) {
+        return getZodObjectShape(schema);
+    }
+    if (isDiscriminatedUnion(schema)) {
+        const options = getZodDefArrayProperty(schema, 'options');
+        if (!options) {
+            return {};
+        }
+        const merged = {};
+        for (const option of options) {
+            const optionShape = isZodObject(option) ? getZodObjectShape(option) : {};
+            for (const [fieldName, fieldSchema] of Object.entries(optionShape)) {
+                if (!(fieldName in merged)) {
+                    merged[fieldName] = fieldSchema;
+                }
+            }
+        }
+        return merged;
+    }
+    return {};
+}
 export function getZodDef(schema) {
     if (!hasZodInternals(schema))
         return undefined;
@@ -536,6 +835,31 @@ export function getFieldUIDisplayConfig(schema) {
     }
     return undefined;
 }
+/**
+ * Display-context base params resolved for the SUMMARY context (cards, list
+ * items, FK reference previews): `summaryOverride` merged over `display`,
+ * key-by-key. A field with no `summaryOverride` behaves exactly as in the
+ * regular display context.
+ *
+ * Summary renderers (the `ResourceSummaryDisplayer` pipeline) call this instead
+ * of {@link getFieldUIDisplayConfig}; everything else keeps reading the plain
+ * display params. The same merge convention applies to the primitive-specific
+ * params (`getEnumUI(s)` consumers merge `{...ui.display, ...ui.summaryOverride}`
+ * when rendering a summary surface).
+ */
+export function getFieldUISummaryDisplayConfig(schema) {
+    const metadata = getCustomFieldMetadata(schema);
+    for (const key of UI_DECORATOR_KEYS) {
+        const params = metadata[key];
+        if (params && typeof params === 'object' && ('display' in params || 'summaryOverride' in params)) {
+            const typed = params;
+            if (!typed.display && !typed.summaryOverride)
+                return undefined;
+            return { ...typed.display, ...typed.summaryOverride };
+        }
+    }
+    return undefined;
+}
 // =============================================================================
 // TOOLTIP DECORATOR UTILITIES
 // =============================================================================
@@ -813,6 +1137,40 @@ function stripZodInternalKeys(shape) {
  *
  * If the schema is wrapped (e.g., with .default()), it will be unwrapped first.
  */
+/**
+ * Resolve ONE field's declared schema from an object-like root, seeing through a discriminated
+ * union.
+ *
+ * `getObjectShape()` deliberately returns `null` for a union, which is correct for its own contract
+ * but useless to a caller that only needs to ask a question about a single named field. Polymorphic
+ * resources (`createSchemaFamily` output) present exactly that shape, so a caller using
+ * `getObjectShape()` alone silently answers "field unknown" for every field of every polymorphic
+ * resource — the failure mode that once left polymorphic form fields unlabelled.
+ *
+ * Union handling returns the FIRST variant that declares the name. Variants of one resource family
+ * share a field's declaration for any field they have in common, so the first match is
+ * representative; a caller needing per-variant precision must narrow the union itself first.
+ *
+ * @param schema - object, or discriminated union of objects (wrappers are unwrapped).
+ * @param fieldName - top-level field name.
+ * @returns the field's declared schema, or `undefined` when no variant declares it.
+ */
+export function getObjectLikeFieldSchema(schema, fieldName) {
+    const directShape = getObjectShape(schema);
+    if (directShape)
+        return directShape[fieldName];
+    const unwrapped = unwrapSchema(schema);
+    if (!isZodUnion(unwrapped))
+        return undefined;
+    const options = getZodDefArrayProperty(unwrapped, 'options') ?? [];
+    for (const option of options) {
+        const optionShape = getObjectShape(option);
+        const fieldSchema = optionShape?.[fieldName];
+        if (fieldSchema)
+            return fieldSchema;
+    }
+    return undefined;
+}
 export function getObjectShape(schema) {
     const unwrapped = unwrapSchema(schema);
     if (getZodType(unwrapped) !== 'object') {
@@ -1117,7 +1475,11 @@ export function getForeignKeyParams(schema) {
 }
 /**
  * Get FK UI display params from `FOREIGN_KEY_UI.display`. Returns mode, linkable, displayPresetOverride.
- * Falls back to default `mode: LABEL` if the FK exists but has no explicit UI config.
+ *
+ * When the FK exists but authors no explicit `display` config, `mode` falls back to
+ * {@link DEFAULT_FOREIGN_KEY_DISPLAY_MODE} — the single source for that default. Do not
+ * restate a `ForeignKeyDisplayMode` member here: a second declaration of the
+ * default is how this surface and the display preset came to disagree.
  */
 export function getForeignKeyUIDisplay(schema) {
     if (!isForeignKeyField(schema))
@@ -1125,7 +1487,7 @@ export function getForeignKeyUIDisplay(schema) {
     const metadata = getCustomFieldMetadata(schema);
     const uiParams = metadata[ZodDecorator.FOREIGN_KEY_UI];
     const display = uiParams?.display;
-    return { mode: ForeignKeyDisplayMode.LABEL, ...display };
+    return { mode: DEFAULT_FOREIGN_KEY_DISPLAY_MODE, ...display };
 }
 /**
  * Get the polymorphic variants from a foreign key field.
@@ -1135,6 +1497,29 @@ export function getPolymorphicFkVariants(schema) {
     const params = getForeignKeyParams(schema);
     return params?.polymorphicVariants;
 }
+/**
+ * Resolve the per-record DISCRIMINATED polymorphic FK declaration, if any.
+ *
+ * Returns `{ discriminatorField, variants }` only when the FK is a single
+ * SHARED field pointing at a polymorphic branch group — i.e. BOTH a
+ * `polymorphicDiscriminatorField` AND at least one `polymorphicVariants` entry
+ * are declared. Returns `undefined` for plain FKs and for rename-only
+ * polymorphic FKs (variants present, no discriminator field).
+ *
+ * Consumers (registry FK→type map builders, FK display/link resolution) use
+ * this as the signal that the FK resolves to a different branch PER RECORD: the
+ * holder record's `discriminatorField` value is matched against each variant's
+ * `discriminatorValue` to pick the branch. See
+ * {@link ForeignKeyStructuralParams.polymorphicDiscriminatorField}.
+ */
+export function getDiscriminatedPolymorphicForeignKey(schema) {
+    const params = getForeignKeyParams(schema);
+    const discriminatorField = params?.polymorphicDiscriminatorField;
+    const variants = params?.polymorphicVariants;
+    if (!discriminatorField || !variants || variants.length === 0)
+        return undefined;
+    return { discriminatorField, variants };
+}
 /**
  * Check if a schema field is a foreign key (recursive traversal through wrappers).
  */
@@ -1182,11 +1567,171 @@ export function getBackendOnlyParams(schema) {
     return value;
 }
 /**
- * Check if a field has auditAccess enabled via `.isBackendOnly({ auditAccess: true })`.
- * Fields with this flag generate FIELD_ACCESS audit events when included in API responses.
+ * Check if a schema field has the isWriteOnlySecret decorator.
+ */
+export function isWriteOnlySecretField(schema) {
+    const metadata = getMetadataRecursive(schema);
+    return metadata?.[ZodDecorator.IS_WRITE_ONLY_SECRET] !== undefined;
+}
+/**
+ * Read a field's stored impersonalization params, declared via the fluent
+ * `.impersonalizeWith(treatment, options?)` method or the equivalent
+ * `addImpersonalizeWith(schema, treatment, options?)` helper.
+ *
+ * Reads through wrapper types (`getMetadataRecursive` walks outer → inner), so it observes the
+ * declaration whether it was made before or after `.optional()` / `.nullable()` / `.nullish()` /
+ * `.default()`. This matters because the retention guards `safeParse` the OUTER wrapper, and
+ * treatments are commonly declared on `.nullish()` fields (`REMOVE` writes `null`).
+ *
+ * The decorator chokepoint normalizes both authoring forms to the params object, so the stored
+ * value is always an object. The bare-string branch below is a defensive read for metadata written
+ * by any path that bypassed the chokepoint — it keeps a legal treatment legible rather than
+ * silently reading as UNTREATED, which is the PII-leak failure mode this decorator exists to
+ * prevent.
+ */
+/**
+ * Read a field's declared portability provenance — where its value came from — set via the fluent
+ * `.portabilityProvenance(provenance)` method or `addPortabilityProvenance(schema, provenance)`.
+ *
+ * Returns the raw string; the saas-models layer types it as `DataPortabilityProvenance`
+ * (zod-decorators sits below saas-models and cannot import the enum).
+ *
+ * Reads through wrapper types (`getMetadataRecursive` walks outer → inner), so it observes the
+ * declaration whether it was made before or after `.optional()` / `.nullable()` / `.nullish()` /
+ * `.default()` — the same wrapper-transparency `getImpersonalizeTreatment` needs, and for the same
+ * reason: personal-data fields are commonly optional.
+ *
+ * `undefined` means the field carries NO declaration of its own. That is not an error — the field
+ * inherits its resource's `portabilityPolicy.defaultProvenance`, and only if THAT is absent too
+ * does an Art. 20 export refuse. Resolving that fallback chain belongs to the resource factory,
+ * which knows the resource; this reader answers only "did the field itself say?".
+ */
+export function getPortabilityProvenance(schema) {
+    const metadata = getMetadataRecursive(schema);
+    const value = metadata?.[ZodDecorator.PORTABILITY_PROVENANCE];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * WHICH KINDS of personal data does this field hold? Returns the declared `PersonalDataCategory`
+ * values (as opaque strings — this package sits below `saas-models` and cannot import the enum),
+ * or `undefined` when the field carries no declaration.
+ *
+ * Set via the fluent `.dataCategories(...)` method or `addDataCategories(schema, ...)`. Always an
+ * ARRAY, deduped and non-empty: the decorator chokepoint normalizes a single-value authoring form
+ * on the way in, so a caller never has to handle two shapes.
+ *
+ * Reads through wrapper types (`getMetadataRecursive` walks outer → inner), so it observes the
+ * declaration whether it was written before or after `.optional()` / `.nullable()` / `.nullish()` /
+ * `.default()`. An optional field is the common shape for exactly the data a notice enumerates, so
+ * a reader that missed the wrapper would under-report — the silent direction.
+ *
+ * `undefined` is the correct and common answer: most fields hold no personal data and carry no
+ * declaration. It is ABSENCE, not an empty array, that the compliance gap report reads — the
+ * chokepoint refuses to store an empty declaration for that reason.
+ *
+ * @wildo_source:part:start zod.decorators.data-categories facet:layer:shared facet:family:decorator facet:kind:api facet:audience:app-developer
+ */
+export function getDataCategories(schema) {
+    const metadata = getMetadataRecursive(schema);
+    const value = metadata?.[ZodDecorator.DATA_CATEGORIES];
+    return Array.isArray(value) && value.length > 0 ? value : undefined;
+}
+/** @wildo_source:part:end zod.decorators.data-categories */
+/**
+ * Is this field's VALUE recorded on the resource-operation audit event when an operation changes
+ * it? Set via the fluent `.isAuditEvidence()` method or `addAuditEvidence(schema)`.
+ *
+ * Reads through wrapper types (`getMetadataRecursive` walks outer → inner), so it observes the
+ * marker whether it was declared before or after `.optional()` / `.nullable()` / `.nullish()` /
+ * `.default()`. That matters here in both directions: a nullable `suspendedUntil` is exactly the
+ * kind of lifecycle field worth marking, and a marker the reader missed would silently drop the
+ * evidence rather than fail.
+ *
+ * `false` is the correct and common answer — the audit event still records that the field CHANGED
+ * (by name); only its before/after VALUES are withheld. Withholding is the default on purpose:
+ * audit rows reach the immutable ledger, which cannot be scrubbed.
+ *
+ * ⚠️ This is the WRITE-side question. The READ-side one ("was this value disclosed?") is answered
+ * only by `isBackendOnly({ isReturnedAtCreation: true })`, which fires a `FIELD_ACCESS` event when a
+ * server-minted secret is first exposed. The two are independent claims; neither implies the other.
  */
-export function isAuditAccessField(schema) {
-    return getBackendOnlyParams(schema)?.auditAccess === true;
+export function isAuditEvidenceField(schema) {
+    const metadata = getMetadataRecursive(schema);
+    return metadata?.[ZodDecorator.IS_AUDIT_EVIDENCE] === true;
+}
+function getImpersonalizeParams(schema) {
+    const metadata = getMetadataRecursive(schema);
+    const value = metadata?.[ZodDecorator.IMPERSONALIZE_WITH];
+    if (typeof value === 'string')
+        return { treatment: value };
+    if (value !== null && typeof value === 'object' && typeof value.treatment === 'string') {
+        return value;
+    }
+    return undefined;
+}
+/**
+ * Get a field's impersonalization scrub treatment (a `RedactionType` value). Returns the raw
+ * string; the saas-models layer types it as `RedactionType` (zod-decorators is below saas-models
+ * and cannot import it). `undefined` means the field carries no treatment and is left intact.
+ */
+export function getImpersonalizeTreatment(schema) {
+    return getImpersonalizeParams(schema)?.treatment;
+}
+/**
+ * @wildo_source:part:start zod.decorators.rag-source facet:layer:shared facet:family:decorator facet:kind:api facet:audience:app-developer
+ *
+ * Read a field's stored RAG-source configuration, declared via the fluent `.ragSource(config?)`
+ * method, the `addRagSource(schema, config?)` helper, or `z_file({ ragSource })`.
+ *
+ * Import from `@wildo-ai/zod-decorators`. Use it in custom implementations or checks that need to
+ * ask "is this field part of the retrieval corpus?" — never to re-derive the corpus itself, which
+ * the framework already does.
+ *
+ * `undefined` means the field is NOT a retrieval-corpus source — presence of the returned object is
+ * the declaration itself (there is no `enabled` flag), and a bare `.ragSource()` reads back as `{}`
+ * because the decorator chokepoint normalizes an omitted config to the empty object.
+ *
+ * Reads through wrapper types (`getMetadataRecursive` walks outer → inner), so it observes the
+ * declaration whether it was made before or after `.optional()` / `.nullable()` / `.nullish()` /
+ * `.default()` — corpus-source fields (descriptions, knowledge bodies) are routinely optional.
+ * This is the ONE detection door: `RagSourceFieldDetection` in the backend walks resource schemas
+ * with it, uniformly for plain string fields and `z_file()` fields.
+ */
+export function getRagSourceConfig(schema) {
+    const metadata = getMetadataRecursive(schema);
+    // Typed as the normalized object, but read defensively as `unknown`: metadata written by any
+    // path that bypassed the chokepoint's normalization (a raw `true` sentinel) must still read as
+    // "declared, default config" rather than silently reading as NOT-a-source, which would drop the
+    // field from every downstream seam (detection, chunk store, erasure).
+    const value = metadata?.[ZodDecorator.RAG_SOURCE];
+    if (value === undefined || value === null || value === false)
+        return undefined;
+    return typeof value === 'object' ? value : {};
+}
+/** @wildo_source:part:end zod.decorators.rag-source */
+/**
+ * Get a field's `MASK` override value — the literal written in place of the field, instead of the
+ * framework mask constant. `undefined` means "use the constant".
+ *
+ * Authored for CONSTRAINED string fields (`z.email()`, `z.uuid()`, `.min(n)`) that the default
+ * constant cannot satisfy. See {@link ImpersonalizeFieldParams} for the contract; the saas-models
+ * boot guard validates the value against the field's own schema and rejects it on a non-`MASK`
+ * treatment.
+ */
+export function getImpersonalizeMaskValue(schema) {
+    return getImpersonalizeParams(schema)?.maskValue;
+}
+/**
+ * Get the isWriteOnlySecret decorator parameters.
+ */
+export function getWriteOnlySecretParams(schema) {
+    const metadata = getMetadataRecursive(schema);
+    const value = metadata?.[ZodDecorator.IS_WRITE_ONLY_SECRET];
+    if (value === undefined)
+        return undefined;
+    if (value === true)
+        return {}; // Default params when decorator is used without params
+    return value;
 }
 /**
  * Check if a schema field has the isDiscriminator decorator.
@@ -1288,6 +1833,55 @@ export function isPrimaryKeyField(schema) {
     const metadata = getMetadataRecursive(schema);
     return metadata?.[ZodDecorator.IS_PRIMARY_KEY] === true;
 }
+// =============================================================================
+// BUSINESS KEY HELPERS (data-seeding subsystem)
+// =============================================================================
+/**
+ * Check if a schema field has the `isBusinessKey` decorator (recursive
+ * traversal through wrappers — `optional`, `nullable`, etc.).
+ *
+ * A business key is the **declaration-side identity** used by the data-seeding
+ * subsystem to upsert / upgrade / sync seeded rows independently from the
+ * random `_id` (`isPrimaryKey`). See `.cursor/plans/seeding-first-class.md`
+ * §3.3 for the semantic contract.
+ */
+export function isBusinessKeyField(schema) {
+    const metadata = getMetadataRecursive(schema);
+    return metadata?.[ZodDecorator.IS_BUSINESS_KEY] === true;
+}
+/**
+ * Read the composite business key declared on an object schema via
+ * `businessKeySet([...])` (object-level decorator). Returns the ordered
+ * list of field names, or `undefined` if no composite key is declared.
+ *
+ * The composite key is the schema-level analog of `isBusinessKey` — used
+ * when identity is `(orgId, templateKey)` rather than a single field. See
+ * `.cursor/plans/seeding-first-class.md` §3.3.
+ */
+export function getBusinessKeySet(schema) {
+    return getBusinessKeySetParams(schema)?.fields;
+}
+/**
+ * Read the FULL composite-business-key declaration, not just its field list.
+ *
+ * `getBusinessKeySet` answers "what identifies a row" and is all the seeding filter builder needs.
+ * The storage adapter needs more: which members take a row out of the constraint when absent
+ * (`skipRowsMissing`), and which error the API should raise when the resulting index is violated
+ * (`conflictMessageReference`). Both are properties OF the key, so they are read from the same
+ * declaration rather than re-derived — a second source would be free to disagree with the first.
+ */
+export function getBusinessKeySetParams(schema) {
+    const metadata = getMetadataRecursive(schema);
+    const params = metadata?.[ZodDecorator.OBJECT_BUSINESS_KEY_SET];
+    return params?.fields ? params : undefined;
+}
+/**
+ * Convenience predicate: does the schema declare any business key
+ * identity (single field-level marker OR composite object-level set)?
+ */
+export function hasBusinessKey(schema) {
+    return isBusinessKeyField(schema) || getBusinessKeySet(schema) !== undefined;
+}
 /**
  * Get all metadata for a schema field (non-recursive, direct access only).
  */
@@ -1594,6 +2188,17 @@ export function isFileSchema(schema) {
     }
     return false;
 }
+/**
+ * Check if a file schema is generated from a backend-bound PDF template.
+ *
+ * This helper intentionally keys off frontend-safe metadata only. Runtime
+ * template objects are bound later by backend resource configuration and must
+ * not leak into shared schema metadata.
+ */
+export function isTemplatableFileField(schema) {
+    const fileMetadata = getFileMetadata(schema);
+    return fileMetadata?.generation?.source === FileGenerationSource.PDF_TEMPLATE;
+}
 /**
  * Get file schema metadata if this is a file schema.
  * Checks both the schema directly and the unwrapped inner schema.
@@ -2145,7 +2750,17 @@ export function serializeZodSchema(schema, seen = new Set()) {
         case 'unknown':
             return withOptionals(withMeta({ type: 'unknown' }), optional, nullable);
         case 'literal': {
-            const value = getZodDefProperty(inner, 'value');
+            // In Zod 4 a literal's value lives in def.values (an ARRAY — z.literal(['a','b'])
+            // is legal in v4); the legacy Zod-3 def.value is always undefined in v4. Reading
+            // def.value alone emitted { type: 'literal', value: undefined } for EVERY literal,
+            // which then round-tripped through deserializeZodSchema as z.literal(undefined).
+            // Read def.values first, fall back to def.value, and take the first non-nullish
+            // entry — preserving string/number/boolean literals. (A bare z.literal(null) has no
+            // non-nullish entry and legitimately serializes as value: undefined.) Mirrors the
+            // Zod-4 literal read in zod-to-mongoose-schema-convertor.backend.service.ts.
+            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);
         }
         case 'enum': {
@@ -2644,4 +3259,4 @@ export function getObjectUI(schema) {
 export function hasObjectUI(schema) {
     return hasDecorator(schema, ZodDecorator.OBJECT_UI);
 }
-//# sourceMappingURL=zod-utils.shared.js.map
+//# sourceMappingURL=zod-utils.shared.js.map