@wildo-ai/zod-decorators 1.1.9 → 1.1.11

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

@@ -5,6 +5,7 @@ import { AvailableCurrency, CurrencyAllowed } from './currencies.shared.schemas'
 import { z } from 'zod';
 import { DecoratedPrimitiveZodType } from './zod.module-override';
 import { ZodBrandedColorInstance } from './zod-color';
+import type { DocumentSequenceParams } from './zod-document-sequence';
 /**
  * @wildo_source:part:start zod.decorators.schema-metadata
  *
@@ -146,9 +147,14 @@ export declare enum AutocompleteModifier {
     PAGER = "pager",
     WEBAUTHN = "webauthn"
 }
+/** @wildo_source:part:start zod.decorators.chrome-modes facet:layer:frontend facet:family:ui facet:surface:form facet:surface:display facet:audience:app-developer */
 /**
  * Chrome layout mode for display context (detail/read-only views).
  * Controls how the field wrapper (label, value, description) is arranged.
+ *
+ * Import from `@wildo-ai/zod-decorators`. Declared per field (`display.chromeMode` in its `…UI()`), per
+ * layout (`layout.defaultChromeMode.display`) or per section; a `<FieldTiles>` host sets TILE for the fields
+ * placed in it. Every mode may be given per breakpoint ({@link ResponsiveAware}).
  */
 export declare const DisplayChromeMode: {
     /** Label above, value below, description below value (default). */
@@ -166,11 +172,32 @@ export declare const DisplayChromeMode: {
     readonly COMPACT: "compact";
     /** No chrome at all — bare value output. */
     readonly HIDDEN: "hidden";
+    /**
+     * A FACT TILE: the name small and quiet above, the value below, on a bounded tile
+     * (`SurfaceVariant.TILE`) — the shape of a record's facts laid out as a grid, which is how they are
+     * read: scanned by name, compared by value.
+     *
+     * Hosted by `<FieldTiles>`, which lays the tiles on a grid and gives its fields this chrome by
+     * default; a field that declares its own `chromeMode` (a description declaring HIDDEN) keeps it and
+     * takes a whole row of the grid in that chrome. Wide values — lists, objects, files, long text, a
+     * reference shown as its record's summary card — take a whole row. A tile shows no description line;
+     * a description the field declares rides in the tile's tooltip.
+     *
+     * Not the SETTINGS_ROW read chrome, which stays the shape of a SETTINGS pane: there the value sits
+     * where its control will appear. On a record the row placed a value up to 300px from its name, and a
+     * record is not a settings pane.
+     */
+    readonly TILE: "tile";
 };
 export type DisplayChromeMode = typeof DisplayChromeMode[keyof typeof DisplayChromeMode];
 /**
  * Chrome layout mode for edit context (forms).
- * Superset of DisplayChromeMode with form-specific modes (SETTINGS_ROW, RELAXED).
+ *
+ * NOT a superset of {@link DisplayChromeMode}, though most members share a name and a value: RELAXED
+ * exists only here (a form's generous onboarding spacing), and TILE exists only on the display side (a
+ * record's facts read as tiles; a form control is never a tile). A shared name is not always a shared
+ * geometry — edit INLINE puts the control BEFORE its label (a switch, a checkbox), display INLINE puts the
+ * name before its value — so read each member's own line.
  */
 export declare const EditChromeMode: {
     /** Label above, control below, description + error below control (default). */
@@ -198,6 +225,7 @@ export type ResponsiveChromeMode = EditChromeMode | Partial<Record<ViewportBreak
  * Used for chromeMode, forceHide, and other properties that may vary by viewport.
  */
 export type ResponsiveAware<T> = T | Partial<Record<ViewportBreakpoint, T>>;
+/** @wildo_source:part:end zod.decorators.chrome-modes */
 export type FormFieldSchemaTypeComponents = {
     [K in FieldSchemaType]: K extends FieldSchemaType.STRING ? FormFieldComponent.INPUT | FormFieldComponent.TEXTAREA | FormFieldComponent.SELECT | FormFieldComponent.RADIO_GROUP | FormFieldComponent.DATE | FormFieldComponent.TIME | FormFieldComponent.DATETIME : K extends FieldSchemaType.NUMBER ? FormFieldComponent.INPUT | FormFieldComponent.SLIDER | FormFieldComponent.SELECT | FormFieldComponent.RADIO_GROUP : K extends FieldSchemaType.BIGINT ? FormFieldComponent.INPUT : K extends FieldSchemaType.BOOLEAN ? FormFieldComponent.SWITCH | FormFieldComponent.CHECKBOX | FormFieldComponent.SELECT | FormFieldComponent.RADIO_GROUP : K extends FieldSchemaType.ENUM ? FormFieldComponent.SELECT | FormFieldComponent.RADIO_GROUP : K extends FieldSchemaType.DATE ? FormFieldComponent.DATE | FormFieldComponent.DATETIME | FormFieldComponent.INPUT : K extends FieldSchemaType.TIME ? FormFieldComponent.TIME | FormFieldComponent.INPUT : K extends FieldSchemaType.DATETIME ? FormFieldComponent.DATETIME | FormFieldComponent.INPUT : K extends FieldSchemaType.RANGE_NUMBER ? FormFieldComponent.RANGE_SLIDER : K extends FieldSchemaType.RANGE_DATE ? FormFieldComponent.DATE_RANGE : K extends FieldSchemaType.RANGE_DATETIME ? FormFieldComponent.DATETIME_RANGE : K extends FieldSchemaType.RANGE_TIME ? FormFieldComponent.TIME_RANGE : K extends FieldSchemaType.RANGE_BIGDECIMAL ? FormFieldComponent.BIGDECIMAL_RANGE : K extends FieldSchemaType.RANGE_MONEY ? FormFieldComponent.MONEY_RANGE : K extends FieldSchemaType.MONEY ? FormFieldComponent.INPUT : K extends FieldSchemaType.DURATION ? FormFieldComponent.DURATION : K extends FieldSchemaType.PHONE ? FormFieldComponent.PHONE : K extends FieldSchemaType.ADDRESS ? FormFieldComponent.ADDRESS : K extends FieldSchemaType.BIGDECIMAL ? FormFieldComponent.INPUT : K extends FieldSchemaType.CODE ? FormFieldComponent.TEXTAREA : K extends FieldSchemaType.FILE ? FormFieldComponent.INPUT : K extends FieldSchemaType.ARRAY ? FormFieldComponent.CHECKBOX_GROUP | FormFieldComponent.SELECT : K extends FieldSchemaType.SET ? FormFieldComponent.INPUT | FormFieldComponent.CHECKBOX_GROUP | FormFieldComponent.SELECT : K extends FieldSchemaType.TUPLE ? FormFieldComponent.INPUT : K extends FieldSchemaType.UNKNOWN ? FormFieldComponent.INPUT : never;
 };
@@ -249,7 +277,8 @@ export type DefaultDisplayComponentForSchemaType<T extends FieldSchemaType> = Di
  * - DEFAULT: Standard section with border and padding
  * - CARD: Wrapped in a card container with shadow
  * - GHOST: Minimal container without visual styling
- * - COLLAPSIBLE: Expandable/collapsible section with trigger
+ * - COLLAPSIBLE: ONE section behind its own open/close trigger. `defaultFocus={false}` starts it
+ *   closed — the mode for an aside a reader reveals on request
  *
  * **Container modes** (sections sharing the same mode are grouped together,
  * rendered at the position of the first occurrence):
@@ -264,9 +293,12 @@ export type DefaultDisplayComponentForSchemaType<T extends FieldSchemaType> = Di
  * - VERTICAL_TABS: Vertical tabs (side navigation)
  * - PILLS: Pill/segment navigation (compact)
  *
- * @category Expandable (toggle section visibility)
- * - ACCORDION: Each section independently collapsible
- * - EXPANDABLE: "Show more" button reveals additional sections
+ * @category Disclosure over a GROUP of sections
+ * - ACCORDION: one trigger per section; single-open unless `allowMultiple`
+ * - EXPANDABLE: truncation, not a toggle — the first `initialVisibleCount` (default 3) sections of
+ *   the group show, and one "Show more" button reveals the rest. A group of `initialVisibleCount`
+ *   sections or fewer never truncates, so EXPANDABLE over a single section renders it always open
+ *   with no button: to hide one section until asked, use COLLAPSIBLE (#2197)
  *
  * @category Guided (sequential, with indicators)
  * - STEPPER: Step-by-step with step indicators
@@ -498,11 +530,32 @@ export declare const StringEditMode: {
      * `/application-config` (`organizationRoles`). Each option reads as the role's word from the `roles` labels. Use it
      * for any string field that names ONE role a setting admits (a reader role, a routing role), so an administrator
      * picks a role that exists instead of typing a key exactly. Falls back to a text input when the backend publishes no
-     * table. The server remains the control: it decides what holding the role grants.
+     * table. An operation's `requestFieldOffers` narrows the roles further (#2778), and `organizationRoleTable:
+     * ANOTHER_ORGANIZATION` (see {@link OrganizationRoleTable}) makes it a role held in another organization, offered from
+     * the operation's offer alone. The server remains the control: it decides what holding the role grants.
      */
     readonly ORGANIZATION_ROLE: "organization_role";
 };
 export type StringEditMode = typeof StringEditMode[keyof typeof StringEditMode];
+/**
+ * WHOSE role table an `ORGANIZATION_ROLE` picker reads (#2778).
+ *
+ * - `CURRENT_ORGANIZATION` (the default): the role is one of the organization being administered, so the picker offers
+ *   that organization's table (the application's organization roles as its type narrows them).
+ * - `ANOTHER_ORGANIZATION`: the role names a role in ANOTHER organization, such as the role a representing organization
+ *   proposes to hold in the granting one. The current organization's table is then the wrong population, so the picker
+ *   offers only the values its operation's request field offer gives (`requestFieldOffers`), and is a text input
+ *   while there is no offer.
+ *
+ * A const object, not an enum, like every edit- and display-mode vocabulary it sits among (`StringEditMode` above):
+ * these values are written inside `stringUI({ edit })` literals, and one vocabulary of the family declared differently
+ * would be the one a reader trips on. Converting the family is one decision for all of them, not a per-member one.
+ */
+export declare const OrganizationRoleTable: {
+    readonly CURRENT_ORGANIZATION: "current_organization";
+    readonly ANOTHER_ORGANIZATION: "another_organization";
+};
+export type OrganizationRoleTable = typeof OrganizationRoleTable[keyof typeof OrganizationRoleTable];
 /**
  * Number display modes for rendering number values
  */
@@ -559,10 +612,28 @@ export type BigDecimalEditMode = typeof BigDecimalEditMode[keyof typeof BigDecim
  * Enum display modes for rendering enum values
  */
 export declare const EnumDisplayMode: {
+    /** The value's word alone, in the voice of the text around it — for a value with no colour to carry. */
     readonly TEXT: "text";
+    /** A soft pill in the value's colour. A value with no icon of its own leads with a state dot. */
     readonly BADGE: "badge";
+    /**
+     * The value's icon alone, on a pill in its colour; the word is read to assistive technology and shown on
+     * hover. The compact form for a summary line (`summaryOverride: { displayMode: ICON }`) where the icon is
+     * already known to the reader. A value with no `icon` of its own shows a dot in its colour instead.
+     */
     readonly ICON: "icon";
+    /** The word on a small card of its own — for a value that is the subject of a surface, not one fact among several. */
     readonly CARD: "card";
+    /**
+     * A tone dot and the label, with no chip around them — the QUIET form of a coloured value.
+     *
+     * For the second coloured value beside a status: priority next to status, severity next to state.
+     * Two filled pills side by side compete for the same attention; one pill and one dot keep the
+     * status as the thing that is read first. The dot fills with the value's colour at full strength and
+     * the label takes the same tone, so the value still reads without the chip. A value whose colour is
+     * the neutral one renders its dot and label muted.
+     */
+    readonly DOT: "dot";
 };
 export type EnumDisplayMode = typeof EnumDisplayMode[keyof typeof EnumDisplayMode];
 /**
@@ -859,7 +930,7 @@ export declare enum RangeType {
 export type RangeTypeMapping = {
     [RangeType.NUMBER]: number;
     [RangeType.DATE]: Date;
-    [RangeType.DATETIME]: string;
+    [RangeType.DATETIME]: Date;
     [RangeType.TIME]: string;
     [RangeType.BIGDECIMAL]: string;
     [RangeType.MONEY]: {
@@ -1372,10 +1443,15 @@ export interface FileMultipleFilePolicy {
  *   <scope>/<scopeId>/                    ← the tenant segments (organizations/<id>, user_self/<id>,
  *                                            or application/<applicationId>)
  *   [folderPath(ctx)/]                    ← dynamic folder path
- *   <fileName(ctx) | fileId>              ← explicit name or UUID fallback
+ *   [<fileId>/]<fileName(ctx)> | <fileId> ← explicit name under the file's own id, or the id alone
  * ```
  *
- * Only the last two lines are authored here. Everything above them is derived by the framework and
+ * A name is display metadata, never the identity of the stored object (#2901): when a name is resolved, the file's id
+ * is the level directly above it, so two files of one field never share a key, whatever the name says. A static
+ * `fileName` once gave every file of the field one key, and a regenerated file was written over the bytes its
+ * predecessor still pointed at.
+ *
+ * Only `folderPath` and the name are authored here. Everything above them is derived by the framework and
  * is identical on every path-based provider, because `<scope>/<scopeId>` is what makes one tenant's
  * blobs a PREFIX — the unit erasure, orphan sweeps and per-tenant listing operate on.
  *
@@ -1420,8 +1496,8 @@ export interface FilePathBinding {
      */
     folderPath?: string | ((context: FilePathBindingContext) => string);
     /**
-     * File name for single `z_file()` fields (non-multiple).
-     * When omitted, falls back to the fileId (UUID-based, legacy behavior).
+     * File name for single `z_file()` fields (non-multiple): the stored object's last segment, placed under the file's own
+     * id, so a static name is safe (#2901). When omitted, the key is the fileId alone.
      *
      * - `string` — static name; can include `{ext}` placeholder.
      * - `function` — receives binding context and returns the file name.
@@ -2163,6 +2239,44 @@ export interface ImpersonalizeFieldParams {
      */
     maskValue?: string;
 }
+/**
+ * The optional second argument of `.dataCategories(categories, options)` (#2119).
+ *
+ * Kept as an options bag, like `impersonalizeWith(treatment, options)`, so a second qualifier lands
+ * here instead of as a new positional argument.
+ */
+export interface DataCategoriesOptions {
+    /**
+     * The condition under which this field's value is personal data at all — a `PersonalDataCondition`
+     * value carried as an opaque string (zod-decorators sits below saas-models and cannot reference
+     * the enum). Absent means the field is personal data on every row.
+     *
+     * The case it exists for: a field naming the PARTY a row describes — a tenant organization, a
+     * customer account — is a natural person's data when that party is an individual (a sole trader)
+     * and not when it is a company. Declaring the categories with this condition lets a privacy
+     * notice say "where the customer is an individual" instead of choosing between two false
+     * sentences. Whether the value is a real member is checked by the saas-models boot guard.
+     */
+    personalOnlyWhen?: string;
+    /**
+     * `true` when the field names a party OTHER than the one the row is about: a copy of another organization's name kept
+     * on a cost aggregate, a relationship, a membership or an access grant (#2535). Absent on a field naming the row's own
+     * party, such as an organization's or a customer account's own name.
+     *
+     * WHOSE data a field is, which is a different question from WHEN it is personal (`personalOnlyWhen`), so it is
+     * declared separately. Only one reader asks it: the `RETAIN_ONLY` contradiction guard, which admits a conditional copy
+     * of another party's name on a resource stating "no personal data about its own subject", and still refuses the row's
+     * own party's name there. Every other reader (erasure, export, the notice) counts the field exactly as before.
+     */
+    aboutAnotherParty?: boolean;
+}
+/**
+ * What `.dataCategories()` STORES: the normalized form of either authoring shape. The categories
+ * are always a deduped, non-empty array; the condition is present only when one was declared.
+ */
+export interface DataCategoriesFieldParams extends DataCategoriesOptions {
+    categories: readonly string[];
+}
 /**
  * Parameters passed to virtual field calculation functions.
  * The `utils` is typed as `any` in shared-lib but will be properly typed at runtime in backend-lib.
@@ -2187,16 +2301,56 @@ export interface VirtualFieldCalculationParams<TObject = any, TContext = any, TU
      */
     utils: any;
 }
+/**
+ * Parameters passed to a virtual field's BATCHED calculation ({@link VirtualFieldParams.calculateMany}): the rows of
+ * one list, in the order the list returns them.
+ */
+export interface VirtualFieldBatchCalculationParams<TObject = any> {
+    /** The rows to compute the field for, in list order. */
+    currentObjects: readonly TObject[];
+    /** The execution context of the request listing them. */
+    executionContext: any;
+    /** The same utility services as {@link VirtualFieldCalculationParams.utils}. */
+    utils: any;
+}
 /**
  * Parameters for the isVirtual decorator.
  * Virtual fields are computed at runtime and not stored in the database.
  */
 export interface VirtualFieldParams<TObject = any, TResult = any> {
     /**
-     * The calculation function that computes this virtual field's value.
-     * Called at runtime by VirtualFieldsBackendService with injected utilities.
+     * The calculation function that computes this virtual field's value for ONE row.
+     * Called at runtime by VirtualFieldsBackendService with injected utilities: on a READ, and on a list row when the
+     * field declares no {@link calculateMany}.
      */
     calculate: (params: VirtualFieldCalculationParams<TObject>) => TResult | Promise<TResult>;
+    /**
+     * The BATCHED form: computes the field for every row of a list in ONE call (#2631). Declare it when the field reads
+     * another resource, so a page of N rows reads that resource once (one query over the rows' keys) instead of N times.
+     *
+     * - Return one value per row, in the same order: an array exactly as long as `currentObjects`. Any other length is
+     *   treated as a failure of the whole batch, like a throw.
+     * - A failing batch gives every row `undefined` when the computation is fault-tolerant (the list default) and throws
+     *   otherwise, exactly as a failing `calculate` does for its one row.
+     * - Used wherever several rows are computed together: a LIST or SEARCH page, and a relationship's children in a
+     *   resource context. One row (a READ) still goes through `calculate`, so the two must give the same value for the same row:
+     *   write the derivation once and call it from both.
+     * - Ignored for a field that declares `needsObjectContext` or `needsUserContext`: those contexts are resolved per
+     *   row, so such a field is computed by `calculate` alone.
+     *
+     * @example
+     * ```ts
+     * tenantStatus: z.string().optional().isVirtual({
+     *   dependencies: ['organizationId'],
+     *   calculate: async ({ currentObject, utils }) => (await statusesOf(utils, [currentObject.organizationId])).get(currentObject.organizationId),
+     *   calculateMany: async ({ currentObjects, utils }) => {
+     *     const statuses = await statusesOf(utils, currentObjects.map((row) => row.organizationId));
+     *     return currentObjects.map((row) => statuses.get(row.organizationId));
+     *   },
+     * }),
+     * ```
+     */
+    calculateMany?: (params: VirtualFieldBatchCalculationParams<TObject>) => readonly TResult[] | Promise<readonly TResult[]>;
     /**
      * If true, the objectContext (parent/child relationships) will be passed to calculate().
      * Setting this to true has a performance cost as it requires fetching related resources.
@@ -2208,8 +2362,8 @@ export interface VirtualFieldParams<TObject = any, TResult = any> {
      */
     needsUserContext?: boolean;
     /**
-     * Optional list of field names this virtual field depends on.
-     * Used for documentation and potential future optimizations.
+     * The stored fields this virtual field reads from its row. The repository adds them to the read projection, so
+     * `calculate` / `calculateMany` receive them even on a SUMMARY row where they are not themselves summary fields.
      */
     dependencies?: string[];
 }
@@ -2265,8 +2419,14 @@ export interface UniqueFieldParams {
      */
     compoundWith?: string;
     /**
-     * Whether to allow null values without triggering uniqueness.
-     * MongoDB unique indexes exclude null by default when sparse is true.
+     * Whether a row WITHOUT a value (the field absent or `null`) is left out of the uniqueness, so any number of such rows
+     * may coexist. PostgreSQL plans it as a unique constraint whose NULLs are distinct. MongoDB builds it as a partial
+     * filter that bounds the field from below in its own type (`{ field: { $gte: '' } }` for a string), which leaves out a
+     * null as well as a missing value (#2582): MongoDB's own `sparse: true` would still index a stored null. The one
+     * exception is a field whose type has no lowest value (an array, a free-form value), whose filter is
+     * `{ $exists: true }` and so indexes a stored null.
+     *
+     * `false` makes rows without a value collide with each other on both stores (`NULLS NOT DISTINCT` on PostgreSQL).
      * @default true
      */
     sparse?: boolean;
@@ -2336,6 +2496,29 @@ export interface BusinessKeySetParams {
      */
     conflictMessageReference?: string;
 }
+/**
+ * Parameters for the object-level `isResourceReference({ targetSet })` decorator (#2471).
+ *
+ * The decorated object names ONE row of a resource whose type is not fixed: its `resourceType` member is the
+ * resource's name and its `resourceId` member the row's id. Unlike `.isForeignKey()` it declares no relationship
+ * and changes nothing about storage: the two members stay plain strings, and the referenced resource is only
+ * known at run time. It is what lets a form offer the resource types first and then the rows of the chosen one.
+ *
+ * `targetSet` names WHICH resource types the reference may name. It is a member of a vocabulary owned by the
+ * layer that knows the types (`ResourceReferenceTargetSet` in `@wildo-ai/saas-models`), and the backend publishes
+ * each set's members on `/application-config` (`resourceReferenceTargets`), derived from what the application
+ * declares. A string here because this package sits below that vocabulary, as `dataCategories` does.
+ *
+ * The server stays the control: a reference is accepted only where the service that owns the field admits it.
+ *
+ * @example
+ * export const WorkUnitRefSchema = z.strictObject({ resourceType: z.string(), resourceId: z.string() })
+ *   .isResourceReference({ targetSet: ResourceReferenceTargetSet.WORK_UNIT_CASES });
+ */
+export interface ResourceReferenceParams {
+    /** The set of resource types the reference may name. */
+    targetSet: 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
@@ -2354,7 +2537,7 @@ export interface BusinessKeySetParams {
  * enforced on both. Do NOT read the MongoDB index as the mechanism and conclude the declaration is
  * inert elsewhere.
  *
- * Two consequences worth knowing before you declare one:
+ * Consequences worth knowing before you declare one:
  * - the sweep is deliberately bounded per run, so a table receiving rows faster than they expire
  *   stays above its target until the rate changes; it reports when it stops early;
  * - a resource CANNOT declare both a lifetime and retrieval-source fields (`.ragSource()`). That
@@ -2363,7 +2546,16 @@ export interface BusinessKeySetParams {
  * - a resource scoped to an ORGANIZATION cannot declare a lifetime at all. For the same reason
  *   no legal hold could suspend the deletion, and a hold on an organization covers every row of
  *   it. A lifetime is for application-level plumbing; tenant data binds a retention class
- *   (`retentionBinding`), whose sweep deletes through the service layer and skips held rows.
+ *   (`retentionBinding`), whose sweep deletes through the service layer and skips held rows;
+ * - a resource that another resource's ENABLED `onParentDelete` edge points at cannot declare a lifetime, whatever the
+ *   strategy (DELETE, IMPERSONALIZE_AND_RETAIN, REFUSE_WHILE_CHILDREN_EXIST) or mode (IMMEDIATE, LAZY). It is refused at startup: an expired
+ *   row leaves with none of its lifecycle running, so its children would outlive it, keep their personal data, or be
+ *   walked past. Bind a retention class instead; its sweep deletes through the service layer, which runs the edges;
+ * - the field must be a TOP-LEVEL field of the main schema (always an object) or of an inheritance level: a lifetime on
+ *   a nested field is refused, since every guard above reads top-level fields while MongoDB would expire rows by the
+ *   nested path natively. An inheritance variant MAY give its rows their own lifetime, on a field only it declares;
+ *   one field has one lifetime, so a field declared with a `.ttl()` in one schema and differently in another (another
+ *   window, or none) is refused (MongoDB keeps one TTL index per path).
  *
  * This is unrelated to `retentionPolicy`, which decides what an ERASURE does to a row that must
  * SURVIVE. This one decides whether the row lives at all.
@@ -2434,7 +2626,7 @@ export interface SummaryFieldParams {
      * // Field definition:
      * userId: z.string().isForeignKey().isSummaryField({ populate: true })
      *
-     * // LIST/SEARCH response will include:
+     * // A LIST or SEARCH response will include:
      * {
      *   _id: "123",
      *   userId: "user-456",
@@ -2665,9 +2857,9 @@ export interface PrimitiveUIBaseDisplayParams {
     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.
+     * whenever its value is empty — null, undefined, a blank string, an empty array or
+     * an empty plain object. `false` and `0` are answers, never empty, and so is a date.
+     * 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
@@ -2675,9 +2867,21 @@ export interface PrimitiveUIBaseDisplayParams {
      * `AutoEmptyValue.HIDDEN` — use it to keep optional metadata (a job title, a
      * secondary contact) from cluttering a read view when unset.
      *
+     * UNSET means `true` inside a `<FieldTiles>` host (a record's facts — an empty tile
+     * is clutter there, and the generated read view uses the host when the layout
+     * declares no `defaultChromeMode.display`) and `false` everywhere else. So a field
+     * whose emptiness is itself worth seeing on a record ("this contact has no email")
+     * declares `hideWhenEmpty: false` explicitly. A field the reader can edit IN PLACE
+     * keeps its empty tile without saying so — hiding it would remove the only way to
+     * fill it there. And the default reaches only the fields placed in the host: the
+     * items of a list and the members of an object a tile shows are its content, not
+     * facts of the grid, and follow their own decorators.
+     *
      * @example
      * // Hide the "Title" row on the profile read view until the user sets one:
      * schemaShape.title.stringUI({ display: { hideWhenEmpty: true } })
+     * // Keep an empty email visible as a tile — the gap is the information:
+     * schemaShape.email.stringUI({ display: { hideWhenEmpty: false } })
      */
     hideWhenEmpty?: boolean;
     /**
@@ -2811,6 +3015,8 @@ export interface StringUIEditParams extends PrimitiveUIBaseEditParams {
     editMode?: StringEditMode;
     /** Number of rows for TEXTAREA editMode. */
     textareaRows?: number;
+    /** ORGANIZATION_ROLE editMode: whose role table the picker reads. Default `CURRENT_ORGANIZATION`. See {@link OrganizationRoleTable}. */
+    organizationRoleTable?: OrganizationRoleTable;
 }
 export interface StringUIParams {
     display?: StringUIDisplayParams;
@@ -2847,7 +3053,7 @@ export interface NumberUIParams {
     edit?: NumberUIEditParams;
 }
 export interface EnumUIDisplayParams extends PrimitiveUIBaseDisplayParams {
-    /** Display renderer. TEXT | BADGE | ICON | CARD. */
+    /** Display renderer — one of {@link EnumDisplayMode}, whose members each say when they are the right one. */
     displayMode?: EnumDisplayMode;
 }
 export interface EnumUIEditParams extends PrimitiveUIBaseEditParams {
@@ -3102,12 +3308,15 @@ export interface ForeignKeyUIParams {
     edit?: ForeignKeyUIEditParams;
 }
 /**
- * List marker treatment for a PRIMITIVE array's display items.
+ * How each item of an array's display announces itself as one of several: bare lines, bullets, a rule
+ * between object entries, or a wrapping row of chips. The members apply to different entries (primitive
+ * lines, object entries, strings), which each member's own line states.
  *
- * Its own enum rather than a new `DisplayDirection` member on purpose: direction answers "which
- * axis do items flow on", marker style answers "does each item announce itself as one of several" —
- * merging them would make `BULLETS × horizontal` an unrepresentable-but-meaningful combination and
- * overload an enum that alignment code also reads.
+ * Its own enum rather than a new `DisplayDirection` member on purpose: direction answers "which axis do
+ * items flow on", list style answers "how is each item set apart" — merging them would make
+ * `BULLETS × horizontal` an unrepresentable-but-meaningful combination and overload an enum that
+ * alignment code also reads. The one member that decides the flow itself is CHIPS: chips always wrap on
+ * a line, so it ignores `displayMode`.
  */
 export declare enum ArrayListStyle {
     /** Bare stacked values — the historical default. */
@@ -3123,7 +3332,17 @@ export declare enum ArrayListStyle {
      * bounded region, a card per entry is a third frame around content that has two. Unlike
      * {@link ArrayListStyle.BULLETS}, which is for primitive lines, this is for entries.
      */
-    SEPARATED = "separated"
+    SEPARATED = "separated",
+    /**
+     * Each entry a small neutral chip, the chips wrapping on one line — the shape of TAGS, labels and
+     * keywords: short, unordered, read as a set.
+     *
+     * Applies to STRING entries. A list of enum values already renders each value in its own display
+     * mode (a badge, a dot), so a chip around it would be a frame around a frame; any other entry type
+     * falls back to the horizontal flow. Without it, two tags under `SEPARATED` stacked one above the
+     * other at the right edge of a settings row, 81px tall for two words.
+     */
+    CHIPS = "chips"
 }
 export interface ArrayUIDisplayParams extends PrimitiveUIBaseDisplayParams {
     /** Direction for rendering items in display context. */
@@ -3131,9 +3350,10 @@ export interface ArrayUIDisplayParams extends PrimitiveUIBaseDisplayParams {
     /** Max items shown in display (rest truncated). */
     maxItems?: number;
     /**
-     * Marker treatment for PRIMITIVE items (see {@link ArrayListStyle}). No effect on object arrays —
-     * their items are cards/rows, not list lines — and no effect on horizontal flow, where markers
-     * have no line to anchor to.
+     * How each item announces itself as one of several (see {@link ArrayListStyle}, whose members each
+     * state the entries they apply to): PLAIN and BULLETS mark primitive lines, SEPARATED rules object
+     * entries, CHIPS renders string entries as a wrapping row of chips and so decides the flow itself.
+     * The line markers have no effect on horizontal flow, where there is no line to anchor to.
      */
     listStyle?: ArrayListStyle;
 }
@@ -3548,6 +3768,11 @@ export declare enum ZodDecorator {
      * 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.
      *
+     * An optional second argument, `{ personalOnlyWhen }` ({@link DataCategoriesOptions}), says the
+     * field is personal data only under a `PersonalDataCondition` — the field naming a customer
+     * organization, which is a person's data only when that customer is a sole trader (#2119). The
+     * field still counts as personal for every guard; only the privacy notice words it conditionally.
+     *
      * ⚠️ 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
@@ -3593,6 +3818,35 @@ export declare enum ZodDecorator {
      * assurance-control: WILDO.SECRETS.DISCLOSURE_AUDIT
      */
     IS_AUDIT_EVIDENCE = "isAuditEvidence",
+    /**
+     * Last-action record: this field holds what the MOST RECENT action on the row said about ITSELF — the
+     * reason a person gave for a decision, the justification typed for a reassignment — not state the next
+     * action starts from.
+     *
+     * Authored fluently on the ROW schema: `decisionReason: z.string().optional().isLastActionRecord()`. A pure
+     * marker. Read it back with `isLastActionRecordField(schema)`.
+     *
+     * What it changes: a form that starts from the row (an update-like verb's form starts from the record it
+     * acts on, so "Set disclosure" opens on the current disclosure) never offers this field's value as the
+     * starting value of the next action. Without it, a verb whose request names the same field opened with the
+     * previous decision's words already typed in: "Suspend" prefilled with the reason an acceptance was given,
+     * which a person who submits without reading records as the reason for the suspension (#2192).
+     *
+     * Mark a field when an action REPLACES it with words about that action. Do not mark a setting an action
+     * edits from its current value (a disclosure level, a list of admitted agents): starting from the current
+     * value is what makes such a form safe to submit.
+     */
+    IS_LAST_ACTION_RECORD = "isLastActionRecord",
+    /**
+     * Decider: this field records WHICH PERSON decided something on the row: who approved, accepted, placed or released
+     * (`decidedByUserId`, `acceptedByUserId`, `placedByUserId`). A pure marker, read back with `isDeciderField(schema)`.
+     *
+     * What it changes: a decider field records a person's decision, so the declaration of a verb that writes it names it
+     * (`approvalSeal.decides`, CAPTURED or NONE with a reason, #2906). The engine's source check, a test over the
+     * engine's own resources, refuses a decider field no declaration names and flags a field NAMED like a decider that is
+     * not marked. No check runs over an application's resources yet: there the marker documents the field.
+     */
+    IS_DECIDER = "isDecider",
     /**
      * 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
@@ -3648,6 +3902,11 @@ export declare enum ZodDecorator {
      * `OBJECT_BUSINESS_KEY_SET` decorator on the schema root.
      */
     IS_BUSINESS_KEY = "isBusinessKey",
+    /**
+     * A server-allocated document number (`INV-2026-00042`), consecutive and gapless per scope. Composite: implies
+     * `excludeFromCreate`, `excludeFromUpdate` and a unique index in the sequence's scope. See `DocumentSequenceParams`.
+     */
+    DOCUMENT_SEQUENCE = "documentSequence",
     /**
      * Object-level decorator declaring a **composite business key** for the
      * schema (e.g. `(organizationId, templateKey)`). Schema-level analog of
@@ -3658,6 +3917,11 @@ export declare enum ZodDecorator {
      * (single field vs composite). Mixing is rejected at decoration time.
      */
     OBJECT_BUSINESS_KEY_SET = "businessKeySet",
+    /**
+     * Object-level: the object (`{ resourceType, resourceId }`) names one row of a resource whose type is chosen at
+     * run time from a published target set. See {@link ResourceReferenceParams}.
+     */
+    RESOURCE_REFERENCE = "isResourceReference",
     TTL = "ttl",
     IS_PASSWORD = "isPassword",
     IS_OTP = "isOtp",
@@ -3672,6 +3936,23 @@ export declare enum ZodDecorator {
     NUMBER_UI = "numberUI",
     ENUM_UI = "enumUI",
     DATE_UI = "dateUI",
+    /**
+     * A `Date` field that holds a CALENDAR DAY — a due date, a birthday, an invoice date — rather than an
+     * instant. Declared with `z.date().isCalendarDate()`; read with `isCalendarDateSchema()`.
+     *
+     * A JavaScript `Date` is an instant, and an instant falls on different days in different time zones: a due
+     * date picked as 3 Oct in Paris, stored as that browser's midnight, read 2 Oct in New York. A calendar day
+     * has no zone. So a calendar date is held as UTC MIDNIGHT of its day, every reader sees that same day, and
+     * the picker writes and reads the day itself. "Tomorrow" still means tomorrow in the READER's zone.
+     *
+     * Undeclared, a `Date` stays an instant (`createdAt`, `expiresAt`, `completedAt`…), shown in the reader's
+     * configured time zone. A date RANGE (`z_range('date')`) is a range of calendar days without declaring it.
+     *
+     * It cannot be combined with `dateTimeUI()`, which declares a moment with a time of day: applying the second of
+     * the two throws. "Today" for a calendar day, in its relative words, its picker, a new item's default and a
+     * preset filter window alike, is today in the reader's resolved time zone.
+     */
+    IS_CALENDAR_DATE = "isCalendarDate",
     DATETIME_UI = "dateTimeUI",
     TIME_UI = "timeUI",
     MONEY_UI = "moneyUI",
@@ -3726,10 +4007,14 @@ export type ZodDecorator_ParamsType = {
     /**
      * 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.
+     * value (the common case) or an array, or the full {@link DataCategoriesFieldParams} object when
+     * the fluent method's `options` argument was given; the chokepoint normalizes all three to that
+     * object.
      */
-    [ZodDecorator.DATA_CATEGORIES]: string | readonly string[];
+    [ZodDecorator.DATA_CATEGORIES]: string | readonly string[] | DataCategoriesFieldParams;
     [ZodDecorator.IS_AUDIT_EVIDENCE]: undefined;
+    [ZodDecorator.IS_LAST_ACTION_RECORD]: undefined;
+    [ZodDecorator.IS_DECIDER]: 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
@@ -3743,7 +4028,9 @@ export type ZodDecorator_ParamsType = {
     [ZodDecorator.IS_UNIQUE]: UniqueFieldParams | DecoratorUpdater<UniqueFieldParams> | undefined;
     [ZodDecorator.IS_PRIMARY_KEY]: undefined;
     [ZodDecorator.IS_BUSINESS_KEY]: undefined;
+    [ZodDecorator.DOCUMENT_SEQUENCE]: DocumentSequenceParams;
     [ZodDecorator.OBJECT_BUSINESS_KEY_SET]: BusinessKeySetParams | DecoratorUpdater<BusinessKeySetParams>;
+    [ZodDecorator.RESOURCE_REFERENCE]: ResourceReferenceParams;
     [ZodDecorator.TTL]: TtlFieldParams | DecoratorUpdater<TtlFieldParams>;
     [ZodDecorator.IS_PASSWORD]: undefined;
     [ZodDecorator.IS_OTP]: OtpFieldParams | DecoratorUpdater<OtpFieldParams> | undefined;
@@ -3758,6 +4045,7 @@ export type ZodDecorator_ParamsType = {
     [ZodDecorator.NUMBER_UI]: NumberUIParams | DecoratorUpdater<NumberUIParams> | undefined;
     [ZodDecorator.ENUM_UI]: EnumUIParams | DecoratorUpdater<EnumUIParams> | undefined;
     [ZodDecorator.DATE_UI]: DateUIParams | DecoratorUpdater<DateUIParams> | undefined;
+    [ZodDecorator.IS_CALENDAR_DATE]: undefined;
     [ZodDecorator.DATETIME_UI]: DateTimeUIParams | DecoratorUpdater<DateTimeUIParams> | undefined;
     [ZodDecorator.TIME_UI]: TimeUIParams | DecoratorUpdater<TimeUIParams> | undefined;
     [ZodDecorator.MONEY_UI]: MoneyUIParams | DecoratorUpdater<MoneyUIParams> | undefined;
@@ -3804,12 +4092,16 @@ export type ZodDecorator_Types = {
      *  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[];
+     *  (zod-decorators sits below saas-models), plus the optional `personalOnlyWhen` condition (#2119).
+     *  ALWAYS the normalized object, its `categories` deduped and non-empty: the chokepoint widens the
+     *  bare-value and array authoring forms on the way in, so every reader sees one shape and
+     *  `getDataCategories` can answer "is this field categorized?" by presence alone. */
+    [ZodDecorator.DATA_CATEGORIES]: DataCategoriesFieldParams;
     /** Audit-evidence marker — stored as the bare `true` sentinel (parameterless, like IS_BUSINESS_KEY). */
     [ZodDecorator.IS_AUDIT_EVIDENCE]: true;
+    /** Last-action-record marker — stored as the bare `true` sentinel (parameterless, like IS_AUDIT_EVIDENCE). */
+    [ZodDecorator.IS_LAST_ACTION_RECORD]: true;
+    [ZodDecorator.IS_DECIDER]: 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. */
@@ -3821,7 +4113,9 @@ export type ZodDecorator_Types = {
     [ZodDecorator.IS_UNIQUE]: UniqueFieldParams | true;
     [ZodDecorator.IS_PRIMARY_KEY]: true;
     [ZodDecorator.IS_BUSINESS_KEY]: true;
+    [ZodDecorator.DOCUMENT_SEQUENCE]: DocumentSequenceParams;
     [ZodDecorator.OBJECT_BUSINESS_KEY_SET]: BusinessKeySetParams;
+    [ZodDecorator.RESOURCE_REFERENCE]: ResourceReferenceParams;
     [ZodDecorator.TTL]: TtlFieldParams;
     [ZodDecorator.IS_PASSWORD]: true;
     [ZodDecorator.IS_OTP]: OtpFieldParams | true;
@@ -3836,6 +4130,7 @@ export type ZodDecorator_Types = {
     [ZodDecorator.NUMBER_UI]: NumberUIParams;
     [ZodDecorator.ENUM_UI]: EnumUIParams;
     [ZodDecorator.DATE_UI]: DateUIParams;
+    [ZodDecorator.IS_CALENDAR_DATE]: true;
     [ZodDecorator.DATETIME_UI]: DateTimeUIParams;
     [ZodDecorator.TIME_UI]: TimeUIParams;
     [ZodDecorator.MONEY_UI]: MoneyUIParams;
@@ -3882,6 +4177,8 @@ export interface CustomFieldMetadata {
     [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.IS_LAST_ACTION_RECORD]?: ZodDecorator_Types[ZodDecorator.IS_LAST_ACTION_RECORD];
+    [ZodDecorator.IS_DECIDER]?: ZodDecorator_Types[ZodDecorator.IS_DECIDER];
     [ZodDecorator.RAG_SOURCE]?: ZodDecorator_Types[ZodDecorator.RAG_SOURCE];
     [ZodDecorator.IS_VIRTUAL]?: ZodDecorator_Types[ZodDecorator.IS_VIRTUAL];
     [ZodDecorator.IS_DISCRIMINATOR]?: ZodDecorator_Types[ZodDecorator.IS_DISCRIMINATOR];
@@ -3890,7 +4187,9 @@ export interface CustomFieldMetadata {
     [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.DOCUMENT_SEQUENCE]?: ZodDecorator_Types[ZodDecorator.DOCUMENT_SEQUENCE];
     [ZodDecorator.OBJECT_BUSINESS_KEY_SET]?: ZodDecorator_Types[ZodDecorator.OBJECT_BUSINESS_KEY_SET];
+    [ZodDecorator.RESOURCE_REFERENCE]?: ZodDecorator_Types[ZodDecorator.RESOURCE_REFERENCE];
     [ZodDecorator.TTL]?: ZodDecorator_Types[ZodDecorator.TTL];
     [ZodDecorator.IS_PASSWORD]?: ZodDecorator_Types[ZodDecorator.IS_PASSWORD];
     [ZodDecorator.IS_OTP]?: ZodDecorator_Types[ZodDecorator.IS_OTP];
@@ -3905,6 +4204,7 @@ export interface CustomFieldMetadata {
     [ZodDecorator.NUMBER_UI]?: ZodDecorator_Types[ZodDecorator.NUMBER_UI];
     [ZodDecorator.ENUM_UI]?: ZodDecorator_Types[ZodDecorator.ENUM_UI];
     [ZodDecorator.DATE_UI]?: ZodDecorator_Types[ZodDecorator.DATE_UI];
+    [ZodDecorator.IS_CALENDAR_DATE]?: ZodDecorator_Types[ZodDecorator.IS_CALENDAR_DATE];
     [ZodDecorator.DATETIME_UI]?: ZodDecorator_Types[ZodDecorator.DATETIME_UI];
     [ZodDecorator.TIME_UI]?: ZodDecorator_Types[ZodDecorator.TIME_UI];
     [ZodDecorator.MONEY_UI]?: ZodDecorator_Types[ZodDecorator.MONEY_UI];