@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/resources/utils/populated-file-fields.shared.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"populated-file-fields.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/populated-file-fields.shared.utils.ts"],"names":[],"mappings":"AAgDA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yFAAyF;AACzF,eAAO,MAAM,yBAAyB,EAAG,MAAe,CAAC;AACzD,iGAAiG;AACjG,eAAO,MAAM,4BAA4B,EAAG,OAAgB,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,CAAC,CAAC,UAkB1C,CAAC;AAqBH;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC;AACtH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;AAChH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,SAAS,EAAE,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC"}
+{"version":3,"file":"populated-file-fields.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/populated-file-fields.shared.utils.ts"],"names":[],"mappings":"AAgDA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yFAAyF;AACzF,eAAO,MAAM,yBAAyB,EAAG,MAAe,CAAC;AACzD,iGAAiG;AACjG,eAAO,MAAM,4BAA4B,EAAG,OAAgB,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,CAAC,CAAC,UAkB8B,CAAC;AA+B3E;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC;AACtH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;AAChH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,SAAS,EAAE,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC"}

package/dist/esm/resources/utils/populated-file-fields.shared.utils.js

@@ -38,29 +38,38 @@ export const POPULATED_MULTIPLE_FILES_KEY = 'files';
  * than stripped — this is server-produced data, never a request.
  */
 export const PopulatedFileMetadataSchema = z.looseObject({
-    readiness: z.enum(FileReadiness),
-    fileId: z.string().min(1),
-    filename: z.string(),
-    size: z.number(),
-    mimeType: z.string(),
-    extension: z.string().optional(),
-    checksum: z.string().optional(),
-    url: z.string().optional(),
-    thumbnailUrl: z.string().optional(),
-    nature: z.enum(FileDisplayNature).optional(),
-    width: z.number().optional(),
-    height: z.number().optional(),
-    duration: z.number().optional(),
-    pageCount: z.number().optional(),
-    uploadedAt: z.coerce.date(),
-    uploadedBy: z.string().optional(),
-    uploadedByEntityType: z.enum(FileUploaderEntityType).optional(),
-});
+    readiness: z.enum(FileReadiness).describe("Whether the file may be attached: `ready` may be, `attached` belongs to its current record and is not reused elsewhere, `processing` is still being checked and must be read again, and `unavailable` cannot be newly attached. An upload's success is not this."),
+    fileId: z.string().min(1).describe("The file's identifier."),
+    filename: z.string().describe("The file's original name."),
+    size: z.number().describe("The file's size in bytes."),
+    mimeType: z.string().describe("The file's media type."),
+    extension: z.string().optional().describe("The file's extension, without the dot."),
+    checksum: z.string().optional().describe("A checksum of the file's content."),
+    url: z.string().optional().describe("Where the file can be downloaded."),
+    thumbnailUrl: z.string().optional().describe("Where a thumbnail of an image or video can be fetched."),
+    nature: z.enum(FileDisplayNature).optional().describe("What kind of file it is, for display: image, video, audio, document or generic."),
+    width: z.number().optional().describe("An image's width in pixels."),
+    height: z.number().optional().describe("An image's height in pixels."),
+    duration: z.number().optional().describe("An audio or video file's length in seconds."),
+    pageCount: z.number().optional().describe("A document's number of pages."),
+    uploadedAt: z.coerce.date().describe("When the file was uploaded."),
+    uploadedBy: z.string().optional().describe("The identifier of whoever uploaded the file."),
+    uploadedByEntityType: z.enum(FileUploaderEntityType).optional().describe("What kind of principal uploaded the file: a user, an anonymous user, or an organization's or the application's machine client."),
+}).describe("The file's details, included when the read populates files.");
 function carrySchemaMetadata(source, rebuilt) {
     const metadata = source[SCHEMA_METADATA];
     if (metadata !== undefined) {
         rebuilt[SCHEMA_METADATA] = metadata;
     }
+    // Zod's own registry too (`.describe()` / `.meta()`, #1625): `.extend()` clones without the parent link
+    // a clone inherits it through, so a widened file field would otherwise publish undescribed. Not `id`,
+    // which names one schema.
+    const registered = z.globalRegistry.get(source);
+    if (registered !== undefined && !z.globalRegistry.has(rebuilt)) {
+        const { id: _id, ...carried } = registered;
+        if (Object.keys(carried).length > 0)
+            z.globalRegistry.add(rebuilt, carried);
+    }
     return rebuilt;
 }
 /** A `z_file()` leaf (the reference object, metadata attached) widened with its optional populated companion. */
