@wildo-ai/saas-models 1.1.4 → 1.1.6

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.relationships.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-polymorphism.relationships.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resource-polymorphism.relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EACL,kBAAkB,EAClB,+BAA+B,EAC/B,KAAK,+BAA+B,EACrC,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAClF,OAAO,KAAK,EAAE,qBAAqB,EAAE,iCAAiC,EAAE,MAAM,oCAAoC,CAAC;AACnH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,iCAAiC,CAAC;AAMpF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,8BAA8B;IAC7C,2CAA2C;IAC3C,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,qCAAqC;IACrC,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,qFAAqF;IACrF,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAClD,kFAAkF;IAClF,SAAS,CAAC,EAAE,+BAA+B,CAAC;IAC5C,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mCAAmC,CACjD,WAAW,EAAE,4BAA4B,EACzC,OAAO,EAAE;IACP,yEAAyE;IACzE,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,gDAAgD;IAChD,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gDAAgD;IAChD,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,+BAA+B,CAAC;CACpD,GACA,oBAAoB,EAAE,CAyBxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,8BAA8B,CAC5C,iBAAiB,EAAE,4BAA4B,EAC/C,sBAAsB,EAAE,4BAA4B,GAAG,YAAY,EACnE,iBAAiB,EAAE,+BAA+B,EAClD,gBAAgB,EAAE,+BAA+B,EACjD,OAAO,EAAE,8BAA8B,GACtC,oBAAoB,EAAE,CA8CxB"}
+{"version":3,"file":"resource-polymorphism.relationships.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-polymorphism.relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EACL,kBAAkB,EAClB,+BAA+B,EAC/B,KAAK,+BAA+B,EACrC,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAClF,OAAO,KAAK,EAAE,qBAAqB,EAAE,iCAAiC,EAAE,MAAM,oCAAoC,CAAC;AACnH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,iCAAiC,CAAC;AAMpF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,8BAA8B;IAC7C,2CAA2C;IAC3C,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,qCAAqC;IACrC,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,qFAAqF;IACrF,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAClD,kFAAkF;IAClF,SAAS,CAAC,EAAE,+BAA+B,CAAC;IAC5C,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mCAAmC,CACjD,WAAW,EAAE,4BAA4B,EACzC,OAAO,EAAE;IACP,yEAAyE;IACzE,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,gDAAgD;IAChD,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gDAAgD;IAChD,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,+BAA+B,CAAC;CACpD,GACA,oBAAoB,EAAE,CAyBxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,8BAA8B,CAC5C,iBAAiB,EAAE,4BAA4B,EAC/C,sBAAsB,EAAE,4BAA4B,GAAG,YAAY,EACnE,iBAAiB,EAAE,+BAA+B,EAClD,gBAAgB,EAAE,+BAA+B,EACjD,OAAO,EAAE,8BAA8B,GACtC,oBAAoB,EAAE,CA8CxB"}

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

@@ -1 +1 @@
-{"version":3,"file":"resource-polymorphism.schemas.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resource-polymorphism.schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource-polymorphism.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-polymorphism.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA6B,KAAK,kCAAkC,EAAiC,MAAM,+BAA+B,CAAC;AAClJ,OAAO,KAAK,EAAE,YAAY,EAAgB,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAMzE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,4BAA6B,SAAQ,kCAAkC;IACtF;;;;OAIG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AACD,yEAAyE;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,4BAA4B,GACvC,4BAA4B,CAE9B;AACD,0EAA0E;AAE1E;;;GAGG;AACH,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;IACrF,2DAA2D;IAC3D,kBAAkB,EAAE,YAAY,CAAC;IACjC,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,cAAc,EAAE,OAAO,CAAC;IACxB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB,uFAAuF;IACvF,YAAY,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5H;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;IACvF,uCAAuC;IACvC,aAAa,EAAE,IAAI,CAAC;IACpB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,UAAU,EAAE,OAAO,CAAC;IACpB,oEAAoE;IACpE,kBAAkB,EAAE,4BAA4B,EAAE,CAAC;IACnD,4FAA4F;IAC5F,QAAQ,EAAE,GAAG,CAAC,YAAY,EAAE,0BAA0B,CAAC,OAAO,CAAC,CAAC,CAAC;CAClE;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU;IAC3E,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,4BAA4B,EAAE,CAAC;CAC1C;AAiCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,EACpE,MAAM,EAAE,+BAA+B,CAAC,OAAO,CAAC,GAC/C,4BAA4B,CAAC,OAAO,CAAC,CAkMvC;AAgED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EACtC,QAAQ,EAAE,aAAa,CAAC;IAAE,kBAAkB,EAAE,MAAM,CAAA;CAAE,CAAC,GACtD,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAezC"}

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

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

