@wildo-ai/zod-decorators 1.0.0 → 1.1.0

package/dist/esm/zod-decorators.types.d.ts

@@ -1,10 +1,22 @@
 import type { ComponentType } from 'react';
-import { ViewportBreakpoint } from './commons.js';
-import { AvailableCurrency, CurrencyAllowed } from './currencies.shared.schemas.js';
+import type { CountryCode as LibPhoneNumberCountryCode } from 'libphonenumber-js';
+import { ViewportBreakpoint } from './commons';
+import { AvailableCurrency, CurrencyAllowed } from './currencies.shared.schemas';
 import { z } from 'zod';
-import { DecoratedPrimitiveZodType } from './zod.module-override.js';
-import { ZodBrandedColorInstance } from './zod-color.js';
+import { DecoratedPrimitiveZodType } from './zod.module-override';
+import { ZodBrandedColorInstance } from './zod-color';
+/**
+ * @wildo_source:part:start zod.decorators.schema-metadata
+ *
+ * Internal metadata key used by Wildo's schema decorators.
+ *
+ * Application schemas obtain this metadata by using the supported decorators
+ * and schema factories from `@wildo-ai/zod-decorators`; application code must
+ * not write this symbol directly. `Symbol.for()` keeps independently loaded
+ * package copies interoperable while the framework reads the schema contract.
+ */
 export declare const SCHEMA_METADATA: symbol;