@@ -72,7 +81,9 @@ function widenFileLeaf(leaf) {
     const companionKey = fileMetadata.multiple ? POPULATED_MULTIPLE_FILES_KEY : POPULATED_SINGLE_FILE_KEY;
     if (companionKey in shape)
         return leaf; // already widened (a DTO derived from a widened DTO)
-    const companion = fileMetadata.multiple ? z.array(PopulatedFileMetadataSchema).optional() : PopulatedFileMetadataSchema.optional();
+    const companion = fileMetadata.multiple
+        ? z.array(PopulatedFileMetadataSchema).optional().describe("Each file's details, included when the read populates files.")
+        : PopulatedFileMetadataSchema.optional();
     return carrySchemaMetadata(leaf, leaf.extend({ [companionKey]: companion }));
 }
 export function widenFileFieldsForPopulatedReads(schema, activeSchemas = new WeakSet()) {

package/dist/esm/resources/utils/populated-file-fields.shared.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"populated-file-fields.shared.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/populated-file-fields.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The shape a file field takes on a POPULATED read, and the DTO that describes it (issue #1059).\n *\n * A file field is STORED as a reference — `{ fileId, updatedAt }` for one file, `{ fileIds, updatedAt }`\n * for several. A SUMMARY or CONTEXT read runs file population, which used to REPLACE that reference with\n * the file's metadata (`toMetadataResponse`: readiness, filename, size, url, …). The operation's DTO still\n * described the reference, so `transformOutput` refused every context read of a resource whose file\n * existed: `expected date, received Invalid Date` at `<field>.updatedAt`, a 500, and a degraded body\n * instead of the record. Measured 2026-09-14 on Wonder Todos.\n *\n * Population now keeps the reference and adds the metadata BESIDE it — `file` for one, `files` for\n * several — and the SUMMARY / CONTEXT DTOs declare that companion. Three candidates were weighed:\n *\n * - **Declare the replacement.** The frontend reads a file field as its stored reference (`'fileId' in\n *   value` / `'fileIds' in value`, then fetches metadata by id itself), so a metadata array in place of\n *   `{ fileIds }` fails its multiple-file guard outright. Declaring the replacement would have made the\n *   DTO agree with a shape one consumer cannot read.\n * - **Populate after `transformOutput`.** Validation would then never see the populated value, and the\n *   response DTO — the OpenAPI contract — would describe less than the wire carries.\n * - **Keep the reference (chosen).** Every reader of the reference keeps working, the companion is\n *   OPTIONAL so a read with population disabled or failed (`populateFileFieldsForSingle` keeps the\n *   original value on any error) still validates, and a consumer that wants the metadata finds it at a\n *   named key.\n *\n * The companion's schema carries the file field's decorator metadata forward, so the widened field is\n * still detected as a FILE field (`isFileSchema`, `getSchemaType`) — the same property\n * `resources-config-operations.dtos-builder.file-metadata-coercion.test.ts` pins for date coercion.\n */\nimport {\n  FileDisplayNature,\n  FileReadiness,\n  FileUploaderEntityType,\n  getFileMetadata,\n  getZodDef,\n  getZodDefArrayProperty,\n  getZodDefProperty,\n  getZodDefSchemaProperty,\n  getZodDefStringProperty,\n  getZodObjectShape,\n  getZodType,\n  isZodArray,\n  isZodDefault,\n  isZodNullable,\n  isZodObject,\n  isZodOptional,\n  SCHEMA_METADATA,\n  withArrayElement,\n} from '@wildo-ai/zod-decorators';\nimport { z } from 'zod';\n\n/** The key a populated single-file field carries its metadata under, beside `fileId`. */\nexport const POPULATED_SINGLE_FILE_KEY = 'file' as const;\n/** The key a populated multiple-file field carries its metadata list under, beside `fileIds`. */\nexport const POPULATED_MULTIPLE_FILES_KEY = 'files' as const;\n\n/**\n * `FileMetadata` (`@wildo-ai/zod-decorators`) as a Zod schema, at the NETWORK boundary: `uploadedAt`\n * coerces an ISO string, and the object is loose so a metadata key added later is carried rather\n * than stripped — this is server-produced data, never a request.\n */\nexport const PopulatedFileMetadataSchema: z.ZodTypeAny = z.looseObject({\n  readiness: z.enum(FileReadiness),\n  fileId: z.string().min(1),\n  filename: z.string(),\n  size: z.number(),\n  mimeType: z.string(),\n  extension: z.string().optional(),\n  checksum: z.string().optional(),\n  url: z.string().optional(),\n  thumbnailUrl: z.string().optional(),\n  nature: z.enum(FileDisplayNature).optional(),\n  width: z.number().optional(),\n  height: z.number().optional(),\n  duration: z.number().optional(),\n  pageCount: z.number().optional(),\n  uploadedAt: z.coerce.date(),\n  uploadedBy: z.string().optional(),\n  uploadedByEntityType: z.enum(FileUploaderEntityType).optional(),\n});\n\nfunction carrySchemaMetadata<TSchema extends z.ZodTypeAny>(source: z.ZodTypeAny, rebuilt: TSchema): TSchema {\n  const metadata = (source as any)[SCHEMA_METADATA];\n  if (metadata !== undefined) {\n    (rebuilt as any)[SCHEMA_METADATA] = metadata;\n  }\n  return rebuilt;\n}\n\n/** A `z_file()` leaf (the reference object, metadata attached) widened with its optional populated companion. */\nfunction widenFileLeaf(leaf: z.ZodTypeAny): z.ZodTypeAny {\n  const fileMetadata = getFileMetadata(leaf);\n  if (!fileMetadata || !isZodObject(leaf)) return leaf;\n  const shape = getZodObjectShape(leaf);\n  const companionKey = fileMetadata.multiple ? POPULATED_MULTIPLE_FILES_KEY : POPULATED_SINGLE_FILE_KEY;\n  if (companionKey in shape) return leaf; // already widened (a DTO derived from a widened DTO)\n  const companion = fileMetadata.multiple ? z.array(PopulatedFileMetadataSchema).optional() : PopulatedFileMetadataSchema.optional();\n  return carrySchemaMetadata(leaf, leaf.extend({ [companionKey]: companion }));\n}\n\n/**\n * Rebuild `schema` so every `z_file()` field accepts its populated companion beside the stored\n * reference. Identity-preserving where nothing beneath changed (a wrapper returns the ORIGINAL\n * instance, so an enclosing object is not rebuilt and keeps its metadata — the #989 lesson recorded\n * on `stripTemplatableFileFieldsRecursively`). Applied to READ-side DTOs only, after date coercion.\n */\nexport function widenFileFieldsForPopulatedReads(schema: z.ZodTypeAny, activeSchemas?: WeakSet<object>): z.ZodTypeAny;\nexport function widenFileFieldsForPopulatedReads(schema: undefined, activeSchemas?: WeakSet<object>): undefined;\nexport function widenFileFieldsForPopulatedReads(schema: z.ZodTypeAny | undefined, activeSchemas?: WeakSet<object>): z.ZodTypeAny | undefined;\nexport function widenFileFieldsForPopulatedReads(schema: z.ZodTypeAny | undefined, activeSchemas: WeakSet<object> = new WeakSet<object>()): z.ZodTypeAny | undefined {\n  // An ABSENT schema passes through (#1138). `activeSchemas.add(undefined)` throws\n  // `TypeError: Invalid value used in weak set` — a message naming neither a DTO nor an operation,\n  // raised while a registry is being initialized, so it reaches a human as a backend that will not\n  // boot. `summaryDto` and `contextDto` are declared OPTIONAL on an operation\n  // (`resources-config.shared.schemas.ts:2098`), so absent is a state the contract permits.\n  //\n  // Measured rather than assumed about where it arrives from: `buildAllOperationDtos` DERIVES both\n  // (:545, :572), so its own four call sites never pass an absent one. The reported failure was the\n  // dev companion's projector rebuilding DTOs against the runtime registry — an EXTERNAL caller of\n  // this exported function, which is exactly why the guard belongs here and not at those call\n  // sites (`invariant-call-site-enumeration.md`: prefer making the invariant unbypassable).\n  //\n  // The overloads keep a definite schema in returning a definite schema, so no caller is handed a\n  // widened `| undefined` it then has to narrow.\n  if (!schema) return schema;\n  if (activeSchemas.has(schema)) return schema;\n  activeSchemas.add(schema);\n  try {\n    if (getFileMetadata(schema) && isZodObject(schema)) return widenFileLeaf(schema);\n\n    if (isZodOptional(schema) || isZodNullable(schema) || isZodDefault(schema)) {\n      const inner = getZodDefSchemaProperty(schema, 'innerType');\n      if (!inner) return schema;\n      const widenedInner = widenFileFieldsForPopulatedReads(inner, activeSchemas);\n      if (widenedInner === inner) return schema;\n      const rewrapped = isZodOptional(schema)\n        ? widenedInner.optional()\n        : isZodNullable(schema)\n          ? widenedInner.nullable()\n          : widenedInner.default(() => getZodDefProperty(schema, 'defaultValue') as unknown);\n      return carrySchemaMetadata(schema, rewrapped);\n    }\n\n    const schemaType = getZodType(schema);\n    if (schemaType === 'lazy') {\n      const getter = getZodDef(schema)?.getter;\n      return typeof getter === 'function' ? z.lazy(() => widenFileFieldsForPopulatedReads(getter() as z.ZodTypeAny, activeSchemas)) : schema;\n    }\n\n    if (schemaType === 'union') {\n      const discriminator = getZodDefStringProperty(schema, 'discriminator');\n      const options = getZodDefArrayProperty(schema, 'options') as z.ZodTypeAny[] | undefined;\n      if (!options?.length) return schema;\n      const widened = options.map((option) => widenFileFieldsForPopulatedReads(option, activeSchemas));\n      if (widened.every((option, index) => option === options[index])) return schema;\n      const rebuilt: z.ZodTypeAny = discriminator\n        ? z.discriminatedUnion(discriminator, widened as [z.ZodObject<any>, z.ZodObject<any>, ...z.ZodObject<any>[]])\n        : z.union(widened as [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]]);\n      return carrySchemaMetadata(schema, rebuilt);\n    }\n\n    if (isZodArray(schema)) {\n      const element = getZodDefProperty(schema, 'element') as z.ZodTypeAny | undefined;\n      if (!element) return schema;\n      const widenedElement = widenFileFieldsForPopulatedReads(element, activeSchemas);\n      return widenedElement === element ? schema : withArrayElement(schema, widenedElement);\n    }\n\n    if (!isZodObject(schema)) return schema;\n\n    const shape = getZodObjectShape(schema);\n    const widenedShape: Record<string, z.ZodTypeAny> = {};\n    let changed = false;\n    for (const [fieldName, fieldSchema] of Object.entries(shape)) {\n      const widened = widenFileFieldsForPopulatedReads(fieldSchema as z.ZodTypeAny, activeSchemas);\n      if (widened !== fieldSchema) changed = true;\n      widenedShape[fieldName] = widened;\n    }\n    if (!changed) return schema;\n    return carrySchemaMetadata(schema, schema.extend(widenedShape));\n  } finally {\n    activeSchemas.delete(schema);\n  }\n}\n"]}
+{"version":3,"file":"populated-file-fields.shared.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/populated-file-fields.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The shape a file field takes on a POPULATED read, and the DTO that describes it (issue #1059).\n *\n * A file field is STORED as a reference — `{ fileId, updatedAt }` for one file, `{ fileIds, updatedAt }`\n * for several. A SUMMARY or CONTEXT read runs file population, which used to REPLACE that reference with\n * the file's metadata (`toMetadataResponse`: readiness, filename, size, url, …). The operation's DTO still\n * described the reference, so `transformOutput` refused every context read of a resource whose file\n * existed: `expected date, received Invalid Date` at `<field>.updatedAt`, a 500, and a degraded body\n * instead of the record. Measured 2026-09-14 on Wonder Todos.\n *\n * Population now keeps the reference and adds the metadata BESIDE it — `file` for one, `files` for\n * several — and the SUMMARY / CONTEXT DTOs declare that companion. Three candidates were weighed:\n *\n * - **Declare the replacement.** The frontend reads a file field as its stored reference (`'fileId' in\n *   value` / `'fileIds' in value`, then fetches metadata by id itself), so a metadata array in place of\n *   `{ fileIds }` fails its multiple-file guard outright. Declaring the replacement would have made the\n *   DTO agree with a shape one consumer cannot read.\n * - **Populate after `transformOutput`.** Validation would then never see the populated value, and the\n *   response DTO — the OpenAPI contract — would describe less than the wire carries.\n * - **Keep the reference (chosen).** Every reader of the reference keeps working, the companion is\n *   OPTIONAL so a read with population disabled or failed (`populateFileFieldsForSingle` keeps the\n *   original value on any error) still validates, and a consumer that wants the metadata finds it at a\n *   named key.\n *\n * The companion's schema carries the file field's decorator metadata forward, so the widened field is\n * still detected as a FILE field (`isFileSchema`, `getSchemaType`) — the same property\n * `resources-config-operations.dtos-builder.file-metadata-coercion.test.ts` pins for date coercion.\n */\nimport {\n  FileDisplayNature,\n  FileReadiness,\n  FileUploaderEntityType,\n  getFileMetadata,\n  getZodDef,\n  getZodDefArrayProperty,\n  getZodDefProperty,\n  getZodDefSchemaProperty,\n  getZodDefStringProperty,\n  getZodObjectShape,\n  getZodType,\n  isZodArray,\n  isZodDefault,\n  isZodNullable,\n  isZodObject,\n  isZodOptional,\n  SCHEMA_METADATA,\n  withArrayElement,\n} from '@wildo-ai/zod-decorators';\nimport { z } from 'zod';\n\n/** The key a populated single-file field carries its metadata under, beside `fileId`. */\nexport const POPULATED_SINGLE_FILE_KEY = 'file' as const;\n/** The key a populated multiple-file field carries its metadata list under, beside `fileIds`. */\nexport const POPULATED_MULTIPLE_FILES_KEY = 'files' as const;\n\n/**\n * `FileMetadata` (`@wildo-ai/zod-decorators`) as a Zod schema, at the NETWORK boundary: `uploadedAt`\n * coerces an ISO string, and the object is loose so a metadata key added later is carried rather\n * than stripped — this is server-produced data, never a request.\n */\nexport const PopulatedFileMetadataSchema: z.ZodTypeAny = z.looseObject({\n  readiness: z.enum(FileReadiness).describe(\"Whether the file may be attached: `ready` may be, `attached` belongs to its current record and is not reused elsewhere, `processing` is still being checked and must be read again, and `unavailable` cannot be newly attached. An upload's success is not this.\"),\n  fileId: z.string().min(1).describe(\"The file's identifier.\"),\n  filename: z.string().describe(\"The file's original name.\"),\n  size: z.number().describe(\"The file's size in bytes.\"),\n  mimeType: z.string().describe(\"The file's media type.\"),\n  extension: z.string().optional().describe(\"The file's extension, without the dot.\"),\n  checksum: z.string().optional().describe(\"A checksum of the file's content.\"),\n  url: z.string().optional().describe(\"Where the file can be downloaded.\"),\n  thumbnailUrl: z.string().optional().describe(\"Where a thumbnail of an image or video can be fetched.\"),\n  nature: z.enum(FileDisplayNature).optional().describe(\"What kind of file it is, for display: image, video, audio, document or generic.\"),\n  width: z.number().optional().describe(\"An image's width in pixels.\"),\n  height: z.number().optional().describe(\"An image's height in pixels.\"),\n  duration: z.number().optional().describe(\"An audio or video file's length in seconds.\"),\n  pageCount: z.number().optional().describe(\"A document's number of pages.\"),\n  uploadedAt: z.coerce.date().describe(\"When the file was uploaded.\"),\n  uploadedBy: z.string().optional().describe(\"The identifier of whoever uploaded the file.\"),\n  uploadedByEntityType: z.enum(FileUploaderEntityType).optional().describe(\"What kind of principal uploaded the file: a user, an anonymous user, or an organization's or the application's machine client.\"),\n}).describe(\"The file's details, included when the read populates files.\");\n\nfunction carrySchemaMetadata<TSchema extends z.ZodTypeAny>(source: z.ZodTypeAny, rebuilt: TSchema): TSchema {\n  const metadata = (source as any)[SCHEMA_METADATA];\n  if (metadata !== undefined) {\n    (rebuilt as any)[SCHEMA_METADATA] = metadata;\n  }\n  // Zod's own registry too (`.describe()` / `.meta()`, #1625): `.extend()` clones without the parent link\n  // a clone inherits it through, so a widened file field would otherwise publish undescribed. Not `id`,\n  // which names one schema.\n  const registered = z.globalRegistry.get(source) as Record<string, unknown> | undefined;\n  if (registered !== undefined && !z.globalRegistry.has(rebuilt)) {\n    const { id: _id, ...carried } = registered;\n    if (Object.keys(carried).length > 0) z.globalRegistry.add(rebuilt, carried as never);\n  }\n  return rebuilt;\n}\n\n/** A `z_file()` leaf (the reference object, metadata attached) widened with its optional populated companion. */\nfunction widenFileLeaf(leaf: z.ZodTypeAny): z.ZodTypeAny {\n  const fileMetadata = getFileMetadata(leaf);\n  if (!fileMetadata || !isZodObject(leaf)) return leaf;\n  const shape = getZodObjectShape(leaf);\n  const companionKey = fileMetadata.multiple ? POPULATED_MULTIPLE_FILES_KEY : POPULATED_SINGLE_FILE_KEY;\n  if (companionKey in shape) return leaf; // already widened (a DTO derived from a widened DTO)\n  const companion = fileMetadata.multiple\n    ? z.array(PopulatedFileMetadataSchema).optional().describe(\"Each file's details, included when the read populates files.\")\n    : PopulatedFileMetadataSchema.optional();\n  return carrySchemaMetadata(leaf, leaf.extend({ [companionKey]: companion }));\n}\n\n/**\n * Rebuild `schema` so every `z_file()` field accepts its populated companion beside the stored\n * reference. Identity-preserving where nothing beneath changed (a wrapper returns the ORIGINAL\n * instance, so an enclosing object is not rebuilt and keeps its metadata — the #989 lesson recorded\n * on `stripTemplatableFileFieldsRecursively`). Applied to READ-side DTOs only, after date coercion.\n */\nexport function widenFileFieldsForPopulatedReads(schema: z.ZodTypeAny, activeSchemas?: WeakSet<object>): z.ZodTypeAny;\nexport function widenFileFieldsForPopulatedReads(schema: undefined, activeSchemas?: WeakSet<object>): undefined;\nexport function widenFileFieldsForPopulatedReads(schema: z.ZodTypeAny | undefined, activeSchemas?: WeakSet<object>): z.ZodTypeAny | undefined;\nexport function widenFileFieldsForPopulatedReads(schema: z.ZodTypeAny | undefined, activeSchemas: WeakSet<object> = new WeakSet<object>()): z.ZodTypeAny | undefined {\n  // An ABSENT schema passes through (#1138). `activeSchemas.add(undefined)` throws\n  // `TypeError: Invalid value used in weak set` — a message naming neither a DTO nor an operation,\n  // raised while a registry is being initialized, so it reaches a human as a backend that will not\n  // boot. `summaryDto` and `contextDto` are declared OPTIONAL on an operation\n  // (`resources-config.shared.schemas.ts:2098`), so absent is a state the contract permits.\n  //\n  // Measured rather than assumed about where it arrives from: `buildAllOperationDtos` DERIVES both\n  // (:545, :572), so its own four call sites never pass an absent one. The reported failure was the\n  // dev companion's projector rebuilding DTOs against the runtime registry — an EXTERNAL caller of\n  // this exported function, which is exactly why the guard belongs here and not at those call\n  // sites (`invariant-call-site-enumeration.md`: prefer making the invariant unbypassable).\n  //\n  // The overloads keep a definite schema in returning a definite schema, so no caller is handed a\n  // widened `| undefined` it then has to narrow.\n  if (!schema) return schema;\n  if (activeSchemas.has(schema)) return schema;\n  activeSchemas.add(schema);\n  try {\n    if (getFileMetadata(schema) && isZodObject(schema)) return widenFileLeaf(schema);\n\n    if (isZodOptional(schema) || isZodNullable(schema) || isZodDefault(schema)) {\n      const inner = getZodDefSchemaProperty(schema, 'innerType');\n      if (!inner) return schema;\n      const widenedInner = widenFileFieldsForPopulatedReads(inner, activeSchemas);\n      if (widenedInner === inner) return schema;\n      const rewrapped = isZodOptional(schema)\n        ? widenedInner.optional()\n        : isZodNullable(schema)\n          ? widenedInner.nullable()\n          : widenedInner.default(() => getZodDefProperty(schema, 'defaultValue') as unknown);\n      return carrySchemaMetadata(schema, rewrapped);\n    }\n\n    const schemaType = getZodType(schema);\n    if (schemaType === 'lazy') {\n      const getter = getZodDef(schema)?.getter;\n      return typeof getter === 'function' ? z.lazy(() => widenFileFieldsForPopulatedReads(getter() as z.ZodTypeAny, activeSchemas)) : schema;\n    }\n\n    if (schemaType === 'union') {\n      const discriminator = getZodDefStringProperty(schema, 'discriminator');\n      const options = getZodDefArrayProperty(schema, 'options') as z.ZodTypeAny[] | undefined;\n      if (!options?.length) return schema;\n      const widened = options.map((option) => widenFileFieldsForPopulatedReads(option, activeSchemas));\n      if (widened.every((option, index) => option === options[index])) return schema;\n      const rebuilt: z.ZodTypeAny = discriminator\n        ? z.discriminatedUnion(discriminator, widened as [z.ZodObject<any>, z.ZodObject<any>, ...z.ZodObject<any>[]])\n        : z.union(widened as [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]]);\n      return carrySchemaMetadata(schema, rebuilt);\n    }\n\n    if (isZodArray(schema)) {\n      const element = getZodDefProperty(schema, 'element') as z.ZodTypeAny | undefined;\n      if (!element) return schema;\n      const widenedElement = widenFileFieldsForPopulatedReads(element, activeSchemas);\n      return widenedElement === element ? schema : withArrayElement(schema, widenedElement);\n    }\n\n    if (!isZodObject(schema)) return schema;\n\n    const shape = getZodObjectShape(schema);\n    const widenedShape: Record<string, z.ZodTypeAny> = {};\n    let changed = false;\n    for (const [fieldName, fieldSchema] of Object.entries(shape)) {\n      const widened = widenFileFieldsForPopulatedReads(fieldSchema as z.ZodTypeAny, activeSchemas);\n      if (widened !== fieldSchema) changed = true;\n      widenedShape[fieldName] = widened;\n    }\n    if (!changed) return schema;\n    return carrySchemaMetadata(schema, schema.extend(widenedShape));\n  } finally {\n    activeSchemas.delete(schema);\n  }\n}\n"]}