@@ -1 +1 @@
-{"version":3,"file":"resource-polymorphism.schemas.js","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-polymorphism.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resource Polymorphism — Schema Declaration (Phase 1)\n *\n * Provides `declarePolymorphicSchemas()` which takes a base schema and a list\n * of parent variant definitions, and produces a `PolymorphicSchemaDeclaration`\n * containing pre-computed schemas for each variant (base + injected parent FK).\n *\n * Supports both plain `z.ZodObject` and `SchemaFamily` as base schema input.\n *\n * @see polymorphic-scope-approach-A-expansion.md — Phase 1\n */\n\nimport { z } from 'zod';\nimport { getZodObjectShape, addDiscriminator, getPolymorphicFkVariants, addDecorators, ZodDecorator, SCHEMA_METADATA, getFieldMetadata } from '@wildo-ai/zod-decorators';\nimport { ResourcePolymorphismUtils, type PolymorphicParentVariantDefinition, type PolymorphicVariantNaming } from './resource-polymorphism.utils';\nimport type { SchemaFamily, EnumLikeType, VariantConfig } from './schema-family-builder.utils';\nimport type { ResourceConfiguration_InheritanceSchemaDefinition } from '../resources-config.shared.schemas';\nimport type { ResourceType } from '../resources.shared.core.definitions';\n\n// =============================================================================\n// TYPES\n// =============================================================================\n\n/**\n * @wildo_source:part:start saas.models.polymorphism.variant-definition facet:layer:shared facet:family:polymorphism\n *\n * One entry in the variant list passed to `declarePolymorphicSchemas()` (from\n * `@wildo-ai/saas-models`) — describes ONE scope a polymorphic resource is\n * stamped out for. Besides the two fields below it also carries the inherited\n * `parentResourceType` (the scope entity — e.g. ORGANIZATIONS / APPLICATION /\n * USERS) and `parentFieldIdentifier` (the scope FK the engine injects into the\n * variant schema — e.g. `organizationId` / `applicationId`). The\n * `isPrimaryScope` + `businessKeyFields` pair is the SINGLETON-vs-MULTI-ROW\n * decision: a singleton scope FK becomes a one-per-scope unique business key; a\n * multi-row (collection) resource must opt out via `optOutPolymorphicAutoBusinessKey`.\n */\nexport interface PolymorphicVariantDefinition extends PolymorphicParentVariantDefinition {\n  /**\n   * Whether this variant's parent is a primary scope entity.\n   * - `true`: identity field injected (e.g., `organizationId`), authorization scope-aware\n   * - `false`: parent FK injected (e.g., `projectId`), scope inherited from parent chain\n   */\n  isPrimaryScope: boolean;\n\n  /**\n   * Optional per-variant business-key declaration.\n   *\n   * The polymorphism engine cannot honour `.isBusinessKey()` on the base\n   * schema for fields that don't yet exist there (the canonical case being\n   * a polymorphic singleton whose business key is the *injected* parent FK\n   * — `organizationId` for the ORG variant, `applicationId` for the APP\n   * variant). This field gives the variant declaration a place to mark\n   * those fields per-variant.\n   *\n   * Resolution rule:\n   *\n   * 1. If `businessKeyFields` is provided (including an empty array `[]`\n   *    to *opt out*), apply `.isBusinessKey()` to each named field on the\n   *    final variant shape. Fail-loud if a name does not exist on the\n   *    variant shape.\n   * 2. Else if `isPrimaryScope: true` and `businessKeyFields` is omitted,\n   *    auto-mark the injected `parentFieldIdentifier` as the business key\n   *    (the singleton-per-scope convention).\n   * 3. Else (no explicit declaration AND not a primary scope), no\n   *    business-key marking is added — the framework's pre-A4 behaviour is\n   *    preserved for non-singleton polymorphism.\n   *\n   * DB UNIQUENESS: when the resolved business key is a SINGLE field (the\n   * singleton case — branch 2, or a one-field branch-1 list), that field is ALSO\n   * stamped `.isUnique()`, compiling to a Mongo unique index that enforces\n   * one-row-per-scope at the DB layer. `.isBusinessKey()` alone is a PURE marker\n   * with no index, so without this a raced insert (e.g. a system lazy-create on\n   * two concurrent logins) could duplicate the singleton row. A COMPOSITE\n   * (>1-field) business key stays marker-only — declare an object-level\n   * `.businessKeySet([...])` for a compound unique index instead. Consequence: a\n   * forgotten opt-out on a MULTI-ROW resource is now a hard duplicate-key insert\n   * failure (see `optOutPolymorphicAutoBusinessKey`), not just silent\n   * `upsertByBusinessKey` misrouting.\n   *\n   * Field names refer to the **post-injection, post-rename** shape — i.e.,\n   * what the field is actually called on the variant schema after\n   * polymorphic FK injection and any `polymorphicVariants`-driven renames\n   * (e.g., `billingAccountId` → `organizationBillingAccountId`). This is\n   * the shape the consumer of `variants[parentResourceType].schema` reads.\n   */\n  businessKeyFields?: string[];\n}\n/** @wildo_source:part:end saas.models.polymorphism.variant-definition */\n\n/**\n * @wildo_source:part:start saas.models.polymorphism.optout-business-key facet:layer:shared facet:family:polymorphism\n *\n * Opt out the auto-default that marks the injected `parentFieldIdentifier`\n * as the business key on every `isPrimaryScope: true` variant.\n *\n * Use this on **non-singleton** polymorphic resources (e.g., delivery logs,\n * SSO connections, SIEM DLQ rows, SCIM tokens, billing usage records, credit\n * pools, subscriptions, invoice refs) where the parent FK alone does NOT\n * uniquely identify a row in the collection. Without this opt-out, the\n * polymorphism engine auto-marks the injected scope FK (`organizationId` /\n * `applicationId` / etc.) as the business key. On a multi-row resource that is\n * now TWO bugs, not one:\n *   1. any `upsertByBusinessKey()` call routes every row in the scope onto a\n *      single document (silent data corruption); AND\n *   2. the single-field business key is ALSO stamped `.isUnique()` (the\n *      singleton ⇒ unique-index convention), so the SECOND row per scope is\n *      rejected at insert with a duplicate-key error — a hard, immediate\n *      failure. The resource is NOT a singleton, so both are wrong.\n * Opt out and both vanish: the scope FK stays a plain non-unique index with no\n * business-key marker.\n *\n * Contract:\n *\n * - Signature is **per-variant**: `(variantDef) => variantDef`. Apply it\n *   to a whole variant array via the standard `Array.prototype.map`:\n *   `[...AUTH_SCOPE_VARIANTS].map(optOutPolymorphicAutoBusinessKey)`.\n *   Direct per-variant calls are also fine — useful when only one\n *   variant in a heterogeneous array needs the opt-out.\n * - The result is a fresh `PolymorphicVariantDefinition` (or array\n *   thereof) with `businessKeyFields: []` per variant (the canonical\n *   \"explicit empty\" opt-out — the empty-array branch of the resolution rule\n *   documented on `PolymorphicVariantDefinition.businessKeyFields`).\n * - **The helper UNCONDITIONALLY overwrites any pre-existing\n *   `businessKeyFields` on the variant** — that is the entire point. If\n *   you need to preserve / extend an existing composite key, do NOT pipe\n *   through this helper; declare `businessKeyFields` inline on the\n *   variant instead.\n *\n * Why a helper instead of inline `.map(v => ({ ...v, businessKeyFields: [] }))`:\n *\n * - Keeps the call-site one-line and self-documenting (the helper name IS\n *   the rationale).\n * - Centralizes the `businessKeyFields: []` literal so a future rename or\n *   semantic change has one source of truth, not eight inlined copies.\n * - Discoverable via `rg optOutPolymorphicAutoBusinessKey`.\n */\nexport function optOutPolymorphicAutoBusinessKey(\n  variantDef: PolymorphicVariantDefinition,\n): PolymorphicVariantDefinition {\n  return { ...variantDef, businessKeyFields: [] };\n}\n/** @wildo_source:part:end saas.models.polymorphism.optout-business-key */\n\n/**\n * A single resolved variant within a polymorphic declaration.\n * Contains all derived naming + the transformed schema.\n */\nexport interface PolymorphicResolvedVariant<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {\n  /** The parent resource type this variant is parented to */\n  parentResourceType: ResourceType;\n  /** The parent's field identifier (e.g., 'organizationId') */\n  parentFieldIdentifier: string;\n  /** Whether this variant's parent is a primary scope entity */\n  isPrimaryScope: boolean;\n  /** Derived variant resource type (e.g., 'organizationBillingAccounts') */\n  resourceType: string;\n  /** Derived variant field identifier (e.g., 'organizationBillingAccountId') */\n  fieldIdentifier: string;\n  /** Derived collection name (same as resourceType) */\n  collectionName: string;\n  /** Derived kebab-case route segment */\n  routeSegment: string;\n  /** Derived CONSTANT_CASE enum key */\n  enumKey: string;\n  /** Transformed schema: base schema + parent FK field injected */\n  schema: TSchema;\n  /** If baseSchema was a SchemaFamily, this holds the rebuilt family for this variant */\n  schemaFamily?: SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>>;\n}\n\n/**\n * The output of `declarePolymorphicSchemas()`.\n * Contains the base declaration + pre-computed variants map.\n */\nexport interface PolymorphicSchemaDeclaration<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {\n  /** Marker for runtime type checking */\n  __polymorphic: true;\n  /** Base resource type (e.g., 'billingAccounts') — the abstract logical name */\n  baseResourceType: string;\n  /** Base field identifier (e.g., 'billingAccountId') */\n  baseFieldIdentifier: string;\n  /** Base CONSTANT_CASE enum key (e.g., 'BILLING_ACCOUNTS') */\n  baseEnumKey: string;\n  /** The original base schema (before variant transformation) */\n  baseSchema: TSchema;\n  /** The original variant definitions as provided by the developer */\n  variantDefinitions: PolymorphicVariantDefinition[];\n  /** Pre-computed map: parentResourceType → resolved variant (naming + transformed schema) */\n  variants: Map<ResourceType, PolymorphicResolvedVariant<TSchema>>;\n}\n\n/**\n * Input configuration for `declarePolymorphicSchemas()`.\n */\nexport interface DeclarePolymorphicSchemasConfig<TSchema extends z.ZodTypeAny> {\n  /** Base resource type (e.g., 'billingAccounts') */\n  baseResourceType: string;\n  /** Base field identifier (e.g., 'billingAccountId') */\n  baseFieldIdentifier: string;\n  /** Base CONSTANT_CASE enum key (e.g., 'BILLING_ACCOUNTS') */\n  baseEnumKey: string;\n  /**\n   * Base schema — either a plain z.ZodObject or a SchemaFamily result.\n   * Must NOT already contain identity fields (organizationId, userId, etc.) — they are injected per variant.\n   */\n  baseSchema: TSchema;\n  /** Variant definitions — one per parent resource */\n  variants: PolymorphicVariantDefinition[];\n}\n\n// =============================================================================\n// TYPE GUARDS\n// =============================================================================\n\n/**\n * Check if a value is a SchemaFamily (result of createSchemaFamily()).\n * Duck-types on the presence of `.union`, `.base`, `.discriminatorField`.\n */\nfunction isSchemaFamily(value: unknown): value is SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>> {\n  if (!value || typeof value !== 'object') return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    'union' in obj &&\n    'base' in obj &&\n    'discriminatorField' in obj &&\n    'variants' in obj &&\n    'inheritenceSchemaDefinition' in obj\n  );\n}\n\n/**\n * Check if a schema is a ZodObject (has .shape).\n */\nfunction isZodObject(schema: z.ZodTypeAny): schema is z.ZodObject<z.ZodRawShape> {\n  return schema instanceof z.ZodObject;\n}\n\n// =============================================================================\n// MAIN FUNCTION\n// =============================================================================\n\n/**\n * Declare polymorphic schemas for a base resource.\n *\n * For each variant definition, this function:\n * 1. Derives all naming identifiers using `ResourcePolymorphismUtils`\n * 2. Clones the base schema and injects the parent's field identifier as a new FK field\n * 3. If the base schema is a `SchemaFamily`, rebuilds the family per variant\n * 4. Returns a `PolymorphicSchemaDeclaration` with pre-computed variants\n *\n * @example\n * ```typescript\n * // Plain z.ZodObject base:\n * const billingDeclaration = declarePolymorphicSchemas({\n *   baseResourceType: 'billingAccounts',\n *   baseFieldIdentifier: 'billingAccountId',\n *   baseEnumKey: 'BILLING_ACCOUNTS',\n *   baseSchema: BillingAccountBaseSchema,\n *   variants: [\n *     { parentResourceType: 'organizations', parentFieldIdentifier: 'organizationId', isPrimaryScope: true },\n *     { parentResourceType: 'users',         parentFieldIdentifier: 'userId',         isPrimaryScope: true },\n *   ],\n * });\n *\n * // SchemaFamily base:\n * const subscriptionDeclaration = declarePolymorphicSchemas({\n *   baseResourceType: 'subscriptions',\n *   baseFieldIdentifier: 'subscriptionId',\n *   baseEnumKey: 'SUBSCRIPTIONS',\n *   baseSchema: SubscriptionSchemaFamily,  // result of createSchemaFamily()\n *   variants: [\n *     { parentResourceType: 'organizations', parentFieldIdentifier: 'organizationId', isPrimaryScope: true },\n *   ],\n * });\n * ```\n */\nexport function declarePolymorphicSchemas<TSchema extends z.ZodTypeAny>(\n  config: DeclarePolymorphicSchemasConfig<TSchema>\n): PolymorphicSchemaDeclaration<TSchema> {\n  const { baseResourceType, baseFieldIdentifier, baseEnumKey, baseSchema, variants: variantDefinitions } = config;\n\n  // Validation: must have at least one variant\n  if (variantDefinitions.length === 0) {\n    throw new Error(\n      `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\": must have at least one variant definition.`\n    );\n  }\n\n  // Validation: no duplicate parentResourceType\n  const parentTypes = variantDefinitions.map(v => v.parentResourceType);\n  const uniqueParentTypes = new Set(parentTypes);\n  if (uniqueParentTypes.size !== parentTypes.length) {\n    throw new Error(\n      `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\": duplicate parentResourceType in variant definitions.`\n    );\n  }\n\n  // Derive naming for all variants\n  const namingKit = ResourcePolymorphismUtils.getVariants(\n    baseResourceType,\n    baseFieldIdentifier,\n    baseEnumKey,\n    variantDefinitions.map(v => ({ parentResourceType: v.parentResourceType, parentFieldIdentifier: v.parentFieldIdentifier }))\n  );\n\n  // Determine the root ZodObject to validate and extend\n  const rootZodObject = isSchemaFamily(baseSchema)\n    ? (baseSchema as SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>>).base\n    : isZodObject(baseSchema as z.ZodTypeAny) ? (baseSchema as unknown as z.ZodObject<z.ZodRawShape>) : null;\n\n  // Validation: base schema must be a ZodObject or SchemaFamily\n  if (!rootZodObject) {\n    throw new Error(\n      `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\": baseSchema must be a z.object() or a SchemaFamily (result of createSchemaFamily()). Got: ${typeof baseSchema}`\n    );\n  }\n\n  // Validation: base schema should NOT already contain any of the parent FK fields\n  const baseShape = getZodObjectShape(rootZodObject);\n  for (const variantDef of variantDefinitions) {\n    if (baseShape[variantDef.parentFieldIdentifier]) {\n      throw new Error(\n        `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\": baseSchema already contains field \"${variantDef.parentFieldIdentifier}\". ` +\n        `The polymorphic declaration injects parent FK fields automatically — remove it from the base schema.`\n      );\n    }\n  }\n\n  // Pre-compute polymorphic FK renames from the base schema.\n  // For each field in the base shape, check if it has `polymorphicVariants` metadata.\n  // If so, build a map: fieldName → { parentResourceType → derivedFieldName }.\n  const polymorphicFkRenames = computePolymorphicFkRenames(baseShape, variantDefinitions);\n\n  // Build the variants map\n  const variantsMap = new Map<ResourceType, PolymorphicResolvedVariant<TSchema>>();\n\n  for (let i = 0; i < variantDefinitions.length; i++) {\n    const variantDef = variantDefinitions[i]!;\n    const naming = namingKit[i]!;\n\n    // Create the parent FK field: z.string().min(1).isForeignKey().isDBIndexed()\n    const parentFkField = z.string().min(1).isForeignKey().isDBIndexed();\n\n    // Compute FK renames for this specific variant\n    const fkRenamesForVariant = getFkRenamesForVariant(polymorphicFkRenames, variantDef.parentResourceType);\n\n    // Compute the business-key field names for this variant (A4 hybrid —\n    // explicit override wins; isPrimaryScope=true auto-defaults to the\n    // injected parent FK; otherwise no marking). See JSDoc on\n    // `PolymorphicVariantDefinition.businessKeyFields`.\n    const businessKeyFieldNames = computeBusinessKeyFieldNames(variantDef);\n\n    // Extend the schema with the parent FK field\n    let variantSchema: z.ZodTypeAny;\n    let variantSchemaFamily: SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>> | undefined;\n\n    if (isSchemaFamily(baseSchema)) {\n      const family = baseSchema as SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>>;\n\n      // Extend the family's base schema with parent FK + apply FK renames\n      // Cast needed: Zod 4's .extend() returns ZodObject<Readonly<...>> which is stricter than ZodRawShape\n      let extendedBase = family.base.extend({\n        [variantDef.parentFieldIdentifier]: parentFkField,\n      }) as z.ZodObject<z.ZodRawShape>;\n      extendedBase = applyFkRenames(extendedBase, fkRenamesForVariant);\n      extendedBase = applyBusinessKeyMarkers(\n        extendedBase,\n        businessKeyFieldNames,\n        baseResourceType,\n        variantDef.parentResourceType,\n      );\n\n      // Rebuild each variant schema with the parent FK injected + FK renames\n      const extendedVariants: Record<string, z.ZodObject<z.ZodRawShape>> = {};\n      for (const [key, variantSchemaEntry] of Object.entries(family.variants)) {\n        let extended = (variantSchemaEntry as z.ZodObject<z.ZodRawShape>).extend({\n          [variantDef.parentFieldIdentifier]: parentFkField,\n        }) as z.ZodObject<z.ZodRawShape>;\n        extended = applyFkRenames(extended, fkRenamesForVariant);\n        extended = applyBusinessKeyMarkers(\n          extended,\n          businessKeyFieldNames,\n          baseResourceType,\n          variantDef.parentResourceType,\n        );\n        extendedVariants[key] = extended;\n      }\n\n      // Rebuild the discriminated union with parent FK in all branches\n      // Use addDiscriminator() to preserve isDiscriminator metadata (matching createSchemaFamily behavior)\n      const allUnionSchemas: z.ZodObject<z.ZodRawShape>[] = [];\n\n      // Base value schemas (base + parent FK + decorated discriminator)\n      for (const baseValue of family.baseValues) {\n        const baseWithDiscriminator = extendedBase.extend({\n          [family.discriminatorField]: addDiscriminator(z.literal(baseValue), { baseValues: family.baseValues }),\n        });\n        allUnionSchemas.push(baseWithDiscriminator as z.ZodObject<z.ZodRawShape>);\n      }\n\n      // Extended variant schemas — re-decorate discriminator to ensure metadata is preserved\n      for (const [variantKey, extendedVariantSchema] of Object.entries(extendedVariants)) {\n        allUnionSchemas.push(\n          extendedVariantSchema.extend({\n            [family.discriminatorField]: addDiscriminator(z.literal(variantKey), { baseValues: family.baseValues }),\n          }) as z.ZodObject<z.ZodRawShape>\n        );\n      }\n\n      // Create the union\n      let union: z.ZodTypeAny;\n      if (allUnionSchemas.length >= 2) {\n        union = z.discriminatedUnion(\n          family.discriminatorField,\n          allUnionSchemas as any\n        );\n      } else if (allUnionSchemas.length === 1) {\n        union = allUnionSchemas[0]!;\n      } else {\n        union = extendedBase;\n      }\n\n      // Build the rebuilt SchemaFamily for this variant\n      variantSchemaFamily = {\n        base: extendedBase as z.ZodObject<z.ZodRawShape>,\n        discriminatorField: family.discriminatorField,\n        baseValues: family.baseValues,\n        variants: extendedVariants as any,\n        union,\n        inheritenceSchemaDefinition: family.inheritenceSchemaDefinition,\n      };\n\n      // The main schema for the resource config is the union\n      variantSchema = union;\n    } else {\n      // Plain ZodObject — simple extend + FK renames + business-key markers\n      let extended = (rootZodObject as z.ZodObject<z.ZodRawShape>).extend({\n        [variantDef.parentFieldIdentifier]: parentFkField,\n      }) as z.ZodObject<z.ZodRawShape>;\n      extended = applyFkRenames(extended, fkRenamesForVariant);\n      extended = applyBusinessKeyMarkers(\n        extended,\n        businessKeyFieldNames,\n        baseResourceType,\n        variantDef.parentResourceType,\n      );\n      variantSchema = extended;\n    }\n\n    variantsMap.set(variantDef.parentResourceType, {\n      parentResourceType: variantDef.parentResourceType,\n      parentFieldIdentifier: variantDef.parentFieldIdentifier,\n      isPrimaryScope: variantDef.isPrimaryScope,\n      resourceType: naming.resourceType,\n      fieldIdentifier: naming.fieldIdentifier,\n      collectionName: naming.collectionName,\n      routeSegment: naming.routeSegment,\n      enumKey: naming.enumKey,\n      schema: variantSchema as TSchema,\n      ...(variantSchemaFamily ? { schemaFamily: variantSchemaFamily } : {}),\n    });\n  }\n\n  return {\n    __polymorphic: true,\n    baseResourceType,\n    baseFieldIdentifier,\n    baseEnumKey,\n    baseSchema,\n    variantDefinitions,\n    variants: variantsMap,\n  };\n}\n\n// =============================================================================\n// FK RENAME HELPERS\n// =============================================================================\n\n/** Map of original field name → per-parentResourceType derived field name */\ntype PolymorphicFkRenameMap = Map<string, Map<string, string>>;\n\n/**\n * Scan the base schema shape for fields with `polymorphicVariants` metadata.\n * Build a rename map: originalFieldName → { parentResourceType → derivedFieldName }.\n */\nfunction computePolymorphicFkRenames(\n  baseShape: Record<string, z.ZodTypeAny>,\n  variantDefinitions: PolymorphicVariantDefinition[],\n): PolymorphicFkRenameMap {\n  const renames: PolymorphicFkRenameMap = new Map();\n\n  for (const [fieldName, fieldSchema] of Object.entries(baseShape)) {\n    const fkVariants = getPolymorphicFkVariants(fieldSchema);\n    if (!fkVariants || fkVariants.length === 0) continue;\n\n    const fieldRenames = new Map<string, string>();\n\n    for (const variantDef of variantDefinitions) {\n      const matchingFkVariant = fkVariants.find(\n        fkv => fkv.parentResourceType === variantDef.parentResourceType\n      );\n      if (matchingFkVariant) {\n        const derivedName = ResourcePolymorphismUtils.deriveVariantFieldIdentifier(\n          matchingFkVariant.parentFieldIdentifier,\n          fieldName,\n        );\n        fieldRenames.set(variantDef.parentResourceType, derivedName);\n      }\n    }\n\n    if (fieldRenames.size > 0) {\n      renames.set(fieldName, fieldRenames);\n    }\n  }\n\n  return renames;\n}\n\n/**\n * Get the FK renames applicable for a specific parent resource type.\n * Returns an array of [originalFieldName, derivedFieldName] pairs.\n */\nfunction getFkRenamesForVariant(\n  renameMap: PolymorphicFkRenameMap,\n  parentResourceType: string,\n): [string, string][] {\n  const result: [string, string][] = [];\n  for (const [originalName, perParent] of renameMap) {\n    const derived = perParent.get(parentResourceType);\n    if (derived) {\n      result.push([originalName, derived]);\n    }\n  }\n  return result;\n}\n\n/**\n * Compute the per-variant renamed schema map for a polymorphic base.\n *\n * Exported as the canonical bridge that callers OUTSIDE this module\n * (notably the frontend lib's `createPolymorphicFrontendPreset`, which\n * threads a `FRONTEND_SCHEMA_KEY` per variant for `z_clone`-style UI\n * mutations) use to derive per-variant schemas without having to reach\n * into the private rename helpers.\n *\n * Given a base schema and an array of variant declarations, returns\n * `Map<parentResourceType, ZodObject>` where each value is the base\n * schema with `polymorphicVariants`-marked FK fields renamed to their\n * variant-specific names (e.g. `billingAccountId` →\n * `organizationBillingAccountId` for the ORGANIZATIONS variant).\n *\n * Why this matters: the polymorphic resource factory ALREADY applies\n * these renames to the runtime variant schemas (see `applyFkRenames`\n * call sites above). But callers that take the BASE schema as input\n * and attach it to per-variant artifacts (e.g. the frontend's UI\n * behavior `FRONTEND_SCHEMA_KEY`) bypass the rename and end up\n * replacing the variant's renamed `mainSchema` with the base's\n * un-renamed shape — breaking the registry's FK→parent map. Use this\n * helper to keep that path aligned with the resource factory's\n * rename semantics.\n *\n * `variants` only needs `parentResourceType`; any extra properties on\n * the input objects are ignored. This lets frontend callers pass\n * `PolymorphicFrontendVariant`-shaped values directly without\n * reaching for the backend's full `PolymorphicVariantDefinition`.\n */\nexport function computePolymorphicVariantSchemas(\n  baseSchema: z.ZodObject<z.ZodRawShape>,\n  variants: ReadonlyArray<{ parentResourceType: string }>,\n): Map<string, z.ZodObject<z.ZodRawShape>> {\n  const baseShape = getZodObjectShape(baseSchema) as Record<string, z.ZodTypeAny>;\n  // Synthesize minimal variantDefinitions for the renames computer — only\n  // `parentResourceType` is read.\n  const minimalDefs = variants.map(({ parentResourceType }) => ({\n    parentResourceType,\n  })) as unknown as PolymorphicVariantDefinition[];\n  const renameMap = computePolymorphicFkRenames(baseShape, minimalDefs);\n\n  const result = new Map<string, z.ZodObject<z.ZodRawShape>>();\n  for (const { parentResourceType } of variants) {\n    const renames = getFkRenamesForVariant(renameMap, parentResourceType);\n    result.set(parentResourceType, applyFkRenames(baseSchema, renames));\n  }\n  return result;\n}\n\n/**\n * Apply FK renames to a ZodObject: remove original field, add derived field with same schema.\n */\nfunction applyFkRenames(\n  schema: z.ZodObject<z.ZodRawShape>,\n  renames: [string, string][],\n): z.ZodObject<z.ZodRawShape> {\n  if (renames.length === 0) return schema;\n\n  // Cast to mutable shape — getZodObjectShape may return Readonly in Zod 4\n  const shape = getZodObjectShape(schema) as Record<string, z.ZodTypeAny>;\n  const newShape: Record<string, z.ZodTypeAny> = {};\n\n  for (const [key, value] of Object.entries(shape)) {\n    const rename = renames.find(([orig]) => orig === key);\n    if (rename) {\n      newShape[rename[1]] = value;\n    } else {\n      newShape[key] = value;\n    }\n  }\n\n  return z.object(newShape) as z.ZodObject<z.ZodRawShape>;\n}\n\n// =============================================================================\n// BUSINESS-KEY MARKER HELPERS (A4 hybrid — Decision A of\n// `.cursor/plans/polymorphic-singleton-business-key-support.md`)\n// =============================================================================\n\n/**\n * Resolve the per-variant business-key field names to mark with\n * `.isBusinessKey()` on the post-injection / post-rename variant shape.\n *\n * Resolution rule (A4 hybrid):\n *\n * 1. Explicit `businessKeyFields` (including `[]` to opt out) → use as-is.\n * 2. `isPrimaryScope: true` AND `businessKeyFields` omitted → auto-default\n *    to `[parentFieldIdentifier]` (the canonical singleton-per-scope case).\n * 3. Otherwise → empty array (preserves pre-A4 behaviour for\n *    non-singleton polymorphism — no business-key marking applied).\n *\n * Pure function — no schema mutation, no metadata access. Always returns a\n * fresh array (never the caller's `businessKeyFields` reference) so a later\n * mutation by the consumer cannot accidentally rewrite the variant\n * declaration.\n */\nfunction computeBusinessKeyFieldNames(variantDef: PolymorphicVariantDefinition): string[] {\n  if (variantDef.businessKeyFields !== undefined) {\n    return [...variantDef.businessKeyFields];\n  }\n  if (variantDef.isPrimaryScope) {\n    return [variantDef.parentFieldIdentifier];\n  }\n  return [];\n}\n\n/**\n * Minimal prototype-based field clone, designed exclusively for the\n * `addDecorators(clone, [IS_BUSINESS_KEY])` flow inside\n * `applyBusinessKeyMarkers`. NOT a general-purpose schema clone — see\n * `z_clone` (in `@wildo-ai/zod-decorators`) for the full-featured version\n * that deep-clones metadata, reruns `addChainableMethods`, and is the\n * right choice when you need an INDEPENDENT leaf-schema reusable across\n * resources.\n *\n * **Why a separate helper rather than `z_clone`:**\n *\n * - `z_clone` deep-clones metadata and reruns `addChainableMethods`. For\n *   the polymorphism engine — which clones a base-shape field once per\n *   variant per call to `declarePolymorphicSchemas` — that's more work\n *   than necessary, and reruns of `addChainableMethods` on schemas that\n *   already have chainable methods are a net no-op (defends via\n *   `__metadataWrapped` / `hasOwnProperty` checks).\n * - This helper keeps the contract MINIMAL and INTENTIONAL: only the\n *   `SCHEMA_METADATA` Symbol property is given an own-property override\n *   (a shallow copy of the source's metadata bag); everything else\n *   (Zod 4's `_zod` internals, the prototype chain, instance methods, any\n *   future Symbol-keyed framework state) is inherited by setting the\n *   source schema as the clone's prototype. The result is structurally\n *   indistinguishable from the source for Zod's own validation\n *   (`isSchema(clone)` is `true` because `_zod` resolves via prototype\n *   lookup), so the clone is safe to re-enter `z.object({...})` as a\n *   field — but every metadata mutation lands on the clone alone.\n *\n * **Why a shallow copy of the metadata bag is sufficient HERE:**\n *\n * `applySingleDecorator` mutates only the top-level entries on the bag\n * (`bag[ZodDecorator.IS_BUSINESS_KEY] = true`, etc.). Nested decorator\n * payloads (e.g., `bag[FOREIGN_KEY_SPEC]`) are read-then-deep-merged into\n * a NEW object before being assigned back, so the existing nested\n * references are never mutated in place. For our single-decorator\n * `addDecorators(clone, [IS_BUSINESS_KEY])` call, a shallow copy of the\n * top-level bag is therefore enough to fully isolate the source.\n *\n * **Symbol-keyed properties OTHER than `SCHEMA_METADATA`** (Plan 1 deep-\n * review L-3, 2026-04-14): only `SCHEMA_METADATA` is shallow-copied as\n * an own property. If `addDecorators` ever evolves to mutate a different\n * Symbol-keyed property on the schema instance, this helper MUST be\n * updated to also override that property — otherwise the first mutation\n * on the clone would create an own property on the clone (correct) but\n * later reads on the source would observe stale state (the source's\n * Symbol value never changes). To future-proof, either (a) iterate\n * `Object.getOwnPropertySymbols(value)` and shallow-copy them all, or\n * (b) add a `addDecorators`-side invariant test that asserts\n * `SCHEMA_METADATA` is the only Symbol-keyed mutation surface.\n *\n * **Why this matters at all** — context: when\n * `declarePolymorphicSchemas` builds variants, `ZodObject.extend(...)`\n * creates a fresh wrapper but the base shape's inner field instances are\n * SHARED across every variant iteration. Mutating those shared leaves\n * directly via `addDecorators` would silently propagate the marker onto\n * sibling variants — even ones that explicitly omit the field or opt out\n * via `optOutPolymorphicAutoBusinessKey`. The clone breaks the share.\n */\nfunction cloneFieldForBusinessKeyDecoration(value: z.ZodTypeAny): z.ZodTypeAny {\n  const clone = Object.create(value);\n  const sourceMetadata = (value as unknown as Record<symbol, unknown>)[SCHEMA_METADATA];\n  (clone as unknown as Record<symbol, unknown>)[SCHEMA_METADATA] =\n    sourceMetadata && typeof sourceMetadata === 'object' ? { ...(sourceMetadata as Record<string, unknown>) } : {};\n  return clone as z.ZodTypeAny;\n}\n\n/**\n * Apply `.isBusinessKey()` to each named field on a ZodObject and return a\n * new ZodObject with the same shape but the named fields re-decorated.\n *\n * Fail-loud: if a name does not exist on the schema's shape, throw with the\n * full `baseResourceType` + `parentResourceType` context. This catches\n * authoring mistakes (e.g., typo'd field name, or a `businessKeyFields`\n * list that references a field that exists on the base but was renamed by\n * `polymorphicVariants` — the post-rename name is the canonical one).\n *\n * Always returns a fresh `z.object(...)` wrapper — even on the no-op path\n * (`fieldNames.length === 0`) — so callers never observe an aliased input\n * reference (low-risk consistency, see Plan 1 review L-2).\n *\n * Cross-variant leak defence: every field that needs a marker is piped\n * through `cloneFieldForBusinessKeyDecoration(...)` first — see that\n * helper's JSDoc for the full rationale. Without it, an explicit\n * `businessKeyFields` referencing a base-shape field on Variant 1 would\n * silently bleed onto every subsequent variant.\n *\n * **Outer-level metadata contract (Plan 1 deep-review M-2, 2026-04-14)**:\n * because we always return a fresh `z.object(newShape)`, any **outer-level**\n * metadata on the input `schema` (i.e., decorators applied to the OBJECT\n * itself rather than its fields — e.g., a future `addDecorators(zObject,\n * [...])` call setting `bag[ZodDecorator.X]` on the ZodObject) would be\n * silently dropped. Every current call site (lines 333 / 347 / 408) feeds\n * us a fresh `applyFkRenames(...)` output which itself is `z.object(...)`\n * with no outer-level metadata, so this is invisible today. The defensive\n * check below FAILS LOUDLY if a future caller violates this assumption,\n * forcing the change to either (a) propagate the outer metadata explicitly\n * or (b) document why it's safe to drop.\n *\n * @param schema The post-injection, post-rename variant ZodObject.\n * @param fieldNames Field names (post-rename) to mark with `.isBusinessKey()`.\n * @param baseResourceType For error context (the polymorphic base name).\n * @param parentResourceType For error context (the variant's parent type).\n *\n * @throws If the input schema carries outer-level metadata that would be\n * silently lost by the fresh-wrapper rebuild — see contract note above.\n */\nfunction applyBusinessKeyMarkers(\n  schema: z.ZodObject<z.ZodRawShape>,\n  fieldNames: string[],\n  baseResourceType: string,\n  parentResourceType: ResourceType,\n): z.ZodObject<z.ZodRawShape> {\n  // Outer-level metadata guard — see JSDoc \"Outer-level metadata contract\".\n  // We deliberately do NOT propagate outer metadata onto the new wrapper\n  // because no current call site needs it; instead we fail loud so the next\n  // caller that DOES need it has to make a deliberate design decision.\n  const outerMetadata = getFieldMetadata(schema);\n  if (outerMetadata && Object.keys(outerMetadata).length > 0) {\n    throw new Error(\n      `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\" parentResourceType=\"${parentResourceType}\": ` +\n      `applyBusinessKeyMarkers received a ZodObject with outer-level metadata ` +\n      `(keys: [${Object.keys(outerMetadata).join(', ')}]). The function rebuilds ` +\n      `the wrapper via z.object(...), which would silently drop those entries. ` +\n      `Either remove the outer metadata before calling, or extend this helper ` +\n      `to propagate it (and add a regression test). See JSDoc \"Outer-level ` +\n      `metadata contract\" for the full rationale.`,\n    );\n  }\n\n  const shape = getZodObjectShape(schema) as Record<string, z.ZodTypeAny>;\n\n  if (fieldNames.length === 0) {\n    return z.object({ ...shape }) as z.ZodObject<z.ZodRawShape>;\n  }\n\n  for (const fieldName of fieldNames) {\n    if (!Object.prototype.hasOwnProperty.call(shape, fieldName)) {\n      throw new Error(\n        `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\" parentResourceType=\"${parentResourceType}\": ` +\n        `businessKeyFields references field \"${fieldName}\" but the post-injection variant shape has no such field. ` +\n        `Available fields: [${Object.keys(shape).join(', ')}]. ` +\n        `Note: businessKeyFields names refer to the POST-rename shape — if a field was renamed via polymorphicVariants ` +\n        `(e.g., billingAccountId → organizationBillingAccountId), use the renamed name.`,\n      );\n    }\n  }\n\n  // A SINGLETON business key (exactly one field — the injected scope FK, e.g.\n  // `organizationId` / `applicationId`; the only polymorphic business-key case\n  // that exists today) is enforced DB-UNIQUE, not merely marked. `.isBusinessKey()`\n  // is a PURE marker with no index (unlike `.isPrimaryKey()`), so without an\n  // explicit `.isUnique()` the one-per-scope invariant is unenforced at the DB\n  // layer: a raced `createAsSystem` / plain insert can write two rows for the same\n  // scope, silently breaking the singleton AND the `upsertByBusinessKey` contract,\n  // which ASSUMES the business key uniquely identifies a row. A single-field\n  // `.isUnique()` on the scope FK compiles to a Mongo unique index (via the\n  // zod→mongoose convertor's `isUnique` path) so a second concurrent insert fails\n  // closed with a duplicate-key error instead of duplicating. Mirrors the\n  // non-polymorphic singleton pattern (`organizationId: z.string().min(1)\n  // .isDBIndexed().isUnique().isForeignKey()` on `organizationPreferences` /\n  // `organizationNotifications`).\n  //\n  // A COMPOSITE business key (>1 field — none exist today) is deliberately left\n  // marker-only here: applying per-field `.isUnique()` would wrongly require each\n  // field to be INDEPENDENTLY unique rather than the tuple. Composite DB uniqueness\n  // is the object-level `.businessKeySet([...])` decorator's job (the convertor\n  // materialises it as a compound unique index via `applyBusinessKeyCompoundUniqueIndex`).\n  const businessKeyDecorators = fieldNames.length === 1\n    ? [ZodDecorator.IS_BUSINESS_KEY, ZodDecorator.IS_UNIQUE]\n    : [ZodDecorator.IS_BUSINESS_KEY];\n\n  const newShape: Record<string, z.ZodTypeAny> = {};\n  for (const [key, value] of Object.entries(shape)) {\n    newShape[key] = fieldNames.includes(key)\n      ? addDecorators(cloneFieldForBusinessKeyDecoration(value), businessKeyDecorators)\n      : value;\n  }\n\n  return z.object(newShape) as z.ZodObject<z.ZodRawShape>;\n}\n"]}
+{"version":3,"file":"resource-polymorphism.schemas.js","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-polymorphism.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resource Polymorphism — Schema Declaration (Phase 1)\n *\n * Provides `declarePolymorphicSchemas()` which takes a base schema and a list\n * of parent variant definitions, and produces a `PolymorphicSchemaDeclaration`\n * containing pre-computed schemas for each variant (base + injected parent FK).\n *\n * Supports both plain `z.ZodObject` and `SchemaFamily` as base schema input.\n *\n * @see polymorphic-scope-approach-A-expansion.md — Phase 1\n */\n\nimport { z } from 'zod';\nimport { getZodObjectShape, addDiscriminator, getPolymorphicFkVariants, addDecorators, ZodDecorator, SCHEMA_METADATA, getFieldMetadata } from '@wildo-ai/zod-decorators';\nimport { ResourcePolymorphismUtils, type PolymorphicParentVariantDefinition, type PolymorphicVariantNaming } from './resource-polymorphism.utils';\nimport type { SchemaFamily, EnumLikeType, VariantConfig } from './schema-family-builder.utils';\nimport type { ResourceConfiguration_InheritanceSchemaDefinition } from '../resources-config.shared.schemas';\nimport type { ResourceType } from '../resources.shared.core.definitions';\n\n// =============================================================================\n// TYPES\n// =============================================================================\n\n/**\n * @wildo_source:part:start saas.models.polymorphism.variant-definition facet:layer:shared facet:family:polymorphism\n *\n * One entry in the variant list passed to `declarePolymorphicSchemas()` (from\n * `@wildo-ai/saas-models`) — describes ONE scope a polymorphic resource is\n * stamped out for. Besides the two fields below it also carries the inherited\n * `parentResourceType` (the scope entity — e.g. ORGANIZATIONS / APPLICATION /\n * USERS) and `parentFieldIdentifier` (the scope FK the engine injects into the\n * variant schema — e.g. `organizationId` / `applicationId`). The\n * `isPrimaryScope` + `businessKeyFields` pair is the SINGLETON-vs-MULTI-ROW\n * decision: a singleton scope FK becomes a one-per-scope unique business key; a\n * multi-row (collection) resource must opt out via `optOutPolymorphicAutoBusinessKey`.\n */\nexport interface PolymorphicVariantDefinition extends PolymorphicParentVariantDefinition {\n  /**\n   * Whether this variant's parent is a primary scope entity.\n   * - `true`: identity field injected (e.g., `organizationId`), authorization scope-aware\n   * - `false`: parent FK injected (e.g., `projectId`), scope inherited from parent chain\n   */\n  isPrimaryScope: boolean;\n\n  /**\n   * Optional per-variant business-key declaration.\n   *\n   * The polymorphism engine cannot honour `.isBusinessKey()` on the base\n   * schema for fields that don't yet exist there (the canonical case being\n   * a polymorphic singleton whose business key is the *injected* parent FK\n   * — `organizationId` for the ORG variant, `applicationId` for the APP\n   * variant). This field gives the variant declaration a place to mark\n   * those fields per-variant.\n   *\n   * Resolution rule:\n   *\n   * 1. If `businessKeyFields` is provided (including an empty array `[]`\n   *    to *opt out*), apply `.isBusinessKey()` to each named field on the\n   *    final variant shape. Fail-loud if a name does not exist on the\n   *    variant shape.\n   * 2. Else if `isPrimaryScope: true` and `businessKeyFields` is omitted,\n   *    auto-mark the injected `parentFieldIdentifier` as the business key\n   *    (the singleton-per-scope convention).\n   * 3. Else (no explicit declaration AND not a primary scope), no\n   *    business-key marking is added — the framework's pre-A4 behaviour is\n   *    preserved for non-singleton polymorphism.\n   *\n   * DB UNIQUENESS: when the resolved business key is a SINGLE field (the\n   * singleton case — branch 2, or a one-field branch-1 list), that field is ALSO\n   * stamped `.isUnique()`, compiling to a Mongo unique index that enforces\n   * one-row-per-scope at the DB layer. `.isBusinessKey()` alone is a PURE marker\n   * with no index, so without this a raced insert (e.g. a system lazy-create on\n   * two concurrent logins) could duplicate the singleton row. A COMPOSITE\n   * (>1-field) business key stays marker-only — declare an object-level\n   * `.businessKeySet([...])` for a compound unique index instead. Consequence: a\n   * forgotten opt-out on a MULTI-ROW resource is now a hard duplicate-key insert\n   * failure (see `optOutPolymorphicAutoBusinessKey`), not just silent\n   * `upsertByBusinessKey` misrouting.\n   *\n   * Field names refer to the **post-injection, post-rename** shape — i.e.,\n   * what the field is actually called on the variant schema after\n   * polymorphic FK injection and any `polymorphicVariants`-driven renames\n   * (e.g., `billingAccountId` → `organizationBillingAccountId`). This is\n   * the shape the consumer of `variants[parentResourceType].schema` reads.\n   */\n  businessKeyFields?: string[];\n}\n/** @wildo_source:part:end saas.models.polymorphism.variant-definition */\n\n/**\n * @wildo_source:part:start saas.models.polymorphism.optout-business-key facet:layer:shared facet:family:polymorphism\n *\n * Opt out the auto-default that marks the injected `parentFieldIdentifier`\n * as the business key on every `isPrimaryScope: true` variant.\n *\n * Use this on **non-singleton** polymorphic resources (e.g., delivery logs,\n * SSO connections, SIEM DLQ rows, SCIM tokens, billing usage records, credit\n * pools, subscriptions, invoice refs) where the parent FK alone does NOT\n * uniquely identify a row in the collection. Without this opt-out, the\n * polymorphism engine auto-marks the injected scope FK (`organizationId` /\n * `applicationId` / etc.) as the business key. On a multi-row resource that is\n * now TWO bugs, not one:\n *   1. any `upsertByBusinessKey()` call routes every row in the scope onto a\n *      single document (silent data corruption); AND\n *   2. the single-field business key is ALSO stamped `.isUnique()` (the\n *      singleton ⇒ unique-index convention), so the SECOND row per scope is\n *      rejected at insert with a duplicate-key error — a hard, immediate\n *      failure. The resource is NOT a singleton, so both are wrong.\n * Opt out and both vanish: the scope FK stays a plain non-unique index with no\n * business-key marker.\n *\n * Contract:\n *\n * - Signature is **per-variant**: `(variantDef) => variantDef`. Apply it\n *   to a whole variant array via the standard `Array.prototype.map`:\n *   `[...AUTH_SCOPE_VARIANTS].map(optOutPolymorphicAutoBusinessKey)`.\n *   Direct per-variant calls are also fine — useful when only one\n *   variant in a heterogeneous array needs the opt-out.\n * - The result is a fresh `PolymorphicVariantDefinition` (or array\n *   thereof) with `businessKeyFields: []` per variant (the canonical\n *   \"explicit empty\" opt-out — the empty-array branch of the resolution rule\n *   documented on `PolymorphicVariantDefinition.businessKeyFields`).\n * - **The helper UNCONDITIONALLY overwrites any pre-existing\n *   `businessKeyFields` on the variant** — that is the entire point. If\n *   you need to preserve / extend an existing composite key, do NOT pipe\n *   through this helper; declare `businessKeyFields` inline on the\n *   variant instead.\n *\n * Why a helper instead of inline `.map(v => ({ ...v, businessKeyFields: [] }))`:\n *\n * - Keeps the call-site one-line and self-documenting (the helper name IS\n *   the rationale).\n * - Centralizes the `businessKeyFields: []` literal so a future rename or\n *   semantic change has one source of truth, not eight inlined copies.\n * - Discoverable via `rg optOutPolymorphicAutoBusinessKey`.\n */\nexport function optOutPolymorphicAutoBusinessKey(\n  variantDef: PolymorphicVariantDefinition,\n): PolymorphicVariantDefinition {\n  return { ...variantDef, businessKeyFields: [] };\n}\n/** @wildo_source:part:end saas.models.polymorphism.optout-business-key */\n\n/**\n * A single resolved variant within a polymorphic declaration.\n * Contains all derived naming + the transformed schema.\n */\nexport interface PolymorphicResolvedVariant<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {\n  /** The parent resource type this variant is parented to */\n  parentResourceType: ResourceType;\n  /** The parent's field identifier (e.g., 'organizationId') */\n  parentFieldIdentifier: string;\n  /** Whether this variant's parent is a primary scope entity */\n  isPrimaryScope: boolean;\n  /** Derived variant resource type (e.g., 'organizationBillingAccounts') */\n  resourceType: string;\n  /** Derived variant field identifier (e.g., 'organizationBillingAccountId') */\n  fieldIdentifier: string;\n  /** Derived collection name (same as resourceType) */\n  collectionName: string;\n  /** Derived kebab-case route segment */\n  routeSegment: string;\n  /** Derived CONSTANT_CASE enum key */\n  enumKey: string;\n  /** Transformed schema: base schema + parent FK field injected */\n  schema: TSchema;\n  /** If baseSchema was a SchemaFamily, this holds the rebuilt family for this variant */\n  schemaFamily?: SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>>;\n}\n\n/**\n * The output of `declarePolymorphicSchemas()`.\n * Contains the base declaration + pre-computed variants map.\n */\nexport interface PolymorphicSchemaDeclaration<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {\n  /** Marker for runtime type checking */\n  __polymorphic: true;\n  /** Base resource type (e.g., 'billingAccounts') — the abstract logical name */\n  baseResourceType: string;\n  /** Base field identifier (e.g., 'billingAccountId') */\n  baseFieldIdentifier: string;\n  /** Base CONSTANT_CASE enum key (e.g., 'BILLING_ACCOUNTS') */\n  baseEnumKey: string;\n  /** The original base schema (before variant transformation) */\n  baseSchema: TSchema;\n  /** The original variant definitions as provided by the developer */\n  variantDefinitions: PolymorphicVariantDefinition[];\n  /** Pre-computed map: parentResourceType → resolved variant (naming + transformed schema) */\n  variants: Map<ResourceType, PolymorphicResolvedVariant<TSchema>>;\n}\n\n/**\n * Input configuration for `declarePolymorphicSchemas()`.\n */\nexport interface DeclarePolymorphicSchemasConfig<TSchema extends z.ZodTypeAny> {\n  /** Base resource type (e.g., 'billingAccounts') */\n  baseResourceType: string;\n  /** Base field identifier (e.g., 'billingAccountId') */\n  baseFieldIdentifier: string;\n  /** Base CONSTANT_CASE enum key (e.g., 'BILLING_ACCOUNTS') */\n  baseEnumKey: string;\n  /**\n   * Base schema — either a plain z.ZodObject or a SchemaFamily result.\n   * Must NOT already contain identity fields (organizationId, userId, etc.) — they are injected per variant.\n   */\n  baseSchema: TSchema;\n  /** Variant definitions — one per parent resource */\n  variants: PolymorphicVariantDefinition[];\n}\n\n// =============================================================================\n// TYPE GUARDS\n// =============================================================================\n\n/**\n * Check if a value is a SchemaFamily (result of createSchemaFamily()).\n * Duck-types on the presence of `.union`, `.base`, `.discriminatorField`.\n */\nfunction isSchemaFamily(value: unknown): value is SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>> {\n  if (!value || typeof value !== 'object') return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    'union' in obj &&\n    'base' in obj &&\n    'discriminatorField' in obj &&\n    'variants' in obj &&\n    'inheritenceSchemaDefinition' in obj\n  );\n}\n\n/**\n * Check if a schema is a ZodObject (has .shape).\n */\nfunction isZodObject(schema: z.ZodTypeAny): schema is z.ZodObject<z.ZodRawShape> {\n  return schema instanceof z.ZodObject;\n}\n\n// =============================================================================\n// MAIN FUNCTION\n// =============================================================================\n\n/**\n * Declare polymorphic schemas for a base resource.\n *\n * For each variant definition, this function:\n * 1. Derives all naming identifiers using `ResourcePolymorphismUtils`\n * 2. Clones the base schema and injects the parent's field identifier as a new FK field\n * 3. If the base schema is a `SchemaFamily`, rebuilds the family per variant\n * 4. Returns a `PolymorphicSchemaDeclaration` with pre-computed variants\n *\n * @example\n * ```typescript\n * // Plain z.ZodObject base:\n * const billingDeclaration = declarePolymorphicSchemas({\n *   baseResourceType: 'billingAccounts',\n *   baseFieldIdentifier: 'billingAccountId',\n *   baseEnumKey: 'BILLING_ACCOUNTS',\n *   baseSchema: BillingAccountBaseSchema,\n *   variants: [\n *     { parentResourceType: 'organizations', parentFieldIdentifier: 'organizationId', isPrimaryScope: true },\n *     { parentResourceType: 'users',         parentFieldIdentifier: 'userId',         isPrimaryScope: true },\n *   ],\n * });\n *\n * // SchemaFamily base:\n * const subscriptionDeclaration = declarePolymorphicSchemas({\n *   baseResourceType: 'subscriptions',\n *   baseFieldIdentifier: 'subscriptionId',\n *   baseEnumKey: 'SUBSCRIPTIONS',\n *   baseSchema: SubscriptionSchemaFamily,  // result of createSchemaFamily()\n *   variants: [\n *     { parentResourceType: 'organizations', parentFieldIdentifier: 'organizationId', isPrimaryScope: true },\n *   ],\n * });\n * ```\n */\nexport function declarePolymorphicSchemas<TSchema extends z.ZodTypeAny>(\n  config: DeclarePolymorphicSchemasConfig<TSchema>\n): PolymorphicSchemaDeclaration<TSchema> {\n  const { baseResourceType, baseFieldIdentifier, baseEnumKey, baseSchema, variants: variantDefinitions } = config;\n\n  // Validation: must have at least one variant\n  if (variantDefinitions.length === 0) {\n    throw new Error(\n      `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\": must have at least one variant definition.`\n    );\n  }\n\n  // Validation: no duplicate parentResourceType\n  const parentTypes = variantDefinitions.map(v => v.parentResourceType);\n  const uniqueParentTypes = new Set(parentTypes);\n  if (uniqueParentTypes.size !== parentTypes.length) {\n    throw new Error(\n      `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\": duplicate parentResourceType in variant definitions.`\n    );\n  }\n\n  // Derive naming for all variants\n  const namingKit = ResourcePolymorphismUtils.getVariants(\n    baseResourceType,\n    baseFieldIdentifier,\n    baseEnumKey,\n    variantDefinitions.map(v => ({ parentResourceType: v.parentResourceType, parentFieldIdentifier: v.parentFieldIdentifier }))\n  );\n\n  // Determine the root ZodObject to validate and extend\n  const rootZodObject = isSchemaFamily(baseSchema)\n    ? (baseSchema as SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>>).base\n    : isZodObject(baseSchema as z.ZodTypeAny) ? (baseSchema as unknown as z.ZodObject<z.ZodRawShape>) : null;\n\n  // Validation: base schema must be a ZodObject or SchemaFamily\n  if (!rootZodObject) {\n    throw new Error(\n      `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\": baseSchema must be a z.object() or a SchemaFamily (result of createSchemaFamily()). Got: ${typeof baseSchema}`\n    );\n  }\n\n  // Validation: base schema should NOT already contain any of the parent FK fields\n  const baseShape = getZodObjectShape(rootZodObject);\n  for (const variantDef of variantDefinitions) {\n    if (baseShape[variantDef.parentFieldIdentifier]) {\n      throw new Error(\n        `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\": baseSchema already contains field \"${variantDef.parentFieldIdentifier}\". ` +\n        `The polymorphic declaration injects parent FK fields automatically — remove it from the base schema.`\n      );\n    }\n  }\n\n  // Pre-compute polymorphic FK renames from the base schema.\n  // For each field in the base shape, check if it has `polymorphicVariants` metadata.\n  // If so, build a map: fieldName → { parentResourceType → derivedFieldName }.\n  const polymorphicFkRenames = computePolymorphicFkRenames(baseShape, variantDefinitions);\n\n  // Build the variants map\n  const variantsMap = new Map<ResourceType, PolymorphicResolvedVariant<TSchema>>();\n\n  for (let i = 0; i < variantDefinitions.length; i++) {\n    const variantDef = variantDefinitions[i]!;\n    const naming = namingKit[i]!;\n\n    // Create the parent FK field: z.string().min(1).isForeignKey().isDBIndexed()\n    const parentFkField = z.string().min(1).isForeignKey().isDBIndexed();\n\n    // Compute FK renames for this specific variant\n    const fkRenamesForVariant = getFkRenamesForVariant(polymorphicFkRenames, variantDef.parentResourceType);\n\n    // Compute the business-key field names for this variant (A4 hybrid —\n    // explicit override wins; isPrimaryScope=true auto-defaults to the\n    // injected parent FK; otherwise no marking). See JSDoc on\n    // `PolymorphicVariantDefinition.businessKeyFields`.\n    const businessKeyFieldNames = computeBusinessKeyFieldNames(variantDef);\n\n    // Extend the schema with the parent FK field\n    let variantSchema: z.ZodTypeAny;\n    let variantSchemaFamily: SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>> | undefined;\n\n    if (isSchemaFamily(baseSchema)) {\n      const family = baseSchema as SchemaFamily<z.ZodObject<z.ZodRawShape>, string, Record<string, VariantConfig<z.ZodObject<z.ZodRawShape>>>>;\n\n      // Extend the family's base schema with parent FK + apply FK renames\n      // Cast needed: Zod 4's .extend() returns ZodObject<Readonly<...>> which is stricter than ZodRawShape\n      let extendedBase = family.base.extend({\n        [variantDef.parentFieldIdentifier]: parentFkField,\n      }) as z.ZodObject<z.ZodRawShape>;\n      extendedBase = applyFkRenames(extendedBase, fkRenamesForVariant);\n      extendedBase = applyBusinessKeyMarkers(\n        extendedBase,\n        businessKeyFieldNames,\n        baseResourceType,\n        variantDef.parentResourceType,\n      );\n\n      // Rebuild each variant schema with the parent FK injected + FK renames\n      const extendedVariants: Record<string, z.ZodObject<z.ZodRawShape>> = {};\n      for (const [key, variantSchemaEntry] of Object.entries(family.variants)) {\n        let extended = (variantSchemaEntry as z.ZodObject<z.ZodRawShape>).extend({\n          [variantDef.parentFieldIdentifier]: parentFkField,\n        }) as z.ZodObject<z.ZodRawShape>;\n        extended = applyFkRenames(extended, fkRenamesForVariant);\n        extended = applyBusinessKeyMarkers(\n          extended,\n          businessKeyFieldNames,\n          baseResourceType,\n          variantDef.parentResourceType,\n        );\n        extendedVariants[key] = extended;\n      }\n\n      // Rebuild the discriminated union with parent FK in all branches\n      // Use addDiscriminator() to preserve isDiscriminator metadata (matching createSchemaFamily behavior)\n      const allUnionSchemas: z.ZodObject<z.ZodRawShape>[] = [];\n\n      // Base value schemas (base + parent FK + decorated discriminator)\n      for (const baseValue of family.baseValues) {\n        const baseWithDiscriminator = extendedBase.extend({\n          [family.discriminatorField]: addDiscriminator(z.literal(baseValue), { baseValues: family.baseValues }),\n        });\n        allUnionSchemas.push(baseWithDiscriminator as z.ZodObject<z.ZodRawShape>);\n      }\n\n      // Extended variant schemas — re-decorate discriminator to ensure metadata is preserved\n      for (const [variantKey, extendedVariantSchema] of Object.entries(extendedVariants)) {\n        allUnionSchemas.push(\n          extendedVariantSchema.extend({\n            [family.discriminatorField]: addDiscriminator(z.literal(variantKey), { baseValues: family.baseValues }),\n          }) as z.ZodObject<z.ZodRawShape>\n        );\n      }\n\n      // Create the union\n      let union: z.ZodTypeAny;\n      if (allUnionSchemas.length >= 2) {\n        union = z.discriminatedUnion(\n          family.discriminatorField,\n          allUnionSchemas as any\n        );\n      } else if (allUnionSchemas.length === 1) {\n        union = allUnionSchemas[0]!;\n      } else {\n        union = extendedBase;\n      }\n\n      // Build the rebuilt SchemaFamily for this variant\n      variantSchemaFamily = {\n        base: extendedBase as z.ZodObject<z.ZodRawShape>,\n        discriminatorField: family.discriminatorField,\n        baseValues: family.baseValues,\n        variants: extendedVariants as any,\n        union,\n        inheritenceSchemaDefinition: family.inheritenceSchemaDefinition,\n      };\n\n      // The main schema for the resource config is the union\n      variantSchema = union;\n    } else {\n      // Plain ZodObject — simple extend + FK renames + business-key markers\n      let extended = (rootZodObject as z.ZodObject<z.ZodRawShape>).extend({\n        [variantDef.parentFieldIdentifier]: parentFkField,\n      }) as z.ZodObject<z.ZodRawShape>;\n      extended = applyFkRenames(extended, fkRenamesForVariant);\n      extended = applyBusinessKeyMarkers(\n        extended,\n        businessKeyFieldNames,\n        baseResourceType,\n        variantDef.parentResourceType,\n      );\n      variantSchema = extended;\n    }\n\n    variantsMap.set(variantDef.parentResourceType, {\n      parentResourceType: variantDef.parentResourceType,\n      parentFieldIdentifier: variantDef.parentFieldIdentifier,\n      isPrimaryScope: variantDef.isPrimaryScope,\n      resourceType: naming.resourceType,\n      fieldIdentifier: naming.fieldIdentifier,\n      collectionName: naming.collectionName,\n      routeSegment: naming.routeSegment,\n      enumKey: naming.enumKey,\n      schema: variantSchema as TSchema,\n      ...(variantSchemaFamily ? { schemaFamily: variantSchemaFamily } : {}),\n    });\n  }\n\n  return {\n    __polymorphic: true,\n    baseResourceType,\n    baseFieldIdentifier,\n    baseEnumKey,\n    baseSchema,\n    variantDefinitions,\n    variants: variantsMap,\n  };\n}\n\n// =============================================================================\n// FK RENAME HELPERS\n// =============================================================================\n\n/** Map of original field name → per-parentResourceType derived field name */\ntype PolymorphicFkRenameMap = Map<string, Map<string, string>>;\n\n/**\n * Scan the base schema shape for fields with `polymorphicVariants` metadata.\n * Build a rename map: originalFieldName → { parentResourceType → derivedFieldName }.\n */\nfunction computePolymorphicFkRenames(\n  baseShape: Record<string, z.ZodTypeAny>,\n  variantDefinitions: PolymorphicVariantDefinition[],\n): PolymorphicFkRenameMap {\n  const renames: PolymorphicFkRenameMap = new Map();\n\n  for (const [fieldName, fieldSchema] of Object.entries(baseShape)) {\n    const fkVariants = getPolymorphicFkVariants(fieldSchema);\n    if (!fkVariants || fkVariants.length === 0) continue;\n\n    const fieldRenames = new Map<string, string>();\n\n    for (const variantDef of variantDefinitions) {\n      const matchingFkVariant = fkVariants.find(\n        fkv => fkv.parentResourceType === variantDef.parentResourceType\n      );\n      if (matchingFkVariant) {\n        const derivedName = ResourcePolymorphismUtils.deriveVariantFieldIdentifier(\n          matchingFkVariant.parentFieldIdentifier,\n          fieldName,\n        );\n        fieldRenames.set(variantDef.parentResourceType, derivedName);\n      }\n    }\n\n    if (fieldRenames.size > 0) {\n      renames.set(fieldName, fieldRenames);\n    }\n  }\n\n  return renames;\n}\n\n/**\n * Get the FK renames applicable for a specific parent resource type.\n * Returns an array of [originalFieldName, derivedFieldName] pairs.\n */\nfunction getFkRenamesForVariant(\n  renameMap: PolymorphicFkRenameMap,\n  parentResourceType: string,\n): [string, string][] {\n  const result: [string, string][] = [];\n  for (const [originalName, perParent] of renameMap) {\n    const derived = perParent.get(parentResourceType);\n    if (derived) {\n      result.push([originalName, derived]);\n    }\n  }\n  return result;\n}\n\n/**\n * Compute the per-variant renamed schema map for a polymorphic base.\n *\n * Exported as the canonical bridge that callers OUTSIDE this module\n * (notably the frontend lib's `createPolymorphicFrontendPreset`, which\n * threads a `FRONTEND_SCHEMA_KEY` per variant for `z_clone`-style UI\n * mutations) use to derive per-variant schemas without having to reach\n * into the private rename helpers.\n *\n * Given a base schema and an array of variant declarations, returns\n * `Map<parentResourceType, ZodObject>` where each value is the base\n * schema with `polymorphicVariants`-marked FK fields renamed to their\n * variant-specific names (e.g. `billingAccountId` →\n * `organizationBillingAccountId` for the ORGANIZATIONS variant).\n *\n * Why this matters: the polymorphic resource factory ALREADY applies\n * these renames to the runtime variant schemas (see `applyFkRenames`\n * call sites above). But callers that take the BASE schema as input\n * and attach it to per-variant artifacts (e.g. the frontend's UI\n * behavior `FRONTEND_SCHEMA_KEY`) bypass the rename and end up\n * replacing the variant's renamed `mainSchema` with the base's\n * un-renamed shape — breaking the registry's FK→parent map. Use this\n * helper to keep that path aligned with the resource factory's\n * rename semantics.\n *\n * `variants` only needs `parentResourceType`; any extra properties on\n * the input objects are ignored. This lets frontend callers pass\n * `PolymorphicFrontendVariant`-shaped values directly without\n * reaching for the backend's full `PolymorphicVariantDefinition`.\n */\nexport function computePolymorphicVariantSchemas(\n  baseSchema: z.ZodObject<z.ZodRawShape>,\n  variants: ReadonlyArray<{ parentResourceType: string }>,\n): Map<string, z.ZodObject<z.ZodRawShape>> {\n  const baseShape = getZodObjectShape(baseSchema) as Record<string, z.ZodTypeAny>;\n  // Synthesize minimal variantDefinitions for the renames computer — only\n  // `parentResourceType` is read.\n  const minimalDefs = variants.map(({ parentResourceType }) => ({\n    parentResourceType,\n  })) as unknown as PolymorphicVariantDefinition[];\n  const renameMap = computePolymorphicFkRenames(baseShape, minimalDefs);\n\n  const result = new Map<string, z.ZodObject<z.ZodRawShape>>();\n  for (const { parentResourceType } of variants) {\n    const renames = getFkRenamesForVariant(renameMap, parentResourceType);\n    result.set(parentResourceType, applyFkRenames(baseSchema, renames));\n  }\n  return result;\n}\n\n/**\n * Apply FK renames to a ZodObject: remove original field, add derived field with same schema.\n */\nfunction applyFkRenames(\n  schema: z.ZodObject<z.ZodRawShape>,\n  renames: [string, string][],\n): z.ZodObject<z.ZodRawShape> {\n  if (renames.length === 0) return schema;\n\n  // Cast to mutable shape — getZodObjectShape may return Readonly in Zod 4\n  const shape = getZodObjectShape(schema) as Record<string, z.ZodTypeAny>;\n  const newShape: Record<string, z.ZodTypeAny> = {};\n\n  for (const [key, value] of Object.entries(shape)) {\n    const rename = renames.find(([orig]) => orig === key);\n    if (rename) {\n      newShape[rename[1]] = value;\n    } else {\n      newShape[key] = value;\n    }\n  }\n\n  return z.object(newShape) as z.ZodObject<z.ZodRawShape>;\n}\n\n// =============================================================================\n// BUSINESS-KEY MARKER HELPERS (A4 hybrid — Decision A of\n// `.cursor/plans/polymorphic-singleton-business-key-support.md`)\n// =============================================================================\n\n/**\n * Resolve the per-variant business-key field names to mark with\n * `.isBusinessKey()` on the post-injection / post-rename variant shape.\n *\n * Resolution rule (A4 hybrid):\n *\n * 1. Explicit `businessKeyFields` (including `[]` to opt out) → use as-is.\n * 2. `isPrimaryScope: true` AND `businessKeyFields` omitted → auto-default\n *    to `[parentFieldIdentifier]` (the canonical singleton-per-scope case).\n * 3. Otherwise → empty array (preserves pre-A4 behaviour for\n *    non-singleton polymorphism — no business-key marking applied).\n *\n * Pure function — no schema mutation, no metadata access. Always returns a\n * fresh array (never the caller's `businessKeyFields` reference) so a later\n * mutation by the consumer cannot accidentally rewrite the variant\n * declaration.\n */\nfunction computeBusinessKeyFieldNames(variantDef: PolymorphicVariantDefinition): string[] {\n  if (variantDef.businessKeyFields !== undefined) {\n    return [...variantDef.businessKeyFields];\n  }\n  if (variantDef.isPrimaryScope) {\n    return [variantDef.parentFieldIdentifier];\n  }\n  return [];\n}\n\n/**\n * Minimal prototype-based field clone, designed exclusively for the\n * `addDecorators(clone, [IS_BUSINESS_KEY])` flow inside\n * `applyBusinessKeyMarkers`. NOT a general-purpose schema clone — see\n * `z_clone` (in `@wildo-ai/zod-decorators`) for the full-featured version\n * that deep-clones metadata, reruns `addChainableMethods`, and is the\n * right choice when you need an INDEPENDENT leaf-schema reusable across\n * resources.\n *\n * **Why a separate helper rather than `z_clone`:**\n *\n * - `z_clone` deep-clones metadata and reruns `addChainableMethods`. For\n *   the polymorphism engine — which clones a base-shape field once per\n *   variant per call to `declarePolymorphicSchemas` — that's more work\n *   than necessary, and reruns of `addChainableMethods` on schemas that\n *   already have chainable methods are a net no-op (defends via\n *   `__metadataWrapped` / `hasOwnProperty` checks).\n * - This helper keeps the contract MINIMAL and INTENTIONAL: only the\n *   `SCHEMA_METADATA` Symbol property is given an own-property override\n *   (a shallow copy of the source's metadata bag); everything else\n *   (Zod 4's `_zod` internals, the prototype chain, instance methods, any\n *   future Symbol-keyed framework state) is inherited by setting the\n *   source schema as the clone's prototype. The result is structurally\n *   indistinguishable from the source for Zod's own validation\n *   (`isSchema(clone)` is `true` because `_zod` resolves via prototype\n *   lookup), so the clone is safe to re-enter `z.object({...})` as a\n *   field — but every metadata mutation lands on the clone alone.\n *\n * **Why a shallow copy of the metadata bag is sufficient HERE:**\n *\n * `applySingleDecorator` mutates only the top-level entries on the bag\n * (`bag[ZodDecorator.IS_BUSINESS_KEY] = true`, etc.). Nested decorator\n * payloads (e.g., `bag[FOREIGN_KEY_SPEC]`) are read-then-deep-merged into\n * a NEW object before being assigned back, so the existing nested\n * references are never mutated in place. For our single-decorator\n * `addDecorators(clone, [IS_BUSINESS_KEY])` call, a shallow copy of the\n * top-level bag is therefore enough to fully isolate the source.\n *\n * **Symbol-keyed properties OTHER than `SCHEMA_METADATA`** (Plan 1 deep-\n * review L-3, 2026-04-14): only `SCHEMA_METADATA` is shallow-copied as\n * an own property. If `addDecorators` ever evolves to mutate a different\n * Symbol-keyed property on the schema instance, this helper MUST be\n * updated to also override that property — otherwise the first mutation\n * on the clone would create an own property on the clone (correct) but\n * later reads on the source would observe stale state (the source's\n * Symbol value never changes). To future-proof, either (a) iterate\n * `Object.getOwnPropertySymbols(value)` and shallow-copy them all, or\n * (b) add a `addDecorators`-side invariant test that asserts\n * `SCHEMA_METADATA` is the only Symbol-keyed mutation surface.\n *\n * **Why this matters at all** — context: when\n * `declarePolymorphicSchemas` builds variants, `ZodObject.extend(...)`\n * creates a fresh wrapper but the base shape's inner field instances are\n * SHARED across every variant iteration. Mutating those shared leaves\n * directly via `addDecorators` would silently propagate the marker onto\n * sibling variants — even ones that explicitly omit the field or opt out\n * via `optOutPolymorphicAutoBusinessKey`. The clone breaks the share.\n */\nfunction cloneFieldForBusinessKeyDecoration(value: z.ZodTypeAny): z.ZodTypeAny {\n  const clone = Object.create(value);\n  const sourceMetadata = (value as unknown as Record<symbol, unknown>)[SCHEMA_METADATA];\n  (clone as unknown as Record<symbol, unknown>)[SCHEMA_METADATA] =\n    sourceMetadata && typeof sourceMetadata === 'object' ? { ...(sourceMetadata as Record<string, unknown>) } : {};\n  return clone as z.ZodTypeAny;\n}\n\n/**\n * Apply `.isBusinessKey()` to each named field on a ZodObject and return a\n * new ZodObject with the same shape but the named fields re-decorated.\n *\n * Fail-loud: if a name does not exist on the schema's shape, throw with the\n * full `baseResourceType` + `parentResourceType` context. This catches\n * authoring mistakes (e.g., typo'd field name, or a `businessKeyFields`\n * list that references a field that exists on the base but was renamed by\n * `polymorphicVariants` — the post-rename name is the canonical one).\n *\n * Always returns a fresh `z.object(...)` wrapper — even on the no-op path\n * (`fieldNames.length === 0`) — so callers never observe an aliased input\n * reference (low-risk consistency, see Plan 1 review L-2).\n *\n * Cross-variant leak defence: every field that needs a marker is piped\n * through `cloneFieldForBusinessKeyDecoration(...)` first — see that\n * helper's JSDoc for the full rationale. Without it, an explicit\n * `businessKeyFields` referencing a base-shape field on Variant 1 would\n * silently bleed onto every subsequent variant.\n *\n * **Outer-level metadata contract (Plan 1 deep-review M-2, 2026-04-14)**:\n * because we always return a fresh `z.object(newShape)`, any **outer-level**\n * metadata on the input `schema` (i.e., decorators applied to the OBJECT\n * itself rather than its fields — e.g., a future `addDecorators(zObject,\n * [...])` call setting `bag[ZodDecorator.X]` on the ZodObject) would be\n * silently dropped. Every current call site (lines 333 / 347 / 408) feeds\n * us a fresh `applyFkRenames(...)` output which itself is `z.object(...)`\n * with no outer-level metadata, so this is invisible today. The defensive\n * check below FAILS LOUDLY if a future caller violates this assumption,\n * forcing the change to either (a) propagate the outer metadata explicitly\n * or (b) document why it's safe to drop.\n *\n * **The one outer decorator that IS propagated: `.businessKeySet([...])`**\n * (#1596). A many-rows-per-scope polymorphic resource whose identity is a\n * COMPOSITE of base fields — the inbound-delivery ledger's\n * `(sourceKey, dedupKey)` — declares it on the base object, and each variant\n * is its own table, so each variant must carry the compound unique index.\n * Dropping it would leave the dedup ledger with no index at all, which is the\n * exact silent loss this guard exists to stop; refusing it would leave a\n * polymorphic resource no way to declare a composite identity. So the set is\n * re-applied to the fresh wrapper, after checking every named field still\n * exists on the post-injection, post-rename shape (a renamed field would\n * otherwise produce an index over a column that does not exist). Every OTHER\n * outer key still fails loud, for the reason above.\n *\n * @param schema The post-injection, post-rename variant ZodObject.\n * @param fieldNames Field names (post-rename) to mark with `.isBusinessKey()`.\n * @param baseResourceType For error context (the polymorphic base name).\n * @param parentResourceType For error context (the variant's parent type).\n *\n * @throws If the input schema carries outer-level metadata that would be\n * silently lost by the fresh-wrapper rebuild — see contract note above.\n */\nfunction applyBusinessKeyMarkers(\n  schema: z.ZodObject<z.ZodRawShape>,\n  fieldNames: string[],\n  baseResourceType: string,\n  parentResourceType: ResourceType,\n): z.ZodObject<z.ZodRawShape> {\n  // Outer-level metadata guard — see JSDoc \"Outer-level metadata contract\".\n  // We deliberately do NOT propagate outer metadata onto the new wrapper\n  // because no current call site needs it; instead we fail loud so the next\n  // caller that DOES need it has to make a deliberate design decision.\n  const outerMetadata = getFieldMetadata(schema);\n  const propagatedBusinessKeySet = outerMetadata?.[ZodDecorator.OBJECT_BUSINESS_KEY_SET] as\n    | { fields: string[]; skipRowsMissing?: string[]; conflictMessageReference?: string }\n    | undefined;\n  const unpropagatedOuterKeys = Object.keys(outerMetadata ?? {}).filter((key) => key !== ZodDecorator.OBJECT_BUSINESS_KEY_SET);\n  if (unpropagatedOuterKeys.length > 0) {\n    throw new Error(\n      `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\" parentResourceType=\"${parentResourceType}\": ` +\n      `applyBusinessKeyMarkers received a ZodObject with outer-level metadata ` +\n      `(keys: [${unpropagatedOuterKeys.join(', ')}]). The function rebuilds ` +\n      `the wrapper via z.object(...), which would silently drop those entries. ` +\n      `Either remove the outer metadata before calling, or extend this helper ` +\n      `to propagate it (and add a regression test). See JSDoc \"Outer-level ` +\n      `metadata contract\" for the full rationale.`,\n    );\n  }\n\n  const shape = getZodObjectShape(schema) as Record<string, z.ZodTypeAny>;\n\n  if (propagatedBusinessKeySet) {\n    const missingKeyFields = propagatedBusinessKeySet.fields.filter((field) => !Object.prototype.hasOwnProperty.call(shape, field));\n    if (missingKeyFields.length > 0) {\n      throw new Error(\n        `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\" parentResourceType=\"${parentResourceType}\": ` +\n        `the base object's businessKeySet names field(s) absent from the post-injection variant shape: ` +\n        `[${missingKeyFields.join(', ')}]. A renamed field cannot carry a compound unique index under its old name.`,\n      );\n    }\n  }\n  const withPropagatedBusinessKeySet = (rebuilt: z.ZodObject<z.ZodRawShape>): z.ZodObject<z.ZodRawShape> =>\n    propagatedBusinessKeySet\n      ? addDecorators(rebuilt, [{ ref: ZodDecorator.OBJECT_BUSINESS_KEY_SET, params: { ...propagatedBusinessKeySet } }]) as unknown as z.ZodObject<z.ZodRawShape>\n      : rebuilt;\n\n  if (fieldNames.length === 0) {\n    return withPropagatedBusinessKeySet(z.object({ ...shape }) as z.ZodObject<z.ZodRawShape>);\n  }\n\n  for (const fieldName of fieldNames) {\n    if (!Object.prototype.hasOwnProperty.call(shape, fieldName)) {\n      throw new Error(\n        `[PolymorphicSchemas] baseResourceType=\"${baseResourceType}\" parentResourceType=\"${parentResourceType}\": ` +\n        `businessKeyFields references field \"${fieldName}\" but the post-injection variant shape has no such field. ` +\n        `Available fields: [${Object.keys(shape).join(', ')}]. ` +\n        `Note: businessKeyFields names refer to the POST-rename shape — if a field was renamed via polymorphicVariants ` +\n        `(e.g., billingAccountId → organizationBillingAccountId), use the renamed name.`,\n      );\n    }\n  }\n\n  // A SINGLETON business key (exactly one field — the injected scope FK, e.g.\n  // `organizationId` / `applicationId`; the only polymorphic business-key case\n  // that exists today) is enforced DB-UNIQUE, not merely marked. `.isBusinessKey()`\n  // is a PURE marker with no index (unlike `.isPrimaryKey()`), so without an\n  // explicit `.isUnique()` the one-per-scope invariant is unenforced at the DB\n  // layer: a raced `createAsSystem` / plain insert can write two rows for the same\n  // scope, silently breaking the singleton AND the `upsertByBusinessKey` contract,\n  // which ASSUMES the business key uniquely identifies a row. A single-field\n  // `.isUnique()` on the scope FK compiles to a Mongo unique index (via the\n  // zod→mongoose convertor's `isUnique` path) so a second concurrent insert fails\n  // closed with a duplicate-key error instead of duplicating. Mirrors the\n  // non-polymorphic singleton pattern (`organizationId: z.string().min(1)\n  // .isDBIndexed().isUnique().isForeignKey()` on `organizationPreferences` /\n  // `organizationNotifications`).\n  //\n  // A COMPOSITE business key (>1 field — none exist today) is deliberately left\n  // marker-only here: applying per-field `.isUnique()` would wrongly require each\n  // field to be INDEPENDENTLY unique rather than the tuple. Composite DB uniqueness\n  // is the object-level `.businessKeySet([...])` decorator's job (the convertor\n  // materialises it as a compound unique index via `applyBusinessKeyCompoundUniqueIndex`).\n  const businessKeyDecorators = fieldNames.length === 1\n    ? [ZodDecorator.IS_BUSINESS_KEY, ZodDecorator.IS_UNIQUE]\n    : [ZodDecorator.IS_BUSINESS_KEY];\n\n  const newShape: Record<string, z.ZodTypeAny> = {};\n  for (const [key, value] of Object.entries(shape)) {\n    newShape[key] = fieldNames.includes(key)\n      ? addDecorators(cloneFieldForBusinessKeyDecoration(value), businessKeyDecorators)\n      : value;\n  }\n\n  return withPropagatedBusinessKeySet(z.object(newShape) as z.ZodObject<z.ZodRawShape>);\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"resource-polymorphism.utils.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resource-polymorphism.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAMzE;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,sEAAsE;IACtE,kBAAkB,EAAE,YAAY,CAAC;IACjC,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,kBAAkB,EAAE,YAAY,CAAC;IACjC,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,qBAAa,yBAAyB;IAEpC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,gBAAgB,CAAC,qBAAqB,EAAE,MAAM,GAAG,MAAM;IAI9D;;;;;;;;OAQG;IACH,MAAM,CAAC,yBAAyB,CAAC,qBAAqB,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,MAAM;IAMjG;;;;;;;OAOG;IACH,MAAM,CAAC,4BAA4B,CAAC,qBAAqB,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,MAAM;IAMvG;;;;;;OAMG;IACH,MAAM,CAAC,oBAAoB,CAAC,qBAAqB,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAMvF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,WAAW,CAChB,gBAAgB,EAAE,MAAM,EACxB,mBAAmB,EAAE,MAAM,EAC3B,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,kCAAkC,EAAE,GACnD,wBAAwB,EAAE;CAgB9B"}
+{"version":3,"file":"resource-polymorphism.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-polymorphism.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAMzE;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,sEAAsE;IACtE,kBAAkB,EAAE,YAAY,CAAC;IACjC,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,kBAAkB,EAAE,YAAY,CAAC;IACjC,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,qBAAa,yBAAyB;IAEpC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,gBAAgB,CAAC,qBAAqB,EAAE,MAAM,GAAG,MAAM;IAI9D;;;;;;;;OAQG;IACH,MAAM,CAAC,yBAAyB,CAAC,qBAAqB,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,MAAM;IAMjG;;;;;;;OAOG;IACH,MAAM,CAAC,4BAA4B,CAAC,qBAAqB,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,MAAM;IAMvG;;;;;;OAMG;IACH,MAAM,CAAC,oBAAoB,CAAC,qBAAqB,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAMvF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,WAAW,CAChB,gBAAgB,EAAE,MAAM,EACxB,mBAAmB,EAAE,MAAM,EAC3B,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,kCAAkC,EAAE,GACnD,wBAAwB,EAAE;CAgB9B"}

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

@@ -1 +1 @@
-{"version":3,"file":"resource-subtree.utils.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resource-subtree.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAExE,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAqDlD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,oBAAoB,EAAE,GAAG,UAAU,CAWnF"}
+{"version":3,"file":"resource-subtree.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-subtree.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAExE,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAqDlD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,oBAAoB,EAAE,GAAG,UAAU,CAWnF"}

package/dist/esm/resources/utils/resources-config-context-needs.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources-config-context-needs.utils.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resources-config-context-needs.utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,0CAA0C,EAAE,8CAA8C,EAAE,MAAM,oCAAoC,CAAC;AAErJ;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACnF,EAAE,EAAE,8CAA8C,CAAC,SAAS,CAAC,GAAG,SAAS,GAAG,SAAS,GACpF,0CAA0C,CAa5C;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAClF,EAAE,EAAE,8CAA8C,CAAC,SAAS,CAAC,GAAG,SAAS,GAAG,SAAS,GACpF,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAChF,EAAE,EAAE,8CAA8C,CAAC,SAAS,CAAC,GAAG,SAAS,GAAG,SAAS,GACpF,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,SAAS;IAC9D,gBAAgB,CAAC,EAAE,8CAA8C,CAAC,GAAG,CAAC,CAAC;IACvE,oBAAoB,CAAC,EAAE,8CAA8C,CAAC,GAAG,CAAC,CAAC;CAC5E,EAAE,SAAS,EAAE,UAAU,GAAG,0CAA0C,CAQpE"}
+{"version":3,"file":"resources-config-context-needs.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resources-config-context-needs.utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,0CAA0C,EAAE,8CAA8C,EAAE,MAAM,oCAAoC,CAAC;AAErJ;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACnF,EAAE,EAAE,8CAA8C,CAAC,SAAS,CAAC,GAAG,SAAS,GAAG,SAAS,GACpF,0CAA0C,CAa5C;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAClF,EAAE,EAAE,8CAA8C,CAAC,SAAS,CAAC,GAAG,SAAS,GAAG,SAAS,GACpF,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAChF,EAAE,EAAE,8CAA8C,CAAC,SAAS,CAAC,GAAG,SAAS,GAAG,SAAS,GACpF,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,SAAS;IAC9D,gBAAgB,CAAC,EAAE,8CAA8C,CAAC,GAAG,CAAC,CAAC;IACvE,oBAAoB,CAAC,EAAE,8CAA8C,CAAC,GAAG,CAAC,CAAC;CAC5E,EAAE,SAAS,EAAE,UAAU,GAAG,0CAA0C,CAQpE"}

package/dist/esm/resources/utils/resources-config-naming.utils.d.ts

@@ -9,6 +9,21 @@ export declare class ResourcesConfigNamingUtils {
      * This is a reliable implementation covering most common cases
      */
     static singularize(word: string): string;
+    /**
+     * The singular nouns whose plural changes `f` / `fe` to `ves`. Deliberately SMALL and closed:
+     * everything else ending in `f` or `fe` takes a plain `s`, which is the common case in the
+     * identifiers this framework derives (`…Ref`, `…Proof`). Shared by `pluralize` and `singularize`
+     * so the two directions cannot disagree about which words are exceptions.
+     */
+    private static readonly F_TO_VES_WORDS;
+    private static readonly FE_TO_VES_WORDS;
+    /**
+     * The last English word of a lower-cased identifier. Word boundaries are lost by lower-casing, so
+     * this matches a trailing exception word against the whole-string suffix instead: `bookshelf`
+     * yields `shelf`, `organizationinvoiceref` yields itself (no exception word is its suffix), and a
+     * `snake_case` or `kebab-case` tail is split on its separator.
+     */
+    private static lastWordOf;
     /**
      * Preserve the case pattern of the original word in the result
      */

package/dist/esm/resources/utils/resources-config-naming.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources-config-naming.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resources-config-naming.utils.ts"],"names":[],"mappings":"AAAA,qBAAa,0BAA0B;IAMnC;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IA2DtC;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IA0DxC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAiB3B;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;IAqB9D;;;;;;OAMG;IACH,MAAM,CAAC,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAW9D;;;;;OAKG;IACH,MAAM,CAAC,sBAAsB,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;IAKtE;;;;;OAKG;IACH,MAAM,CAAC,uBAAuB,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;IAiBvE;;;;;OAKG;IACH,MAAM,CAAC,yBAAyB,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;IAiBzE;;OAEG;IACH,MAAM,CAAC,uBAAuB,CAAC,uBAAuB,EAAE,MAAM,GAAG,OAAO;IAIxE;;OAEG;IACH,MAAM,CAAC,yBAAyB,CAAC,uBAAuB,EAAE,MAAM,GAAG,OAAO;IAQ1E;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAQvC;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAMvC;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAKxC;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAQvC;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAI1C;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAI5C;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAQ5C;;;OAGG;IACH,MAAM,CAAC,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAa3D;;;OAGG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAiBhD;;OAEG;IACH,MAAM,CAAC,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG;QAClD,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;KACzB;IAYD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,eAAe,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;CAalE"}
+{"version":3,"file":"resources-config-naming.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resources-config-naming.utils.ts"],"names":[],"mappings":"AAAA,qBAAa,0BAA0B;IAMnC;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAgEtC;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAwExC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAEnC;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAA2D;IAElG;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;IAUzB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAiB3B;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;IAqB9D;;;;;;OAMG;IACH,MAAM,CAAC,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAW9D;;;;;OAKG;IACH,MAAM,CAAC,sBAAsB,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;IAKtE;;;;;OAKG;IACH,MAAM,CAAC,uBAAuB,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;IAiBvE;;;;;OAKG;IACH,MAAM,CAAC,yBAAyB,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;IAiBzE;;OAEG;IACH,MAAM,CAAC,uBAAuB,CAAC,uBAAuB,EAAE,MAAM,GAAG,OAAO;IAIxE;;OAEG;IACH,MAAM,CAAC,yBAAyB,CAAC,uBAAuB,EAAE,MAAM,GAAG,OAAO;IAQ1E;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAQvC;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAMvC;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAKxC;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAQvC;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAI1C;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAI5C;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAQ5C;;;OAGG;IACH,MAAM,CAAC,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAa3D;;;OAGG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAiBhD;;OAEG;IACH,MAAM,CAAC,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG;QAClD,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;KACzB;IAYD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,eAAe,CAAC,uBAAuB,EAAE,MAAM,GAAG,MAAM;CAalE"}

package/dist/esm/resources/utils/resources-config-naming.utils.js

@@ -35,19 +35,24 @@ export class ResourcesConfigNamingUtils {
         if (irregularPlurals[lowerWord]) {
             return this.preserveCase(word, irregularPlurals[lowerWord]);
         }
-        // Words ending in 's', 'ss', 'sh', 'ch', 'x', 'z' add 'es'
-        if (/[sxz]$/.test(lowerWord) || /[sh]$/.test(lowerWord) || /ch$/.test(lowerWord)) {
+        // Words ending in 's', 'ss', 'sh', 'ch', 'x', 'z' add 'es'. `sh`, not `[sh]`: a bare 'h'
+        // takes a plain 's' (`path` → `paths`, `month` → `months`).
+        if (/[sxz]$/.test(lowerWord) || /sh$/.test(lowerWord) || /ch$/.test(lowerWord)) {
             return word + 'es';
         }
         // Words ending in consonant + 'y' change 'y' to 'ies'
         if (/[bcdfghjklmnpqrstvwxz]y$/.test(lowerWord)) {
             return word.slice(0, -1) + 'ies';
         }
-        // Words ending in 'f' or 'fe' change to 'ves'
-        if (/f$/.test(lowerWord)) {
+        // `f → ves` is the English EXCEPTION, not the rule: `ref`, `proof`, `chef`, `roof`, `belief`
+        // and `safe` take a plain 's'. A blanket `/f$/` put `organizationInvoiceReves` and
+        // `workbenchMarketProoves` on the wire (#580). Only the closed list below changes form, and it
+        // is matched on the LAST camelCase word so a compound (`bookShelf`) behaves like its head noun.
+        const lastWord = ResourcesConfigNamingUtils.lastWordOf(lowerWord);
+        if (ResourcesConfigNamingUtils.F_TO_VES_WORDS.has(lastWord)) {
             return word.slice(0, -1) + 'ves';
         }
-        if (/fe$/.test(lowerWord)) {
+        if (ResourcesConfigNamingUtils.FE_TO_VES_WORDS.has(lastWord)) {
             return word.slice(0, -2) + 'ves';
         }
         // Words ending in consonant + 'o' add 'es'
@@ -86,17 +91,30 @@ export class ResourcesConfigNamingUtils {
         if (/ies$/.test(lowerWord)) {
             return word.slice(0, -3) + 'y';
         }
-        // Words ending in 'ves' change to 'f' or 'fe'
+        // 'ves' → 'f' / 'fe' ONLY for the closed exception list `pluralize` uses; every other 'ves'
+        // word just drops its 's' (`workbenchMarketAlternatives` → `…Alternative`, not `…Alternatif`).
         if (/ves$/.test(lowerWord)) {
-            // Common words that end in 'fe' when singular
-            const fWords = ['wives', 'knives', 'lives'];
-            if (fWords.includes(lowerWord)) {
+            const lastWord = ResourcesConfigNamingUtils.lastWordOf(lowerWord).slice(0, -3);
+            if (ResourcesConfigNamingUtils.FE_TO_VES_WORDS.has(lastWord + 'fe')) {
                 return word.slice(0, -3) + 'fe';
             }
-            return word.slice(0, -3) + 'f';
+            if (ResourcesConfigNamingUtils.F_TO_VES_WORDS.has(lastWord + 'f')) {
+                return word.slice(0, -3) + 'f';
+            }
+            return word.slice(0, -1);
+        }
+        // '-ses' is ambiguous in English, and the naive "remove 'es'" turned `workbenchRoadmapPhases`
+        // into `…Phas`. A stem that itself ends in 's' (`classes`, `addresses`) or in 'us' (`buses`,
+        // `statuses`) drops 'es'; a vowel or n/l/r before 'se' (`phases`, `cases`, `databases`,
+        // `responses`, `licenses`, `courses`) marks a singular that ENDS in 'e', so only 's' goes.
+        if (/(sses|uses)$/.test(lowerWord)) {
+            return word.slice(0, -2);
+        }
+        if (/[aeionlr]ses$/.test(lowerWord)) {
+            return word.slice(0, -1);
         }
         // Words ending in 'ses', 'xes', 'zes', 'shes', 'ches' remove 'es'
-        if (/[sxz]es$/.test(lowerWord) || /[sh]es$/.test(lowerWord) || /ches$/.test(lowerWord)) {
+        if (/[sxz]es$/.test(lowerWord) || /shes$/.test(lowerWord) || /ches$/.test(lowerWord)) {
             return word.slice(0, -2);
         }
         // Words ending in 'oes' remove 'es'
@@ -110,6 +128,33 @@ export class ResourcesConfigNamingUtils {
         // If doesn't match any pattern, return as is (might already be singular)
         return word;
     }
+    /**
+     * The singular nouns whose plural changes `f` / `fe` to `ves`. Deliberately SMALL and closed:
+     * everything else ending in `f` or `fe` takes a plain `s`, which is the common case in the
+     * identifiers this framework derives (`…Ref`, `…Proof`). Shared by `pluralize` and `singularize`
+     * so the two directions cannot disagree about which words are exceptions.
+     */
+    static F_TO_VES_WORDS = new Set([
+        'calf', 'elf', 'half', 'leaf', 'loaf', 'self', 'sheaf', 'shelf', 'thief', 'wolf',
+    ]);
+    static FE_TO_VES_WORDS = new Set(['knife', 'life', 'wife']);
+    /**
+     * The last English word of a lower-cased identifier. Word boundaries are lost by lower-casing, so
+     * this matches a trailing exception word against the whole-string suffix instead: `bookshelf`
+     * yields `shelf`, `organizationinvoiceref` yields itself (no exception word is its suffix), and a
+     * `snake_case` or `kebab-case` tail is split on its separator.
+     */
+    static lastWordOf(lowerWord) {
+        const tail = lowerWord.split(/[_\-\s]/).pop() ?? lowerWord;
+        for (const candidate of [...ResourcesConfigNamingUtils.F_TO_VES_WORDS, ...ResourcesConfigNamingUtils.FE_TO_VES_WORDS]) {
+            if (tail.endsWith(candidate))
+                return candidate;
+            const plural = candidate.endsWith('fe') ? candidate.slice(0, -2) + 'ves' : candidate.slice(0, -1) + 'ves';
+            if (tail.endsWith(plural))
+                return plural;
+        }
+        return tail;
+    }
     /**
      * Preserve the case pattern of the original word in the result
      */