@wildo-ai/zod-decorators 1.1.1 → 1.1.3

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

@@ -402,6 +402,12 @@ export declare const StringDisplayMode: {
      * `TEXTAREA` — the edit side stays markdown SOURCE either way.
      */
     readonly MARKDOWN: "markdown";
+    /**
+     * A MACHINE IDENTIFIER — a slug, a ref, an addressable key (`success-criterion-…`). Rendered
+     * small, muted and monospace so it stays greppable and verbatim while RECEDING behind the prose
+     * it identifies. Use for values a reader needs to copy or trace, never to read as content.
+     */
+    readonly IDENTIFIER: "identifier";
     readonly COLOR: "color";
     readonly LINK: "link";
     readonly EMAIL: "email";
@@ -710,6 +716,21 @@ export interface ForeignKeyStructuralParams {
      * (e.g. `referrerScopeType`). Without it, `polymorphicVariants` is rename-only.
      */
     polymorphicDiscriminatorField?: string;
+    /**
+     * EXPLICIT target resource type, for an FK whose FIELD NAME cannot resolve it.
+     *
+     * The frontend resolves a reference field's target through the field-name → resource map
+     * (enriched from relationships' `foreignKeyField`). That works only when the field is named for
+     * its target (`assignedToUserId`) or a relationship declares it — and relationship FK names are
+     * held to the `Id`/`Ids` convention. A field that references a resource under its OWN vocabulary
+     * (`icpRefs` inside a specification document, a rename-only FK) has no honest entry in that map;
+     * declaring the target here lets the reference display resolve, label and navigate it without
+     * bending the field's name or the map's uniqueness.
+     *
+     * Takes precedence over the field-name map; polymorphic variants (above) still win over both,
+     * because a per-record discriminator is more specific than any static declaration.
+     */
+    referencedResourceType?: string;
 }
 /** @wildo_source:part:end zod.decorators.shared-structural-params */
 /**
@@ -977,7 +998,14 @@ export declare const FileMimeTypeGroups: {
 };
 export type FileMimeTypeGroup = keyof typeof FileMimeTypeGroups;
 /**
- * File nature classification for constraint validation and UI display.
+ * @wildo_source:part:start zod.decorators.file-vocabularies facet:layer:shared facet:audience:app-developer
+ *
+ * The vocabularies a `z_file()` field selects from. Pick a member of each; the option bag names the
+ * type, and these are the values.
+ *
+ * File nature classification, chosen with `z_file({ nature })`. It selects which per-nature
+ * constraint bag applies and how the form control and display surface behave. `ALL` accepts any
+ * kind and is the right answer for a generic attachment field.
  */
 export declare enum FileNature {
     IMAGE = "image",
@@ -988,6 +1016,7 @@ export declare enum FileNature {
     ARCHIVE = "archive",
     ALL = "all"
 }
+/** @wildo_source:part:end zod.decorators.file-vocabularies */
 /**
  * Rendering-level file nature categories.
  *
@@ -1123,7 +1152,19 @@ export interface FileMediaPreviewOptions {
     showCaption?: boolean;
 }
 /**
- * Storage providers accepted for file uploads.
+ * @wildo_source:part:start zod.decorators.file-vocabularies
+ *
+ * Where a field's bytes may be stored, chosen with `z_file({ storageAccepted: [...] })`. ORDER
+ * EXPRESSES PREFERENCE: list several and the first CONFIGURED one is used. Omit the option entirely
+ * and the field resolves to managed storage.
+ *
+ * ⚠️ **Only `WILDO_MANAGED` and `LOCAL_DIRECTORY` have a provider behind them.** `ONEDRIVE`,
+ * `GOOGLE_DRIVE` and `DROPBOX` are declared vocabulary with no implementation — a field naming only
+ * those has no configured provider, and startup configuration validation refuses the application
+ * rather than letting it serve a field that could never accept an upload.
+ *
+ * ⚠️ **The target is decided once, when the file is created, and the object never moves.** Changing
+ * a field's declared target changes where NEW files go; it does not relocate what is already stored.
  */
 export declare enum FileStorageAccepted {
     WILDO_MANAGED = "wildo_managed",
@@ -1132,6 +1173,7 @@ export declare enum FileStorageAccepted {
     GOOGLE_DRIVE = "google_drive",
     DROPBOX = "dropbox"
 }
+/** @wildo_source:part:end zod.decorators.file-vocabularies */
 /**
  * Context object passed to `FilePathBinding` resolver functions.
  *
@@ -1186,13 +1228,19 @@ export interface FileMultipleFilePolicy {
  *
  * ```
  * <provider root>/
- *   [applicationId/]              ← only if includeApplicationId is true
- *   [folderPath(ctx)/]            ← dynamic folder path
- *   <fileName(ctx) | fileId>      ← explicit name or UUID fallback
+ *   applications/<applicationId>/files/   ← unless includeApplicationId is false
+ *   <storageName>/                        ← the linked resource's collection, else `_unlinked`
+ *   <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
  * ```
  *
- * When nothing is configured, the fallback is the legacy `{fileId}` key
- * for full backward compatibility.
+ * Only the last two lines 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.
+ *
+ * When nothing is configured, the leaf is the `{fileId}` UUID.
  *
  * @example
  * ```typescript
@@ -1250,13 +1298,18 @@ export interface FilePathBinding {
      */
     multipleFilePolicy?: FileMultipleFilePolicy;
     /**
-     * Whether to include the applicationId as a path segment.
+     * Whether the framework-derived prefix — `applications/<appId>/files/<storageName>/<scope>/<scopeId>/`
+     * — is placed above the authored `folderPath` / `fileName`.
      *
-     * Each provider has its own default:
-     *  - `wildo_managed` (S3) → `true` (always, for bucket isolation)
-     *  - `local_directory`    → `false` (volume is typically per-app)
+     * Defaults to `true` on EVERY provider. It used to default to `false` for `local_directory`
+     * ("the volume is typically per-app"), and that is what left local-directory deployments with no
+     * tenant structure at all: a per-app volume separates applications from one another and separates
+     * nothing inside one.
      *
-     * Set explicitly to override the provider default.
+     * Setting it to `false` collapses the key to the bare `[folderPath/]<fileName|fileId>` on every
+     * provider. That discards the whole prefix, not merely the application segment — so erasure,
+     * orphan sweeps, per-tenant listing and credential confinement all stop being expressible for
+     * that field. Author it only for a store whose layout is fixed by something outside Wildo.
      */
     includeApplicationId?: boolean;
 }
@@ -1304,6 +1357,22 @@ export declare const AudioFormat: {
 };
 export type AudioFormat = typeof AudioFormat[keyof typeof AudioFormat];
 /**
+ * @wildo_source:part:start zod.decorators.file-nature-constraints facet:layer:shared facet:audience:app-developer
+ *
+ * The per-NATURE constraint bags a `z_file()` field may carry — one per media kind, selected by the
+ * field's `nature`. `imageConstraints`, `videoConstraints`, `audioConstraints` and
+ * `documentConstraints` on the `z_file()` options each take the matching interface below.
+ *
+ * ⚠️ **A constraint describes what the FIELD ACCEPTS, not what the bytes ARE.** The media type comes
+ * from the upload's declared content type; nothing here decodes the file to confirm that something
+ * claiming to be an image is one. Treat these as an authoring contract and a form control's
+ * behaviour, not as a security boundary — the defence against a mislabelled file is on the SERVING
+ * side, where every response carries a no-sniff header and a restrictive content policy.
+ *
+ * ⚠️ **`generateThumbnails` (image, PLURAL) and `generateThumbnail` (video, SINGULAR) are different
+ * options on different bags.** The names differ by one letter and do not behave alike; read each
+ * one's own note below rather than assuming the image semantics carry over.
+ *
  * Image-specific constraints for file validation.
  */
 export interface FileNatureConstraints_Image {
@@ -1316,6 +1385,22 @@ export interface FileNatureConstraints_Image {
         height: number;
     };
     allowedFormats?: ImageFormat[];
+    /**
+     * May the serve path derive a downscaled preview rendition of this image?
+     *
+     * **Opt-OUT, and absence means PERMIT.** Omitting it, or setting `true`, lets `?variant=thumbnail`
+     * return a rendition. Setting it **`false` REFUSES** that request — it does not quietly serve the
+     * original bytes, which is what every other ineligible case does and what an author suppressing
+     * renditions for cost or privacy is trying to avoid. A caller wanting the image anyway asks for
+     * the original variant explicitly.
+     *
+     * The `{ sizes: [...] }` form reads as permission and **its sizes are not honoured**: the
+     * derivation has one fixed longest edge. Do not author sizes expecting them to reach the renderer.
+     *
+     * Wired 2026-09-08 (#477's sibling, #478). Before that this flag was declared, set on the
+     * framework's own user-avatar field, and read by nothing — so it degraded permissively: an author
+     * who set it `false` still got thumbnails, and got no error saying so.
+     */
     generateThumbnails?: boolean | {
         sizes: {
             width: number;
@@ -1347,6 +1432,7 @@ export interface FileNatureConstraints_Document {
     maxPages?: number;
     minPages?: number;
 }
+/** @wildo_source:part:end zod.decorators.file-nature-constraints */
 /**
  * @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
  *
@@ -1365,7 +1451,6 @@ export interface FileNatureConstraints_Document {
  *
  * - `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
@@ -1373,11 +1458,16 @@ export interface FileNatureConstraints_Document {
  *   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.
+ *
+ * There is deliberately NO semantic/embedding-based member. It is the option people reach for
+ * first, and published evaluations put it BELOW `RECURSIVE` on both recall and precision while
+ * costing an embedding pass per document — so `RECURSIVE` is the right default for prose, and the
+ * two structure-aware members are for text whose structure carries meaning.
+ *
  */
 export declare const RAGChunkingStrategy: {
     readonly FIXED_SIZE: "fixed_size";
     readonly RECURSIVE: "recursive";
-    readonly SEMANTIC: "semantic";
     readonly MARKDOWN: "markdown";
     readonly CODE: "code";
 };
@@ -1472,6 +1562,15 @@ export type FileMetadata = {
     uploadedAt: Date;
 } & FileUploaderOwnership;
 /**
+ * @wildo_source:part:start zod.decorators.file-vocabularies
+ *
+ * What happens to the file when its parent record is deleted, chosen with
+ * `z_file({ onParentDelete })`. Defaults to `CASCADE`.
+ *
+ * ⚠️ `SOFT_DELETE` behaves IDENTICALLY to `CASCADE` at runtime today. It exists as an explicit
+ * semantic marker for consumers that want to model a softer intent — choosing it does not currently
+ * change what happens to the file.
+ *
  * File behavior when parent resource is deleted.
  * - CASCADE: Mark the file deleted as part of parent removal; physical storage cleanup is deferred to the cleanup batch
  * - SOFT_DELETE: Same current runtime behavior as CASCADE, but keeps an explicit semantic marker for consumers that want to model softer intent
@@ -1483,6 +1582,7 @@ export declare const FileOnParentDelete: {
     readonly ORPHAN: "orphan";
 };
 export type FileOnParentDelete = typeof FileOnParentDelete[keyof typeof FileOnParentDelete];
+/** @wildo_source:part:end zod.decorators.file-vocabularies */
 /**
  * @wildo_source:part:start zod.decorators.file-schema
  *
@@ -1541,9 +1641,16 @@ export interface FileSchemaMetadata {
     textExtraction?: FileTextExtractionOptions;
     /**
      * Antivirus scan policy for this file field.
-     * - 'required': always scan after upload, regardless of global config
-     * - 'skip': never scan this field, even if global scanning is enabled
-     * - undefined: inherit from `appConfig.files.scanning.enabled`
+     * - 'required': always scan after upload, whatever the application-wide default says. If no scanner
+     *   is reachable the upload is FAILED rather than passed — a demanded scan that cannot run refuses.
+     * - 'skip': never scan this field, even when the application has a scanner.
+     * - undefined: inherit the application-wide default, which is DERIVED from whether a scanner is
+     *   reachable at all (a ClamAV host, or YARA both enabled and reachable). Provisioning the sidecar IS
+     *   the application-level opt-in; there is no separate on/off flag to set.
+     *
+     * That last line named `appConfig.files.scanning.enabled` until 2026-09-09. No configuration schema
+     * has ever declared a `files` section, so the value an undeclared field inherited was `false` in every
+     * application — this text described a switch that could not be turned on.
      */
     scanPolicy?: 'required' | 'skip';
     /** Behavior when parent resource is deleted (default: CASCADE) */
@@ -1654,9 +1761,16 @@ export interface FileSchemaOptions {
     /** @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
-     * - 'skip': never scan this field, even if global scanning is enabled
-     * - undefined: inherit from `appConfig.files.scanning.enabled`
+     * - 'required': always scan after upload, whatever the application-wide default says. If no scanner
+     *   is reachable the upload is FAILED rather than passed — a demanded scan that cannot run refuses.
+     * - 'skip': never scan this field, even when the application has a scanner.
+     * - undefined: inherit the application-wide default, which is DERIVED from whether a scanner is
+     *   reachable at all (a ClamAV host, or YARA both enabled and reachable). Provisioning the sidecar IS
+     *   the application-level opt-in; there is no separate on/off flag to set.
+     *
+     * That last line named `appConfig.files.scanning.enabled` until 2026-09-09. No configuration schema
+     * has ever declared a `files` section, so the value an undeclared field inherited was `false` in every
+     * application — this text described a switch that could not be turned on.
      */
     scanPolicy?: 'required' | 'skip';
     /** Behavior when parent resource is deleted (default: CASCADE) */
@@ -1786,12 +1900,18 @@ export interface BackendOnlyFieldParams {
      * 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
+     * This is one of the framework's two disclosure-audit triggers: 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
+     * 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
+     * The other trigger is `.isEphemeral()`, which fires on ANY operation rather than only on create,
+     * so a rotate or a regenerate that hands the secret over again is recorded too. The two answer
+     * different questions and neither implies the other: this one names the stored artifact, the
+     * ephemeral marker names the value actually handed over. A field may carry either, both, or
+     * neither, and one marked both is audited once.
+     *
+     * Scope limit worth knowing before relying on either: 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.
      *
@@ -2060,8 +2180,28 @@ export interface BusinessKeySetParams {
  * @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.
+ *
+ * Declares a ROW LIFETIME: rows of this resource are deleted once the instant derived from this
+ * Date field has passed. This is storage limitation — a compliance surface — not housekeeping, so
+ * the declaration is ADAPTER-NEUTRAL and means the same thing wherever the resource is stored.
+ *
+ * How the deletion happens differs, and you do not choose it:
+ * - on MongoDB, a native index expires the rows;
+ * - on PostgreSQL there is no equivalent, so a scheduled sweep deletes them in bounded batches.
+ *
+ * The sweep is registered whichever store is in use, so a resource that declares a lifetime is
+ * 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:
+ * - 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
+ *   pair is refused at startup, because rows expiring under a native index leave with no
+ *   application code running, so the derived search chunks could never be removed with them.
+ *
+ * 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.
  *
  * @example
  * createdAt: z.date().ttl({ expireAfterSeconds: 3600 }) // Expire 1 hour after createdAt
@@ -2326,6 +2466,19 @@ export interface BooleanLabellingCustomParams {
     trueValue: string;
     falseValue: string;
 }
+/**
+ * How a display field's LABEL is styled, independent of chrome mode (which decides layout).
+ *
+ * - `DEFAULT` — the chrome's ordinary label treatment.
+ * - `TITLE` — the label reads as a SMALL TITLE above its content (small, semibold, foreground):
+ *   for a field that acts as a mini-section inside a prose flow — "Who suffers it" above its
+ *   answer — where the ordinary muted label would not carry the structure.
+ */
+export declare const DisplayLabelStyle: {
+    readonly DEFAULT: "default";
+    readonly TITLE: "title";
+};
+export type DisplayLabelStyle = typeof DisplayLabelStyle[keyof typeof DisplayLabelStyle];
 /**
  * @wildo_source:part:start zod.decorators.primitive-ui
  *
@@ -2337,6 +2490,8 @@ export interface PrimitiveUIBaseDisplayParams {
     component?: DisplayFieldComponent;
     /** Chrome layout mode for the field wrapper in display context. */
     chromeMode?: ResponsiveAware<DisplayChromeMode>;
+    /** Label styling, orthogonal to `chromeMode` (which decides LAYOUT). See `DisplayLabelStyle`. */
+    labelStyle?: DisplayLabelStyle;
     /** Force-hide specific chrome sub-elements in display context. Plain object = all breakpoints. */
     forceHide?: ResponsiveAware<ForceHideDisplayConfig>;
     /** Whether to show a tooltip icon in display chrome. Text comes from i18n. */
@@ -2681,11 +2836,41 @@ export interface ForeignKeyUIParams {
     summaryOverride?: ForeignKeyUIDisplayParams;
     edit?: ForeignKeyUIEditParams;
 }
+/**
+ * List marker treatment for a PRIMITIVE array's display items.
+ *
+ * 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.
+ */
+export declare enum ArrayListStyle {
+    /** Bare stacked values — the historical default. */
+    PLAIN = "plain",
+    /** A real bulleted list. For enumerations a reader SCANS — alternatives, consequences, principles — where bare stacked lines read as one run-on paragraph. */
+    BULLETS = "bullets",
+    /**
+     * A RULED list: one hairline between entries, none above the first or below the last.
+     *
+     * For OBJECT entries a reader compares — an ICP after an ICP, a persona after a persona — where
+     * spacing alone stops saying where one ends. It is the alternative to framing each entry as a
+     * card, and the reason to prefer it is compounding chrome: inside a section that is already a
+     * 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"
+}
 export interface ArrayUIDisplayParams extends PrimitiveUIBaseDisplayParams {
     /** Direction for rendering items in display context. */
     displayMode?: DisplayDirection;
     /** 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.
+     */
+    listStyle?: ArrayListStyle;
 }
 /**
  * How NEW items are added to an array field in an edit / inline-edit surface.
@@ -2767,6 +2952,18 @@ export interface ObjectUIDisplayParams extends PrimitiveUIBaseDisplayParams {
     displayMode?: DisplayDirection;
     /** Max properties shown in display (rest truncated). */
     maxItems?: number;
+    /**
+     * The member that IS this object's headline when the object renders as a unit (a nested object
+     * block, an array item card): it renders FIRST, label hidden, with title emphasis; the remaining
+     * members follow in schema order.
+     *
+     * Explicit rather than detected: "the first string field" guesses wrong the moment a stable
+     * identifier precedes the human statement in the schema — exactly the shape ref-addressable
+     * entries have (`ref` first, `statement` second), where detection would headline the machine key.
+     * Names a member that does not exist → ignored, so a schema rename degrades to the old uniform
+     * rendering instead of crashing the display.
+     */
+    primaryField?: string;
 }
 export type ObjectUIEditParams = PrimitiveUIBaseEditParams;
 export interface ObjectUIParams {
@@ -2846,15 +3043,34 @@ export declare enum CodeDeclarationKind {
     UNKNOWN = "unknown"
 }
 /**
- * Public-import-oriented symbol reference used by semantic specifications.
+ * Symbol reference used by semantic specifications to address one exported symbol.
+ *
+ * Downstream transposers and prompts prefer these refs over file-path guesses, so a
+ * ref has to be honest about WHICH KIND of address it carries. Two facts are useful
+ * and they are not the same fact, so they have separate fields:
  *
- * Downstream transposers/prompts should prefer these refs over file-path
- * guesses so generated code imports the right public symbol.
+ * - `importPath` is an IMPORT SPECIFIER — something a generated `import` statement
+ *   can actually resolve, declared in the owning package's `package.json#exports`.
+ * - `filePathHint` is a LOCATION — where a maintainer opens the file. It is never
+ *   rendered as something importable.
+ *
+ * Authoring a source path in `importPath` is the defect issue #150 records: it made
+ * the companion hand a coding agent an import specifier that cannot resolve, because
+ * an application package typically declares no export map entry for its internal
+ * modules. When in doubt, author `filePathHint` — a location that is merely useful
+ * is better than an address that is wrong.
  */
 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. */
+    /**
+     * Optional PUBLIC SUBPATH, when the package root is not the import target.
+     *
+     * Must be a subpath the owning package declares in `package.json#exports`, so that
+     * `${packageName}/${importPath}` is a resolvable import specifier. If the symbol has
+     * no public door, leave this unset and author `filePathHint` instead — do NOT put a
+     * path inside `src/` here.
+     */
     importPath?: string;
     /** Literal exported symbol name. */
     exportName: string;
@@ -2862,7 +3078,14 @@ export interface CodeSymbolRef {
     symbolKind: CodeSymbolKind;
     /** More specific declaration family for code-generation handling. */
     declarationKind?: CodeDeclarationKind;
-    /** Optional local-path hint for companion-side tooling/debugging. */
+    /**
+     * Optional MODULE LOCATION — where the symbol is defined inside the owning package,
+     * relative to that package's source root (for example
+     * `modules/tasks-manager/resources/tasks/tasks.ui-behavior`).
+     *
+     * This is a navigation aid, not an import target: it is rendered as a location and
+     * must never be concatenated onto `packageName` to build an import specifier.
+     */
     filePathHint?: string;
     /** Extra caveats or usage notes for downstream prompts. */
     notes?: string[];
@@ -3094,10 +3317,12 @@ export declare enum ZodDecorator {
      * 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.
+     * is independent of the READ-side disclosure trail. The framework has exactly two disclosure
+     * triggers: `isBackendOnly({ isReturnedAtCreation: true })`, which fires one `FIELD_ACCESS` event
+     * when a server-minted secret is first exposed on a create, and `.isEphemeral()`, which fires on
+     * any operation so a rotate or regenerate is recorded as well. A field can carry any combination
+     * of the three markers. There is still no general "audit every read of this field" marker; do not
+     * go looking for one.
      *
      * assurance-control: WILDO.SECRETS.DISCLOSURE_AUDIT
      */