package/dist/esm/resources/utils/request-schema-field-carriage.shared.utils.d.ts

@@ -0,0 +1,2 @@
+export declare function requestSchemaCarriesField(schema: unknown, fieldName: string, depth?: number): boolean;
+//# sourceMappingURL=request-schema-field-carriage.shared.utils.d.ts.map

package/dist/esm/resources/utils/request-schema-field-carriage.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-schema-field-carriage.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/request-schema-field-carriage.shared.utils.ts"],"names":[],"mappings":"AAQA,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,OAAO,CAehG"}

package/dist/esm/resources/utils/request-schema-field-carriage.shared.utils.js

@@ -0,0 +1,33 @@
+/**
+ * Whether a request schema can carry `fieldName` as a row field — through wrappers (repeatedly),
+ * unions and discriminated unions (any branch), intersections (either side: a bulk DTO over a non-plain
+ * row is `selector.and(row)`), and the bulk envelope `{ data: row[] }` of CREATE_MANY. Only the `data`
+ * member is followed into an array, so a custom request with an unrelated array of objects is not read as
+ * rows. Used by the closure-clock ownership check (#1613), which must see every shape a client route accepts.
+ */
+const BULK_REQUEST_ROWS_KEY = 'data';
+export function requestSchemaCarriesField(schema, fieldName, depth = 0) {
+    if (!schema || typeof schema !== 'object' || depth > 12)
+        return false;
+    const def = schema._zod?.def ?? schema._def;
+    if (!def)
+        return false;
+    if (def.shape && typeof def.shape === 'object') {
+        if (Object.prototype.hasOwnProperty.call(def.shape, fieldName))
+            return true;
+        const rows = def.shape[BULK_REQUEST_ROWS_KEY];
+        return rows !== undefined && requestSchemaCarriesField(rows, fieldName, depth + 1);
+    }
+    if (Array.isArray(def.options))
+        return def.options.some((option) => requestSchemaCarriesField(option, fieldName, depth + 1));
+    if (def.left || def.right)
+        return requestSchemaCarriesField(def.left, fieldName, depth + 1) || requestSchemaCarriesField(def.right, fieldName, depth + 1);
+    if (def.element)
+        return requestSchemaCarriesField(def.element, fieldName, depth + 1);
+    if (def.innerType)
+        return requestSchemaCarriesField(def.innerType, fieldName, depth + 1);
+    if (def.in)
+        return requestSchemaCarriesField(def.in, fieldName, depth + 1);
+    return false;
+}
+//# sourceMappingURL=request-schema-field-carriage.shared.utils.js.map

