@wildo-ai/zod-decorators 1.1.11 → 1.1.13

package/dist/esm/zod.module-override.d.ts

@@ -9,162 +9,31 @@ export type EnumStringValues<T extends EnumLikeType> = EnumValues<T> extends str
 export declare const ZodDecorator_ApplyableType: Record<ZodDecorator, string[]>;
 type DecoratorFn = (this: z.ZodTypeAny, ...args: any[]) => DecoratedPrimitiveZodType<z.ZodTypeAny>;
 export declare const ZodDecorator_FunctionType: Record<string, DecoratorFn>;
-export type DecoratedPrimitiveZodType<T extends z.ZodTypeAny = z.ZodTypeAny> = T & {
-    /** @wildo_source:part:start zod.decorators.shared-structural-methods facet:layer:shared facet:family:decorator facet:family:method-surface */
-    [ZodDecorator.IS_DB_INDEXED](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_FOREIGN_KEY](params?: ZodDecorator_ParamsType[ZodDecorator.IS_FOREIGN_KEY]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_SUMMARY_FIELD](params?: ZodDecorator_ParamsType[ZodDecorator.IS_SUMMARY_FIELD]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_BACKEND_ONLY](params?: ZodDecorator_ParamsType[ZodDecorator.IS_BACKEND_ONLY]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_WRITE_ONLY_SECRET](params?: ZodDecorator_ParamsType[ZodDecorator.IS_WRITE_ONLY_SECRET]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_DISCRIMINATOR](params?: ZodDecorator_ParamsType[ZodDecorator.IS_DISCRIMINATOR]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_UNIQUE](params?: ZodDecorator_ParamsType[ZodDecorator.IS_UNIQUE]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_PRIMARY_KEY](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_BUSINESS_KEY](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.DOCUMENT_SEQUENCE](params: DocumentSequenceParams): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.OBJECT_BUSINESS_KEY_SET](fields: string[], params?: Omit<BusinessKeySetParams, 'fields'>): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.RESOURCE_REFERENCE](params: ResourceReferenceParams): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.TTL](params: ZodDecorator_ParamsType[ZodDecorator.TTL]): DecoratedPrimitiveZodType<T>;
-    /**
-     * `z.date().isCalendarDate()` — the date is a CALENDAR DAY (a due date, a birthday, an invoice date), not an
-     * instant. It is held as UTC midnight of the day and shown and picked as that day for every reader, whatever
-     * their time zone; "tomorrow" is still measured from the reader's today. Leave it off a moment in time
-     * (`createdAt`, `expiresAt`, `completedAt`): an undeclared date is an instant, shown in the reader's zone.
-     * A day has no time of day, so it cannot also declare `dateTimeUI()`: combining the two throws when the schema
-     * loads. Use `dateUI()` to style a calendar date's display, and `dateTimeUI()` alone for a moment.
-     */
-    [ZodDecorator.IS_CALENDAR_DATE](): DecoratedPrimitiveZodType<T>;
-    /** @wildo_source:part:end zod.decorators.shared-structural-methods */
-    [ZodDecorator.IMPERSONALIZE_WITH](treatment: string, options?: Omit<ImpersonalizeFieldParams, 'treatment'>): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.PORTABILITY_PROVENANCE](provenance: string): DecoratedPrimitiveZodType<T>;
-    /**
-     * @wildo_source:part:start zod.decorators.data-categories facet:layer:shared facet:family:decorator facet:kind:api facet:audience:app-developer facet:family:method-surface
-     *
-     * Declare WHICH KINDS of personal data this field holds — the vocabulary a privacy notice
-     * enumerates. Import `PersonalDataCategory` from `@wildo-ai/saas-models`.
-     *
-     * Accepts a single category (the common case) or an array when a field genuinely spans two. At
-     * least one is required: a field that holds NO personal data carries no declaration at all, and
-     * that absence is exactly what the compliance gap report reads.
-     *
-     * Declare it on the field that holds the value. Never on a field merely because its NAME suggests
-     * a category — `credentials` is the one category the framework derives for you, and it derives it
-     * from `.isPassword()` / `.isOtp()` / `.isWriteOnlySecret()`, never from an identifier.
-     *
-     * `options.personalOnlyWhen` takes a `PersonalDataCondition` (also from `@wildo-ai/saas-models`)
-     * for a field that is personal data only on some rows. The case it exists for is a field naming
-     * the PARTY a row describes — a customer account, a supplier: it is an individual's data when that
-     * party is a sole trader, and a company's when it is not. The field still counts as personal data
-     * for erasure, export and every guard; the privacy notice lists it as held "where the customer is
-     * an individual" instead of claiming it about every customer. Do not use it for a field naming a
-     * person AT a company (a contact's email): that is personal on every row.
-     *
-     * `options.aboutAnotherParty: true` says the field names a party OTHER than the one the row is about: a
-     * copy of another organization's name kept on a cost record or a relationship. It decides only one thing:
-     * a resource declaring `retentionPolicy: RETAIN_ONLY` ("no personal data about its own subject") may keep
-     * such a copy. Leave it off the row's own party's name (a customer account's own name), which that
-     * resource may not keep.
-     *
-     * @example
-     * fullName: z.string().dataCategories(PersonalDataCategory.IDENTITY)
-     * @example
-     * email: z.email().nullish().dataCategories(PersonalDataCategory.CONTACT_DETAILS)
-     * @example
-     * // A field that genuinely spans two — an array never forces you to pick a lie.
-     * dietaryNotes: z.string().dataCategories([PersonalDataCategory.USER_CONTENT, PersonalDataCategory.SPECIAL_CATEGORY_HEALTH])
-     * @example
-     * // A customer account's name: a person's data only when the customer is a sole trader.
-     * accountName: z.string().dataCategories(PersonalDataCategory.IDENTITY, { personalOnlyWhen: PersonalDataCondition.DESCRIBED_PARTY_IS_A_NATURAL_PERSON })
-     * @example
-     * // The billed customer's name copied onto an invoice line: another party's name, not the line's subject.
-     * customerName: z.string().dataCategories(PersonalDataCategory.IDENTITY, { personalOnlyWhen: PersonalDataCondition.DESCRIBED_PARTY_IS_A_NATURAL_PERSON, aboutAnotherParty: true })
-     */
-    [ZodDecorator.DATA_CATEGORIES](categories: string | readonly string[], options?: DataCategoriesOptions): DecoratedPrimitiveZodType<T>;
-    /** @wildo_source:part:end zod.decorators.data-categories */
-    [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<T>;
-    /**
-     * `.isLastActionRecord()` — this row field holds what the most recent action said about itself (the reason
-     * given for a decision), so a form that starts from the row never offers it as the next action's starting
-     * value. Mark it where an action REPLACES the field with words about that action; never on a setting an
-     * action edits from its current value. Read back with `isLastActionRecordField(schema)`.
-     *
-     * @example
-     * decisionReason: z.string().max(1000).optional().excludeFromCreate().excludeFromUpdate().isLastActionRecord()
-     */
-    [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<T>;
-    /**
-     * `.isDecider()` — this row field records which person decided something on the row (who approved, accepted,
-     * placed, released). The declaration of the verb that writes it names it (`approvalSeal.decides`, #2906); the engine
-     * checks that over its own resources. Read back with `isDeciderField(schema)`.
-     *
-     * @example
-     * decidedByUserId: z.string().optional().excludeFromCreate().excludeFromUpdate().isDecider()
-     */
-    [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<T>;
-    /**
-     * @wildo_source:part:start zod.decorators.rag-source facet:layer:shared facet:family:decorator facet:family:method-surface facet:kind:api facet:audience:app-developer
-     *
-     * `.ragSource(config?)` — declare this field's text a source of the application's retrieval
-     * corpus. Live on every string-backed schema (`z.string()` and every string FORMAT such as
-     * `z.email()` / `z.url()`) and carried across the `.optional()` / `.nullable()` / `.default()`
-     * wrappers, so it composes anywhere in a decorator chain.
-     *
-     * The config is OPTIONAL and there is no `enabled` flag: a bare `.ragSource()` is a complete
-     * declaration that accepts the framework chunking defaults. Presence IS enablement.
-     *
-     * @example
-     * z.string().ragSource()
-     * @example
-     * z.string().ragSource({ chunkingStrategy: RAGChunkingStrategy.MARKDOWN, chunkSize: 1200, chunkOverlap: 150 }).optional()
-     */
-    [ZodDecorator.RAG_SOURCE](config?: RagSourceConfiguration): DecoratedPrimitiveZodType<T>;
-    /** @wildo_source:part:end zod.decorators.rag-source */
-    [ZodDecorator.IS_HIDDEN](params?: ZodDecorator_ParamsType[ZodDecorator.IS_HIDDEN]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_NOT_EDITABLE](params?: ZodDecorator_ParamsType[ZodDecorator.IS_NOT_EDITABLE]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_VIRTUAL](params: ZodDecorator_ParamsType[ZodDecorator.IS_VIRTUAL]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_PASSWORD](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_OTP](params?: ZodDecorator_ParamsType[ZodDecorator.IS_OTP]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_COLOR](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_DRAFT_RELAXED](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.SHOW_WHEN](params: ZodDecorator_ParamsType[ZodDecorator.SHOW_WHEN]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.SYSTEM_ENUM](name: string): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_EPHEMERAL](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.IS_CRDT](): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.BOOLEAN_UI](params?: ZodDecorator_ParamsType[ZodDecorator.BOOLEAN_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.STRING_UI](params?: ZodDecorator_ParamsType[ZodDecorator.STRING_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.NUMBER_UI](params?: ZodDecorator_ParamsType[ZodDecorator.NUMBER_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.ENUM_UI](params?: ZodDecorator_ParamsType[ZodDecorator.ENUM_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.DATE_UI](params?: ZodDecorator_ParamsType[ZodDecorator.DATE_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.DATETIME_UI](params?: ZodDecorator_ParamsType[ZodDecorator.DATETIME_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.TIME_UI](params?: ZodDecorator_ParamsType[ZodDecorator.TIME_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.MONEY_UI](params?: ZodDecorator_ParamsType[ZodDecorator.MONEY_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.CODE_UI](params?: ZodDecorator_ParamsType[ZodDecorator.CODE_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.FILE_UI](params?: ZodDecorator_ParamsType[ZodDecorator.FILE_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.DURATION_UI](params?: ZodDecorator_ParamsType[ZodDecorator.DURATION_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.PHONE_UI](params?: ZodDecorator_ParamsType[ZodDecorator.PHONE_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.BIGDECIMAL_UI](params?: ZodDecorator_ParamsType[ZodDecorator.BIGDECIMAL_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.FOREIGN_KEY_UI](params?: ZodDecorator_ParamsType[ZodDecorator.FOREIGN_KEY_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.ARRAY_UI](params?: ZodDecorator_ParamsType[ZodDecorator.ARRAY_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.OBJECT_UI](params?: ZodDecorator_ParamsType[ZodDecorator.OBJECT_UI]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.STRING_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.STRING_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.NUMBER_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.NUMBER_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.BOOLEAN_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.BOOLEAN_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.ENUM_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.ENUM_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.DATE_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.DATE_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.DATETIME_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.DATETIME_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.TIME_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.TIME_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.MONEY_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.MONEY_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.CODE_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.CODE_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.FILE_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.FILE_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.DURATION_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.DURATION_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.PHONE_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.PHONE_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.BIGDECIMAL_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.BIGDECIMAL_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.FOREIGN_KEY_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.FOREIGN_KEY_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.ARRAY_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.ARRAY_SPEC]): DecoratedPrimitiveZodType<T>;
-    [ZodDecorator.OBJECT_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.OBJECT_SPEC]): DecoratedPrimitiveZodType<T>;
-    addDecorators(decorators: DecoratorInput[]): DecoratedPrimitiveZodType<T>;
-};
+/**
+ * The type every decorator returns: the schema's OWN type, and nothing more (#3031).
+ *
+ * A decorated schema keeps exactly the chainable surface its `declare module 'zod'` interface declares
+ * below, because every declared member returns `DecoratedPrimitiveZodType<this>`. So
+ * `z.enum(X).isDBIndexed()` is a `ZodEnum<…>` and offers what `ZodEnum` declares; `.isUnique()` on it is a
+ * compile error, as it is on the bare enum.
+ *
+ * WHY NOT `T & { …every decorator… }`, which this was until 2026-11-06. That intersection declared all of
+ * them on every schema after its first decoration, while the runtime installs each one only where its
+ * interface declares it (`declared-decorator-surface-parity.contract.test.ts` holds the two equal). Measured
+ * on 2026-10-21: 569 (type, decorator) pairs typechecked after one decoration and threw at load, such as
+ * `z.enum(ModelUsageUnit).isDBIndexed().isUnique()` (TypeError while loading saas-models, `tsc` clean).
+ * Narrowing it broke no chain anywhere in the repository (measured 2026-11-06 over every package that
+ * authors one), which is what the old type was hiding: only the wrong chains needed it.
+ *
+ * REJECTED: installing the missing decorators so the old promise came true. Most of the 569 are refused on
+ * purpose by `ZodDecorator_ApplyableType` (`isPrimaryKey` on a boolean, `stringUI` on a number), so the
+ * promise was the defect, not the install. A decorator a type should carry is added to that type's
+ * interface and installed on its prototype, as one change.
+ *
+ * Factory schemas (`z_money()`, `z_file()`, …) keep their extra members because `this` is the factory's
+ * own intersection or interface, which already carries them.
+ */
+export type DecoratedPrimitiveZodType<T extends z.ZodTypeAny = z.ZodTypeAny> = T;
 export declare function ZodDecorator_FunctionAddDecorators(this: z.ZodTypeAny, decorators: DecoratorInput[]): DecoratedPrimitiveZodType<z.ZodTypeAny>;
 export declare const defaultZodDecoSchemaProperties: {
     enumerable: boolean;
@@ -460,11 +329,89 @@ declare module 'zod' {
         [ZodDecorator.IS_WRITE_ONLY_SECRET](params?: WriteOnlySecretFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IMPERSONALIZE_WITH](treatment: string, options?: Omit<ImpersonalizeFieldParams, 'treatment'>): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.PORTABILITY_PROVENANCE](provenance: string): DecoratedPrimitiveZodType<this>;
+        /**
+         * @wildo_source:part:start zod.decorators.data-categories facet:layer:shared facet:family:decorator facet:kind:api facet:audience:app-developer facet:family:method-surface
+         *
+         * Declare WHICH KINDS of personal data this field holds — the vocabulary a privacy notice
+         * enumerates. Import `PersonalDataCategory` from `@wildo-ai/saas-models`.
+         *
+         * Accepts a single category (the common case) or an array when a field genuinely spans two. At
+         * least one is required: a field that holds NO personal data carries no declaration at all, and
+         * that absence is exactly what the compliance gap report reads.
+         *
+         * Declare it on the field that holds the value. Never on a field merely because its NAME suggests
+         * a category — `credentials` is the one category the framework derives for you, and it derives it
+         * from `.isPassword()` / `.isOtp()` / `.isWriteOnlySecret()`, never from an identifier.
+         *
+         * `options.personalOnlyWhen` takes a `PersonalDataCondition` (also from `@wildo-ai/saas-models`)
+         * for a field that is personal data only on some rows. The case it exists for is a field naming
+         * the PARTY a row describes — a customer account, a supplier: it is an individual's data when that
+         * party is a sole trader, and a company's when it is not. The field still counts as personal data
+         * for erasure, export and every guard; the privacy notice lists it as held "where the customer is
+         * an individual" instead of claiming it about every customer. Do not use it for a field naming a
+         * person AT a company (a contact's email): that is personal on every row.
+         *
+         * `options.aboutAnotherParty: true` says the field names a party OTHER than the one the row is about: a
+         * copy of another organization's name kept on a cost record or a relationship. It decides only one thing:
+         * a resource declaring `retentionPolicy: RETAIN_ONLY` ("no personal data about its own subject") may keep
+         * such a copy. Leave it off the row's own party's name (a customer account's own name), which that
+         * resource may not keep.
+         *
+         * @example
+         * fullName: z.string().dataCategories(PersonalDataCategory.IDENTITY)
+         * @example
+         * email: z.email().nullish().dataCategories(PersonalDataCategory.CONTACT_DETAILS)
+         * @example
+         * // A field that genuinely spans two — an array never forces you to pick a lie.
+         * dietaryNotes: z.string().dataCategories([PersonalDataCategory.USER_CONTENT, PersonalDataCategory.SPECIAL_CATEGORY_HEALTH])
+         * @example
+         * // A customer account's name: a person's data only when the customer is a sole trader.
+         * accountName: z.string().dataCategories(PersonalDataCategory.IDENTITY, { personalOnlyWhen: PersonalDataCondition.DESCRIBED_PARTY_IS_A_NATURAL_PERSON })
+         * @example
+         * // The billed customer's name copied onto an invoice line: another party's name, not the line's subject.
+         * customerName: z.string().dataCategories(PersonalDataCategory.IDENTITY, { personalOnlyWhen: PersonalDataCondition.DESCRIBED_PARTY_IS_A_NATURAL_PERSON, aboutAnotherParty: true })
+         */
         [ZodDecorator.DATA_CATEGORIES](categories: string | readonly string[], options?: DataCategoriesOptions): DecoratedPrimitiveZodType<this>;
+        /** @wildo_source:part:end zod.decorators.data-categories */
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
+        /**
+         * `.isLastActionRecord()` — this row field holds what the most recent action said about itself (the reason
+         * given for a decision), so a form that starts from the row never offers it as the next action's starting
+         * value. Mark it where an action REPLACES the field with words about that action; never on a setting an
+         * action edits from its current value. Read back with `isLastActionRecordField(schema)`.
+         *
+         * @example
+         * decisionReason: z.string().max(1000).optional().excludeFromCreate().excludeFromUpdate().isLastActionRecord()
+         */
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
+        /**
+         * `.isDecider()` — this row field records which person decided something on the row (who approved, accepted,
+         * placed, released). The declaration of the verb that writes it names it (`approvalSeal.decides`, #2906); the engine
+         * checks that over its own resources. Read back with `isDeciderField(schema)`.
+         *
+         * @example
+         * decidedByUserId: z.string().optional().excludeFromCreate().excludeFromUpdate().isDecider()
+         */
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
+        /**
+         * @wildo_source:part:start zod.decorators.rag-source facet:layer:shared facet:family:decorator facet:family:method-surface facet:kind:api facet:audience:app-developer
+         *
+         * `.ragSource(config?)` — declare this field's text a source of the application's retrieval
+         * corpus. Live on every string-backed schema (`z.string()` and every string FORMAT such as
+         * `z.email()` / `z.url()`) and carried across the `.optional()` / `.nullable()` / `.default()`
+         * wrappers, so it composes anywhere in a decorator chain.
+         *
+         * The config is OPTIONAL and there is no `enabled` flag: a bare `.ragSource()` is a complete
+         * declaration that accepts the framework chunking defaults. Presence IS enablement.
+         *
+         * @example
+         * z.string().ragSource()
+         * @example
+         * z.string().ragSource({ chunkingStrategy: RAGChunkingStrategy.MARKDOWN, chunkSize: 1200, chunkOverlap: 150 }).optional()
+         */
         [ZodDecorator.RAG_SOURCE](config?: RagSourceConfiguration): DecoratedPrimitiveZodType<this>;
+        /** @wildo_source:part:end zod.decorators.rag-source */
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DISCRIMINATOR](params?: DiscriminatorFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
@@ -503,6 +450,7 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.RAG_SOURCE](config?: RagSourceConfiguration): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DISCRIMINATOR](params?: DiscriminatorFieldParams): DecoratedPrimitiveZodType<this>;
@@ -539,6 +487,7 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DISCRIMINATOR](params?: DiscriminatorFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
@@ -565,6 +514,7 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedPrimitiveZodType<this>;
@@ -588,6 +538,7 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedPrimitiveZodType<this>;
@@ -613,13 +564,24 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.TTL](params: TtlFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_CRDT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.DATE_UI](params?: ZodDecorator_ParamsType[ZodDecorator.DATE_UI]): DecoratedPrimitiveZodType<this>;
+        /** @wildo_source:part:start zod.decorators.shared-structural-methods facet:layer:shared facet:family:decorator facet:family:method-surface */
+        /**
+         * `z.date().isCalendarDate()` — the date is a CALENDAR DAY (a due date, a birthday, an invoice date), not an
+         * instant. It is held as UTC midnight of the day and shown and picked as that day for every reader, whatever
+         * their time zone; "tomorrow" is still measured from the reader's today. Leave it off a moment in time
+         * (`createdAt`, `expiresAt`, `completedAt`): an undeclared date is an instant, shown in the reader's zone.
+         * A day has no time of day, so it cannot also declare `dateTimeUI()`: combining the two throws when the schema
+         * loads. Use `dateUI()` to style a calendar date's display, and `dateTimeUI()` alone for a moment.
+         */
         [ZodDecorator.IS_CALENDAR_DATE](): DecoratedPrimitiveZodType<this>;
+        /** @wildo_source:part:end zod.decorators.shared-structural-methods */
         [ZodDecorator.DATE_SPEC](params?: ZodDecorator_ParamsType[ZodDecorator.DATE_SPEC]): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.SHOW_WHEN](params: ZodDecorator_ParamsType[ZodDecorator.SHOW_WHEN]): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DRAFT_RELAXED](): DecoratedPrimitiveZodType<this>;
@@ -642,6 +604,7 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DISCRIMINATOR](params?: DiscriminatorFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
@@ -675,6 +638,15 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        /**
+         * `.isRoleGrant()` — this field's values are roles the writer grants, so a form offers only the roles the person
+         * filling it may grant, plus any the record already holds (#3248). Mark a field a form offers roles in, where the
+         * write is checked against the writer's role ceiling. Read back with `isRoleGrantField(schema)`.
+         *
+         * @example
+         * roles: z.array(OrgRolesSchema).default([]).isRoleGrant()
+         */
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedPrimitiveZodType<this>;
@@ -702,6 +674,8 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        /** `.isRoleGrant()`: the field's values are roles the writer grants. Documented on `ZodArray`. */
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.RAG_SOURCE](config?: RagSourceConfiguration): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_HIDDEN](params?: ZodDecorator_ParamsType[ZodDecorator.IS_HIDDEN]): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_NOT_EDITABLE](params?: ZodDecorator_ParamsType[ZodDecorator.IS_NOT_EDITABLE]): DecoratedPrimitiveZodType<this>;
@@ -769,8 +743,11 @@ declare module 'zod' {
         [ZodDecorator.PORTABILITY_PROVENANCE](provenance: string): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.DATA_CATEGORIES](categories: string | readonly string[], options?: DataCategoriesOptions): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
+        /** `.isLastActionRecord()`: the field holds what the most recent action said about itself. Documented on `ZodString`. */
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
+        /** `.isDecider()`: the field records which person decided something on the row. Documented on `ZodString`. */
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.RAG_SOURCE](config?: RagSourceConfiguration): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_HIDDEN](params?: ZodDecorator_ParamsType[ZodDecorator.IS_HIDDEN]): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_NOT_EDITABLE](params?: ZodDecorator_ParamsType[ZodDecorator.IS_NOT_EDITABLE]): DecoratedPrimitiveZodType<this>;
@@ -835,6 +812,7 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.RAG_SOURCE](config?: RagSourceConfiguration): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DISCRIMINATOR](params?: DiscriminatorFieldParams): DecoratedPrimitiveZodType<this>;
@@ -901,6 +879,7 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DISCRIMINATOR](params?: DiscriminatorFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
@@ -921,11 +900,13 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_CRDT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.OBJECT_BUSINESS_KEY_SET](fields: string[], params?: Omit<BusinessKeySetParams, 'fields'>): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.OBJECT_COMPOUND_INDEX](fields: string[]): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.RESOURCE_REFERENCE](params: ResourceReferenceParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.SHOW_WHEN](params: ZodDecorator_ParamsType[ZodDecorator.SHOW_WHEN]): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DRAFT_RELAXED](): DecoratedPrimitiveZodType<this>;
@@ -946,6 +927,7 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedPrimitiveZodType<this>;
@@ -968,6 +950,7 @@ declare module 'zod' {
         [ZodDecorator.IS_AUDIT_EVIDENCE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_LAST_ACTION_RECORD](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_DECIDER](): DecoratedPrimitiveZodType<this>;
+        [ZodDecorator.IS_ROLE_GRANT](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.IS_VIRTUAL](params: VirtualFieldParams): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_CREATE](): DecoratedPrimitiveZodType<this>;
         [ZodDecorator.EXCLUDE_FROM_UPDATE](): DecoratedPrimitiveZodType<this>;