+/** @wildo_source:part:end zod.decorators.schema-metadata */
 export declare enum FieldSchemaType {
     STRING = "string",// String schemas (z.string)
     NUMBER = "number",// Number schemas (z.number, z.int)
@@ -57,6 +69,81 @@ export declare enum FormFieldComponent {
     DURATION = "duration",// Duration input (value + unit selector)
     PHONE = "phone"
 }
+/**
+ * Official HTML autocomplete field identifiers.
+ * Excludes `section-*`, `on`, and `off` because the decorator contract here is
+ * focused on typed semantic field tokens rather than raw form-level switches.
+ */
+export declare enum AutocompleteFieldIdentifier {
+    NAME = "name",
+    HONORIFIC_PREFIX = "honorific-prefix",
+    GIVEN_NAME = "given-name",
+    ADDITIONAL_NAME = "additional-name",
+    FAMILY_NAME = "family-name",
+    HONORIFIC_SUFFIX = "honorific-suffix",
+    NICKNAME = "nickname",
+    USERNAME = "username",
+    NEW_PASSWORD = "new-password",
+    CURRENT_PASSWORD = "current-password",
+    ONE_TIME_CODE = "one-time-code",
+    ORGANIZATION_TITLE = "organization-title",
+    ORGANIZATION = "organization",
+    STREET_ADDRESS = "street-address",
+    ADDRESS_LINE_1 = "address-line1",
+    ADDRESS_LINE_2 = "address-line2",
+    ADDRESS_LINE_3 = "address-line3",
+    ADDRESS_LEVEL_4 = "address-level4",
+    ADDRESS_LEVEL_3 = "address-level3",
+    ADDRESS_LEVEL_2 = "address-level2",
+    ADDRESS_LEVEL_1 = "address-level1",
+    COUNTRY = "country",
+    COUNTRY_NAME = "country-name",
+    POSTAL_CODE = "postal-code",
+    CC_NAME = "cc-name",
+    CC_GIVEN_NAME = "cc-given-name",
+    CC_ADDITIONAL_NAME = "cc-additional-name",
+    CC_FAMILY_NAME = "cc-family-name",
+    CC_NUMBER = "cc-number",
+    CC_EXP = "cc-exp",
+    CC_EXP_MONTH = "cc-exp-month",
+    CC_EXP_YEAR = "cc-exp-year",
+    CC_CSC = "cc-csc",
+    CC_TYPE = "cc-type",
+    TRANSACTION_CURRENCY = "transaction-currency",
+    TRANSACTION_AMOUNT = "transaction-amount",
+    LANGUAGE = "language",
+    BDAY = "bday",
+    BDAY_DAY = "bday-day",
+    BDAY_MONTH = "bday-month",
+    BDAY_YEAR = "bday-year",
+    SEX = "sex",
+    URL = "url",
+    PHOTO = "photo",
+    TEL = "tel",
+    TEL_COUNTRY_CODE = "tel-country-code",
+    TEL_NATIONAL = "tel-national",
+    TEL_AREA_CODE = "tel-area-code",
+    TEL_LOCAL = "tel-local",
+    TEL_LOCAL_PREFIX = "tel-local-prefix",
+    TEL_LOCAL_SUFFIX = "tel-local-suffix",
+    TEL_EXTENSION = "tel-extension",
+    EMAIL = "email",
+    IMPP = "impp"
+}
+/**
+ * Official non-`section-*` HTML autocomplete modifiers.
+ * Rendering code is responsible for placing them in spec order.
+ */
+export declare enum AutocompleteModifier {
+    SHIPPING = "shipping",
+    BILLING = "billing",
+    HOME = "home",
+    WORK = "work",
+    MOBILE = "mobile",
+    FAX = "fax",
+    PAGER = "pager",
+    WEBAUTHN = "webauthn"
+}
 /**
  * Chrome layout mode for display context (detail/read-only views).
  * Controls how the field wrapper (label, value, description) is arranged.
@@ -64,6 +151,13 @@ export declare enum FormFieldComponent {
 export declare const DisplayChromeMode: {
     /** Label above, value below, description below value (default). */
     readonly STACKED: "stacked";
+    /**
+     * Label + description inline-start, value inline-end (settings page style).
+     * The read-mode counterpart of `EditChromeMode.SETTINGS_ROW` — pairing the two
+     * keeps a view→edit drill (e.g. inside the Settings Hub) visually coherent: the
+     * value sits where its control will appear.
+     */
+    readonly SETTINGS_ROW: "settings_row";
     /** Label and value on the same line. */
     readonly INLINE: "inline";
     /** No label/description, just value (dense mode). */
@@ -75,8 +169,6 @@ export type DisplayChromeMode = typeof DisplayChromeMode[keyof typeof DisplayChr
 /**
  * Chrome layout mode for edit context (forms).
  * Superset of DisplayChromeMode with form-specific modes (SETTINGS_ROW, RELAXED).
- *
- * Also exported as `FormFieldChromeMode` for backward compatibility.
  */
 export declare const EditChromeMode: {
     /** Label above, control below, description + error below control (default). */
@@ -93,23 +185,6 @@ export declare const EditChromeMode: {
     readonly HIDDEN: "hidden";
 };
 export type EditChromeMode = typeof EditChromeMode[keyof typeof EditChromeMode];
-/** @deprecated Use `EditChromeMode` directly. Kept as alias for backward compatibility. */
-export declare const FormFieldChromeMode: {
-    /** Label above, control below, description + error below control (default). */
-    readonly STACKED: "stacked";
-    /** Label + description left, control + error right (settings page style). */
-    readonly SETTINGS_ROW: "settings_row";
-    /** Control left, label + description right (switch/checkbox style). */
-    readonly INLINE: "inline";
-    /** Generous spacing, heading-size label (onboarding, OTP, wizard). */
-    readonly RELAXED: "relaxed";
-    /** No label/description, just control + error (dense mode). */
-    readonly COMPACT: "compact";
-    /** No chrome at all — bare control output. */
-    readonly HIDDEN: "hidden";
-};
-/** @deprecated Use `EditChromeMode` directly. */
-export type FormFieldChromeMode = EditChromeMode;
 /**
  * Responsive chrome mode — either a single mode or per-breakpoint mapping.
  * When a breakpoint mapping is provided, FormFieldChrome resolves the effective
@@ -264,6 +339,22 @@ export declare enum HorizontalAlign {
     CENTER = "center",
     END = "end"
 }
+/**
+ * @wildo_source:part:start zod.decorators.display-edit-modes facet:layer:frontend facet:family:ui facet:surface:form facet:surface:display
+ *
+ * Frontend UI vocabulary for choosing how a field renders and edits.
+ *
+ * These values are not the persisted resource semantics themselves. They are
+ * consumed by the frontend resource UI behavior layer, typically in
+ * files like `frontend/src/modules/<module>/resources/<resource>/<resource>.ui-behavior.tsx`, where the AI
+ * calls decorators like `.stringUI()`, `.enumUI()`, `.booleanUI()`, etc. on the
+ * schema shape exposed to `resourceUIBehavior(...)`.
+ *
+ * Keep these mode enums in the framework source as the canonical list of
+ * supported display/edit behaviors. Authoring skills and generated knowledge
+ * should reference these definitions instead of copying literal mode tables
+ * into markdown by hand.
+ */
 /**
  * Labelling values for boolean fields
  */
@@ -301,6 +392,16 @@ export declare const StringDisplayMode: {
     readonly TEXT: "text";
     readonly TRUNCATE: "truncate";
     readonly MULTILINE: "multiline";
+    /**
+     * Render the value as rich markdown (GFM: headings, lists, tables, links,
+     * task lists, fenced code). For long-form authored content — descriptions,
+     * notes, documentation fields. Headings are demoted for embedded context
+     * (a `#` inside a field body never competes with the page title) and every
+     * element is styled through the active theme's typography recipes. Pair
+     * with `edit.editMode: MARKDOWN` (syntax-tinted source editor) — or plain
+     * `TEXTAREA` — the edit side stays markdown SOURCE either way.
+     */
+    readonly MARKDOWN: "markdown";
     readonly COLOR: "color";
     readonly LINK: "link";
     readonly EMAIL: "email";
@@ -318,6 +419,14 @@ export declare const StringEditMode: {
     readonly COLOR: "color";
     readonly PASSWORD: "password";
     readonly OTP: "otp";
+    /**
+     * Markdown SOURCE editor (CodeMirror-backed, syntax-tinted, theme-token
+     * styled). The stored value stays plain markdown source — display-side
+     * rendering remains owned by `StringDisplayMode.MARKDOWN` (Streamdown).
+     * This is deliberately NOT a WYSIWYG mode; a rich visual editor is a
+     * separate future edit mode/component.
+     */
+    readonly MARKDOWN: "markdown";
 };
 export type StringEditMode = typeof StringEditMode[keyof typeof StringEditMode];
 /**
@@ -369,7 +478,10 @@ export declare const BigDecimalEditMode: {
     readonly INPUT: "input";
 };
 export type BigDecimalEditMode = typeof BigDecimalEditMode[keyof typeof BigDecimalEditMode];
+/** @wildo_source:part:end zod.decorators.display-edit-modes */
 /**
+ * @wildo_source:part:start zod.decorators.enums.frontend-handling facet:layer:frontend facet:layer:shared facet:family:enum facet:family:ui facet:surface:form facet:surface:display
+ *
  * Enum display modes for rendering enum values
  */
 export declare const EnumDisplayMode: {
@@ -438,14 +550,16 @@ export interface EnumValueDisplayConfig {
     /** Icon for this enum value — React component or StandardIconReference string */
     icon?: IconLike;
 }
+/** @wildo_source:part:end zod.decorators.enums.frontend-handling */
 /**
  * Updater function accepted by any decorator with object params.
  *
  * Receives the current metadata value (or `undefined` if no prior decorator
  * or if the prior value is the `true` boolean shorthand). Returns the new value.
  *
- * For `{primitive}UI` decorators, the updater bypasses the
- * normal merge behavior — the returned value replaces entirely.
+ * For mergeable primitive decorators (`{primitive}UI()` and `{primitive}Spec()`),
+ * the updater bypasses the normal deep-merge behavior — the returned value
+ * replaces entirely.
  *
  * @example
  * ```ts
@@ -464,13 +578,31 @@ export interface EnumValueDisplayConfig {
  */
 export type DecoratorUpdater<T> = (current: T | undefined) => T;
 /**
- * Foreign key display mode options
- * - ID: Show raw FK ID value
- * - LABEL: Show resolved label via getFrontendResourceLabel
- * - SUMMARY: Show the referenced resource's summary view (compact card) (default)
+ * @wildo_source:part:start zod.decorators.foreign-key-display-mode facet:layer:frontend facet:family:ui facet:surface:display facet:surface:picker
+ *
+ * Foreign-key reference display vocabulary — how a foreign-key field renders, both
+ * as a stored VALUE in read views and as each ROW in the reference picker's
+ * dropdown (the picker is shared by forms and collection filters). Authored via
+ * `.foreignKeyUI(...)` from `@wildo-ai/zod-decorators` on the FK field:
+ * - `display.mode` — how the saved FK value renders in a read view.
+ * - `edit.optionDisplayMode` — how each picker dropdown ROW renders while selecting.
+ *
+ * Modes:
+ * - `ID`: the raw FK id string. As a picker row this is treated as `LABEL`.
+ * - `LABEL`: a one-line resolved label via `getFrontendResourceLabel`. The default on
+ *   BOTH surfaces — see {@link DEFAULT_FOREIGN_KEY_DISPLAY_MODE} and
+ *   {@link DEFAULT_FOREIGN_KEY_OPTION_DISPLAY_MODE}.
+ * - `SUMMARY`: the referenced resource's summary view — its summary fields with NO
+ *   action bar (a compact card). Always an opt-in, on both surfaces.
  *
- * Note: "summary" here is about *FK rendering*, not API data shape (see DataMode.SUMMARY)
- * or operation bar density (see ResourceOperationDisplayMode.SUMMARY).
+ * "summary" here is about FK RENDERING, not API data shape (`DataMode.SUMMARY`) or
+ * operation-bar density (`ResourceOperationDisplayMode.SUMMARY`).
+ *
+ * @example
+ * // Make the picker dropdown rows show the referenced resource's summary card:
+ * assigneeUserId: z.string().isForeignKey().foreignKeyUI({
+ *   edit: { optionDisplayMode: ForeignKeyDisplayMode.SUMMARY },
+ * })
  */
 export declare const ForeignKeyDisplayMode: {
     readonly ID: "id";
@@ -478,25 +610,108 @@ export declare const ForeignKeyDisplayMode: {
     readonly SUMMARY: "summary";
 };
 export type ForeignKeyDisplayMode = typeof ForeignKeyDisplayMode[keyof typeof ForeignKeyDisplayMode];
+/**
+ * The mode an FK's stored VALUE renders in when the field authors no
+ * `.foreignKeyUI({ display: { mode } })`.
+ *
+ * **This is the single source for that default.** Every site that has to supply a
+ * fallback display mode derives from this constant rather than restating a member of
+ * {@link ForeignKeyDisplayMode}. It exists because the default was previously declared
+ * twice and the two declarations DISAGREED — the metadata reader said `LABEL`, the
+ * display preset said `SUMMARY` — so the answer an app author got depended on which
+ * resolution path happened to run, and the prose above this enum documented the losing
+ * one.
+ *
+ * `LABEL` is the default because it is the cheap, composable rendering: one resolved
+ * line that fits a table cell, a detail row and a dense list alike. `SUMMARY` renders a
+ * card of the referenced record's summary fields — appropriate when the parent's
+ * details matter AT the point of reference, which is a per-field authoring judgement,
+ * not something a framework can assume for every FK in an application.
+ *
+ * @example
+ * // Opt a single field into the card rendering:
+ * todoListId: z.string().isForeignKey().foreignKeyUI({
+ *   display: { mode: ForeignKeyDisplayMode.SUMMARY },
+ * })
+ */
+export declare const DEFAULT_FOREIGN_KEY_DISPLAY_MODE: ForeignKeyDisplayMode;
+/**
+ * The mode each ROW of the reference picker's dropdown renders in when the field
+ * authors no `.foreignKeyUI({ edit: { optionDisplayMode } })`.
+ *
+ * **This is the single source for that default**, and it is deliberately a SEPARATE
+ * constant from {@link DEFAULT_FOREIGN_KEY_DISPLAY_MODE}. The two answer different
+ * questions — "how does a stored reference read?" versus "how does a candidate read
+ * while I am choosing one?" — and a framework that collapsed them would make one
+ * surface's default un-tunable without moving the other. They currently coincide on
+ * `LABEL`; that agreement is a fact about today's values, not a shared identity.
+ */
+export declare const DEFAULT_FOREIGN_KEY_OPTION_DISPLAY_MODE: ForeignKeyDisplayMode;
+/** @wildo_source:part:end zod.decorators.foreign-key-display-mode */
 /**
  * Polymorphic FK variant definition.
- * Specifies which parent resource variants a polymorphic FK targets.
- * Used by the polymorphic factory to derive the correct FK field name per variant.
+ *
+ * Describes one scope-branch of a polymorphic foreign key. A variant has two
+ * complementary roles, depending on whether the FK is renamed-per-holder or
+ * shared-with-discriminator (see {@link ForeignKeyStructuralParams.polymorphicVariants}):
+ *
+ * 1. **Rename role** (`parentResourceType` + `parentFieldIdentifier`): when the
+ *    FK's HOLDER resource is polymorphically expanded into per-scope variants,
+ *    the factory uses these to rename the FK field per variant — e.g.
+ *    `billingAccountId` → `organizationBillingAccountId`.
+ * 2. **Discriminated-resolution role** (`discriminatorValue`): when the FK is a
+ *    single SHARED field on a flat holder that points at a polymorphic branch
+ *    GROUP, this value links the holder record's discriminator field value to
+ *    THIS branch. See {@link ForeignKeyStructuralParams.polymorphicDiscriminatorField}.
  */
 export interface PolymorphicFkVariant {
-    /** The parent resource type (e.g., 'organizations') */
+    /** The parent (scope-root) resource type, e.g. `'organizations'` / `'users'`. */
     parentResourceType: string;
-    /** The parent's field identifier (e.g., 'organizationId') */
+    /** The parent's field identifier, e.g. `'organizationId'` / `'userId'`. */
     parentFieldIdentifier: string;
+    /**
+     * Value of the FK's `polymorphicDiscriminatorField` (read off the SAME record)
+     * that selects this variant's branch. Only meaningful for shared-field
+     * discriminated FKs; ignored by the per-variant rename path. E.g. a referral's
+     * `referrerScopeType === 'organizations'` selects the organizations variant,
+     * whose branch is `organizationBillingAccounts`.
+     */
+    discriminatorValue?: string;
 }
 /**
+ * @wildo_source:part:start zod.decorators.shared-structural-params facet:layer:shared facet:family:decorator facet:family:param-surface
+ *
  * Structural FK params — backend/factory-relevant subset.
  * Stays on `IS_FOREIGN_KEY`. UI-specific params (mode, linkable,
  * displayPresetOverride) live on `ForeignKeyUIParams` via `.foreignKeyUI()`.
  */
 export interface ForeignKeyStructuralParams {
+    /**
+     * Marks this FK as polymorphic over a set of scope branches.
+     *
+     * - On a resource that is itself polymorphically expanded, these drive the
+     *   per-variant FK field RENAME (e.g. `billingAccountId` →
+     *   `organizationBillingAccountId`).
+     * - On a FLAT resource that holds ONE shared FK to a polymorphic branch group
+     *   (e.g. a referral's `referrerBillingAccountId` → user OR organization
+     *   billing account), combine with {@link polymorphicDiscriminatorField}: each
+     *   variant carries a `discriminatorValue`, and the concrete branch is
+     *   resolved PER RECORD from the discriminator field. The single-valued
+     *   registry FK→type map keeps a non-authoritative representative for these
+     *   fields; the per-record resolver is authoritative for display/links.
+     */
     polymorphicVariants?: PolymorphicFkVariant[];
+    /**
+     * Sibling field name (on the SAME record) whose value selects which
+     * {@link polymorphicVariants} branch this record's FK points at. Required to
+     * turn `polymorphicVariants` into a per-record discriminated FK; pairs with
+     * each variant's `discriminatorValue`. The value is matched against the
+     * candidate branches' primary scope, so it typically holds a scope-type enum
+     * (e.g. `referrerScopeType`). Without it, `polymorphicVariants` is rename-only.
+     */
+    polymorphicDiscriminatorField?: string;
 }
+/** @wildo_source:part:end zod.decorators.shared-structural-params */
 /**
  * Supported types for range schemas.
  */
@@ -684,8 +899,16 @@ export interface DurationSchemaMetadata {
     /** Maximum value (for the numeric part) */
     maxValue?: number;
 }
-/** ISO 3166-1 alpha-2 country code (e.g., 'US', 'FR') */
-export type PhoneCountryCode = string;
+/**
+ * ISO 3166-1 alpha-2 country code (e.g., 'US', 'FR').
+ *
+ * Narrowed to libphonenumber's `CountryCode` union (not a bare `string`) so an
+ * invalid code fails at COMPILE time. The runtime consequence of a bad code is
+ * a throw from `getCountryCallingCode` — and since the international phone
+ * edit control renders the selected dial code, an invalid authored
+ * `defaultCountry` would crash the form at first render, not merely misparse.
+ */
+export type PhoneCountryCode = LibPhoneNumberCountryCode;
 /**
  * Metadata stored on phone schemas for detection and configuration.
  * Phone schemas store E.164 strings.
@@ -783,6 +1006,122 @@ export declare enum FileDisplayNature {
     DOCUMENT = "document",
     GENERIC = "generic"
 }
+/**
+ * Frame shape for an inline media (image) preview — see `FileUIDisplayParams.preview`.
+ * - `ROUNDED` (default): rounded-corner rectangle, aspect preserved (`object-contain`).
+ * - `SQUARE`: sharp-corner rectangle, aspect preserved.
+ * - `CIRCLE`: circular frame; the image is cropped to fill (`object-cover`). Typical
+ *   for avatars / profile pictures.
+ */
+export declare enum FileMediaShape {
+    ROUNDED = "rounded",
+    SQUARE = "square",
+    CIRCLE = "circle"
+}
+/**
+ * Rendered size tier for an inline media (image) preview — see
+ * `FileUIDisplayParams.preview`. `XS`–`XL` are fixed dimensions (a `CIRCLE` uses the
+ * value as its diameter; a rectangle uses it as the max width). `FULL` fills the
+ * available column width (the default, container-responsive) — best for cover images,
+ * not avatars.
+ */
+export declare enum FileMediaSize {
+    XS = "xs",
+    SM = "sm",
+    MD = "md",
+    LG = "lg",
+    XL = "xl",
+    FULL = "full"
+}
+/**
+ * How a file field renders AT REST, before any interaction — one of the two
+ * orthogonal axes of the file display policy (the other is
+ * {@link FileActivationPolicy}, what a click does).
+ *
+ * - `CARD` (default): the neutral file card — icon + filename + size. Compact and
+ *   nature-agnostic, so a detail view holding several documents stays scannable.
+ * - `THUMBNAIL`: a small rendered preview of the media beside the title (an image
+ *   thumbnail, a PDF's rasterised first page). Informative but still compact.
+ * - `FULL`: the media rendered inline at full width — an image, a video player, a
+ *   paginated PDF viewer. The heaviest option: for documents it downloads and mounts
+ *   the viewer on first paint, so prefer `CARD` + an `OVERLAY` activation unless the
+ *   document IS the page.
+ *
+ * `THUMBNAIL` and `FULL` require a displayer for the file's resolved nature; a
+ * request the nature cannot satisfy is refused at registry build (narrow declared
+ * nature) or degraded to `CARD` at runtime (open nature) — never a broken render.
+ */
+export declare enum FileDisplayPresentation {
+    CARD = "card",
+    THUMBNAIL = "thumbnail",
+    FULL = "full"
+}
+/**
+ * What activating (clicking / Enter) a displayed file does — the second axis of the
+ * file display policy. Applies to EVERY file nature, not just images.
+ *
+ * - `NONE`: inert. No cursor affordance, no handler, not focusable as a control.
+ * - `OVERLAY`: open the nature's displayer in an overlay (the generalisation of the
+ *   old image-only lightbox). Requires a displayer for the resolved nature.
+ * - `DOWNLOAD`: fetch the bytes over the authenticated serve route and save them.
+ * - `NEW_TAB`: open the authenticated serve URL in a new tab (the browser's own
+ *   viewer, with its native print/save affordances).
+ * - `CUSTOM`: run an operation declared on the resource that OWNS this file field —
+ *   see {@link FileActivationConfig}.
+ */
+export declare enum FileActivationPolicy {
+    NONE = "none",
+    OVERLAY = "overlay",
+    DOWNLOAD = "download",
+    NEW_TAB = "new_tab",
+    CUSTOM = "custom"
+}
+/**
+ * The authored activation, discriminated on `policy`.
+ *
+ * `CUSTOM` names an operation **by identifier**, never a callback. The reference is
+ * resolved against the resource that owns the file field, so the click inherits that
+ * operation's entire contract for free — `roles` authorization, `enabledCondition`,
+ * i18n label/tooltip, icon, risk level and audit emission — none of which a raw
+ * handler could carry. It also keeps display config serializable, which the
+ * specification layer, the companion and i18n generation all depend on.
+ *
+ * Dispatch follows the referenced operation's own frontend surface: `ADDRESSABLE`
+ * navigates, `EMBEDDED` opens in the overlay host, `API_ONLY` executes directly
+ * (with the standard confirmation for critical operations). The clicked file travels
+ * to the operation as context (`{ fieldName, fileId }`); the operation targets the
+ * owning row. An unresolvable reference fails at registry build, never as a dead control.
+ *
+ * @example
+ * // Click the attachment card to run the owning resource's `send_to_dms` operation.
+ * { policy: FileActivationPolicy.CUSTOM, operationIdentifier: 'send_to_dms' }
+ */
+export type FileActivationConfig = {
+    policy: FileActivationPolicy.NONE | FileActivationPolicy.OVERLAY | FileActivationPolicy.DOWNLOAD | FileActivationPolicy.NEW_TAB;
+} | {
+    policy: FileActivationPolicy.CUSTOM;
+    /** Operation identifier declared on the resource owning this file field. */
+    operationIdentifier: string;
+    /** Disambiguates when the operation has several keyed variants. */
+    variantKey?: string;
+};
+/**
+ * Presentation detail for a rendered media preview. Applies when
+ * {@link FileUIDisplayParams.presentation} is `THUMBNAIL` or `FULL`; ignored by `CARD`.
+ * All fields are optional with sensible defaults (rounded rectangle, full width,
+ * caption on). An avatar typically sets `{ shape: CIRCLE, size: MD, showCaption: false }`.
+ *
+ * Click behaviour is NOT here — it is the separate `activation` axis, so that every
+ * nature (not only images) can express it.
+ */
+export interface FileMediaPreviewOptions {
+    /** Frame shape. @default FileMediaShape.ROUNDED */
+    shape?: FileMediaShape;
+    /** Rendered size tier. @default FileMediaSize.FULL */
+    size?: FileMediaSize;
+    /** Show the caption row (filename / size / dimensions / download) under the media. @default true */
+    showCaption?: boolean;
+}
 /**
  * Storage providers accepted for file uploads.
  */
@@ -924,8 +1263,8 @@ export interface FilePathBinding {
 export declare enum FileUploaderEntityType {
     USER = "user",
     ANONYMOUS_USER = "anonymous_user",
-    ORGANIZATION_API_KEY = "organization_api_key",
-    APPLICATION_API_KEY = "application_api_key"
+    ORGANIZATION_MACHINE = "organization_machine",
+    APPLICATION_MACHINE = "application_machine"
 }
 export type FileUploaderOwnership = {
     uploadedBy: string;
@@ -1009,25 +1348,95 @@ export interface FileNatureConstraints_Document {
     minPages?: number;
 }
 /**
- * RAG chunking strategy options for file content indexing.
+ * @wildo_source:part:start zod.decorators.rag-source facet:layer:shared facet:family:decorator facet:family:param-surface facet:kind:api facet:audience:app-developer
+ *
+ * How a RAG-source field's text is split into retrieval chunks.
+ *
+ * Import from `@wildo-ai/zod-decorators`. Every member is a chunking STRATEGY — pick the one that
+ * matches the field's real content shape, because chunk boundaries decide what a retrieval hit can
+ * quote: a heading-aware split over markdown returns a coherent section, while a fixed-size split
+ * over the same text returns whatever fell inside the window.
+ *
+ * **This is the single named home for the chunking vocabulary** (semantic-string-literals rule).
+ * It lives in `zod-decorators` — not `saas-models` — because the dependency arrow points the other
+ * way: `saas-models` depends on this package, while the `.ragSource()` decorator params below could
+ * never import a `saas-models` enum. Chunking is authored ON THE FIELD, through `.ragSource()`;
+ * there is no separate agent-level chunking configuration to keep in step with it.
+ *
+ * - `FIXED_SIZE` — split every `chunkSize` characters/tokens regardless of structure.
+ * - `RECURSIVE` — split on a separator hierarchy (paragraph → sentence → word) down to `chunkSize`.
+ * - `SEMANTIC` — split at embedding-detected topic boundaries.
+ * - `MARKDOWN` — split on markdown structure (headings, lists, code fences).
+ * - `CODE` — split on source-code structure (functions, classes, blocks). Unified in (2026-08-26)
+ *   from a second copy of this vocabulary that `saas-models` then carried: the member sets differed
+ *   only by this entry, and shrinking the vocabulary to fit the field decorator would have silently
+ *   invalidated configurations authored against the wider one — so the union won. That second copy,
+ *   and the agent-level RAG configuration schemas around it, were retired on 2026-08-27 as a
+ *   pre-capability design the shipped capability superseded; this object is now the only home.
  */
 export declare const RAGChunkingStrategy: {
     readonly FIXED_SIZE: "fixed_size";
     readonly RECURSIVE: "recursive";
     readonly SEMANTIC: "semantic";
     readonly MARKDOWN: "markdown";
+    readonly CODE: "code";
 };
 export type RAGChunkingStrategy = typeof RAGChunkingStrategy[keyof typeof RAGChunkingStrategy];
 /**
- * RAG configuration for file content indexing.
+ * Stored metadata for the RAG-source declaration (`.ragSource()` / `addRagSource()` /
+ * `z_file({ ragSource })`).
+ *
+ * Every knob is optional — `z.string().ragSource()` is a complete declaration that accepts the
+ * framework chunking defaults — and there is deliberately NO `enabled` flag: a field either carries
+ * the decorator (it IS a retrieval-corpus source) or it does not. A boolean that could say
+ * "decorated but disabled" would make every downstream reader (detection, chunk store, erasure
+ * seams) re-ask a question the decorator's presence already answers.
+ *
+ * Validated at decoration time by the `applySingleDecorator` chokepoint (shared by the fluent
+ * method and the escape hatch): `chunkingStrategy` must be a {@link RAGChunkingStrategy} member,
+ * `chunkSize` a positive integer, `chunkOverlap` a non-negative integer strictly smaller than
+ * `chunkSize` when both are present. Read the stored config back with `getRagSourceConfig(schema)`.
+ *
+ * Note the split of concerns with file fields: this object configures CHUNKING — how text becomes
+ * retrieval chunks — and is identical for a plain string field and a file field. How the TEXT is
+ * OBTAINED in the first place is the text provider's concern: trivial for a string field (the value
+ * is the text), file-side config for a file field (`FileSchemaOptions.textExtraction`, e.g. OCR).
  */
-export interface FileRAGConfiguration {
-    enabled: boolean;
-    extractText?: boolean;
+export interface RagSourceConfiguration {
+    /** Chunking strategy for this field's text. Omitted = the framework default strategy. */
     chunkingStrategy?: RAGChunkingStrategy;
+    /** Target chunk size. Positive integer; omitted = the strategy's default size. */
     chunkSize?: number;
+    /** Overlap carried between consecutive chunks. Non-negative integer, `< chunkSize` when both are set. */
     chunkOverlap?: number;
 }
+/** @wildo_source:part:end zod.decorators.rag-source */
+/**
+ * @wildo_source:part:start zod.decorators.file-generation facet:layer:schema facet:family:pdf-templates
+ *
+ * Generation sources supported by `z_file()`.
+ *
+ * Keep this enum in `zod-decorators` instead of `saas-models` so shared schemas
+ * can mark generated files without creating a dependency cycle back into the
+ * resource/model packages that already consume decorators.
+ */
+export declare enum FileGenerationSource {
+    PDF_TEMPLATE = "pdfTemplate"
+}
+/**
+ * Frontend-safe file generation metadata.
+ *
+ * This is deliberately a stable identifier only. The backend binds that
+ * identifier to an imported `PdfTemplateDefinition` during application startup,
+ * which keeps live functions and React components out of shared schema metadata.
+ */
+export interface FileGenerationConfig {
+    /** The generation system responsible for materializing the file value. */
+    source: FileGenerationSource.PDF_TEMPLATE;
+    /** Stable id of the backend-bound PDF template definition. */
+    templateId: string;
+}
+/** @wildo_source:part:end zod.decorators.file-generation */
 /**
  * File metadata returned by the getMetadata endpoint.
  * This describes the uploaded file's properties.
@@ -1075,6 +1484,8 @@ export declare const FileOnParentDelete: {
 };
 export type FileOnParentDelete = typeof FileOnParentDelete[keyof typeof FileOnParentDelete];
 /**
+ * @wildo_source:part:start zod.decorators.file-schema
+ *
  * Metadata stored on file schemas for detection and configuration.
  * File schemas represent file references with upload capabilities.
  * Structure (single): { fileId: string, updatedAt: Date }
@@ -1101,6 +1512,12 @@ export interface FileSchemaMetadata {
     storageAccepted?: FileStorageAccepted[];
     /** File path binding for structured storage organization */
     filePathBinding?: FilePathBinding;
+    /**
+     * Generation metadata for files materialized by framework operations instead
+     * of user uploads. Generated file fields are readable but omitted from write
+     * DTOs by downstream resource tooling.
+     */
+    generation?: FileGenerationConfig;
     /** Image-specific constraints */
     imageConstraints?: FileNatureConstraints_Image;
     /** Video-specific constraints */
@@ -1109,8 +1526,19 @@ export interface FileSchemaMetadata {
     audioConstraints?: FileNatureConstraints_Audio;
     /** Document-specific constraints */
     documentConstraints?: FileNatureConstraints_Document;
-    /** RAG configuration */
-    rag?: FileRAGConfiguration;
+    /**
+     * Text-provider configuration for this file field — HOW text is obtained from the file's bytes
+     * when something needs it (today: RAG chunking of a `ragSource` file field; the standalone
+     * text-extraction operation reads it too).
+     *
+     * Deliberately file-side and separate from {@link RagSourceConfiguration}: extraction is a
+     * property of the FILE FIELD (its bytes need decoding — PDF parsing, OCR), while chunking is the
+     * shared RAG-source concern a plain string field carries identically. The former `extractText`
+     * boolean is gone with `z_file({ rag })`: for a `ragSource` file field extraction is implied
+     * (a corpus source whose text is never extracted would be a silent no-op), so the only honest
+     * remaining knobs are the ones that change HOW extraction runs.
+     */
+    textExtraction?: FileTextExtractionOptions;
     /**
      * Antivirus scan policy for this file field.
      * - 'required': always scan after upload, regardless of global config
@@ -1140,6 +1568,27 @@ export interface FileSchemaMetadata {
         consumptionMode?: 'SINGLE_USE' | 'BOUNDED_REUSE';
     };
 }
+/** @wildo_source:part:end zod.decorators.file-schema */
+/**
+ * @wildo_source:part:start zod.decorators.file-rag-source facet:layer:shared facet:family:decorator facet:family:file facet:kind:api facet:audience:app-developer
+ *
+ * File-side text-extraction knobs (see {@link FileSchemaMetadata.textExtraction} for why these are
+ * NOT part of {@link RagSourceConfiguration}).
+ *
+ * Import from `@wildo-ai/zod-decorators` and pass under `z_file({ textExtraction })`. Extraction
+ * answers "how are this file's BYTES turned into text"; chunking (`RagSourceConfiguration`) answers
+ * "how is that text split", and is identical for a file field and a plain string field.
+ */
+export interface FileTextExtractionOptions {
+    /**
+     * Opt into OCR for image-backed content (scanned documents, photos of text). Off by default:
+     * OCR is an external, per-page cost, and most corpus files (PDF with a text layer, plain text,
+     * markdown) never need it.
+     * @default false
+     */
+    ocr?: boolean;
+}
+/** @wildo_source:part:end zod.decorators.file-rag-source */
 /**
  * Options for creating a file schema.
  */
@@ -1162,6 +1611,14 @@ export interface FileSchemaOptions {
     storageAccepted?: FileStorageAccepted[];
     /** File path binding for structured storage organization */
     filePathBinding?: FilePathBinding;
+    /**
+     * Marks this file as generated by a framework operation.
+     *
+     * `FileGenerationSource.PDF_TEMPLATE` is v1's only source and is always
+     * single-file PDF output; callers must not combine it with upload-style MIME
+     * broadening or multiple-file semantics.
+     */
+    generation?: FileGenerationConfig;
     /** Image-specific constraints */
     imageConstraints?: FileNatureConstraints_Image;
     /** Video-specific constraints */
@@ -1170,8 +1627,31 @@ export interface FileSchemaOptions {
     audioConstraints?: FileNatureConstraints_Audio;
     /** Document-specific constraints */
     documentConstraints?: FileNatureConstraints_Document;
-    /** RAG configuration */
-    rag?: FileRAGConfiguration;
+    /**
+     * @wildo_source:part:start zod.decorators.file-rag-source facet:layer:shared facet:family:decorator facet:family:file facet:kind:api facet:audience:app-developer
+     *
+     * Declare this file field a RAG retrieval-corpus source.
+     *
+     * (The two `z_file()` options below are declared on `FileSchemaOptions` — the object literal
+     * `z_file()` accepts.)
+     *
+     * `z_file({ ragSource: {} })` registers the shared {@link ZodDecorator.RAG_SOURCE} decorator on
+     * the schema it returns — the SAME decorator `z.string().ragSource()` uses — so detection and
+     * every downstream seam (chunk store, erasure, re-index) see one uniform declaration. The config
+     * is stored ONLY on the decorator (read it with `getRagSourceConfig`), never duplicated into
+     * {@link FileSchemaMetadata}; how the file's TEXT is obtained is the sibling
+     * {@link FileSchemaOptions.textExtraction} knob.
+     *
+     * Refused with `generation` (a PDF-template output is framework-rendered presentation, not an
+     * authored corpus), and subject to the decorator chokepoint's own refusals (secrets, `.ttl()`).
+     */
+    ragSource?: RagSourceConfiguration;
+    /**
+     * Text-provider configuration for this file field (OCR opt-in). See
+     * {@link FileSchemaMetadata.textExtraction} for the extraction-vs-chunking split.
+     */
+    textExtraction?: FileTextExtractionOptions;
+    /** @wildo_source:part:end zod.decorators.file-rag-source */
     /**
      * Antivirus scan policy for this file field.
      * - 'required': always scan after upload, regardless of global config
@@ -1214,6 +1694,16 @@ export interface FileFieldEndpoints {
     override?: string;
     /** URL to delete a file (optional) */
     delete?: string;
+    /**
+     * Base URL of the resource-integrated file **serve** route for this field, with
+     * parent/resource ids already substituted:
+     * `{apiBase}/api/v1/…/{resourceId}/files/{fieldSegment}`. The display consumer
+     * appends `/{fileId}` and fetches the bytes over the AUTHENTICATED client
+     * (authorization inherits the parent resource's READ). Omitted when no resource
+     * context is available (fail-closed to the neutral file card). This is distinct
+     * from the global `/files/:fileId` download/share surface.
+     */
+    serve?: string;
 }
 /**
  * Metadata stored on versioned schemas for detection and configuration.
@@ -1235,6 +1725,29 @@ export interface VersionedForeignKeySchemaMetadata {
     /** The name of the target resource this foreign key references */
     targetResource?: string;
 }
+/**
+ * @wildo_source:part:start zod.decorators.structural-lifecycle-params facet:layer:shared facet:layer:backend facet:family:decorator facet:family:lifecycle
+ *
+ * Structural and lifecycle decorator parameter types for shared resource
+ * schemas.
+ *
+ * These shapes belong to the shared schema layer:
+ * `shared-lib/src/modules/<module>/resources/<resource>/<resource>.schemas.ts`.
+ *
+ * They describe field behavior that affects persistence, DTO derivation,
+ * security boundaries, discriminated variants, validation lifecycle, and other
+ * cross-layer mechanics. They are appropriate in the shared Zod schema because
+ * backend and frontend consumers both depend on the resulting metadata.
+ *
+ * Do NOT place per-field UI rendering configuration here. UI decorators such as
+ * `.stringUI()` / `.enumUI()` belong in frontend `*.ui-behavior.tsx` files.
+ * Do NOT place business-semantics prose here. `{primitive}Spec()` decorators
+ * belong in specification overlays.
+ *
+ * When framework knowledge is generated, this anchored block is intended to be
+ * inserted as the deterministic source-of-truth reference for structural
+ * decorator parameters instead of maintaining parallel markdown tables.
+ */
 export interface HiddenFieldParams {
     display?: boolean;
     edit?: boolean;
@@ -1262,6 +1775,8 @@ export declare const InlineEditSaveOn: {
 };
 export type InlineEditSaveOn = typeof InlineEditSaveOn[keyof typeof InlineEditSaveOn];
 /**
+ * @wildo_source:part:start zod.decorators.shared-structural-params facet:layer:shared facet:family:decorator facet:family:param-surface
+ *
  * Parameters for the isBackendOnly decorator.
  * Marks fields that should only exist on the backend and be stripped from API responses.
  */
@@ -1270,13 +1785,96 @@ export interface BackendOnlyFieldParams {
      * If true, the field will be included in the response for CREATE operations only,
      * then stripped from all subsequent READ operations.
      * Useful for secrets, API keys, etc. that should only be returned once.
+     *
+     * This is also the framework's ONLY disclosure-audit trigger: a field that carries it emits one
+     * `FIELD_ACCESS` audit event at the moment it is first (and last) exposed. That pairing is not a
+     * coincidence — first exposure is the only point at which a backend-only field crosses the client
+     * boundary at all, so it is the only point at which "this value left the system" is a true claim.
+     *
+     * Scope limit worth knowing before relying on it: the audit event is raised from the TOP-LEVEL
+     * shape of the response DTO. A single `CREATE` is the reliably covered case; do not assume a
+     * bulk-create response gives you the same guarantee without checking.
+     *
+     * assurance-control: WILDO.SECRETS.DISCLOSURE_AUDIT — first disclosure of server-minted secret
+     * material is attributable.
      */
     isReturnedAtCreation?: boolean;
+}
+/**
+ * Parameters for the isWriteOnlySecret decorator.
+ * Marks a user-provided secret that stays in CREATE/UPDATE request DTOs
+ * (client-writable) but is masked to a placeholder on every client-facing
+ * response DTO; the real value is retained for backend internal reads.
+ * Read-side masking and the write-back sentinel are enforced by the framework
+ * at the client-serialization boundary — no per-resource custom implementation
+ * needed.
+ *
+ * Pick the right secret posture by **who owns the value and which direction it
+ * flows** — the three are mutually exclusive on a field:
+ * - `.isWriteOnlySecret()` — the CLIENT supplies the secret and the server keeps
+ *   it (e.g. a webhook signing key, an SSO client secret). Client-writable,
+ *   masked on read, real value kept for backend use. Re-submitting the mask is
+ *   a no-op (the stored value is preserved).
+ * - `.isEphemeral()` — the SERVER mints the secret and hands it to the client
+ *   exactly once at creation (e.g. an API key shown in a one-time reveal). Not
+ *   client-writable, not re-readable afterwards. A composite decorator (secret
+ *   display + one-time reveal + not-editable).
+ * - `.isBackendOnly()` — the field never crosses the client boundary in EITHER
+ *   direction. Do NOT use it for a client-provided secret: it strips the field
+ *   from the write DTOs too, so the client could never set the value.
+ */
+export interface WriteOnlySecretFieldParams {
     /**
-     * If true, access to this field will be logged for audit purposes.
-     * Useful for sensitive data that needs audit trail.
+     * Intentionally empty.
+     *
+     * A write-only secret is masked on EVERY client-facing response, so there is no disclosure to
+     * audit — the real value never crosses the boundary. The parameter bag is kept so the decorator
+     * can gain options later without changing its call shape.
      */
-    auditAccess?: boolean;
+    readonly _reserved?: never;
+}
+/** @wildo_source:part:end zod.decorators.shared-structural-params */
+/**
+ * Stored metadata for the impersonalization scrub treatment (`.impersonalizeWith()` /
+ * `addImpersonalizeWith()`).
+ *
+ * This metadata deliberately stays outside the `shared-structural-params` subsection, mirroring
+ * the decorator method itself. Impersonalization has distinct lifecycle and retention semantics,
+ * so it needs dedicated application-facing guidance when the installed runtime exposes it.
+ */
+export interface ImpersonalizeFieldParams {
+    /**
+     * The scrub treatment — a `RedactionType` value carried as an opaque string (zod-decorators sits
+     * below saas-models and cannot reference the enum type). REQUIRED and non-empty: a field either
+     * declares how it is scrubbed, or carries no treatment at all.
+     */
+    treatment: string;
+    /**
+     * `MASK` only — the literal value written in place of this field, overriding the framework's
+     * default mask constant.
+     *
+     * **Why this exists.** The default mask is an UNCONSTRAINED string, so it cannot be written into
+     * exactly the fields most likely to need masking: a CONSTRAINED string — `z.email()`, `z.uuid()`,
+     * `.min(n)` — rejects it and the boot guard fails the config. Without an override, such a field
+     * can only be erased by widening it to `.nullish()` for a `REMOVE` scrub. For a unique identity
+     * anchor (`User.email` is the motivating case) that trades a permanently weaker type on every
+     * consumer for a state only the audited see-through reader can ever observe, since a retained row
+     * is hidden from every normal read. The override keeps the authored type intact.
+     *
+     * **Contract.** The value must satisfy the field's OWN schema — the boot guard `safeParse`s it
+     * against that schema and fails loud otherwise. It is STATIC: the same value is written to every
+     * row of a scrub batch (the scrub is one `$set`), so choose something meaningless as data and
+     * safe to collide on. For an email, an RFC 2606 reserved `.invalid` address is the honest choice —
+     * that TLD can never be registered or delivered to.
+     *
+     * **Collision is not a concern**, even on a `.isUnique()` field: every unique index on a
+     * retention-governed resource is scoped to NON-RETAINED rows, and the scrub flips the row to
+     * `RETAINED` in the same write, so scrubbed rows leave the index.
+     *
+     * Declaring it alongside a non-`MASK` treatment is a config error — nothing would ever write it.
+     * That check lives in the saas-models boot guard, which is the layer that knows `RedactionType`.
+     */
+    maskValue?: string;
 }
 /**
  * Parameters passed to virtual field calculation functions.
@@ -1329,6 +1927,8 @@ export interface VirtualFieldParams<TObject = any, TResult = any> {
     dependencies?: string[];
 }
 /**
+ * @wildo_source:part:start zod.decorators.shared-structural-params facet:layer:shared facet:family:decorator facet:family:param-surface
+ *
  * Parameters for the isDiscriminator decorator.
  * Marks a field as the discriminator for a discriminated union schema.
  */
@@ -1339,7 +1939,10 @@ export interface DiscriminatorFieldParams {
      */
     baseValues?: string[];
 }
+/** @wildo_source:part:end zod.decorators.shared-structural-params */
 /**
+ * @wildo_source:part:start zod.decorators.shared-structural-params facet:layer:shared facet:family:decorator facet:family:param-surface
+ *
  * Scope for unique constraint enforcement.
  * - 'global': Unique across the entire collection (default)
  * - 'organization': Unique within an organization (compound index with organizationId)
@@ -1386,8 +1989,76 @@ export interface UniqueFieldParams {
      * @example "This {fieldName} is already taken"
      */
     errorMessage?: string;
+    /**
+     * The custom message reference the API returns when THIS field's unique index is violated.
+     *
+     * Without it, every duplicate-key rejection collapses to one generic conflict code, so an
+     * integrator cannot tell "that slug is taken" from "that invoice number is taken" without
+     * parsing a message. Naming the reference here — next to the constraint that produces it —
+     * keeps one authority: the key and the error it raises cannot drift apart.
+     *
+     * Pass a member of the framework's error-reference vocabulary, never a bare literal.
+     *
+     * @example slug: z.string().isUnique({ conflictMessageReference: ErrorCustomMessageReference.ORGANIZATION_SLUG_EXISTS })
+     */
+    conflictMessageReference?: string;
 }
 /**
+ * Parameters for the object-level `businessKeySet([...])` decorator.
+ *
+ * Declares a **composite business key**: the ordered list of `fields` is the stable identity of a
+ * row, used both by seeding upsert / upgrade / sync passes to find an existing row independently
+ * from its random `_id`, and by the storage adapter to materialize a compound UNIQUE index so the
+ * identity is enforced by the database rather than by a race-prone read-then-write.
+ *
+ * - `fields` must be non-empty and every entry must be a key declared on the
+ *   underlying `ZodObject` shape (validated at decoration time).
+ * - This decorator is **mutually exclusive** with field-level `isBusinessKey()`
+ *   on the same schema — pick one identity model.
+ *
+ * @example
+ * // "one membership per user per organization"
+ * z.object({ userId: z.string(), organizationId: z.string(), roles: z.array(z.string()) })
+ *   .businessKeySet(['userId', 'organizationId'])
+ */
+export interface BusinessKeySetParams {
+    fields: string[];
+    /**
+     * Fields whose ABSENCE takes a row out of the uniqueness constraint entirely.
+     *
+     * By default a missing member counts as a real value, so two rows that both omit it COLLIDE.
+     * That is the correct default for an identity whose members are always meaningful — two rows
+     * that are "unscoped" in the same way really are the same row.
+     *
+     * It is wrong when a member is optional in the domain sense: "unit code, unique among siblings"
+     * must still allow any number of siblings that carry NO code. Listing that field here scopes the
+     * constraint to the rows that actually have it.
+     *
+     * Every entry must also appear in `fields`. List only the members whose absence means "this row
+     * has no key", never merely "this member happens to be optional" — a field left out of the list
+     * keeps the default null-collides behaviour, which is what most composite keys want.
+     *
+     * @example
+     * // many code-less siblings are fine; two siblings sharing a code are not
+     * .businessKeySet(['organizationId', 'parentUnitId', 'code'], { skipRowsMissing: ['code'] })
+     */
+    skipRowsMissing?: string[];
+    /**
+     * The custom message reference the API returns when THIS key's unique index is violated.
+     *
+     * Without it, every duplicate-key rejection collapses to one generic conflict code, so an
+     * integrator cannot tell which identity was violated without parsing a message. Naming the
+     * reference here — next to the key that produces it — keeps one authority: the key and the error
+     * it raises cannot drift apart.
+     *
+     * Pass a member of the framework's error-reference vocabulary, never a bare literal.
+     */
+    conflictMessageReference?: string;
+}
+/** @wildo_source:part:end zod.decorators.shared-structural-params */
+/**
+ * @wildo_source:part:start zod.decorators.shared-structural-params facet:layer:shared facet:family:decorator facet:family:param-surface
+ *
  * Parameters for the ttl decorator.
  * Marks a Date field for TTL (Time To Live) expiration in MongoDB.
  * MongoDB will automatically delete documents when the TTL expires.
@@ -1414,6 +2085,7 @@ export interface TtlFieldParams {
      */
     expireAfterSeconds: number;
 }
+/** @wildo_source:part:end zod.decorators.shared-structural-params */
 /**
  * Parameters for the isOtp decorator.
  * Configures the OTP (One-Time Password) input field behavior.
@@ -1436,6 +2108,8 @@ export interface OtpFieldParams {
     maxLength?: number;
 }
 /**
+ * @wildo_source:part:start zod.decorators.shared-structural-params facet:layer:shared facet:family:decorator facet:family:param-surface
+ *
  * Parameters for the isSummaryField decorator.
  * Controls how summary fields are handled, particularly for foreign key population.
  */
@@ -1464,6 +2138,7 @@ export interface SummaryFieldParams {
      */
     populate?: boolean;
 }
+/** @wildo_source:part:end zod.decorators.shared-structural-params */
 /**
  * Validation mode for form fields.
  * Configures when field validation is triggered.
@@ -1509,7 +2184,10 @@ export interface AutosaveFieldParams {
      */
     debounceMs?: number;
 }
+/** @wildo_source:part:end zod.decorators.structural-lifecycle-params */
 /**
+ * @wildo_source:part:start zod.decorators.conditional-visibility facet:layer:frontend facet:family:form facet:surface:conditional
+ *
  * FIX-P5-H1: Operator for showWhen condition comparison.
  * - EQUALS: Field value equals the specified value
  * - NOT_EQUALS: Field value does not equal the specified value
@@ -1550,6 +2228,11 @@ export interface ShowWhenCondition {
  * FIX-P5-H1: Parameters for the showWhen decorator.
  * Configures conditional visibility for form fields.
  *
+ * Available on every form-field type — each primitive, plus object and array, plus the `optional` /
+ * `default` / `nullable` wrappers — matching `ZodDecorator_ApplyableType[SHOW_WHEN]`. The bare form
+ * below is the documented one and works as written; before 2026-08-12 it threw, because the
+ * decorator was installed on the wrapper prototypes only.
+ *
  * @example
  * ```ts
  * // Show when 'type' field equals 'advanced'
@@ -1559,7 +2242,12 @@ export interface ShowWhenCondition {
  *
  * // Show when 'type' is one of multiple values
  * featureOption: z.string().showWhen({
- *   conditions: { field: 'type', value: ['pro', 'enterprise'], operator: 'in' }
+ *   conditions: { field: 'type', value: ['pro', 'enterprise'], operator: ShowWhenOperator.IN }
+ * })
+ *
+ * // On a defaulted field — the shape used by Wonder Todos' `reminder.leadTimeMinutes`
+ * leadTimeMinutes: z.number().int().default(30).showWhen({
+ *   conditions: { field: 'enabled', value: true }
  * })
  *
  * // Show when both conditions are met
@@ -1586,6 +2274,7 @@ export interface ShowWhenParams {
      */
     combineWith?: 'and' | 'or';
 }
+/** @wildo_source:part:end zod.decorators.conditional-visibility */
 /**
  * Parameters for the isDraftable decorator.
  * Configures draft mode behavior at the schema level.
@@ -1638,6 +2327,8 @@ export interface BooleanLabellingCustomParams {
     falseValue: string;
 }
 /**
+ * @wildo_source:part:start zod.decorators.primitive-ui
+ *
  * Display-context base params.
  * Controls chrome, inline editing, and tooltip behavior when a field is rendered in a read-only view.
  */
@@ -1650,6 +2341,23 @@ export interface PrimitiveUIBaseDisplayParams {
     forceHide?: ResponsiveAware<ForceHideDisplayConfig>;
     /** Whether to show a tooltip icon in display chrome. Text comes from i18n. */
     tooltip?: boolean;
+    /**
+     * When `true`, the field is omitted entirely from the DISPLAY (read) surface
+     * whenever its value is empty — null, undefined, an empty string, or an empty
+     * array. The whole row (label + chrome + em-dash placeholder) is removed, not
+     * just the value.
+     *
+     * DISPLAY-ONLY: the edit form always renders the field so an empty value can
+     * still be filled in. This is the field-level counterpart to the section-level
+     * `SectionConfigBase.hideWhenEmpty` and to the surface-policy
+     * `AutoEmptyValue.HIDDEN` — use it to keep optional metadata (a job title, a
+     * secondary contact) from cluttering a read view when unset.
+     *
+     * @example
+     * // Hide the "Title" row on the profile read view until the user sets one:
+     * schemaShape.title.stringUI({ display: { hideWhenEmpty: true } })
+     */
+    hideWhenEmpty?: boolean;
     /**
      * Opt-in for description text below the field value in display mode.
      * When true, the companion generates an i18n key for the description.
@@ -1681,6 +2389,14 @@ export interface PrimitiveUIBaseEditParams {
     tooltip?: boolean;
     /** Auto-focus this field when the form mounts. */
     autoFocus?: boolean;
+    /** Official HTML autocomplete field identifier for browser autofill. */
+    autoComplete?: AutocompleteFieldIdentifier;
+    /**
+     * Optional official HTML autocomplete modifiers.
+     * Supports a single modifier or an array. `section-*` is intentionally excluded
+     * from this typed contract and can be added later via a dedicated API if needed.
+     */
+    autoCompleteModifier?: AutocompleteModifier | AutocompleteModifier[];
     /**
      * Opt-in for description/helper text below the form input in edit mode.
      * When true, the companion generates an i18n key for the description.
@@ -1704,6 +2420,29 @@ export interface PrimitiveUIBaseParams {
     /** Config for Edition context (forms). */
     edit?: PrimitiveUIBaseEditParams;
 }
+/** @wildo_source:part:end zod.decorators.primitive-ui */
+/**
+ * @wildo_source:part:start zod.decorators.per-primitive-ui facet:layer:frontend facet:family:ui facet:surface:form facet:surface:display
+ *
+ * Per-primitive frontend UI decorator parameter types.
+ *
+ * These interfaces define the arguments accepted by decorators such as
+ * `.stringUI()`, `.numberUI()`, `.enumUI()`, `.booleanUI()`, `.moneyUI()`,
+ * `.foreignKeyUI()`, etc.
+ *
+ * They belong to the frontend resource behavior layer, not to shared resource
+ * schemas. In application code, they are typically authored in files like:
+ * `frontend/src/modules/<module>/resources/<resource>/<resource>.ui-behavior.tsx`
+ *
+ * The shared schema establishes structural meaning (`isSummaryField`,
+ * `isForeignKey`, `excludeFromUpdate`, ...). These UI parameter types control
+ * presentation concerns such as display widgets, edit widgets, chrome modes,
+ * per-enum colors/icons, inline editing, and layout details.
+ *
+ * Generated framework knowledge should prefer extracting these definitions from
+ * source rather than restating the supported UI parameters in handcrafted
+ * markdown documents.
+ */
 export interface BooleanUIDisplayParams extends PrimitiveUIBaseDisplayParams {
     /** Display renderer. RAW = plain text, CHECKMARK = checkmark/cross, EDIT_LIKE = shows the edit control read-only. */
     displayMode?: BooleanDisplayMode;
@@ -1723,10 +2462,18 @@ export interface BooleanUIParams {
     edit?: BooleanUIEditParams;
 }
 export interface StringUIDisplayParams extends PrimitiveUIBaseDisplayParams {
-    /** Display renderer. TEXT | TRUNCATE | MULTILINE | COLOR | LINK | EMAIL | BADGE | COPY | SECRET. */
+    /** Display renderer. TEXT | TRUNCATE | MULTILINE | MARKDOWN | COLOR | LINK | EMAIL | BADGE | COPY | SECRET. */
     displayMode?: StringDisplayMode;
     /** Max characters before truncation (TRUNCATE displayMode only). */
     truncateLength?: number;
+    /**
+     * SECRET displayMode only: render the value revealed (not masked) on first
+     * paint. Defaults to `false` (masked, reveal via the eye toggle) for secrets
+     * shown in persistent surfaces. `.isEphemeral()` sets this `true` because an
+     * ephemeral one-time-reveal exists precisely so the caller can read + copy the
+     * secret immediately; the toggle still lets them re-hide it.
+     */
+    initiallyRevealed?: boolean;
 }
 export interface StringUIEditParams extends PrimitiveUIBaseEditParams {
     /** Edit control. INPUT | TEXTAREA | COLOR | PASSWORD | OTP. */
@@ -1833,7 +2580,28 @@ export interface CodeUIParams {
     summaryOverride?: CodeUIDisplayParams;
     edit?: CodeUIEditParams;
 }
-export type FileUIDisplayParams = PrimitiveUIBaseDisplayParams;
+export interface FileUIDisplayParams extends PrimitiveUIBaseDisplayParams {
+    /**
+     * How the file renders AT REST — see {@link FileDisplayPresentation}. Media display
+     * is never mandatory: the default is the neutral file card, and `THUMBNAIL`/`FULL`
+     * are opt-in. Rendered media is fetched over the authenticated resource-integrated
+     * serve route (authz inherits the parent READ).
+     * @default FileDisplayPresentation.CARD
+     */
+    presentation?: FileDisplayPresentation;
+    /**
+     * What activating the file does — see {@link FileActivationConfig}. Applies to every
+     * nature. Omit for the nature-derived default: `OVERLAY` when a displayer exists for
+     * the resolved nature, `DOWNLOAD` otherwise.
+     */
+    activation?: FileActivationConfig;
+    /**
+     * Presentation detail for rendered media (shape / size / caption). Applies when
+     * `presentation` is `THUMBNAIL` or `FULL`; ignored by `CARD`.
+     * @example { shape: FileMediaShape.CIRCLE, size: FileMediaSize.MD, showCaption: false } // avatar
+     */
+    preview?: FileMediaPreviewOptions;
+}
 export type FileUIEditParams = PrimitiveUIBaseEditParams;
 export interface FileUIParams {
     display?: FileUIDisplayParams;
@@ -1896,7 +2664,18 @@ export interface ForeignKeyUIDisplayParams extends PrimitiveUIBaseDisplayParams
     /** Override the preset used to display the referenced resource summary. */
     displayPresetOverride?: string;
 }
-export type ForeignKeyUIEditParams = PrimitiveUIBaseEditParams;
+export interface ForeignKeyUIEditParams extends PrimitiveUIBaseEditParams {
+    /**
+     * How each RESULT in the reference picker's dropdown renders — applies to both
+     * the form picker and the collection filter picker (they share one component):
+     * - `LABEL` (default): a one-line resource label (via `getFrontendResourceLabel`).
+     * - `SUMMARY`: the referenced resource's summary view — its summary fields with
+     *   NO action bar — rendered via `ResourceSummaryDisplayer`.
+     * `ID` is treated as `LABEL` here (a raw id is not a useful picker row). Only the
+     * dropdown options are affected; the selected value still shows as a label.
+     */
+    optionDisplayMode?: ForeignKeyDisplayMode;
+}
 export interface ForeignKeyUIParams {
     display?: ForeignKeyUIDisplayParams;
     summaryOverride?: ForeignKeyUIDisplayParams;
@@ -1908,6 +2687,38 @@ export interface ArrayUIDisplayParams extends PrimitiveUIBaseDisplayParams {
     /** Max items shown in display (rest truncated). */
     maxItems?: number;
 }
+/**
+ * How NEW items are added to an array field in an edit / inline-edit surface.
+ *
+ * When unset, the renderer resolves a default by item shape: a SIMPLE item
+ * (a primitive, or an object with a single prominent authored field — e.g. a
+ * checklist `{ label, done }`) defaults to {@link ArrayAddMode.QUICK_ADD}; a
+ * MULTI-field object defaults to {@link ArrayAddMode.APPEND_INLINE}.
+ *
+ * The key distinction is WHEN the new item is validated:
+ * - `APPEND_INLINE` validates AFTER append (a freshly-added required field shows
+ *   its error until filled);
+ * - `QUICK_ADD` / `DIALOG` validate BEFORE append (the list never holds a blank
+ *   or invalid item).
+ */
+export declare enum ArrayAddMode {
+    /**
+     * "+ Add" appends a blank, in-place editable item card/row; validated AFTER
+     * it is added. Best for rich objects the author edits in place.
+     */
+    APPEND_INLINE = "append-inline",
+    /**
+     * A single inline add-row (the item's primary field + Enter / "+"). The item
+     * is built from the row and validated BEFORE it is appended, so the list never
+     * holds a blank/invalid item. Best for simple items — checklists.
+     */
+    QUICK_ADD = "quick-add",
+    /**
+     * "+ Add" opens a dialog with the item's form; the item is validated on submit
+     * and then appended. Best for complex, multi-field items.
+     */
+    DIALOG = "dialog"
+}
 export interface ArrayUIEditParams extends PrimitiveUIBaseEditParams {
     /** Allow reordering via drag-and-drop in edit context. Set via `.isSortable()` convenience or directly. */
     isSortable?: boolean;
@@ -1915,11 +2726,41 @@ export interface ArrayUIEditParams extends PrimitiveUIBaseEditParams {
     dnd?: boolean;
     /** Show up/down manual move buttons. */
     upDownIcons?: boolean;
+    /**
+     * How new items are added (append-inline / quick-add / dialog). When unset,
+     * the renderer picks a default by item shape — see {@link ArrayAddMode}.
+     */
+    addMode?: ArrayAddMode;
+}
+/**
+ * How each item of an OBJECT array (`z.array(z.object({...}))`) is framed in
+ * BOTH display and edit surfaces.
+ *
+ * - `CARD` (default) — each item is a framed card (border + padding) with a
+ *   floating summary chip and a stacked column of its sub-fields. Best for
+ *   rich, multi-field items the author edits in place.
+ * - `ROW` — each item is a compact single-row: its sub-fields render inline
+ *   (boolean fields lead as compact toggles — the "☐" of a checklist — then
+ *   the primary field fills the row), reorder/remove controls inline, NO card
+ *   frame or floating chip. Best for lists of small objects — checklists,
+ *   tag/value pairs, key-value rows.
+ *
+ * Applies to object-array items only; primitive arrays already render as rows.
+ */
+export declare enum ArrayObjectItemLayout {
+    CARD = "card",
+    ROW = "row"
 }
 export interface ArrayUIParams {
     display?: ArrayUIDisplayParams;
     summaryOverride?: ArrayUIDisplayParams;
     edit?: ArrayUIEditParams;
+    /**
+     * How OBJECT-array items are framed (card vs compact row). Governs display
+     * AND edit/inline-edit rendering. Defaults to {@link ArrayObjectItemLayout.CARD}.
+     * No effect on primitive arrays. See {@link ArrayObjectItemLayout}.
+     */
+    objectItemLayout?: ArrayObjectItemLayout;
 }
 export interface ObjectUIDisplayParams extends PrimitiveUIBaseDisplayParams {
     /** Direction for rendering properties in display context. */
@@ -1933,6 +2774,230 @@ export interface ObjectUIParams {
     summaryOverride?: ObjectUIDisplayParams;
     edit?: ObjectUIEditParams;
 }
+/** @wildo_source:part:end zod.decorators.per-primitive-ui */
+/**
+ * @wildo_source:part:start zod.decorators.field-spec-params facet:layer:specification facet:family:companion facet:family:semantics
+ *
+ * Semantic specification parameter types for companion/specification overlays.
+ *
+ * These types are intentionally separate from both:
+ * - shared schema structural decorators (`*.schemas.ts`)
+ * - frontend UI decorators (`*.ui-behavior.tsx`)
+ *
+ * `{primitive}Spec()` calls belong in specification-side files such as
+ * `specifications/src/modules/<module>/resources/<resource>.resource.specification.ts`.
+ * They enrich schema fields with business meaning, importance, enum value
+ * semantics, relationship context, and import-oriented symbol references used by
+ * companion-time reasoning and code generation.
+ *
+ * These params should carry meaning that cannot be deterministically inferred
+ * from the Zod type, requiredness, or structural decorators alone.
+ */
+/**
+ * Relative weight of a semantic entry inside its owning resource.
+ *
+ * Not about technical optionality — tells the AI how central a field is
+ * to understanding the resource:
+ * - PRIMARY: core to understanding or using the resource correctly.
+ *   The AI should prioritize these in summaries, forms, and behavior generation.
+ * - CONTEXTUAL: provides useful context but is not central.
+ *   The AI can include or omit based on available space/attention.
+ *
+ * Default is CONTEXTUAL — only genuinely important fields should be explicitly
+ * flagged as PRIMARY.
+ */
+export declare enum FieldSemanticImportance {
+    PRIMARY = "primary",
+    CONTEXTUAL = "contextual"
+}
+/**
+ * Base field specification parameters shared by all `{primitive}Spec()` decorators.
+ *
+ * Carries the semantic delta that the Zod schema definition alone cannot convey:
+ * domain meaning, business relevance, and guidance for the AI companion.
+ *
+ * These values are **never rendered in the frontend UI** — they exist on the
+ * schema metadata for companion-time extraction only. The `{primitive}Spec()` calls
+ * happen in the specification overlay (which the frontend never imports), so
+ * the prose is attached to schema instances only in companion/test contexts.
+ *
+ * Do not duplicate information already expressed by the schema type, requiredness,
+ * enum values, or structural decorators. This is for meaning that is not derivable.
+ */
+export declare enum CodeSymbolKind {
+    SCHEMA = "schema",
+    ENUM = "enum",
+    FACTORY = "factory",
+    FUNCTION = "function",
+    CONFIG = "config",
+    TYPE = "type",
+    COMPONENT = "component",
+    UI_BEHAVIOR = "uiBehavior"
+}
+export declare enum CodeDeclarationKind {
+    TYPESCRIPT_ENUM = "typescriptEnum",
+    CONST_OBJECT = "constObject",
+    ZOD_ENUM = "zodEnum",
+    LITERAL_UNION = "literalUnion",
+    ZOD_SCHEMA = "zodSchema",
+    FUNCTION = "function",
+    INTERFACE = "interface",
+    TYPE_ALIAS = "typeAlias",
+    UNKNOWN = "unknown"
+}
+/**
+ * Public-import-oriented symbol reference used by semantic specifications.
+ *
+ * Downstream transposers/prompts should prefer these refs over file-path
+ * guesses so generated code imports the right public symbol.
+ */
+export interface CodeSymbolRef {
+    /** Package name to import from (for example `@wildo-ai/saas-models`). */
+    packageName: string;
+    /** Optional public subpath when the package root is not the import target. */
+    importPath?: string;
+    /** Literal exported symbol name. */
+    exportName: string;
+    /** High-level category of symbol. */
+    symbolKind: CodeSymbolKind;
+    /** More specific declaration family for code-generation handling. */
+    declarationKind?: CodeDeclarationKind;
+    /** Optional local-path hint for companion-side tooling/debugging. */
+    filePathHint?: string;
+    /** Extra caveats or usage notes for downstream prompts. */
+    notes?: string[];
+}
+/**
+ * Reference to one member of a declared enum/const-object vocabulary.
+ */
+export interface CodeEnumMemberRef {
+    /** Declared enum/const-object that owns the member. */
+    enumDeclaration: CodeSymbolRef;
+    /** Literal member name on that declaration (for example `USERS`). */
+    memberName: string;
+}
+export declare enum CollectionElementKind {
+    PRIMITIVE = "primitive",
+    ENUM = "enum",
+    FOREIGN_KEY = "foreignKey",
+    OBJECT = "object",
+    SCHEMA_REF = "schemaRef",
+    UNION = "union",
+    UNKNOWN = "unknown"
+}
+export declare enum CodePrimitiveKind {
+    STRING = "string",
+    NUMBER = "number",
+    BOOLEAN = "boolean",
+    DATE = "date",
+    DATETIME = "datetime",
+    TIME = "time",
+    MONEY = "money",
+    CODE = "code",
+    FILE = "file",
+    DURATION = "duration",
+    PHONE = "phone",
+    BIGDECIMAL = "bigdecimal",
+    UNKNOWN = "unknown"
+}
+/**
+ * Author-only metadata for array elements.
+ *
+ * `elementMeaning` (on `ArraySpecParams`) explains business semantics; this
+ * shape captures the **author-only** overlays that the framework cannot
+ * derive on its own: a public `enumDeclaration` for ENUM/UNION-of-ENUM
+ * branches and free-form `notes`.
+ *
+ * This shape intentionally excludes `kind`, `primitiveType`,
+ * `schemaDeclaration` and `foreignKeyTargetResource`. The schema and
+ * relationship declarations already provide those structural facts, so
+ * repeating them here would create two sources of truth.
+ *
+ * Authors keep `enumDeclaration` so the companion can render `Use member X
+ * from ENUM_NAME imported via PACKAGE` lines without re-walking the enum
+ * to find its public symbol — there is no Zod-side metadata that carries
+ * the public import path. UNION branches that are themselves enums also
+ * reuse the parent `enumDeclaration` (the dominant vocabulary).
+ */
+export interface ArrayElementTypeSpec {
+    /** Named enum/const-object declaration when elements use a vocabulary. */
+    enumDeclaration?: CodeSymbolRef;
+    /** Extra caveats for downstream coding prompts. */
+    notes?: string[];
+}
+export interface FieldSpecBaseParams {
+    /** Business meaning of the field: what it represents in the domain. */
+    meaning: string;
+    /** Why the AI should care about this field when authoring behavior or UI. */
+    whyItMatters?: string;
+    /** Relative weight of this field in the resource understanding. */
+    importance?: FieldSemanticImportance;
+}
+export interface StringSpecParams extends FieldSpecBaseParams {
+    /** Semantic role of the string content in the domain. */
+    semanticRole?: 'identifier' | 'name' | 'description' | 'content' | 'label' | 'code' | 'uri';
+}
+export interface NumberSpecParams extends FieldSpecBaseParams {
+    /** Business unit of the numeric value (e.g., "days", "percentage", "count"). */
+    unit?: string;
+}
+export type BooleanSpecParams = FieldSpecBaseParams;
+export interface DateSpecParams extends FieldSpecBaseParams {
+    /** Temporal semantic role (e.g., deadline, creation timestamp, expiration). */
+    temporalRole?: 'deadline' | 'creation' | 'expiration' | 'scheduled' | 'occurred' | 'modified';
+}
+export type DateTimeSpecParams = DateSpecParams;
+export type TimeSpecParams = FieldSpecBaseParams;
+/** Per-value semantic meaning for an enum field. */
+export interface EnumValueSpecConfig {
+    /** What this enum value means in business terms. */
+    meaning: string;
+}
+export interface EnumSpecParams extends FieldSpecBaseParams {
+    /** Per-value business semantics — keyed by enum value. */
+    values?: Record<string, EnumValueSpecConfig>;
+    /** Public declaration that owns the enum vocabulary. */
+    enumDeclaration?: CodeSymbolRef;
+}
+export type MoneySpecParams = FieldSpecBaseParams;
+export type CodeSpecParams = FieldSpecBaseParams;
+export type FileSpecParams = FieldSpecBaseParams;
+export type DurationSpecParams = FieldSpecBaseParams;
+export type PhoneSpecParams = FieldSpecBaseParams;
+export interface BigDecimalSpecParams extends FieldSpecBaseParams {
+    /** Business unit of the value (e.g., "currency", "weight", "rate"). */
+    unit?: string;
+}
+export interface ForeignKeySpecParams extends FieldSpecBaseParams {
+    /** Business meaning of the relationship this FK represents. */
+    relationshipContext?: string;
+}
+export interface ArraySpecParams extends FieldSpecBaseParams {
+    /** Business meaning of each element in the collection. */
+    elementMeaning?: string;
+    /** Structural/code-handling description of each array element. */
+    elementType?: ArrayElementTypeSpec;
+}
+/**
+ * Object-spec params are intentionally identical to the base shape.
+ *
+ * The decorator keeps a distinct semantic identity (an `objectSpec()` call
+ * marks a nested structure as field-spec-bearing for completeness checks),
+ * but it carries no extra structural metadata: nested-structure shape and
+ * any `schemaDeclaration` are derivable from the Zod object itself, and
+ * `structureRole` overlapped with the base `meaning` field with no clear
+ * delineation.
+ *
+ * The type intentionally adds no separate structural metadata: duplicating
+ * the base semantics would make nested-object authoring ambiguous.
+ */
+export type ObjectSpecParams = FieldSpecBaseParams;
+/** @wildo_source:part:end zod.decorators.field-spec-params */
+/**
+ * @wildo_source:part:start zod.decorators.decorator-vocabulary
+ *
+ * Canonical string identifiers for framework Zod field decorators (`ZodDecorator` enum).
+ */
 export declare enum ZodDecorator {
     IS_DB_INDEXED = "isDBIndexed",
     IS_FOREIGN_KEY = "isForeignKey",
@@ -1940,12 +3005,168 @@ export declare enum ZodDecorator {
     IS_NOT_EDITABLE = "isNotEditable",
     IS_SUMMARY_FIELD = "isSummaryField",
     IS_BACKEND_ONLY = "isBackendOnly",
+    IS_WRITE_ONLY_SECRET = "isWriteOnlySecret",
+    /**
+     * Impersonalization: per-field erasure-scrub treatment — a `RedactionType` value (string),
+     * read by the saas-models impersonalize writer. NOT the anonymous-user concept.
+     *
+     * Authored fluently: `z.string().nullish().impersonalizeWith(RedactionType.REMOVE)`. The
+     * treatment is REQUIRED and must be a non-empty string — a blank/missing value throws at
+     * decoration time rather than silently leaving the field untreated (an unscrubbed personal
+     * field). `addImpersonalizeWith(schema, treatment)` is the equivalent programmatic escape hatch;
+     * read the treatment back with `getImpersonalizeTreatment(schema)`.
+     *
+     * A `MASK` treatment may carry a field-specific mask value —
+     * `addImpersonalizeWith(schema, RedactionType.MASK, { maskValue: 'erased@erased.invalid' })` —
+     * for a CONSTRAINED string the default mask constant cannot satisfy; read it back with
+     * `getImpersonalizeMaskValue(schema)`. Both authoring doors normalize to
+     * {@link ImpersonalizeFieldParams}, which is what this decorator stores.
+     */
+    IMPERSONALIZE_WITH = "impersonalizeWith",
+    /**
+     * Portability: where this field's value CAME FROM — a `DataPortabilityProvenance` value (string),
+     * read by the subject-export orchestrator to decide GDPR Art. 20 scope.
+     *
+     * Authored fluently: `z.string().portabilityProvenance(DataPortabilityProvenance.SUBJECT_PROVIDED)`.
+     * The value is REQUIRED and must be a non-empty string — a blank/missing value throws at
+     * decoration time rather than storing an undeclared provenance, which an Art. 20 export treats as
+     * a REFUSAL rather than guessing. `addPortabilityProvenance(schema, provenance)` is the equivalent
+     * programmatic escape hatch; read it back with `getPortabilityProvenance(schema)`.
+     *
+     * A field that carries no declaration inherits its resource's `portabilityPolicy.defaultProvenance`;
+     * only fields differing from that default need this decorator.
+     *
+     * ⚠️ NOT a redaction or scrub concept, and NOT the anonymous-user concept. This says where a value
+     * ORIGINATED, for a DISCLOSURE decision. What happens to a value on ERASURE is
+     * {@link ZodDecorator.IMPERSONALIZE_WITH}, an orthogonal axis — a field is commonly both
+     * `SUBJECT_PROVIDED` and masked on erasure.
+     */
+    PORTABILITY_PROVENANCE = "portabilityProvenance",
+    /**
+     * Data categories: WHICH KINDS of personal data this field holds — one or more
+     * `PersonalDataCategory` values (strings), read by the compliance fact producer to answer the
+     * privacy-notice question "which categories of personal data do you process".
+     *
+     * Authored fluently: `email: z.email().dataCategories(PersonalDataCategory.CONTACT_DETAILS)`, or
+     * with an array when a field genuinely spans two —
+     * `.dataCategories([PersonalDataCategory.USER_CONTENT, PersonalDataCategory.SPECIAL_CATEGORY_HEALTH])`.
+     * The chokepoint normalizes either form to a deduped array, so every reader sees one shape.
+     * At least one category is REQUIRED and each must be a non-empty string: a blank declaration
+     * would read back as declared-but-meaningless, which is worse than absent, because absence is
+     * what the gap report is looking for. `addDataCategories(schema, categories)` is the equivalent
+     * programmatic escape hatch; read them back with `getDataCategories(schema)`.
+     *
+     * WHETHER each value is a real `PersonalDataCategory` member is checked by the resource factory's
+     * boot guard, which owns the enum — this layer knows only that non-empty strings were declared.
+     *
+     * ⚠️ Four adjacent axes, none of them this one. {@link ZodDecorator.IMPERSONALIZE_WITH} says what
+     * happens to the value on ERASURE; {@link ZodDecorator.PORTABILITY_PROVENANCE} says where it CAME
+     * FROM; `Compliance_DataClassification` is a SENSITIVITY ladder for flows-actors config; a
+     * retention class says HOW LONG it is kept. A single field is routinely all five at once, and
+     * none of the other four can answer "what kind of personal data is this".
+     *
+     * ⚠️ Do NOT declare a category on a field merely because its NAME suggests one. The decorator
+     * exists precisely so categories are never derived from identifiers: `email`, `phone` and
+     * `dateOfBirth` are suggestive while `notes` is not, and an inventory assembled by
+     * pattern-matching names is a guess whose misses are silently undisclosed. `CREDENTIALS` is the
+     * one category the producer derives, and it derives it from `.isPassword()` / `.isOtp()` /
+     * `.isWriteOnlySecret()` — markers the author wrote, not names it read.
+     *
+     * assurance-control: WILDO.PRIVACY.PERSONAL_DATA_INVENTORY — the application declares which
+     * categories of personal data each field holds
+     */
+    DATA_CATEGORIES = "dataCategories",
+    /**
+     * Audit evidence: this field's BEFORE/AFTER VALUES are recorded when a resource operation
+     * mutates it, on the `resource_operation_performed` audit event.
+     *
+     * Authored fluently: `appRoles: z.array(z.string()).isAuditEvidence()`. A pure marker — no
+     * parameters, no implied decorators. `addAuditEvidence(schema)` is the equivalent programmatic
+     * escape hatch; read it back with `isAuditEvidenceField(schema)`.
+     *
+     * **Mark the fields whose VALUES are the evidence, and only those.** The audit event always
+     * records the NAMES of every changed field (a field name is not personal data). This marker adds
+     * the values, and values are the part that must be justified: audit rows replicate to the per-org
+     * SIEM and to the immutable ledger, and the ledger cannot be scrubbed — so marking a personal-data
+     * field manufactures an unerasable copy of it, defeating the impersonalization/retention
+     * capability. Mark authority (`appRoles`, `roles`), lifecycle state (`status`), and scope-bearing
+     * fields; do NOT mark names, contact details, addresses, free text, or anything a data subject
+     * could ask to have erased.
+     *
+     * ⚠️ This is a WRITE-side claim — "when this field CHANGES, the change itself is evidence" — and
+     * is independent of the READ-side disclosure trail. The only disclosure trigger the framework has
+     * is `isBackendOnly({ isReturnedAtCreation: true })`, which fires one `FIELD_ACCESS` event when a
+     * server-minted secret is first exposed. A field can carry either, both, or neither. There is no
+     * general "audit every read of this field" marker — do not go looking for one.
+     *
+     * assurance-control: WILDO.SECRETS.DISCLOSURE_AUDIT
+     */
+    IS_AUDIT_EVIDENCE = "isAuditEvidence",
+    /**
+     * RAG source: this field's TEXT is a retrieval-corpus source. The framework chunks the value
+     * (extracting text first for file fields), stores the chunks in the application's OWN datastore
+     * (pgvector on PostgreSQL, `$vectorSearch` on MongoDB — never a third store), and erases them
+     * with the row: chunks are a derived-data tier keyed `(resourceType, resourceId, fieldName)`,
+     * so row deletion, field impersonalization, and subject erasure all reach them.
+     *
+     * Authored fluently: `z.string().ragSource()` or `z.string().ragSource({ chunkingStrategy:
+     * RAGChunkingStrategy.MARKDOWN, chunkSize: 1200, chunkOverlap: 150 })`. All params are optional
+     * and there is NO `enabled` flag — presence of the decorator IS the declaration (see
+     * {@link RagSourceConfiguration}). `addRagSource(schema, config?)` is the equivalent programmatic
+     * escape hatch; read the config back with `getRagSourceConfig(schema)`.
+     *
+     * **File fields are one text provider, not a separate mechanism.** `z_file({ ragSource: {...} })`
+     * registers THIS decorator on the schema it returns, so detection is uniform across plain-text
+     * and file-backed sources; file-only extraction knobs (OCR) live file-side in
+     * `FileSchemaOptions.textExtraction`, never here.
+     *
+     * **Refused companions, enforced in BOTH application orders at the decorator chokepoint:**
+     * - {@link ZodDecorator.IS_PASSWORD}, {@link ZodDecorator.IS_OTP},
+     *   {@link ZodDecorator.IS_WRITE_ONLY_SECRET}, {@link ZodDecorator.IS_EPHEMERAL} — a secret or
+     *   ephemeral value must never enter a retrieval corpus.
+     * - {@link ZodDecorator.TTL} — MongoDB honours `.ttl()` natively: rows vanish with NO application
+     *   code running, so derived chunks of a TTL row could never be erased with their parent (plan
+     *   `resource-rag-capability` DL3). The refusal lifts when a sweep-cascade reconciles chunk rows
+     *   against vanished parents.
+     *
+     * {@link ZodDecorator.IS_BACKEND_ONLY} composes: a backend-only field can be a corpus source —
+     * retrieval access is governed by the resource's own access binding, not by field visibility.
+     * {@link ZodDecorator.IMPERSONALIZE_WITH} composes too: an impersonalize decision deletes the
+     * field's chunks in the same decision.
+     */
+    RAG_SOURCE = "ragSource",
     IS_VIRTUAL = "isVirtual",
     IS_DISCRIMINATOR = "isDiscriminator",
     EXCLUDE_FROM_CREATE = "excludeFromCreate",
     EXCLUDE_FROM_UPDATE = "excludeFromUpdate",
     IS_UNIQUE = "isUnique",
     IS_PRIMARY_KEY = "isPrimaryKey",
+    /**
+     * Marks a field as a stable, declaration-side **business key** —
+     * an identity independent from the random `_id` (`isPrimaryKey`).
+     *
+     * Used by data seeding to safely upsert, upgrade and synchronize seeded rows.
+     * Unlike `isPrimaryKey`,
+     * a business key is mutable by users (renames are handled by a per-seed
+     * `renames: [{ from, to }]` migrator), and it carries no implicit
+     * decorators (`isPrimaryKey` is composite — `isBusinessKey` is purely
+     * a marker so it can co-exist with whatever editing semantics the field
+     * already has).
+     *
+     * Composite scope-aware identity uses the object-level
+     * `OBJECT_BUSINESS_KEY_SET` decorator on the schema root.
+     */
+    IS_BUSINESS_KEY = "isBusinessKey",
+    /**
+     * Object-level decorator declaring a **composite business key** for the
+     * schema (e.g. `(organizationId, templateKey)`). Schema-level analog of
+     * `IS_BUSINESS_KEY`. Used by the data-seeding subsystem.
+     *
+     * Field-level `IS_BUSINESS_KEY` and object-level `OBJECT_BUSINESS_KEY_SET`
+     * are **mutually exclusive** on the same schema — pick one identity model
+     * (single field vs composite). Mixing is rejected at decoration time.
+     */
+    OBJECT_BUSINESS_KEY_SET = "businessKeySet",
     TTL = "ttl",
     IS_PASSWORD = "isPassword",
     IS_OTP = "isOtp",
@@ -1970,7 +3191,23 @@ export declare enum ZodDecorator {
     BIGDECIMAL_UI = "bigDecimalUI",
     FOREIGN_KEY_UI = "foreignKeyUI",
     ARRAY_UI = "arrayUI",
-    OBJECT_UI = "objectUI"
+    OBJECT_UI = "objectUI",
+    STRING_SPEC = "stringSpec",
+    NUMBER_SPEC = "numberSpec",
+    BOOLEAN_SPEC = "booleanSpec",
+    DATE_SPEC = "dateSpec",
+    DATETIME_SPEC = "dateTimeSpec",
+    TIME_SPEC = "timeSpec",
+    ENUM_SPEC = "enumSpec",
+    MONEY_SPEC = "moneySpec",
+    CODE_SPEC = "codeSpec",
+    FILE_SPEC = "fileSpec",
+    DURATION_SPEC = "durationSpec",
+    PHONE_SPEC = "phoneSpec",
+    BIGDECIMAL_SPEC = "bigDecimalSpec",
+    FOREIGN_KEY_SPEC = "foreignKeySpec",
+    ARRAY_SPEC = "arraySpec",
+    OBJECT_SPEC = "objectSpec"
 }
 export type ZodDecorator_ParamsType = {
     [ZodDecorator.IS_DB_INDEXED]: undefined;
@@ -1979,12 +3216,43 @@ export type ZodDecorator_ParamsType = {
     [ZodDecorator.IS_NOT_EDITABLE]: NotEditableFieldParams | DecoratorUpdater<NotEditableFieldParams> | undefined;
     [ZodDecorator.IS_SUMMARY_FIELD]: SummaryFieldParams | DecoratorUpdater<SummaryFieldParams> | undefined;
     [ZodDecorator.IS_BACKEND_ONLY]: BackendOnlyFieldParams | DecoratorUpdater<BackendOnlyFieldParams> | undefined;
+    [ZodDecorator.IS_WRITE_ONLY_SECRET]: WriteOnlySecretFieldParams | DecoratorUpdater<WriteOnlySecretFieldParams> | undefined;
+    /**
+     * The field's impersonalization treatment. Accepts BOTH authored forms — a bare `RedactionType`
+     * value (the common case) or the full {@link ImpersonalizeFieldParams} object when a `MASK` needs
+     * a field-specific `maskValue`. The decorator chokepoint normalizes either to the params object.
+     * The treatment is typed as a plain string at this layer (zod-decorators sits below saas-models
+     * and cannot import `RedactionType`).
+     */
+    [ZodDecorator.IMPERSONALIZE_WITH]: string | ImpersonalizeFieldParams;
+    /**
+     * The field's portability provenance — a `DataPortabilityProvenance` value, typed as a plain
+     * string at this layer (zod-decorators sits below saas-models and cannot import the enum). One
+     * datum, so unlike {@link ZodDecorator.IMPERSONALIZE_WITH} there is no object authoring form to
+     * normalize; if a second axis is ever needed the chokepoint widens exactly as that one did.
+     */
+    [ZodDecorator.PORTABILITY_PROVENANCE]: string;
+    /**
+     * The field's personal-data categories — `PersonalDataCategory` values, typed as plain strings at
+     * this layer (zod-decorators sits below saas-models and cannot import the enum). Accepts a single
+     * value (the common case) or an array; the chokepoint normalizes either to a deduped array.
+     */
+    [ZodDecorator.DATA_CATEGORIES]: string | readonly string[];
+    [ZodDecorator.IS_AUDIT_EVIDENCE]: undefined;
+    /**
+     * RAG-source declaration. The config object is optional — `.ragSource()` with no argument is a
+     * complete declaration — and the chokepoint normalizes an omitted config to `{}` so every reader
+     * sees one stored shape (see {@link ZodDecorator_Types}).
+     */
+    [ZodDecorator.RAG_SOURCE]: RagSourceConfiguration | undefined;
     [ZodDecorator.IS_VIRTUAL]: VirtualFieldParams | DecoratorUpdater<VirtualFieldParams>;
     [ZodDecorator.IS_DISCRIMINATOR]: DiscriminatorFieldParams | DecoratorUpdater<DiscriminatorFieldParams> | undefined;
     [ZodDecorator.EXCLUDE_FROM_CREATE]: undefined;
     [ZodDecorator.EXCLUDE_FROM_UPDATE]: undefined;
     [ZodDecorator.IS_UNIQUE]: UniqueFieldParams | DecoratorUpdater<UniqueFieldParams> | undefined;
     [ZodDecorator.IS_PRIMARY_KEY]: undefined;
+    [ZodDecorator.IS_BUSINESS_KEY]: undefined;
+    [ZodDecorator.OBJECT_BUSINESS_KEY_SET]: BusinessKeySetParams | DecoratorUpdater<BusinessKeySetParams>;
     [ZodDecorator.TTL]: TtlFieldParams | DecoratorUpdater<TtlFieldParams>;
     [ZodDecorator.IS_PASSWORD]: undefined;
     [ZodDecorator.IS_OTP]: OtpFieldParams | DecoratorUpdater<OtpFieldParams> | undefined;
@@ -2010,6 +3278,22 @@ export type ZodDecorator_ParamsType = {
     [ZodDecorator.FOREIGN_KEY_UI]: ForeignKeyUIParams | DecoratorUpdater<ForeignKeyUIParams> | undefined;
     [ZodDecorator.ARRAY_UI]: ArrayUIParams | DecoratorUpdater<ArrayUIParams> | undefined;
     [ZodDecorator.OBJECT_UI]: ObjectUIParams | DecoratorUpdater<ObjectUIParams> | undefined;
+    [ZodDecorator.STRING_SPEC]: StringSpecParams | DecoratorUpdater<StringSpecParams> | undefined;
+    [ZodDecorator.NUMBER_SPEC]: NumberSpecParams | DecoratorUpdater<NumberSpecParams> | undefined;
+    [ZodDecorator.BOOLEAN_SPEC]: BooleanSpecParams | DecoratorUpdater<BooleanSpecParams> | undefined;
+    [ZodDecorator.DATE_SPEC]: DateSpecParams | DecoratorUpdater<DateSpecParams> | undefined;
+    [ZodDecorator.DATETIME_SPEC]: DateTimeSpecParams | DecoratorUpdater<DateTimeSpecParams> | undefined;
+    [ZodDecorator.TIME_SPEC]: TimeSpecParams | DecoratorUpdater<TimeSpecParams> | undefined;
+    [ZodDecorator.ENUM_SPEC]: EnumSpecParams | DecoratorUpdater<EnumSpecParams> | undefined;
+    [ZodDecorator.MONEY_SPEC]: MoneySpecParams | DecoratorUpdater<MoneySpecParams> | undefined;
+    [ZodDecorator.CODE_SPEC]: CodeSpecParams | DecoratorUpdater<CodeSpecParams> | undefined;
+    [ZodDecorator.FILE_SPEC]: FileSpecParams | DecoratorUpdater<FileSpecParams> | undefined;
+    [ZodDecorator.DURATION_SPEC]: DurationSpecParams | DecoratorUpdater<DurationSpecParams> | undefined;
+    [ZodDecorator.PHONE_SPEC]: PhoneSpecParams | DecoratorUpdater<PhoneSpecParams> | undefined;
+    [ZodDecorator.BIGDECIMAL_SPEC]: BigDecimalSpecParams | DecoratorUpdater<BigDecimalSpecParams> | undefined;
+    [ZodDecorator.FOREIGN_KEY_SPEC]: ForeignKeySpecParams | DecoratorUpdater<ForeignKeySpecParams> | undefined;
+    [ZodDecorator.ARRAY_SPEC]: ArraySpecParams | DecoratorUpdater<ArraySpecParams> | undefined;
+    [ZodDecorator.OBJECT_SPEC]: ObjectSpecParams | DecoratorUpdater<ObjectSpecParams> | undefined;
 };
 export type ZodDecorator_Types = {
     [ZodDecorator.IS_DB_INDEXED]: boolean;
@@ -2018,12 +3302,35 @@ export type ZodDecorator_Types = {
     [ZodDecorator.IS_NOT_EDITABLE]: NotEditableFieldParams | true;
     [ZodDecorator.IS_SUMMARY_FIELD]: SummaryFieldParams | true;
     [ZodDecorator.IS_BACKEND_ONLY]: BackendOnlyFieldParams | true;
+    [ZodDecorator.IS_WRITE_ONLY_SECRET]: WriteOnlySecretFieldParams | true;
+    /** Impersonalization scrub params — the treatment (a `RedactionType` value carried as an opaque
+     *  `string`, since zod-decorators sits below saas-models) plus an optional `MASK` override value.
+     *  ALWAYS the normalized object: the chokepoint widens a bare-string authoring form on the way in,
+     *  so every reader sees one shape. */
+    [ZodDecorator.IMPERSONALIZE_WITH]: ImpersonalizeFieldParams;
+    /** Portability provenance — a `DataPortabilityProvenance` value carried as an opaque `string`
+     *  (zod-decorators sits below saas-models). Stored exactly as authored; the chokepoint only
+     *  rejects blanks. */
+    [ZodDecorator.PORTABILITY_PROVENANCE]: string;
+    /** Personal-data categories — `PersonalDataCategory` values carried as opaque `string`s
+     *  (zod-decorators sits below saas-models). ALWAYS the normalized array, deduped and non-empty:
+     *  the chokepoint widens a bare single-value authoring form on the way in, so every reader sees
+     *  one shape and `getDataCategories` can answer "is this field categorized?" by presence alone. */
+    [ZodDecorator.DATA_CATEGORIES]: readonly string[];
+    /** Audit-evidence marker — stored as the bare `true` sentinel (parameterless, like IS_BUSINESS_KEY). */
+    [ZodDecorator.IS_AUDIT_EVIDENCE]: true;
+    /** RAG-source config — ALWAYS the normalized object ( `{}` when authored with no argument): the
+     *  chokepoint validates and normalizes on the way in, so every reader sees one shape and
+     *  `getRagSourceConfig` can answer "is this field a source?" by presence alone. */
+    [ZodDecorator.RAG_SOURCE]: RagSourceConfiguration;
     [ZodDecorator.IS_VIRTUAL]: VirtualFieldParams;
     [ZodDecorator.IS_DISCRIMINATOR]: DiscriminatorFieldParams | true;
     [ZodDecorator.EXCLUDE_FROM_CREATE]: true;
     [ZodDecorator.EXCLUDE_FROM_UPDATE]: true;
     [ZodDecorator.IS_UNIQUE]: UniqueFieldParams | true;
     [ZodDecorator.IS_PRIMARY_KEY]: true;
+    [ZodDecorator.IS_BUSINESS_KEY]: true;
+    [ZodDecorator.OBJECT_BUSINESS_KEY_SET]: BusinessKeySetParams;
     [ZodDecorator.TTL]: TtlFieldParams;
     [ZodDecorator.IS_PASSWORD]: true;
     [ZodDecorator.IS_OTP]: OtpFieldParams | true;
@@ -2049,7 +3356,29 @@ export type ZodDecorator_Types = {
     [ZodDecorator.FOREIGN_KEY_UI]: ForeignKeyUIParams;
     [ZodDecorator.ARRAY_UI]: ArrayUIParams;
     [ZodDecorator.OBJECT_UI]: ObjectUIParams;
+    [ZodDecorator.STRING_SPEC]: StringSpecParams;
+    [ZodDecorator.NUMBER_SPEC]: NumberSpecParams;
+    [ZodDecorator.BOOLEAN_SPEC]: BooleanSpecParams;
+    [ZodDecorator.DATE_SPEC]: DateSpecParams;
+    [ZodDecorator.DATETIME_SPEC]: DateTimeSpecParams;
+    [ZodDecorator.TIME_SPEC]: TimeSpecParams;
+    [ZodDecorator.ENUM_SPEC]: EnumSpecParams;
+    [ZodDecorator.MONEY_SPEC]: MoneySpecParams;
+    [ZodDecorator.CODE_SPEC]: CodeSpecParams;
+    [ZodDecorator.FILE_SPEC]: FileSpecParams;
+    [ZodDecorator.DURATION_SPEC]: DurationSpecParams;
+    [ZodDecorator.PHONE_SPEC]: PhoneSpecParams;
+    [ZodDecorator.BIGDECIMAL_SPEC]: BigDecimalSpecParams;
+    [ZodDecorator.FOREIGN_KEY_SPEC]: ForeignKeySpecParams;
+    [ZodDecorator.ARRAY_SPEC]: ArraySpecParams;
+    [ZodDecorator.OBJECT_SPEC]: ObjectSpecParams;
 };
+/** @wildo_source:part:end zod.decorators.decorator-vocabulary */
+/**
+ * @wildo_source:part:start zod.decorators.schema-metadata
+ *
+ * Per-field decorator metadata bag stored on schema instances under `SCHEMA_METADATA`.
+ */
 export interface CustomFieldMetadata {
     [ZodDecorator.IS_DB_INDEXED]?: ZodDecorator_Types[ZodDecorator.IS_DB_INDEXED];
     [ZodDecorator.IS_FOREIGN_KEY]?: ZodDecorator_Types[ZodDecorator.IS_FOREIGN_KEY];
@@ -2057,12 +3386,20 @@ export interface CustomFieldMetadata {
     [ZodDecorator.IS_NOT_EDITABLE]?: ZodDecorator_Types[ZodDecorator.IS_NOT_EDITABLE];
     [ZodDecorator.IS_SUMMARY_FIELD]?: ZodDecorator_Types[ZodDecorator.IS_SUMMARY_FIELD];
     [ZodDecorator.IS_BACKEND_ONLY]?: ZodDecorator_Types[ZodDecorator.IS_BACKEND_ONLY];
+    [ZodDecorator.IS_WRITE_ONLY_SECRET]?: ZodDecorator_Types[ZodDecorator.IS_WRITE_ONLY_SECRET];
+    [ZodDecorator.IMPERSONALIZE_WITH]?: ZodDecorator_Types[ZodDecorator.IMPERSONALIZE_WITH];
+    [ZodDecorator.PORTABILITY_PROVENANCE]?: ZodDecorator_Types[ZodDecorator.PORTABILITY_PROVENANCE];
+    [ZodDecorator.DATA_CATEGORIES]?: ZodDecorator_Types[ZodDecorator.DATA_CATEGORIES];
+    [ZodDecorator.IS_AUDIT_EVIDENCE]?: ZodDecorator_Types[ZodDecorator.IS_AUDIT_EVIDENCE];
+    [ZodDecorator.RAG_SOURCE]?: ZodDecorator_Types[ZodDecorator.RAG_SOURCE];
     [ZodDecorator.IS_VIRTUAL]?: ZodDecorator_Types[ZodDecorator.IS_VIRTUAL];
     [ZodDecorator.IS_DISCRIMINATOR]?: ZodDecorator_Types[ZodDecorator.IS_DISCRIMINATOR];
     [ZodDecorator.EXCLUDE_FROM_CREATE]?: ZodDecorator_Types[ZodDecorator.EXCLUDE_FROM_CREATE];
     [ZodDecorator.EXCLUDE_FROM_UPDATE]?: ZodDecorator_Types[ZodDecorator.EXCLUDE_FROM_UPDATE];
     [ZodDecorator.IS_UNIQUE]?: ZodDecorator_Types[ZodDecorator.IS_UNIQUE];
     [ZodDecorator.IS_PRIMARY_KEY]?: ZodDecorator_Types[ZodDecorator.IS_PRIMARY_KEY];
+    [ZodDecorator.IS_BUSINESS_KEY]?: ZodDecorator_Types[ZodDecorator.IS_BUSINESS_KEY];
+    [ZodDecorator.OBJECT_BUSINESS_KEY_SET]?: ZodDecorator_Types[ZodDecorator.OBJECT_BUSINESS_KEY_SET];
     [ZodDecorator.TTL]?: ZodDecorator_Types[ZodDecorator.TTL];
     [ZodDecorator.IS_PASSWORD]?: ZodDecorator_Types[ZodDecorator.IS_PASSWORD];
     [ZodDecorator.IS_OTP]?: ZodDecorator_Types[ZodDecorator.IS_OTP];
@@ -2088,6 +3425,22 @@ export interface CustomFieldMetadata {
     [ZodDecorator.FOREIGN_KEY_UI]?: ZodDecorator_Types[ZodDecorator.FOREIGN_KEY_UI];
     [ZodDecorator.ARRAY_UI]?: ZodDecorator_Types[ZodDecorator.ARRAY_UI];
     [ZodDecorator.OBJECT_UI]?: ZodDecorator_Types[ZodDecorator.OBJECT_UI];
+    [ZodDecorator.STRING_SPEC]?: ZodDecorator_Types[ZodDecorator.STRING_SPEC];
+    [ZodDecorator.NUMBER_SPEC]?: ZodDecorator_Types[ZodDecorator.NUMBER_SPEC];
+    [ZodDecorator.BOOLEAN_SPEC]?: ZodDecorator_Types[ZodDecorator.BOOLEAN_SPEC];
+    [ZodDecorator.DATE_SPEC]?: ZodDecorator_Types[ZodDecorator.DATE_SPEC];
+    [ZodDecorator.DATETIME_SPEC]?: ZodDecorator_Types[ZodDecorator.DATETIME_SPEC];
+    [ZodDecorator.TIME_SPEC]?: ZodDecorator_Types[ZodDecorator.TIME_SPEC];
+    [ZodDecorator.ENUM_SPEC]?: ZodDecorator_Types[ZodDecorator.ENUM_SPEC];
+    [ZodDecorator.MONEY_SPEC]?: ZodDecorator_Types[ZodDecorator.MONEY_SPEC];
+    [ZodDecorator.CODE_SPEC]?: ZodDecorator_Types[ZodDecorator.CODE_SPEC];
+    [ZodDecorator.FILE_SPEC]?: ZodDecorator_Types[ZodDecorator.FILE_SPEC];
+    [ZodDecorator.DURATION_SPEC]?: ZodDecorator_Types[ZodDecorator.DURATION_SPEC];
+    [ZodDecorator.PHONE_SPEC]?: ZodDecorator_Types[ZodDecorator.PHONE_SPEC];
+    [ZodDecorator.BIGDECIMAL_SPEC]?: ZodDecorator_Types[ZodDecorator.BIGDECIMAL_SPEC];
+    [ZodDecorator.FOREIGN_KEY_SPEC]?: ZodDecorator_Types[ZodDecorator.FOREIGN_KEY_SPEC];
+    [ZodDecorator.ARRAY_SPEC]?: ZodDecorator_Types[ZodDecorator.ARRAY_SPEC];
+    [ZodDecorator.OBJECT_SPEC]?: ZodDecorator_Types[ZodDecorator.OBJECT_SPEC];
     /** Range schema type (only present for range schemas) */
     rangeType?: RangeType;
     /** Full range schema configuration (only present for range schemas) */
@@ -2109,6 +3462,7 @@ export interface CustomFieldMetadata {
     /** Versioned foreign key configuration (only present for versioned foreign key schemas) */
     versionedForeignKeyConfig?: VersionedForeignKeySchemaMetadata;
 }
+/** @wildo_source:part:end zod.decorators.schema-metadata */
 type ZodenumInstance = ReturnType<typeof z.enum>;
 export type PrimitiveZodType = z.ZodString | z.ZodNumber | z.ZodBoolean | z.ZodDate | z.ZodEnum<any> | ZodenumInstance | ZodBrandedColorInstance | DecoratedPrimitiveZodType<z.ZodString> | DecoratedPrimitiveZodType<z.ZodNumber> | DecoratedPrimitiveZodType<z.ZodBoolean> | DecoratedPrimitiveZodType<z.ZodDate> | DecoratedPrimitiveZodType<z.ZodEnum<any>> | DecoratedPrimitiveZodType<ZodenumInstance>;
 export type SerializableZodSchema = {