package/dist/esm/resources/utils/request-schema-field-carriage.shared.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-schema-field-carriage.shared.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/request-schema-field-carriage.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,qBAAqB,GAAG,MAAM,CAAC;AACrC,MAAM,UAAU,yBAAyB,CAAC,MAAe,EAAE,SAAiB,EAAE,KAAK,GAAG,CAAC;IACrF,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,KAAK,CAAC;IACtE,MAAM,GAAG,GAAI,MAAc,CAAC,IAAI,EAAE,GAAG,IAAK,MAAc,CAAC,IAAI,CAAC;IAC9D,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,IAAI,GAAG,CAAC,KAAK,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/C,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5E,MAAM,IAAI,GAAI,GAAG,CAAC,KAAiC,CAAC,qBAAqB,CAAC,CAAC;QAC3E,OAAO,IAAI,KAAK,SAAS,IAAI,yBAAyB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAe,EAAE,EAAE,CAAC,yBAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACtI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK;QAAE,OAAO,yBAAyB,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,IAAI,yBAAyB,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC1J,IAAI,GAAG,CAAC,OAAO;QAAE,OAAO,yBAAyB,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACrF,IAAI,GAAG,CAAC,SAAS;QAAE,OAAO,yBAAyB,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACzF,IAAI,GAAG,CAAC,EAAE;QAAE,OAAO,yBAAyB,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC3E,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["/**\n * Whether a request schema can carry `fieldName` as a row field — through wrappers (repeatedly),\n * unions and discriminated unions (any branch), intersections (either side: a bulk DTO over a non-plain\n * row is `selector.and(row)`), and the bulk envelope `{ data: row[] }` of CREATE_MANY. Only the `data`\n * member is followed into an array, so a custom request with an unrelated array of objects is not read as\n * rows. Used by the closure-clock ownership check (#1613), which must see every shape a client route accepts.\n */\nconst BULK_REQUEST_ROWS_KEY = 'data';\nexport function requestSchemaCarriesField(schema: unknown, fieldName: string, depth = 0): boolean {\n  if (!schema || typeof schema !== 'object' || depth > 12) return false;\n  const def = (schema as any)._zod?.def ?? (schema as any)._def;\n  if (!def) return false;\n  if (def.shape && typeof def.shape === 'object') {\n    if (Object.prototype.hasOwnProperty.call(def.shape, fieldName)) return true;\n    const rows = (def.shape as Record<string, unknown>)[BULK_REQUEST_ROWS_KEY];\n    return rows !== undefined && requestSchemaCarriesField(rows, fieldName, depth + 1);\n  }\n  if (Array.isArray(def.options)) return def.options.some((option: unknown) => requestSchemaCarriesField(option, fieldName, depth + 1));\n  if (def.left || def.right) return requestSchemaCarriesField(def.left, fieldName, depth + 1) || requestSchemaCarriesField(def.right, fieldName, depth + 1);\n  if (def.element) return requestSchemaCarriesField(def.element, fieldName, depth + 1);\n  if (def.innerType) return requestSchemaCarriesField(def.innerType, fieldName, depth + 1);\n  if (def.in) return requestSchemaCarriesField(def.in, fieldName, depth + 1);\n  return false;\n}\n"]}

package/dist/esm/resources/utils/resource-polymorphism.factory.d.ts

@@ -58,6 +58,21 @@ export type PolymorphicOperationVariant<TMainSchema extends z.ZodTypeAny = z.Zod
     polymorphicRole?: Record<string, string[]>;
     /** Standard roles — used directly or as fallback when polymorphicRole doesn't have the parent */
     roles?: string[];
