@wildo-ai/saas-models 1.0.1

package/dist/esm/resources/resources.shared.schemas.js

@@ -0,0 +1,717 @@
+/**
+ * Operations Shared Schemas
+ *
+ * Reusable operation schemas for bulk actions and common operations
+ */
+import { z } from 'zod';
+import { CoreResourceOperation, ResourceTypeSchema } from './resources.shared.core.definitions.js';
+import { RelationshipContextPolicySchema } from './context-policy.shared.schemas.js';
+import { ChildLifecycleMode, ChildOperationsConfigSchema, ResourceRelationshipDiscriminatorSchema, } from './child-operations.shared.schemas.js';
+import { RelationshipDisplayConfigSchema } from './relationship-display.shared.schemas.js';
+export var ResourceOperationRiskLevel;
+(function (ResourceOperationRiskLevel) {
+    ResourceOperationRiskLevel["LOW"] = "low";
+    ResourceOperationRiskLevel["MEDIUM"] = "medium";
+    ResourceOperationRiskLevel["HIGH"] = "high";
+    ResourceOperationRiskLevel["CRITICAL"] = "critical";
+})(ResourceOperationRiskLevel || (ResourceOperationRiskLevel = {}));
+/**
+ * Display mode for resource operation action bars — controls operation bar density.
+ * SUMMARY = compact row actions (icon-only, in list/table rows).
+ *
+ * Note: "summary" here is about *UI density*, not API data shape (see DataMode.SUMMARY)
+ * or FK rendering (see ForeignKeyDisplayMode.SUMMARY).
+ */
+export var ResourceOperationDisplayMode;
+(function (ResourceOperationDisplayMode) {
+    /** In a list/table row — compact, icon-only, includes "View Details" */
+    ResourceOperationDisplayMode["SUMMARY"] = "summary";
+    /** In a full read/detail view — can show inline labels */
+    ResourceOperationDisplayMode["DETAIL"] = "detail";
+})(ResourceOperationDisplayMode || (ResourceOperationDisplayMode = {}));
+export var ResourcePrimaryScope;
+(function (ResourcePrimaryScope) {
+    ResourcePrimaryScope["USER_SELF"] = "user_self";
+    ResourcePrimaryScope["ORGANIZATIONS"] = "organizations";
+    ResourcePrimaryScope["APPLICATION"] = "applications";
+    ResourcePrimaryScope["ANONYMOUS"] = "anonymous";
+})(ResourcePrimaryScope || (ResourcePrimaryScope = {}));
+/**
+ * W7.3a: Controls how anonymous resources are handled during transposition
+ * (when an anonymous user registers/logs in as an authenticated user).
+ */
+export var ResourceTranspositionPolicy;
+(function (ResourceTranspositionPolicy) {
+    /** Simply reassign ownership (anonymousUserId → userId). No conflict check. Default. */
+    ResourceTranspositionPolicy["ADD"] = "ADD";
+    /** Delete the authenticated user's existing records of this type, then reassign anonymous ones. */
+    ResourceTranspositionPolicy["REPLACE"] = "REPLACE";
+    /** Delegate to a custom service hook (app-developer-defined merge logic). */
+    ResourceTranspositionPolicy["MERGE"] = "MERGE";
+    /** Skip transposition entirely — anonymous records are not carried over. */
+    ResourceTranspositionPolicy["DISCARD"] = "DISCARD";
+})(ResourceTranspositionPolicy || (ResourceTranspositionPolicy = {}));
+// ============================================================================
+// Primary Scope Field Mappings (Single Source of Truth)
+// ============================================================================
+import { CoreResourceType, coreResourceShared_FieldIdentifier } from './resources.shared.core.definitions.js';
+/**
+ * Map from ResourcePrimaryScope to the CoreResourceType it represents.
+ * This is the foundation - other mappings derive from this.
+ */
+export const PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE = {
+    [ResourcePrimaryScope.ORGANIZATIONS]: CoreResourceType.ORGANIZATIONS,
+    [ResourcePrimaryScope.USER_SELF]: CoreResourceType.USERS,
+    [ResourcePrimaryScope.APPLICATION]: CoreResourceType.APPLICATION,
+    [ResourcePrimaryScope.ANONYMOUS]: CoreResourceType.ANONYMOUS_USERS,
+};
+/**
+ * Map from ResourcePrimaryScope to its field identifier.
+ * Uses coreResourceShared_FieldIdentifier as the source of truth for field names.
+ */
+export const PRIMARY_SCOPE_TO_FIELD_IDENTIFIER = {
+    [ResourcePrimaryScope.ORGANIZATIONS]: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS],
+    [ResourcePrimaryScope.USER_SELF]: coreResourceShared_FieldIdentifier[CoreResourceType.USERS],
+    [ResourcePrimaryScope.APPLICATION]: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION],
+    [ResourcePrimaryScope.ANONYMOUS]: coreResourceShared_FieldIdentifier[CoreResourceType.ANONYMOUS_USERS],
+};
+/**
+ * Primary scope field identifiers - auto-populated from execution context.
+ * These fields should be excluded from CREATE/UPDATE DTOs because they are
+ * automatically injected by the backend based on the authenticated user's context.
+ *
+ * Derived from PRIMARY_SCOPE_TO_FIELD_IDENTIFIER values.
+ */
+export const PRIMARY_SCOPE_FIELD_IDENTIFIERS = Object.values(PRIMARY_SCOPE_TO_FIELD_IDENTIFIER);
+/**
+ * Map from field identifier to ResourcePrimaryScope.
+ * Built by inverting PRIMARY_SCOPE_TO_FIELD_IDENTIFIER.
+ */
+export const FIELD_IDENTIFIER_TO_PRIMARY_SCOPE = Object.fromEntries(Object.entries(PRIMARY_SCOPE_TO_FIELD_IDENTIFIER).map(([scope, field]) => [field, scope]));
+/**
+ * Map from ResourcePrimaryScope to the CoreResourceType(s) it represents.
+ * Returns as array for compatibility (though each scope maps to a single type).
+ */
+export const PRIMARY_SCOPE_TO_RESOURCE_TYPES = {
+    [ResourcePrimaryScope.ORGANIZATIONS]: [PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE[ResourcePrimaryScope.ORGANIZATIONS]],
+    [ResourcePrimaryScope.USER_SELF]: [PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE[ResourcePrimaryScope.USER_SELF]],
+    [ResourcePrimaryScope.APPLICATION]: [PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE[ResourcePrimaryScope.APPLICATION]],
+    [ResourcePrimaryScope.ANONYMOUS]: [PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE[ResourcePrimaryScope.ANONYMOUS]],
+};
+/**
+ * Get the field identifier for a primary scope.
+ */
+export function getPrimaryScopeFieldIdentifier(primaryScope) {
+    return PRIMARY_SCOPE_TO_FIELD_IDENTIFIER[primaryScope];
+}
+// ============================================================================
+// Billing Scope → Resource Type Mapping
+// ============================================================================
+/**
+ * The 2 scopes that have billing polymorphic variants.
+ * APPLICATION scope is intentionally absent — it has no billing variants;
+ * scope-agnostic billing resources (Products, Prices, etc.) are not per-scope.
+ */
+export const BILLING_SCOPES = [
+    ResourcePrimaryScope.ORGANIZATIONS,
+    ResourcePrimaryScope.USER_SELF,
+];
+/**
+ * Per-scope billing resource types.
+ * Maps each billing scope to the set of polymorphic resource type variants
+ * that belong to it. Used to selectively exclude disabled scopes while
+ * keeping enabled scopes and scope-agnostic resources (Products, Prices, etc.).
+ */
+export const BILLING_SCOPE_RESOURCE_TYPES = {
+    [ResourcePrimaryScope.ORGANIZATIONS]: new Set([
+        CoreResourceType.ORGANIZATION_BILLING_ACCOUNTS,
+        CoreResourceType.ORGANIZATION_SUBSCRIPTIONS,
+        CoreResourceType.ORGANIZATION_INVOICE_REFS,
+        CoreResourceType.ORGANIZATION_USAGE_RECORDS,
+        CoreResourceType.ORGANIZATION_CREDIT_POOLS,
+    ]),
+    [ResourcePrimaryScope.USER_SELF]: new Set([
+        CoreResourceType.USER_BILLING_ACCOUNTS,
+        CoreResourceType.USER_SUBSCRIPTIONS,
+        CoreResourceType.USER_INVOICE_REFS,
+        CoreResourceType.USER_USAGE_RECORDS,
+        CoreResourceType.USER_CREDIT_POOLS,
+    ]),
+};
+/**
+ * Get the primary scope for a field identifier.
+ * Returns undefined if the field is not a primary scope field.
+ */
+export function getPrimaryScopeFromFieldIdentifier(fieldIdentifier) {
+    return FIELD_IDENTIFIER_TO_PRIMARY_SCOPE[fieldIdentifier];
+}
+/**
+ * Check if a field identifier is a primary scope field.
+ */
+export function isPrimaryScopeFieldIdentifier(fieldIdentifier) {
+    return PRIMARY_SCOPE_FIELD_IDENTIFIERS.includes(fieldIdentifier);
+}
+export var ResourceRelationshipCardinality;
+(function (ResourceRelationshipCardinality) {
+    ResourceRelationshipCardinality["ONE"] = "one";
+    ResourceRelationshipCardinality["ZERO_OR_ONE"] = "zero_or_one";
+    ResourceRelationshipCardinality["ONE_OR_MANY"] = "one_or_many";
+    ResourceRelationshipCardinality["MANY"] = "many";
+})(ResourceRelationshipCardinality || (ResourceRelationshipCardinality = {}));
+/**
+ * Check if a cardinality represents a 1:1 relationship (single object).
+ * Both `ONE` (mandatory) and `ZERO_OR_ONE` (optional) are single-object cardinalities.
+ *
+ * Use this utility instead of checking `=== ONE` directly, to avoid
+ * the common bug of missing `ZERO_OR_ONE` (optional 1:1) handling.
+ *
+ * Determines:
+ * - DTO shape: single optional object (not array)
+ * - Nested field naming: singular (e.g., "profile" not "profiles")
+ * - Fetch strategy: READ (not LIST)
+ * - URL path: singular entity path
+ */
+export function isOneToOneCardinality(cardinality) {
+    return cardinality === ResourceRelationshipCardinality.ONE ||
+        cardinality === ResourceRelationshipCardinality.ZERO_OR_ONE;
+}
+/**
+ * Check if a cardinality represents a 1:N relationship (array/collection).
+ * Both `MANY` (zero or more) and `ONE_OR_MANY` (at least one) are array cardinalities.
+ *
+ * Use this utility instead of checking `=== MANY` directly, to avoid
+ * the common bug of missing `ONE_OR_MANY` (mandatory at-least-one) handling.
+ *
+ * Determines:
+ * - DTO shape: array of objects
+ * - Nested field naming: plural (e.g., "tasks" not "task")
+ * - Fetch strategy: LIST
+ * - URL path: collection path
+ */
+export function isArrayCardinality(cardinality) {
+    return cardinality === ResourceRelationshipCardinality.MANY ||
+        cardinality === ResourceRelationshipCardinality.ONE_OR_MANY;
+}
+export var ResourceOperationVariantType;
+(function (ResourceOperationVariantType) {
+    ResourceOperationVariantType["API_CALL"] = "api_call";
+    ResourceOperationVariantType["API_CALL_WITH_CALLBACK"] = "api_call_with_callback";
+    ResourceOperationVariantType["CRON_JOB"] = "cron_job";
+    ResourceOperationVariantType["BATCH_JOB"] = "batch_job";
+    ResourceOperationVariantType["INTERNAL_CALL"] = "internal_call";
+    ResourceOperationVariantType["REPOSITORY_ONLY"] = "repository_only";
+})(ResourceOperationVariantType || (ResourceOperationVariantType = {}));
+export var ResourceOperation_ServiceRuntimeMode;
+(function (ResourceOperation_ServiceRuntimeMode) {
+    ResourceOperation_ServiceRuntimeMode["INLINE"] = "inline";
+    ResourceOperation_ServiceRuntimeMode["INLINE_NOT_AWAITABLE"] = "inline_not_awaitable";
+    ResourceOperation_ServiceRuntimeMode["BACKGROUND_JOB"] = "background_job";
+    ResourceOperation_ServiceRuntimeMode["QUEUED"] = "queued";
+    ResourceOperation_ServiceRuntimeMode["QUEUED_NOT_AWAITABLE"] = "queued_not_awaitable";
+    ResourceOperation_ServiceRuntimeMode["NONE"] = "none";
+})(ResourceOperation_ServiceRuntimeMode || (ResourceOperation_ServiceRuntimeMode = {}));
+export var ResourceOperation_CustomServiceImplementationMode;
+(function (ResourceOperation_CustomServiceImplementationMode) {
+    ResourceOperation_CustomServiceImplementationMode["OVERRIDE_ALL"] = "override_all";
+    ResourceOperation_CustomServiceImplementationMode["PREFIX_CORE_OPERARTIONS"] = "prefix_core_operations";
+    ResourceOperation_CustomServiceImplementationMode["POSTFIX_CORE_OPERARTIONS"] = "postfix_core_operations";
+    ResourceOperation_CustomServiceImplementationMode["REPLACE_CORE_OPERARTIONS"] = "between_core_operations";
+    ResourceOperation_CustomServiceImplementationMode["AFTER_USER_NOTIFICATIONS"] = "after_user_notifications";
+    ResourceOperation_CustomServiceImplementationMode["AT_THE_END"] = "at_the_end";
+})(ResourceOperation_CustomServiceImplementationMode || (ResourceOperation_CustomServiceImplementationMode = {}));
+export var ResourceParentResourceRequirement;
+(function (ResourceParentResourceRequirement) {
+    ResourceParentResourceRequirement["MANDATORY"] = "mandatory";
+    ResourceParentResourceRequirement["OPTIONAL"] = "optional";
+})(ResourceParentResourceRequirement || (ResourceParentResourceRequirement = {}));
+export var ResourceOperation_InputPolicy;
+(function (ResourceOperation_InputPolicy) {
+    ResourceOperation_InputPolicy["DEFAULT"] = "default";
+    ResourceOperation_InputPolicy["CUSTOM"] = "custom";
+})(ResourceOperation_InputPolicy || (ResourceOperation_InputPolicy = {}));
+export var ResourceOperation_OutputPolicy;
+(function (ResourceOperation_OutputPolicy) {
+    ResourceOperation_OutputPolicy["DEFAULT"] = "default";
+    ResourceOperation_OutputPolicy["CUSTOM"] = "custom";
+    ResourceOperation_OutputPolicy["SUMMARY"] = "summary";
+    ResourceOperation_OutputPolicy["CONTEXT"] = "context";
+})(ResourceOperation_OutputPolicy || (ResourceOperation_OutputPolicy = {}));
+/*
+ accessScopeStrategy defines how a related resource should be accessed in service, controller, and route generation:
+REQUIRES_CONTEXT: the resource must be accessed within the context of its parent (e.g. nested route, scoped service)
+OPTIONAL_CONTEXT: the resource can be accessed either within its parent context or independently.
+STANDALONE: the resource must be accessed independently, even if a parent relationship exists.
+ */
+export var ResourceRelationshipAccessScopeStrategy;
+(function (ResourceRelationshipAccessScopeStrategy) {
+    ResourceRelationshipAccessScopeStrategy["REQUIRES_CONTEXT"] = "requires_context";
+    ResourceRelationshipAccessScopeStrategy["OPTIONAL_CONTEXT"] = "optional_context";
+    ResourceRelationshipAccessScopeStrategy["STANDALONE"] = "standalone";
+})(ResourceRelationshipAccessScopeStrategy || (ResourceRelationshipAccessScopeStrategy = {}));
+/**
+ * High-level semantic kind of relationship.
+ *
+ * This is the primary shared meaning. Resolver/runtime layers may later derive
+ * engine-facing handling from it, but the declaration should start here rather
+ * than from low-level DTO or lifecycle toggles.
+ *
+ * Developer-facing interpretation:
+ *
+ * - `COMPOSITION`
+ *   The parent owns an aggregate boundary around the child. The relationship is
+ *   about parent-managed nested resources. Child lifecycle is typically
+ *   dependent on the parent, and nested create/update/delete is the natural UX.
+ *
+ * - `REFERENCE`
+ *   The current resource points to another independent resource. The default UX
+ *   is "select existing / clear / navigate". A future "quick create" shortcut
+ *   may exist, but it still means "create independent resource, then set the
+ *   reference" rather than aggregate-managed nested creation.
+ *
+ * - `ASSOCIATION`
+ *   The current resource is linked to peer resources through membership/link
+ *   semantics. The default UX is "link / unlink / replace peer set". A future
+ *   "quick create" shortcut may exist, but it still means "create independent
+ *   peer, then link it" rather than treating the peer as an owned child.
+ *
+ * Important rule:
+ * - "quick create" is a frontend workflow capability layered on top of a
+ *   relationship, not a fourth relationship nature.
+ */
+export var RelationshipNature;
+(function (RelationshipNature) {
+    RelationshipNature["COMPOSITION"] = "composition";
+    RelationshipNature["REFERENCE"] = "reference";
+    RelationshipNature["ASSOCIATION"] = "association";
+})(RelationshipNature || (RelationshipNature = {}));
+/**
+ * Parent-surface DTO model implied by relationship semantics.
+ *
+ * This tells the framework what kind of shape the parent-facing interaction
+ * should expose:
+ * - `NESTED_RESOURCE` → full nested child payloads
+ * - `REFERENCE_HANDLE` → handle/pointer semantics to an independent resource
+ * - `ASSOCIATION_HANDLE` → peer membership/link semantics
+ */
+export var RelationshipDtoModel;
+(function (RelationshipDtoModel) {
+    RelationshipDtoModel["NESTED_RESOURCE"] = "nested_resource";
+    RelationshipDtoModel["REFERENCE_HANDLE"] = "reference_handle";
+    RelationshipDtoModel["ASSOCIATION_HANDLE"] = "association_handle";
+})(RelationshipDtoModel || (RelationshipDtoModel = {}));
+/**
+ * Parent-driven mutation semantics for the relationship.
+ *
+ * Interpretation:
+ * - `AGGREGATE_MANAGED` → parent can orchestrate nested child CRUD
+ * - `REFERENCE_MANAGED` → parent mutates only the reference handle/pointer
+ * - `ASSOCIATION_MANAGED` → parent mutates membership/link state to peers
+ * - `NONE` → no parent-driven relationship-object mutation contract
+ */
+export var RelationshipMutationModel;
+(function (RelationshipMutationModel) {
+    RelationshipMutationModel["AGGREGATE_MANAGED"] = "aggregate_managed";
+    RelationshipMutationModel["REFERENCE_MANAGED"] = "reference_managed";
+    RelationshipMutationModel["ASSOCIATION_MANAGED"] = "association_managed";
+    RelationshipMutationModel["NONE"] = "none";
+})(RelationshipMutationModel || (RelationshipMutationModel = {}));
+/**
+ * Lifecycle dependency semantics between the parent and the related element.
+ *
+ * This is about dependency, not frontend chrome:
+ * - `DEPENDENT` → child lifecycle follows parent ownership
+ * - `INDEPENDENT` → related resource lives independently
+ * - `LINK_ONLY` → only the relationship membership/link is owned here
+ */
+export var RelationshipLifecycleModel;
+(function (RelationshipLifecycleModel) {
+    RelationshipLifecycleModel["DEPENDENT"] = "dependent";
+    RelationshipLifecycleModel["INDEPENDENT"] = "independent";
+    RelationshipLifecycleModel["LINK_ONLY"] = "link_only";
+})(RelationshipLifecycleModel || (RelationshipLifecycleModel = {}));
+/**
+ * Shared read intent for the relationship.
+ *
+ * Important: this is NOT the same semantic plane as `DataMode`,
+ * `ContextPolicy_ObjectMode`, or `childOperations.nested.onRead`.
+ * It is the high-level engine-facing read intent that later resolver steps may
+ * project into those operational surfaces where the meaning is truly identical.
+ *
+ * Interpretation:
+ * - `EMBEDDED` → read as an owned nested child/children
+ * - `REFERENCE_ONLY` → read as a pointer/reference surface
+ * - `ASSOCIATION_EMBEDDED` → read as associated peers, while preserving peer
+ *   semantics rather than collapsing them into composition
+ */
+export var RelationshipReadModel;
+(function (RelationshipReadModel) {
+    RelationshipReadModel["EMBEDDED"] = "embedded";
+    RelationshipReadModel["REFERENCE_ONLY"] = "reference_only";
+    RelationshipReadModel["ASSOCIATION_EMBEDDED"] = "association_embedded";
+})(RelationshipReadModel || (RelationshipReadModel = {}));
+/**
+ * Explicit semantic read contract for a relationship.
+ *
+ * This answers the semantic question "how should this relationship read?" and
+ * intentionally stays separate from the low-level nested projection in
+ * `childOperations.nested.onRead`, which still carries payload-shaping details
+ * like `dataMode`, list behavior, limits, and sort order.
+ */
+export const RelationshipHandlingReadSettingsSchema = z.object({
+    model: z.enum(RelationshipReadModel),
+});
+/**
+ * Narrow mutation refinements under the semantic handling contract.
+ *
+ * These are still low-level operational hints, not a replacement for
+ * `nature` or the top-level handling models.
+ */
+export const RelationshipHandlingMutationSettingsSchema = z.object({
+    allowParentCreate: z.boolean().optional(),
+    allowParentUpdate: z.boolean().optional(),
+    allowParentDelete: z.boolean().optional(),
+    maxDepth: z.number().int().min(0).optional(),
+});
+/**
+ * Narrow lifecycle refinements under the semantic handling contract.
+ */
+export const RelationshipHandlingLifecycleOnParentDeleteSettingsSchema = z.object({
+    enabled: z.boolean().optional(),
+    mode: z.enum(ChildLifecycleMode).optional(),
+    maxDepth: z.number().int().min(0).optional(),
+});
+export const RelationshipHandlingLifecycleSettingsSchema = z.object({
+    onParentDelete: RelationshipHandlingLifecycleOnParentDeleteSettingsSchema.optional(),
+});
+/**
+ * Explicit multi-target relationship actions.
+ *
+ * These actions are intentionally narrower than generic nested CRUD replay:
+ * - `SET` / `CLEAR` target reference relationships from the current resource as child
+ * - `CREATE` targets composition relationships from the current resource as parent
+ * - `LINK` / `UNLINK` target peer associations while keeping junction-row
+ *   persistence an internal implementation detail
+ * - `REPLACE` atomically expresses the desired peer set for association-backed
+ *   form controls without forcing the client to orchestrate unlink/link diffs
+ */
+export var ResourceRelationshipBulkAction;
+(function (ResourceRelationshipBulkAction) {
+    ResourceRelationshipBulkAction["SET"] = "set";
+    ResourceRelationshipBulkAction["CLEAR"] = "clear";
+    ResourceRelationshipBulkAction["CREATE"] = "create";
+    ResourceRelationshipBulkAction["LINK"] = "link";
+    ResourceRelationshipBulkAction["UNLINK"] = "unlink";
+    ResourceRelationshipBulkAction["REPLACE"] = "replace";
+})(ResourceRelationshipBulkAction || (ResourceRelationshipBulkAction = {}));
+export const ResourceRelationshipBulkOperationIdentifierPrefix = {
+    [ResourceRelationshipBulkAction.SET]: 'bulk_set_',
+    [ResourceRelationshipBulkAction.CLEAR]: 'bulk_clear_',
+    [ResourceRelationshipBulkAction.CREATE]: 'bulk_create_',
+    [ResourceRelationshipBulkAction.LINK]: 'bulk_link_',
+    [ResourceRelationshipBulkAction.UNLINK]: 'bulk_unlink_',
+    [ResourceRelationshipBulkAction.REPLACE]: 'bulk_replace_',
+};
+export const ResourceRelationshipBulkSetActionRequestSchema = z.object({
+    relationshipField: z.string().min(1),
+    action: z.literal(ResourceRelationshipBulkAction.SET),
+    targetId: z.string().min(1),
+});
+export const ResourceRelationshipBulkClearActionRequestSchema = z.object({
+    relationshipField: z.string().min(1),
+    action: z.literal(ResourceRelationshipBulkAction.CLEAR),
+});
+export const ResourceRelationshipBulkCreateActionRequestSchema = z.object({
+    relationshipField: z.string().min(1),
+    action: z.literal(ResourceRelationshipBulkAction.CREATE),
+    data: z.record(z.string(), z.any()).refine((data) => Object.keys(data).length > 0, 'data must not be empty'),
+});
+export const ResourceRelationshipBulkLinkActionRequestSchema = z.object({
+    relationshipField: z.string().min(1),
+    action: z.literal(ResourceRelationshipBulkAction.LINK),
+    peerIds: z.array(z.string().min(1)).min(1),
+});
+export const ResourceRelationshipBulkUnlinkActionRequestSchema = z.object({
+    relationshipField: z.string().min(1),
+    action: z.literal(ResourceRelationshipBulkAction.UNLINK),
+    peerIds: z.array(z.string().min(1)).min(1),
+});
+export const ResourceRelationshipBulkReplaceActionRequestSchema = z.object({
+    relationshipField: z.string().min(1),
+    action: z.literal(ResourceRelationshipBulkAction.REPLACE),
+    peerIds: z.array(z.string().min(1)),
+});
+export const ResourceRelationshipBulkActionRequestSchema = z.discriminatedUnion('action', [
+    ResourceRelationshipBulkSetActionRequestSchema,
+    ResourceRelationshipBulkClearActionRequestSchema,
+    ResourceRelationshipBulkCreateActionRequestSchema,
+    ResourceRelationshipBulkLinkActionRequestSchema,
+    ResourceRelationshipBulkUnlinkActionRequestSchema,
+    ResourceRelationshipBulkReplaceActionRequestSchema,
+]);
+const ResourceRelationshipBulkFilterSelectorSchema = z.object({
+    filter: z.record(z.string(), z.any()).refine((filter) => Object.keys(filter).length > 0, 'filter must not be empty'),
+    _ids: z.undefined().optional(),
+});
+const ResourceRelationshipBulkIdsSelectorSchema = z.object({
+    _ids: z.array(z.string().min(1)).min(1),
+    filter: z.undefined().optional(),
+});
+/**
+ * Public request selector for explicit bulk relationship operations.
+ *
+ * Unlike the legacy bulk DTO base, this selector intentionally supports either:
+ * - `_ids` for UI-driven selection over a finite checked list
+ * - `filter` for backend/automation-driven targeting over a query
+ *
+ * The exposed operation surface stays one-selector / one-action / one-payload.
+ */
+export const ResourceRelationshipBulkOperationSelectorSchema = z.union([
+    ResourceRelationshipBulkIdsSelectorSchema,
+    ResourceRelationshipBulkFilterSelectorSchema,
+]);
+export const ResourceRelationshipBulkSetOperationRequestSchema = ResourceRelationshipBulkOperationSelectorSchema.and(z.object({
+    targetId: z.string().min(1),
+}));
+export const ResourceRelationshipBulkClearOperationRequestSchema = ResourceRelationshipBulkOperationSelectorSchema;
+export const ResourceRelationshipBulkCreateOperationRequestSchema = ResourceRelationshipBulkOperationSelectorSchema.and(z.object({
+    data: z.record(z.string(), z.any()).refine((data) => Object.keys(data).length > 0, 'data must not be empty'),
+}));
+export const ResourceRelationshipBulkLinkOperationRequestSchema = ResourceRelationshipBulkOperationSelectorSchema.and(z.object({
+    peerIds: z.array(z.string().min(1)).min(1),
+}));
+export const ResourceRelationshipBulkUnlinkOperationRequestSchema = ResourceRelationshipBulkOperationSelectorSchema.and(z.object({
+    peerIds: z.array(z.string().min(1)).min(1),
+}));
+export const ResourceRelationshipBulkReplaceOperationRequestSchema = ResourceRelationshipBulkOperationSelectorSchema.and(z.object({
+    peerIds: z.array(z.string().min(1)),
+}));
+export const ResourceRelationshipBulkActionResultSchema = z.object({
+    relationshipField: z.string().min(1),
+    action: z.enum(ResourceRelationshipBulkAction),
+    matchedTargetIds: z.array(z.string()),
+    affectedCount: z.number().int().min(0),
+    results: z.array(z.any()),
+});
+/**
+ * Fully resolved relationship handling contract.
+ *
+ * This describes the engine-facing semantic handling after `nature` has been
+ * resolved. The `read` block is the semantic source of truth, while
+ * `childOperations.nested.onRead` remains the low-level operational projection
+ * for payload shaping.
+ */
+export const RelationshipHandlingContractSchema = z.object({
+    dtoModelMode: z.enum(RelationshipDtoModel),
+    mutationModelMode: z.enum(RelationshipMutationModel),
+    lifecycleModelMode: z.enum(RelationshipLifecycleModel),
+    readModelMode: z.enum(RelationshipReadModel),
+    read: RelationshipHandlingReadSettingsSchema,
+    mutation: RelationshipHandlingMutationSettingsSchema.optional(),
+    lifecycle: RelationshipHandlingLifecycleSettingsSchema.optional(),
+});
+export const ResourceRelationshipBaseSchema = z.object({
+    resourceType1: ResourceTypeSchema,
+    resourceType2: ResourceTypeSchema,
+});
+export const ResourceRelationshipSchema = z.object({
+    cardinality1: z.enum(ResourceRelationshipCardinality),
+    cardinality2: z.enum(ResourceRelationshipCardinality),
+    resourceType1: ResourceTypeSchema,
+    resourceType2: ResourceTypeSchema,
+    accessScopeStrategy: z.enum(ResourceRelationshipAccessScopeStrategy).default(ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT),
+    parentResourceRequirement: z.enum(ResourceParentResourceRequirement).default(ResourceParentResourceRequirement.MANDATORY),
+    jointResourceType: ResourceTypeSchema.optional(),
+    isPrimaryScope: z.boolean().optional().default(false),
+    primaryScope: z.enum(ResourcePrimaryScope).optional(),
+    /**
+     * Opt-in flag for relationships that form cycles in the resource graph.
+     * When `true`, schema-level cycle detection (at registration) allows this edge.
+     * Applies to all cycle types: direct self-reference (A→A), M:N self-reference
+     * (A↔A via junction), and edges participating in transitive cycles (A→B→C→A).
+     *
+     * Default `false` — cycles are rejected at registration unless every edge
+     * in the cycle has `allowCycle: true`.
+     */
+    allowCycle: z.boolean().optional().default(false),
+    isDisabled: z.boolean().optional().default(false),
+    // Context policy for this relationship - controls how related resources are fetched
+    contextPolicy: RelationshipContextPolicySchema.optional(),
+    /**
+     * High-level shared meaning of the relationship.
+     *
+     * Greenfield direction:
+     * - `nature` remains the primary semantic field app developers author.
+     * - `read` is the explicit semantic read intent when the default read meaning
+     *   derived from low-level nested projection is not precise enough.
+     * - The framework derives its internal handling contract from that semantic
+     *   declaration plus structural topology.
+     *
+     */
+    nature: z.enum(RelationshipNature),
+    /**
+     * Explicit semantic read contract for this relationship.
+     *
+     * This is the authored read intent. It does NOT replace
+     * `childOperations.nested.onRead`, which still carries the low-level nested
+     * response projection details when embedding is operationally enabled.
+     */
+    read: RelationshipHandlingReadSettingsSchema.optional(),
+    /**
+     * Child operations configuration for this relationship.
+     * Handles BACKEND concerns: lifecycle cascade and nested DTO aggregation.
+     *
+     * - lifecycle.onParentDelete: Delete children when parent is deleted
+     * - nested.onRead: Include children in parent READ response
+     * - nested.onCreate/onUpdate: Allow child mutations in parent requests
+     */
+    childOperations: ChildOperationsConfigSchema.optional(),
+    /**
+     * Static discriminator filter for conditional relationships.
+     * When specified, this relationship only applies when the PARENT resource's
+     * discriminator field matches one of the specified values.
+     *
+     * This field is part of the Zod schema (serializable). For arbitrary function-based
+     * conditions, use the `condition` field on the `ResourceRelationship` TypeScript type
+     * (which extends this schema via intersection).
+     *
+     * Runtime evaluation uses the shared
+     * `Resources_SharedUtils.matchesRelationshipDiscriminator()` helper, which
+     * applies `String()` coercion:
+     * `values.includes(String(parent[discriminatorField]))`.
+     *
+     * @see ResourceRelationshipDiscriminatorSchema — for the full schema definition
+     * @see ResourceRelationship — for the full type including the `condition` function
+     *
+     * @example Recurring todos have occurrences, one-time todos don't:
+     * { discriminatorField: 'recurringType', values: ['RECURRING'] }
+     */
+    discriminator: ResourceRelationshipDiscriminatorSchema.optional(),
+    /**
+     * Frontend relationship presentation configuration.
+     *
+     * This remains on the frontend/UI plane:
+     * - read composition in parent/child views
+     * - narrow interaction hints such as `interaction.allowQuickCreate`
+     *
+     * It must NOT redefine the core meaning of the relationship. In particular,
+     * `display.interaction.allowQuickCreate` is only a workflow shortcut hint:
+     * - for `REFERENCE`: "create independent resource, then set reference"
+     * - for `ASSOCIATION`: "create independent peer, then link/replace"
+     * - for `COMPOSITION`: usually ignored because nested creation is already the
+     *   native aggregate workflow
+     *
+     * Labels remain managed by the i18n mechanism.
+     */
+    display: RelationshipDisplayConfigSchema.optional(),
+    /**
+     * Foreign key field name for this relationship.
+     *
+     * When omitted: Inferred from parent's resourceFieldIdentifier via allResourceFieldIdentifiers map.
+     * When specified: Used for disambiguation when multiple FKs point to same resource type,
+     *                 or when FK field name differs from standard naming convention.
+     *
+     * Examples:
+     * - Standard: ORGANIZATIONS → TODOS uses organizationId (inferred)
+     * - Disambiguation: TODOS → USERS via assignedToUserId vs createdByUserId (explicit)
+     * - M:N self-reference: TODOS → TODOS via junction table uses todoId/targetTodoId (explicit)
+     */
+    foreignKeyField: z.string().optional(),
+});
+// --------------------------------
+// Default Operation Response Patterns
+// --------------------------------
+/**
+ * Default response patterns for resource operations based on best practices
+ */
+export const DefaultDeleteResponseSchema = z.object({
+    id: z.string(),
+    deletedAt: z.date().optional()
+});
+export const DefaultBulkDeleteResponseSchema = z.object({
+    deletedIds: z.array(z.string()),
+    deletedCount: z.number(),
+    deletedAt: z.date().optional()
+});
+export const DefaultUpdateManyResponseSchema = z.object({
+    updatedCount: z.number(),
+    updatedIds: z.array(z.string()).optional(),
+    updatedAt: z.date().optional()
+});
+export const DefaultCountResponseSchema = z.object({
+    count: z.number().int().min(0),
+});
+export const DefaultCreateManyResponseSchema = (itemSchema) => z.object({
+    items: z.array(itemSchema),
+    createdCount: z.number(),
+    createdAt: z.date().optional()
+});
+/**
+ * Generic success envelope for explicit custom action-style operations.
+ *
+ * This schema is intentionally transport-oriented. It can be attached through
+ * explicit `customResponseDto` / `responseDto` config when a custom operation
+ * returns a generic success envelope instead of a resource DTO.
+ */
+export const DefaultActionResponseSchema = z.object({
+    success: z.boolean(),
+    message: z.string().optional(),
+    executedAt: z.date(),
+    result: z.any().optional()
+});
+/**
+ * Fields that are always discarded from create/update payloads at runtime.
+ * These are auto-generated or system-managed fields.
+ *
+ * Note: _id is also handled by the isPrimaryKey decorator at the schema level,
+ * but is kept here as a runtime safety net for backward compatibility.
+ */
+export const createOrUpdateMandatoryDiscardFields = [
+    '_id', // Also handled by isPrimaryKey decorator
+    'createdAt',
+    'updatedAt',
+    'deletedAt',
+    '_version_db_doc',
+];
+// Utility to get default response schema based on operation
+export function getDefaultResponseSchemaForOperation(operation, mainSchema) {
+    switch (operation) {
+        case CoreResourceOperation.READ:
+        case CoreResourceOperation.CREATE:
+        case CoreResourceOperation.UPDATE:
+            return mainSchema;
+        case CoreResourceOperation.DELETE:
+            return DefaultDeleteResponseSchema;
+        case CoreResourceOperation.DELETE_MANY:
+            return DefaultBulkDeleteResponseSchema;
+        case CoreResourceOperation.UPDATE_MANY:
+            return DefaultUpdateManyResponseSchema;
+        case CoreResourceOperation.CREATE_MANY:
+            return DefaultCreateManyResponseSchema(mainSchema);
+        case CoreResourceOperation.LIST:
+            // List operations should use pagination wrapper - handled separately
+            return mainSchema;
+        case CoreResourceOperation.COUNT:
+            return DefaultCountResponseSchema;
+        case CoreResourceOperation.SEARCH:
+            return mainSchema;
+        default:
+            // For custom operations, default to mainSchema
+            return mainSchema;
+    }
+}
+// Utility to determine if operation should have request DTO
+export function operationShouldHaveRequestDto(operation) {
+    const operationsWithoutRequestDto = ['read', 'list', 'delete', 'count'];
+    return !operationsWithoutRequestDto.includes(operation);
+}
+/**
+ * Supported ID format types
+ */
+export var ResourceIdFormat;
+(function (ResourceIdFormat) {
+    /** MongoDB ObjectId - 24 character hexadecimal string */
+    ResourceIdFormat["OBJECT_ID"] = "OBJECT_ID";
+    /** PostgreSQL UUID - 36 character UUID with dashes */
+    ResourceIdFormat["UUID"] = "UUID";
+})(ResourceIdFormat || (ResourceIdFormat = {}));
+//# sourceMappingURL=resources.shared.schemas.js.map