+    /**
+     * A response DTO built from EACH variant's own main schema, for a response that must carry that variant's
+     * fields — above all its scope foreign key (`organizationId` on the organization variant, `applicationId`
+     * on the application variant), which only the variant schema has. A static `customResponseDto` built from
+     * the shared base schema silently drops it (#1596 review N4).
+     *
+     * Resolved per variant into `customResponseDto`; declaring both is refused, since only one can win.
+     *
+     * @example
+     * polymorphicCustomResponseDto: (variantSchema) => z.object({
+     *   data: z.array((variantSchema as z.ZodObject<z.ZodRawShape>).omit({ rawBody: true })),
+     *   pagination: createPaginationResponseMetadataSchema(DEFAULT_LIST_PAGE_CEILING),
+     * }),
+     */
+    polymorphicCustomResponseDto?: (variantMainSchema: TMainSchema) => z.ZodTypeAny;
 };
 /**
  * Operation configuration with polymorphic role support.

package/dist/esm/resources/utils/resource-polymorphism.factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-polymorphism.factory.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-polymorphism.factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,uCAAuC,EACvC,2CAA2C,EAC3C,iDAAiD,EACjD,wDAAwD,EACxD,2BAA2B,EAC5B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAgB,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,4BAA4B,EAA8B,MAAM,iCAAiC,CAAC;AAMhH;;;;GAIG;AACH,KAAK,gBAAgB,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,IAAI,CAAC,SAAS,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;AAErF;;;;;;;;;;GAUG;AACH;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,CAAC,WAAW,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,IACrF,gBAAgB,CAAC,wDAAwD,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,GAChG,2BAA2B,GAAG;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEJ;;GAEG;AACH,MAAM,MAAM,0BAA0B,CAAC,WAAW,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,IAAI,IAAI,CACxF,iDAAiD,CAAC,WAAW,CAAC,EAC9D,UAAU,CACX,GAAG;IACF,QAAQ,EAAE,2BAA2B,CAAC,WAAW,CAAC,EAAE,CAAC;CACtD,CAAC;AAEF;;;GAGG;AACH,KAAK,yBAAyB,GAC1B,YAAY,GACZ,oBAAoB,GACpB,yBAAyB,GACzB,uBAAuB,GACvB,yBAAyB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,yBAAyB,CACnC,oBAAoB,SAAS,YAAY,GAAG,SAAS,GAAG,SAAS,EACjE,kBAAkB,SAAS,OAAO,CAAC,qBAAqB,CAAC,GAAG,SAAS,GAAG,SAAS,EACjF,WAAW,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,IACzC,IAAI,CACN,uCAAuC,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,WAAW,CAAC,EAC9F,yBAAyB,CAC1B,GAAG;IACF,yEAAyE;IACzE,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,WAAW,CAAC,CAAC,CAAC;CAClF,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,uCAAuC,CACrD,oBAAoB,SAAS,YAAY,GAAG,SAAS,GAAG,SAAS,EACjE,kBAAkB,SAAS,OAAO,CAAC,qBAAqB,CAAC,GAAG,SAAS,GAAG,SAAS,EACjF,WAAW,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,EAE3C,WAAW,EAAE,4BAA4B,CAAC,WAAW,CAAC,EACtD,YAAY,EAAE,yBAAyB,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,WAAW,CAAC,GAC7F,MAAM,CAAC,MAAM,EAAE,2CAA2C,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,GAAG,CAAC,CAAC,CAwC5G"}
+{"version":3,"file":"resource-polymorphism.factory.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-polymorphism.factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,uCAAuC,EACvC,2CAA2C,EAC3C,iDAAiD,EACjD,wDAAwD,EACxD,2BAA2B,EAC5B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAgB,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,4BAA4B,EAA8B,MAAM,iCAAiC,CAAC;AAMhH;;;;GAIG;AACH,KAAK,gBAAgB,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,IAAI,CAAC,SAAS,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;AAErF;;;;;;;;;;GAUG;AACH;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,CAAC,WAAW,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,IACrF,gBAAgB,CAAC,wDAAwD,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,GAChG,2BAA2B,GAAG;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;;;;;;;;OAaG;IACH,4BAA4B,CAAC,EAAE,CAAC,iBAAiB,EAAE,WAAW,KAAK,CAAC,CAAC,UAAU,CAAC;CACjF,CAAC;AAEJ;;GAEG;AACH,MAAM,MAAM,0BAA0B,CAAC,WAAW,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,IAAI,IAAI,CACxF,iDAAiD,CAAC,WAAW,CAAC,EAC9D,UAAU,CACX,GAAG;IACF,QAAQ,EAAE,2BAA2B,CAAC,WAAW,CAAC,EAAE,CAAC;CACtD,CAAC;AAEF;;;GAGG;AACH,KAAK,yBAAyB,GAC1B,YAAY,GACZ,oBAAoB,GACpB,yBAAyB,GACzB,uBAAuB,GACvB,yBAAyB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,yBAAyB,CACnC,oBAAoB,SAAS,YAAY,GAAG,SAAS,GAAG,SAAS,EACjE,kBAAkB,SAAS,OAAO,CAAC,qBAAqB,CAAC,GAAG,SAAS,GAAG,SAAS,EACjF,WAAW,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,IACzC,IAAI,CACN,uCAAuC,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,WAAW,CAAC,EAC9F,yBAAyB,CAC1B,GAAG;IACF,yEAAyE;IACzE,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,WAAW,CAAC,CAAC,CAAC;CAClF,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,uCAAuC,CACrD,oBAAoB,SAAS,YAAY,GAAG,SAAS,GAAG,SAAS,EACjE,kBAAkB,SAAS,OAAO,CAAC,qBAAqB,CAAC,GAAG,SAAS,GAAG,SAAS,EACjF,WAAW,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,EAE3C,WAAW,EAAE,4BAA4B,CAAC,WAAW,CAAC,EACtD,YAAY,EAAE,yBAAyB,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,WAAW,CAAC,GAC7F,MAAM,CAAC,MAAM,EAAE,2CAA2C,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,GAAG,CAAC,CAAC,CAwC5G"}

package/dist/esm/resources/utils/resource-polymorphism.factory.js

@@ -95,7 +95,11 @@ function resolveOperationsForVariant(operationsConfiguration, variant) {
     for (const [operationKey, opConfig] of Object.entries(operationsConfiguration)) {
         const resolvedVariants = [];
         for (const opVariant of opConfig.variants) {
-            const { polymorphicRole, roles: fallbackRoles, ...rest } = opVariant;
+            const { polymorphicRole, roles: fallbackRoles, polymorphicCustomResponseDto, ...rest } = opVariant;
+            if (polymorphicCustomResponseDto && rest.customResponseDto !== undefined) {
+                throw new Error(`[PolymorphicFactory] Operation "${operationKey}" variant declares both customResponseDto and polymorphicCustomResponseDto. ` +
+                    'Declare one: the per-variant form when the response must carry the variant schema\'s own fields.');
+            }
             let resolvedRoles;
             if (polymorphicRole) {
                 // Resolve from polymorphicRole map using the parent resource type
@@ -121,6 +125,7 @@ function resolveOperationsForVariant(operationsConfiguration, variant) {
             resolvedVariants.push({
                 ...rest,
                 roles: resolvedRoles,
+                ...(polymorphicCustomResponseDto ? { customResponseDto: polymorphicCustomResponseDto(variant.schema) } : {}),
             });
         }
         resolved[operationKey] = {

package/dist/esm/resources/utils/resource-polymorphism.factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-polymorphism.factory.js","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-polymorphism.factory.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resource Polymorphism — Factory Configuration (Phase 3)\n *\n * Provides `createPolymorphicResourceConfigurations()` which takes a polymorphic\n * declaration + shared resource configuration, and produces N factory functions\n * (one per variant) that can be spread into the resource configurations factory map.\n *\n * Key transformation: `polymorphicRole` on operation variants is resolved to\n * standard `roles` for each variant's scope.\n *\n * @see polymorphic-scope-approach-A-expansion.md — Phase 3\n */\n\nimport { z } from 'zod';\nimport { createResourceConfiguration_Initialization } from '../resources-config.shared.factory';\nimport type {\n  ResourceConfiguration_BuilderParameters,\n  ResourceConfiguration_InitializationFactory,\n  ResourceConfiguration_Operation_BuilderParameters,\n  ResourceConfiguration_OperationVariant_BuilderParameters,\n  CollectionViewFields_Search,\n} from '../resources-config.shared.schemas';\nimport type { ResourceType, CoreResourceOperation } from '../resources.shared.core.definitions';\nimport type { EnumLikeType } from '@wildo-ai/zod-decorators';\nimport type { PolymorphicSchemaDeclaration, PolymorphicResolvedVariant } from './resource-polymorphism.schemas';\n\n// =============================================================================\n// TYPES\n// =============================================================================\n\n/**\n * Distributive Omit — preserves union members individually.\n * Standard `Omit<A | B, K>` collapses to common keys only, losing per-member properties.\n * This helper distributes the Omit over each union member, preserving all variant-specific fields.\n */\ntype DistributiveOmit<T, K extends PropertyKey> = T extends any ? Omit<T, K> : never;\n\n/**\n * Operation variant with `polymorphicRole` support.\n * Extends the standard variant by adding `polymorphicRole` as an alternative to `roles`.\n *\n * - `polymorphicRole`: `Record<ResourceType, string[]>` — role mapping per parent resource type.\n *   The factory resolves this to standard `roles` for each generated variant.\n * - `roles`: standard roles array — used directly (e.g., for admin variants).\n *\n * If both `polymorphicRole` and `roles` are provided, `polymorphicRole` takes precedence\n * for the matching parent resource type. If the parent isn't in `polymorphicRole`, `roles` is used as fallback.\n */\n/**\n * Polymorphic variant type. Intersects with CollectionViewFields_Search so that\n * SEARCH operation variants (including REPOSITORY_ONLY) can specify isSearchable,\n * searchableFields, filterFields, sortFields, etc. All fields are optional.\n */\nexport type PolymorphicOperationVariant<TMainSchema extends z.ZodTypeAny = z.ZodTypeAny> =\n  DistributiveOmit<ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema>, 'roles'> &\n  CollectionViewFields_Search & {\n    /**\n     * Role mapping per parent resource type.\n     * The factory resolves this into standard `roles` for each generated variant.\n     *\n     * ⚠️ An EMPTY array is NOT \"skip the role check\" — it is fail-CLOSED. The\n     * authorization gate evaluates `operationRoles.some(...)`, and `[].some()`\n     * is always `false`, so an empty array denies EVERY caller (403). For the\n     * user-self scope, list the baseline authenticated role (`APP_USER`); role\n     * membership is the floor, while row ownership is enforced separately by the\n     * USER_SELF scope authorizer.\n     *\n     * @example\n     * polymorphicRole: {\n     *   'organizations': ['ORG_OWNER', 'ORG_ADMIN'],\n     *   'users': ['APP_USER'],  // user-self: any authenticated user (ownership checked by scope)\n     * }\n     */\n    polymorphicRole?: Record<string, string[]>;\n    /** Standard roles — used directly or as fallback when polymorphicRole doesn't have the parent */\n    roles?: string[];\n  };\n\n/**\n * Operation configuration with polymorphic role support.\n */\nexport type PolymorphicOperationConfig<TMainSchema extends z.ZodTypeAny = z.ZodAny> = Omit<\n  ResourceConfiguration_Operation_BuilderParameters<TMainSchema>,\n  'variants'\n> & {\n  variants: PolymorphicOperationVariant<TMainSchema>[];\n};\n\n/**\n * Keys the polymorphic factory derives PER VARIANT — the only things a shared config cannot supply.\n * Everything else is shared, and is now inherited structurally (see {@link PolymorphicResourceConfig}).\n */\ntype PolymorphicPerVariantKeys =\n  | 'mainSchema'              // derived per variant from the declaration\n  | 'resourceIdentifier'      // derived per variant\n  | 'resourceFieldIdentifier' // derived per variant\n  | 'resourceRelationships'   // provided at factory call time by the registry\n  | 'operationsConfiguration';// replaced by the polymorphicRole-aware shape below\n\n/**\n * Shared resource configuration for polymorphic resources — everything common across all variants.\n *\n * ⚠️ DERIVED FROM `ResourceConfiguration_BuilderParameters`, deliberately. This used to be a\n * hand-maintained whitelist of forwarded fields, and it silently DROPPED every resource-level\n * capability axis added after it was written (`isAnonymizable`, `transpositionPolicy`,\n * `retentionPolicy`). The failure mode was invisible: a polymorphic resource could ASK for a\n * capability and simply not get it — no type error, no runtime error, the opt-in just evaporated.\n * Because the type is now an `Omit` of the real parameter surface and the values are spread through,\n * ANY capability added to the builder parameters is automatically available to polymorphic resources\n * and forwarded — there is no list left to forget.\n *\n * Per-variant keys are omitted (see {@link PolymorphicPerVariantKeys}); `operationsConfiguration` is\n * re-declared with the `polymorphicRole`-aware variant shape.\n *\n * NOTE ON SEMANTICS: a capability declared here applies to EVERY generated variant (that is the point\n * — e.g. all billing scopes retain identically). A capability that is invalid for one variant's scope\n * fails loud in that variant's factory call, which is the correct outcome; per-variant capability\n * overrides are intentionally NOT modelled (no consumer needs them, and they would reintroduce the\n * \"which variant actually got it?\" ambiguity this contract removes).\n */\nexport type PolymorphicResourceConfig<\n  TCustomOperationEnum extends EnumLikeType | undefined = undefined,\n  TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,\n  TMainSchema extends z.ZodTypeAny = z.ZodAny,\n> = Omit<\n  ResourceConfiguration_BuilderParameters<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,\n  PolymorphicPerVariantKeys\n> & {\n  /** Operations configuration — supports `polymorphicRole` on variants. */\n  operationsConfiguration: Record<string, PolymorphicOperationConfig<TMainSchema>>;\n};\n\n// =============================================================================\n// MAIN FUNCTION\n// =============================================================================\n\n/**\n * Create N resource configuration factories from a polymorphic declaration.\n *\n * For each variant in the declaration, produces a standard\n * `ResourceConfiguration_InitializationFactory` that can be registered in the factory map.\n *\n * The key transformation: `polymorphicRole` on operation variants is resolved to\n * standard `roles` for each variant's parent resource type.\n *\n * @returns Record mapping variant resource type → factory function\n *\n * @example\n * ```typescript\n * const billingAccountFactories = createPolymorphicResourceConfigurations(\n *   billingAccountsPolymorphicDeclaration,\n *   {\n *     coreOperations: [CoreResourceOperation.READ, CoreResourceOperation.LIST, ...],\n *     operationsConfiguration: {\n *       [CoreResourceOperation.READ]: {\n *         variants: [{\n *           variantType: ResourceOperationVariantType.API_CALL,\n *           isDefault: true,\n *           polymorphicRole: {\n *             'organizations': [CORE_ORG_ROLES.ORG_OWNER],\n *             'users': [CORE_APP_ROLES.APP_USER], // never [] — empty is fail-closed (403)\n *           },\n *           riskLevel: ResourceOperationRiskLevel.LOW,\n *         }],\n *       },\n *     },\n *   },\n * );\n * // → {\n * //     'organizationBillingAccounts': (rels) => ResourceConfiguration,\n * //     'userBillingAccounts': (rels) => ResourceConfiguration,\n * //   }\n * ```\n */\nexport function createPolymorphicResourceConfigurations<\n  TCustomOperationEnum extends EnumLikeType | undefined = undefined,\n  TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,\n  TMainSchema extends z.ZodTypeAny = z.ZodAny,\n>(\n  declaration: PolymorphicSchemaDeclaration<TMainSchema>,\n  sharedConfig: PolymorphicResourceConfig<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,\n): Record<string, ResourceConfiguration_InitializationFactory<TCustomOperationEnum, TCoreOperationEnum, any>> {\n  const result: Record<string, ResourceConfiguration_InitializationFactory<TCustomOperationEnum, TCoreOperationEnum, any>> = {};\n\n  for (const [, variant] of declaration.variants) {\n    const resolvedOpsConfig = resolveOperationsForVariant(\n      sharedConfig.operationsConfiguration,\n      variant,\n    );\n\n    // Determine the schema for this variant:\n    // - If SchemaFamily, use the rebuilt union\n    // - If plain ZodObject, use the variant schema directly\n    const variantMainSchema = variant.schema;\n\n    // Determine inheritenceSchemaDefinition:\n    // - If SchemaFamily, use the rebuilt family's inheritenceSchemaDefinition\n    // - Otherwise, use the shared config's (if any)\n    const inheritenceSchemaDefinition = variant.schemaFamily\n      ? variant.schemaFamily.inheritenceSchemaDefinition as any\n      : sharedConfig.inheritenceSchemaDefinition;\n\n    // Lazy factory: relationships are provided at registry call time, not at declaration time.\n    // SPREAD the shared config rather than re-listing its fields: that is what makes every current\n    // AND FUTURE resource-level capability (retentionPolicy, isAnonymizable, transpositionPolicy, …)\n    // reach the generated variants automatically. Re-listing is how those three were silently lost.\n    // Only the genuinely per-variant keys are overridden below.\n    result[variant.resourceType] = (resourcesRelationships) =>\n      createResourceConfiguration_Initialization({\n        ...(sharedConfig as any),\n        mainSchema: variantMainSchema,\n        resourceIdentifier: variant.resourceType as ResourceType,\n        resourceFieldIdentifier: variant.fieldIdentifier,\n        resourceRelationships: resourcesRelationships,\n        // A variant carrying its own SchemaFamily overrides the shared definition.\n        inheritenceSchemaDefinition,\n        operationsConfiguration: resolvedOpsConfig as any,\n      });\n  }\n\n  return result;\n}\n\n// =============================================================================\n// INTERNALS\n// =============================================================================\n\n/**\n * Resolve `polymorphicRole` → `roles` for each operation variant for a specific scope variant.\n */\nfunction resolveOperationsForVariant<TMainSchema extends z.ZodTypeAny>(\n  operationsConfiguration: Record<string, PolymorphicOperationConfig<TMainSchema>>,\n  variant: PolymorphicResolvedVariant<TMainSchema>,\n): Record<string, ResourceConfiguration_Operation_BuilderParameters<TMainSchema>> {\n  const resolved: Record<string, ResourceConfiguration_Operation_BuilderParameters<TMainSchema>> = {};\n\n  for (const [operationKey, opConfig] of Object.entries(operationsConfiguration)) {\n    const resolvedVariants: ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema>[] = [];\n\n    for (const opVariant of opConfig.variants) {\n      const { polymorphicRole, roles: fallbackRoles, ...rest } = opVariant;\n\n      let resolvedRoles: string[];\n\n      if (polymorphicRole) {\n        // Resolve from polymorphicRole map using the parent resource type\n        const parentType = variant.parentResourceType as string;\n        if (parentType in polymorphicRole) {\n          resolvedRoles = polymorphicRole[parentType]!;\n        } else if (fallbackRoles) {\n          resolvedRoles = fallbackRoles;\n        } else {\n          throw new Error(\n            `[PolymorphicFactory] Operation \"${operationKey}\" variant has polymorphicRole but no entry ` +\n            `for parentResourceType=\"${parentType}\" and no fallback roles. ` +\n            `Either add \"${parentType}\" to polymorphicRole or provide fallback roles.`\n          );\n        }\n      } else if (fallbackRoles) {\n        resolvedRoles = fallbackRoles;\n      } else {\n        throw new Error(\n          `[PolymorphicFactory] Operation \"${operationKey}\" variant has neither polymorphicRole nor roles.`\n        );\n      }\n\n      resolvedVariants.push({\n        ...rest,\n        roles: resolvedRoles,\n      } as ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema>);\n    }\n\n    resolved[operationKey] = {\n      ...opConfig,\n      variants: resolvedVariants,\n    };\n  }\n\n  return resolved;\n}\n"]}
+{"version":3,"file":"resource-polymorphism.factory.js","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-polymorphism.factory.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resource Polymorphism — Factory Configuration (Phase 3)\n *\n * Provides `createPolymorphicResourceConfigurations()` which takes a polymorphic\n * declaration + shared resource configuration, and produces N factory functions\n * (one per variant) that can be spread into the resource configurations factory map.\n *\n * Key transformation: `polymorphicRole` on operation variants is resolved to\n * standard `roles` for each variant's scope.\n *\n * @see polymorphic-scope-approach-A-expansion.md — Phase 3\n */\n\nimport { z } from 'zod';\nimport { createResourceConfiguration_Initialization } from '../resources-config.shared.factory';\nimport type {\n  ResourceConfiguration_BuilderParameters,\n  ResourceConfiguration_InitializationFactory,\n  ResourceConfiguration_Operation_BuilderParameters,\n  ResourceConfiguration_OperationVariant_BuilderParameters,\n  CollectionViewFields_Search,\n} from '../resources-config.shared.schemas';\nimport type { ResourceType, CoreResourceOperation } from '../resources.shared.core.definitions';\nimport type { EnumLikeType } from '@wildo-ai/zod-decorators';\nimport type { PolymorphicSchemaDeclaration, PolymorphicResolvedVariant } from './resource-polymorphism.schemas';\n\n// =============================================================================\n// TYPES\n// =============================================================================\n\n/**\n * Distributive Omit — preserves union members individually.\n * Standard `Omit<A | B, K>` collapses to common keys only, losing per-member properties.\n * This helper distributes the Omit over each union member, preserving all variant-specific fields.\n */\ntype DistributiveOmit<T, K extends PropertyKey> = T extends any ? Omit<T, K> : never;\n\n/**\n * Operation variant with `polymorphicRole` support.\n * Extends the standard variant by adding `polymorphicRole` as an alternative to `roles`.\n *\n * - `polymorphicRole`: `Record<ResourceType, string[]>` — role mapping per parent resource type.\n *   The factory resolves this to standard `roles` for each generated variant.\n * - `roles`: standard roles array — used directly (e.g., for admin variants).\n *\n * If both `polymorphicRole` and `roles` are provided, `polymorphicRole` takes precedence\n * for the matching parent resource type. If the parent isn't in `polymorphicRole`, `roles` is used as fallback.\n */\n/**\n * Polymorphic variant type. Intersects with CollectionViewFields_Search so that\n * SEARCH operation variants (including REPOSITORY_ONLY) can specify isSearchable,\n * searchableFields, filterFields, sortFields, etc. All fields are optional.\n */\nexport type PolymorphicOperationVariant<TMainSchema extends z.ZodTypeAny = z.ZodTypeAny> =\n  DistributiveOmit<ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema>, 'roles'> &\n  CollectionViewFields_Search & {\n    /**\n     * Role mapping per parent resource type.\n     * The factory resolves this into standard `roles` for each generated variant.\n     *\n     * ⚠️ An EMPTY array is NOT \"skip the role check\" — it is fail-CLOSED. The\n     * authorization gate evaluates `operationRoles.some(...)`, and `[].some()`\n     * is always `false`, so an empty array denies EVERY caller (403). For the\n     * user-self scope, list the baseline authenticated role (`APP_USER`); role\n     * membership is the floor, while row ownership is enforced separately by the\n     * USER_SELF scope authorizer.\n     *\n     * @example\n     * polymorphicRole: {\n     *   'organizations': ['ORG_OWNER', 'ORG_ADMIN'],\n     *   'users': ['APP_USER'],  // user-self: any authenticated user (ownership checked by scope)\n     * }\n     */\n    polymorphicRole?: Record<string, string[]>;\n    /** Standard roles — used directly or as fallback when polymorphicRole doesn't have the parent */\n    roles?: string[];\n    /**\n     * A response DTO built from EACH variant's own main schema, for a response that must carry that variant's\n     * fields — above all its scope foreign key (`organizationId` on the organization variant, `applicationId`\n     * on the application variant), which only the variant schema has. A static `customResponseDto` built from\n     * the shared base schema silently drops it (#1596 review N4).\n     *\n     * Resolved per variant into `customResponseDto`; declaring both is refused, since only one can win.\n     *\n     * @example\n     * polymorphicCustomResponseDto: (variantSchema) => z.object({\n     *   data: z.array((variantSchema as z.ZodObject<z.ZodRawShape>).omit({ rawBody: true })),\n     *   pagination: createPaginationResponseMetadataSchema(DEFAULT_LIST_PAGE_CEILING),\n     * }),\n     */\n    polymorphicCustomResponseDto?: (variantMainSchema: TMainSchema) => z.ZodTypeAny;\n  };\n\n/**\n * Operation configuration with polymorphic role support.\n */\nexport type PolymorphicOperationConfig<TMainSchema extends z.ZodTypeAny = z.ZodAny> = Omit<\n  ResourceConfiguration_Operation_BuilderParameters<TMainSchema>,\n  'variants'\n> & {\n  variants: PolymorphicOperationVariant<TMainSchema>[];\n};\n\n/**\n * Keys the polymorphic factory derives PER VARIANT — the only things a shared config cannot supply.\n * Everything else is shared, and is now inherited structurally (see {@link PolymorphicResourceConfig}).\n */\ntype PolymorphicPerVariantKeys =\n  | 'mainSchema'              // derived per variant from the declaration\n  | 'resourceIdentifier'      // derived per variant\n  | 'resourceFieldIdentifier' // derived per variant\n  | 'resourceRelationships'   // provided at factory call time by the registry\n  | 'operationsConfiguration';// replaced by the polymorphicRole-aware shape below\n\n/**\n * Shared resource configuration for polymorphic resources — everything common across all variants.\n *\n * ⚠️ DERIVED FROM `ResourceConfiguration_BuilderParameters`, deliberately. This used to be a\n * hand-maintained whitelist of forwarded fields, and it silently DROPPED every resource-level\n * capability axis added after it was written (`isAnonymizable`, `transpositionPolicy`,\n * `retentionPolicy`). The failure mode was invisible: a polymorphic resource could ASK for a\n * capability and simply not get it — no type error, no runtime error, the opt-in just evaporated.\n * Because the type is now an `Omit` of the real parameter surface and the values are spread through,\n * ANY capability added to the builder parameters is automatically available to polymorphic resources\n * and forwarded — there is no list left to forget.\n *\n * Per-variant keys are omitted (see {@link PolymorphicPerVariantKeys}); `operationsConfiguration` is\n * re-declared with the `polymorphicRole`-aware variant shape.\n *\n * NOTE ON SEMANTICS: a capability declared here applies to EVERY generated variant (that is the point\n * — e.g. all billing scopes retain identically). A capability that is invalid for one variant's scope\n * fails loud in that variant's factory call, which is the correct outcome; per-variant capability\n * overrides are intentionally NOT modelled (no consumer needs them, and they would reintroduce the\n * \"which variant actually got it?\" ambiguity this contract removes).\n */\nexport type PolymorphicResourceConfig<\n  TCustomOperationEnum extends EnumLikeType | undefined = undefined,\n  TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,\n  TMainSchema extends z.ZodTypeAny = z.ZodAny,\n> = Omit<\n  ResourceConfiguration_BuilderParameters<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,\n  PolymorphicPerVariantKeys\n> & {\n  /** Operations configuration — supports `polymorphicRole` on variants. */\n  operationsConfiguration: Record<string, PolymorphicOperationConfig<TMainSchema>>;\n};\n\n// =============================================================================\n// MAIN FUNCTION\n// =============================================================================\n\n/**\n * Create N resource configuration factories from a polymorphic declaration.\n *\n * For each variant in the declaration, produces a standard\n * `ResourceConfiguration_InitializationFactory` that can be registered in the factory map.\n *\n * The key transformation: `polymorphicRole` on operation variants is resolved to\n * standard `roles` for each variant's parent resource type.\n *\n * @returns Record mapping variant resource type → factory function\n *\n * @example\n * ```typescript\n * const billingAccountFactories = createPolymorphicResourceConfigurations(\n *   billingAccountsPolymorphicDeclaration,\n *   {\n *     coreOperations: [CoreResourceOperation.READ, CoreResourceOperation.LIST, ...],\n *     operationsConfiguration: {\n *       [CoreResourceOperation.READ]: {\n *         variants: [{\n *           variantType: ResourceOperationVariantType.API_CALL,\n *           isDefault: true,\n *           polymorphicRole: {\n *             'organizations': [CORE_ORG_ROLES.ORG_OWNER],\n *             'users': [CORE_APP_ROLES.APP_USER], // never [] — empty is fail-closed (403)\n *           },\n *           riskLevel: ResourceOperationRiskLevel.LOW,\n *         }],\n *       },\n *     },\n *   },\n * );\n * // → {\n * //     'organizationBillingAccounts': (rels) => ResourceConfiguration,\n * //     'userBillingAccounts': (rels) => ResourceConfiguration,\n * //   }\n * ```\n */\nexport function createPolymorphicResourceConfigurations<\n  TCustomOperationEnum extends EnumLikeType | undefined = undefined,\n  TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,\n  TMainSchema extends z.ZodTypeAny = z.ZodAny,\n>(\n  declaration: PolymorphicSchemaDeclaration<TMainSchema>,\n  sharedConfig: PolymorphicResourceConfig<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,\n): Record<string, ResourceConfiguration_InitializationFactory<TCustomOperationEnum, TCoreOperationEnum, any>> {\n  const result: Record<string, ResourceConfiguration_InitializationFactory<TCustomOperationEnum, TCoreOperationEnum, any>> = {};\n\n  for (const [, variant] of declaration.variants) {\n    const resolvedOpsConfig = resolveOperationsForVariant(\n      sharedConfig.operationsConfiguration,\n      variant,\n    );\n\n    // Determine the schema for this variant:\n    // - If SchemaFamily, use the rebuilt union\n    // - If plain ZodObject, use the variant schema directly\n    const variantMainSchema = variant.schema;\n\n    // Determine inheritenceSchemaDefinition:\n    // - If SchemaFamily, use the rebuilt family's inheritenceSchemaDefinition\n    // - Otherwise, use the shared config's (if any)\n    const inheritenceSchemaDefinition = variant.schemaFamily\n      ? variant.schemaFamily.inheritenceSchemaDefinition as any\n      : sharedConfig.inheritenceSchemaDefinition;\n\n    // Lazy factory: relationships are provided at registry call time, not at declaration time.\n    // SPREAD the shared config rather than re-listing its fields: that is what makes every current\n    // AND FUTURE resource-level capability (retentionPolicy, isAnonymizable, transpositionPolicy, …)\n    // reach the generated variants automatically. Re-listing is how those three were silently lost.\n    // Only the genuinely per-variant keys are overridden below.\n    result[variant.resourceType] = (resourcesRelationships) =>\n      createResourceConfiguration_Initialization({\n        ...(sharedConfig as any),\n        mainSchema: variantMainSchema,\n        resourceIdentifier: variant.resourceType as ResourceType,\n        resourceFieldIdentifier: variant.fieldIdentifier,\n        resourceRelationships: resourcesRelationships,\n        // A variant carrying its own SchemaFamily overrides the shared definition.\n        inheritenceSchemaDefinition,\n        operationsConfiguration: resolvedOpsConfig as any,\n      });\n  }\n\n  return result;\n}\n\n// =============================================================================\n// INTERNALS\n// =============================================================================\n\n/**\n * Resolve `polymorphicRole` → `roles` for each operation variant for a specific scope variant.\n */\nfunction resolveOperationsForVariant<TMainSchema extends z.ZodTypeAny>(\n  operationsConfiguration: Record<string, PolymorphicOperationConfig<TMainSchema>>,\n  variant: PolymorphicResolvedVariant<TMainSchema>,\n): Record<string, ResourceConfiguration_Operation_BuilderParameters<TMainSchema>> {\n  const resolved: Record<string, ResourceConfiguration_Operation_BuilderParameters<TMainSchema>> = {};\n\n  for (const [operationKey, opConfig] of Object.entries(operationsConfiguration)) {\n    const resolvedVariants: ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema>[] = [];\n\n    for (const opVariant of opConfig.variants) {\n      const { polymorphicRole, roles: fallbackRoles, polymorphicCustomResponseDto, ...rest } = opVariant;\n      if (polymorphicCustomResponseDto && (rest as { customResponseDto?: unknown }).customResponseDto !== undefined) {\n        throw new Error(\n          `[PolymorphicFactory] Operation \"${operationKey}\" variant declares both customResponseDto and polymorphicCustomResponseDto. ` +\n          'Declare one: the per-variant form when the response must carry the variant schema\\'s own fields.'\n        );\n      }\n\n      let resolvedRoles: string[];\n\n      if (polymorphicRole) {\n        // Resolve from polymorphicRole map using the parent resource type\n        const parentType = variant.parentResourceType as string;\n        if (parentType in polymorphicRole) {\n          resolvedRoles = polymorphicRole[parentType]!;\n        } else if (fallbackRoles) {\n          resolvedRoles = fallbackRoles;\n        } else {\n          throw new Error(\n            `[PolymorphicFactory] Operation \"${operationKey}\" variant has polymorphicRole but no entry ` +\n            `for parentResourceType=\"${parentType}\" and no fallback roles. ` +\n            `Either add \"${parentType}\" to polymorphicRole or provide fallback roles.`\n          );\n        }\n      } else if (fallbackRoles) {\n        resolvedRoles = fallbackRoles;\n      } else {\n        throw new Error(\n          `[PolymorphicFactory] Operation \"${operationKey}\" variant has neither polymorphicRole nor roles.`\n        );\n      }\n\n      resolvedVariants.push({\n        ...rest,\n        roles: resolvedRoles,\n        ...(polymorphicCustomResponseDto ? { customResponseDto: polymorphicCustomResponseDto(variant.schema) } : {}),\n      } as ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema>);\n    }\n\n    resolved[operationKey] = {\n      ...opConfig,\n      variants: resolvedVariants,\n    };\n  }\n\n  return resolved;\n}\n"]}

package/dist/esm/resources/utils/resource-polymorphism.schemas.js

@@ -495,6 +495,19 @@ function cloneFieldForBusinessKeyDecoration(value) {
  * forcing the change to either (a) propagate the outer metadata explicitly
  * or (b) document why it's safe to drop.
  *
+ * **The one outer decorator that IS propagated: `.businessKeySet([...])`**
+ * (#1596). A many-rows-per-scope polymorphic resource whose identity is a
+ * COMPOSITE of base fields — the inbound-delivery ledger's
+ * `(sourceKey, dedupKey)` — declares it on the base object, and each variant
+ * is its own table, so each variant must carry the compound unique index.
+ * Dropping it would leave the dedup ledger with no index at all, which is the
+ * exact silent loss this guard exists to stop; refusing it would leave a
+ * polymorphic resource no way to declare a composite identity. So the set is
+ * re-applied to the fresh wrapper, after checking every named field still
+ * exists on the post-injection, post-rename shape (a renamed field would
+ * otherwise produce an index over a column that does not exist). Every OTHER
+ * outer key still fails loud, for the reason above.
+ *
  * @param schema The post-injection, post-rename variant ZodObject.
  * @param fieldNames Field names (post-rename) to mark with `.isBusinessKey()`.
  * @param baseResourceType For error context (the polymorphic base name).
@@ -509,18 +522,31 @@ function applyBusinessKeyMarkers(schema, fieldNames, baseResourceType, parentRes
     // because no current call site needs it; instead we fail loud so the next
     // caller that DOES need it has to make a deliberate design decision.
     const outerMetadata = getFieldMetadata(schema);
-    if (outerMetadata && Object.keys(outerMetadata).length > 0) {
+    const propagatedBusinessKeySet = outerMetadata?.[ZodDecorator.OBJECT_BUSINESS_KEY_SET];
+    const unpropagatedOuterKeys = Object.keys(outerMetadata ?? {}).filter((key) => key !== ZodDecorator.OBJECT_BUSINESS_KEY_SET);
+    if (unpropagatedOuterKeys.length > 0) {
         throw new Error(`[PolymorphicSchemas] baseResourceType="${baseResourceType}" parentResourceType="${parentResourceType}": ` +
             `applyBusinessKeyMarkers received a ZodObject with outer-level metadata ` +
-            `(keys: [${Object.keys(outerMetadata).join(', ')}]). The function rebuilds ` +
+            `(keys: [${unpropagatedOuterKeys.join(', ')}]). The function rebuilds ` +
             `the wrapper via z.object(...), which would silently drop those entries. ` +
             `Either remove the outer metadata before calling, or extend this helper ` +
             `to propagate it (and add a regression test). See JSDoc "Outer-level ` +
             `metadata contract" for the full rationale.`);
     }
     const shape = getZodObjectShape(schema);
+    if (propagatedBusinessKeySet) {
+        const missingKeyFields = propagatedBusinessKeySet.fields.filter((field) => !Object.prototype.hasOwnProperty.call(shape, field));
+        if (missingKeyFields.length > 0) {
+            throw new Error(`[PolymorphicSchemas] baseResourceType="${baseResourceType}" parentResourceType="${parentResourceType}": ` +
+                `the base object's businessKeySet names field(s) absent from the post-injection variant shape: ` +
+                `[${missingKeyFields.join(', ')}]. A renamed field cannot carry a compound unique index under its old name.`);
+        }
+    }
+    const withPropagatedBusinessKeySet = (rebuilt) => propagatedBusinessKeySet
+        ? addDecorators(rebuilt, [{ ref: ZodDecorator.OBJECT_BUSINESS_KEY_SET, params: { ...propagatedBusinessKeySet } }])
+        : rebuilt;
     if (fieldNames.length === 0) {
-        return z.object({ ...shape });
+        return withPropagatedBusinessKeySet(z.object({ ...shape }));
     }
     for (const fieldName of fieldNames) {
         if (!Object.prototype.hasOwnProperty.call(shape, fieldName)) {
@@ -560,6 +586,6 @@ function applyBusinessKeyMarkers(schema, fieldNames, baseResourceType, parentRes
             ? addDecorators(cloneFieldForBusinessKeyDecoration(value), businessKeyDecorators)
             : value;
     }
-    return z.object(newShape);
+    return withPropagatedBusinessKeySet(z.object(newShape));
 }
 //# sourceMappingURL=resource-polymorphism.schemas.js.map