@wildo-ai/saas-models 1.0.1

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

@@ -0,0 +1,752 @@
+/**
+ * Resources Shared Utils
+ *
+ * Cross-layer resource helpers shared by backend, frontend, and shared-model
+ * consumers. This includes ID helpers plus runtime relationship activation
+ * evaluation.
+ */
+import { ChildOperationsConfigSchema, ChildLifecycleMode, } from './child-operations.shared.schemas.js';
+import { ResourcesConfigNamingUtils } from './utils/resources-config-naming.utils.js';
+import { CoreResourceOperation } from './resources.shared.core.definitions.js';
+import { RelationshipDtoModel, RelationshipLifecycleModel, RelationshipHandlingContractSchema, RelationshipHandlingReadSettingsSchema, RelationshipMutationModel, RelationshipNature, ResourceRelationshipBulkAction, ResourceRelationshipBulkOperationIdentifierPrefix, RelationshipReadModel, ResourceIdFormat, isOneToOneCardinality, } from './resources.shared.schemas.js';
+import { ErrorType } from '../errors/errors.shared.schemas.js';
+/**
+ * Database-agnostic Resource ID utilities
+ *
+ * Supports both MongoDB ObjectId (24-char hex) and PostgreSQL UUID formats.
+ * Used across the entire stack for ID validation and format detection.
+ */
+export class Resources_SharedUtils {
+    static createConfigurationError(message) {
+        const error = new Error(message);
+        error.type = ErrorType.CONFIGURATION;
+        return error;
+    }
+    static areResolvedRelationshipSemanticsEquivalent(left, right) {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    static hasValidResolvedRelationshipSemantics(semantics) {
+        if (!semantics || typeof semantics !== 'object') {
+            return false;
+        }
+        const candidate = semantics;
+        return (typeof candidate.natureCalculationMode === 'string' &&
+            (candidate.readCalculationMode === 'explicit' ||
+                candidate.readCalculationMode === 'legacy_nested_read_fallback' ||
+                candidate.readCalculationMode === 'default_reference_only') &&
+            Object.values(RelationshipNature).includes(candidate.nature) &&
+            candidate.natureCalculationMode === 'explicit' &&
+            RelationshipHandlingContractSchema.safeParse(candidate.handling).success &&
+            (candidate.childOperations === undefined ||
+                ChildOperationsConfigSchema.safeParse(candidate.childOperations).success));
+    }
+    // ============================================================================
+    // Validation Patterns
+    // ============================================================================
+    /**
+     * MongoDB ObjectId pattern: exactly 24 hexadecimal characters
+     */
+    static OBJECT_ID_PATTERN = /^[a-fA-F0-9]{24}$/;
+    /**
+     * UUID pattern: 8-4-4-4-12 format with dashes
+     * Accepts any UUID version (v1, v4, etc.)
+     */
+    static UUID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+    /**
+     * UUID v4 pattern: stricter validation for version 4 UUIDs
+     * Position 13 must be '4', position 17 must be '8', '9', 'a', or 'b'
+     */
+    static UUID_V4_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/;
+    // ============================================================================
+    // Validation Functions
+    // ============================================================================
+    /**
+     * Validates if a string is a valid MongoDB ObjectId format
+     * @param id - String to validate
+     * @returns true if the string is a valid 24-character hexadecimal ObjectId
+     *
+     * @example
+     * Resources_SharedUtils.isObjectId('507f1f77bcf86cd799439011') // true
+     * Resources_SharedUtils.isObjectId('invalid') // false
+     * Resources_SharedUtils.isObjectId('550e8400-e29b-41d4-a716-446655440000') // false (this is UUID)
+     */
+    static isObjectId(id) {
+        if (typeof id !== 'string')
+            return false;
+        return Resources_SharedUtils.OBJECT_ID_PATTERN.test(id);
+    }
+    /**
+     * Validates if a string is a valid UUID format (any version)
+     * @param id - String to validate
+     * @returns true if the string is a valid UUID with dashes
+     *
+     * @example
+     * Resources_SharedUtils.isUUID('550e8400-e29b-41d4-a716-446655440000') // true
+     * Resources_SharedUtils.isUUID('507f1f77bcf86cd799439011') // false (this is ObjectId)
+     * Resources_SharedUtils.isUUID('not-a-uuid') // false
+     */
+    static isUUID(id) {
+        if (typeof id !== 'string')
+            return false;
+        return Resources_SharedUtils.UUID_PATTERN.test(id);
+    }
+    /**
+     * Validates if a string is a valid UUID v4 format (strict)
+     * @param id - String to validate
+     * @returns true if the string is a valid UUID version 4
+     *
+     * @example
+     * Resources_SharedUtils.isUUIDv4('550e8400-e29b-41d4-a716-446655440000') // true
+     * Resources_SharedUtils.isUUIDv4('550e8400-e29b-11d4-a716-446655440000') // false (this is UUID v1)
+     */
+    static isUUIDv4(id) {
+        if (typeof id !== 'string')
+            return false;
+        return Resources_SharedUtils.UUID_V4_PATTERN.test(id);
+    }
+    /**
+     * Detects the format of a resource ID
+     * @param id - String to analyze
+     * @returns The detected format, or null if the string is not a valid resource ID
+     *
+     * @example
+     * Resources_SharedUtils.detectIdFormat('507f1f77bcf86cd799439011') // ResourceIdFormat.OBJECT_ID
+     * Resources_SharedUtils.detectIdFormat('550e8400-e29b-41d4-a716-446655440000') // ResourceIdFormat.UUID
+     * Resources_SharedUtils.detectIdFormat('invalid') // null
+     */
+    static detectIdFormat(id) {
+        if (Resources_SharedUtils.isObjectId(id))
+            return ResourceIdFormat.OBJECT_ID;
+        if (Resources_SharedUtils.isUUID(id))
+            return ResourceIdFormat.UUID;
+        return null;
+    }
+    /**
+     * Validates if a string is a valid resource ID in any supported format
+     * @param id - String to validate
+     * @returns true if the string is either a valid ObjectId or UUID
+     *
+     * @example
+     * Resources_SharedUtils.isValidResourceId('507f1f77bcf86cd799439011') // true (ObjectId)
+     * Resources_SharedUtils.isValidResourceId('550e8400-e29b-41d4-a716-446655440000') // true (UUID)
+     * Resources_SharedUtils.isValidResourceId('invalid') // false
+     */
+    static isValidResourceId(id) {
+        return Resources_SharedUtils.detectIdFormat(id) !== null;
+    }
+    /**
+     * Validates if a string is a valid resource ID for a specific format
+     * @param id - String to validate
+     * @param format - Expected format
+     * @returns true if the string matches the expected format
+     *
+     * @example
+     * Resources_SharedUtils.isValidResourceIdForFormat('507f1f77bcf86cd799439011', ResourceIdFormat.OBJECT_ID) // true
+     * Resources_SharedUtils.isValidResourceIdForFormat('507f1f77bcf86cd799439011', ResourceIdFormat.UUID) // false
+     */
+    static isValidResourceIdForFormat(id, format) {
+        switch (format) {
+            case ResourceIdFormat.OBJECT_ID:
+                return Resources_SharedUtils.isObjectId(id);
+            case ResourceIdFormat.UUID:
+                return Resources_SharedUtils.isUUID(id);
+            default:
+                return false;
+        }
+    }
+    /**
+     * Asserts that a value is a valid resource ID, throwing an error if not
+     * @param id - Value to validate
+     * @param fieldName - Name of the field for error messages
+     * @throws Error if the value is not a valid resource ID
+     *
+     * @example
+     * Resources_SharedUtils.assertValidResourceId('507f1f77bcf86cd799439011', 'userId') // passes
+     * Resources_SharedUtils.assertValidResourceId('invalid', 'userId') // throws Error
+     */
+    static assertValidResourceId(id, fieldName = 'id') {
+        if (typeof id !== 'string') {
+            throw new Error(`${fieldName} must be a string, got ${typeof id}`);
+        }
+        if (!Resources_SharedUtils.isValidResourceId(id)) {
+            throw new Error(`${fieldName} must be a valid resource ID (MongoDB ObjectId or UUID), got: ${id}`);
+        }
+    }
+    // ============================================================================
+    // Relationship Activation
+    // ============================================================================
+    /**
+     * Resolve the relationship identifier field used to expose nested/context
+     * object names to framework consumers.
+     *
+     * Priority:
+     * 1. explicit `foreignKeyField`
+     * 2. related resource default field identifier from `allResourceFieldIdentifiers`
+     * 3. fallback to naming convention from the related resource type
+     */
+    static resolveRelationshipObjectIdentity(relationship, relatedResourceType, cardinality, allResourceFieldIdentifiers) {
+        const relationshipIdentifierField = relationship.foreignKeyField
+            || allResourceFieldIdentifiers[relatedResourceType]
+            || ResourcesConfigNamingUtils.toResourceFieldIdentifier(relatedResourceType);
+        return {
+            relatedResourceType,
+            relationshipIdentifierField,
+            objectFieldName: isOneToOneCardinality(cardinality)
+                ? ResourcesConfigNamingUtils.extractBaseName(relationshipIdentifierField)
+                : ResourcesConfigNamingUtils.toResourceName(relationshipIdentifierField),
+            isExplicit: Boolean(relationship.foreignKeyField),
+        };
+    }
+    /**
+     * Resolve the relationship object identity from the perspective of one of the
+     * relationship's two resource types.
+     *
+     * This is the caller-facing field name the current resource would use when it
+     * refers to the relationship as an object/collection (`user`, `products`,
+     * `productConsumptions`, ...).
+     */
+    static resolveRelationshipObjectIdentityForResource(relationship, currentResourceType, allResourceFieldIdentifiers) {
+        if (relationship.resourceType1 === currentResourceType) {
+            return this.resolveRelationshipObjectIdentity(relationship, relationship.resourceType2, relationship.cardinality2, allResourceFieldIdentifiers);
+        }
+        if (relationship.resourceType2 === currentResourceType) {
+            return this.resolveRelationshipObjectIdentity(relationship, relationship.resourceType1, relationship.cardinality1, allResourceFieldIdentifiers);
+        }
+        throw new Error(`Cannot resolve relationship object identity for resource "${currentResourceType}". ` +
+            `The relationship ${relationship.resourceType1} -> ${relationship.resourceType2} does not include that resource type.`);
+    }
+    static getRelationshipPerspectiveForResource(relationship, currentResourceType) {
+        if (relationship.resourceType1 === currentResourceType && relationship.resourceType2 === currentResourceType) {
+            return undefined;
+        }
+        if (relationship.resourceType1 === currentResourceType) {
+            return 'resourceType1';
+        }
+        if (relationship.resourceType2 === currentResourceType) {
+            return 'resourceType2';
+        }
+        return undefined;
+    }
+    /**
+     * Build the generated custom-operation identifier used to expose explicit bulk
+     * relationship actions at the resource-operation layer.
+     */
+    static buildRelationshipBulkOperationIdentifier(action, relationshipField) {
+        return `${ResourceRelationshipBulkOperationIdentifierPrefix[action]}${relationshipField}`;
+    }
+    /**
+     * Parse a generated bulk relationship operation identifier back into its
+     * semantic parts so backend dispatch can route it to the shared executor.
+     */
+    static parseRelationshipBulkOperationIdentifier(operationIdentifier) {
+        if (operationIdentifier.startsWith(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.SET])) {
+            return {
+                action: ResourceRelationshipBulkAction.SET,
+                relationshipField: operationIdentifier.slice(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.SET].length),
+            };
+        }
+        if (operationIdentifier.startsWith(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.CLEAR])) {
+            return {
+                action: ResourceRelationshipBulkAction.CLEAR,
+                relationshipField: operationIdentifier.slice(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.CLEAR].length),
+            };
+        }
+        if (operationIdentifier.startsWith(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.CREATE])) {
+            return {
+                action: ResourceRelationshipBulkAction.CREATE,
+                relationshipField: operationIdentifier.slice(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.CREATE].length),
+            };
+        }
+        if (operationIdentifier.startsWith(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.LINK])) {
+            return {
+                action: ResourceRelationshipBulkAction.LINK,
+                relationshipField: operationIdentifier.slice(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.LINK].length),
+            };
+        }
+        if (operationIdentifier.startsWith(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.UNLINK])) {
+            return {
+                action: ResourceRelationshipBulkAction.UNLINK,
+                relationshipField: operationIdentifier.slice(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.UNLINK].length),
+            };
+        }
+        if (operationIdentifier.startsWith(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.REPLACE])) {
+            return {
+                action: ResourceRelationshipBulkAction.REPLACE,
+                relationshipField: operationIdentifier.slice(ResourceRelationshipBulkOperationIdentifierPrefix[ResourceRelationshipBulkAction.REPLACE].length),
+            };
+        }
+        return undefined;
+    }
+    /**
+     * Resolve the FK field identity for a relationship.
+     *
+     * Priority:
+     * 1. explicit `foreignKeyField`
+     * 2. parent resource default field identifier from `allResourceFieldIdentifiers`
+     *
+     * This keeps FK resolution semantics shared across backend and frontend
+     * consumers instead of letting each layer improvise its own fallback.
+     */
+    static resolveRelationshipForeignKeyIdentity(relationship, allResourceFieldIdentifiers) {
+        if (relationship.foreignKeyField) {
+            return {
+                parentResourceType: relationship.resourceType1,
+                childResourceType: relationship.resourceType2,
+                fieldIdentifier: relationship.foreignKeyField,
+                isExplicit: true,
+            };
+        }
+        const fieldIdentifier = allResourceFieldIdentifiers[relationship.resourceType1];
+        if (!fieldIdentifier) {
+            throw new Error(`Cannot resolve FK field for relationship ${relationship.resourceType1} -> ${relationship.resourceType2}. ` +
+                `No explicit foreignKeyField was provided and resource type "${relationship.resourceType1}" has no registered default field identifier.`);
+        }
+        return {
+            parentResourceType: relationship.resourceType1,
+            childResourceType: relationship.resourceType2,
+            fieldIdentifier,
+            isExplicit: false,
+        };
+    }
+    /**
+     * Non-throwing FK resolution helper for validation and optional consumers.
+     */
+    static tryResolveRelationshipForeignKeyIdentity(relationship, allResourceFieldIdentifiers) {
+        try {
+            return this.resolveRelationshipForeignKeyIdentity(relationship, allResourceFieldIdentifiers);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Resolve explicit bulk relationship affordances from the perspective of the
+     * currently selected resource type.
+     *
+     * This is intentionally narrower than generic nested CRUD:
+     * - child-side REFERENCE => `set` / `clear`
+     * - parent-side COMPOSITION => `create`
+     * - peer-side ASSOCIATION => `link` / `unlink` / `replace`
+     *
+     * Important for future UX documentation:
+     * - these actions express the semantic difference between pointer management
+     *   (`REFERENCE`), aggregate-owned nested creation (`COMPOSITION`), and peer
+     *   membership management (`ASSOCIATION`)
+     * - a frontend shortcut such as "quick create" does not add a new action kind;
+     *   it simply orchestrates "create independent resource, then run the normal
+     *   reference/association action"
+     */
+    static resolveAllowedBulkRelationshipActionsForResource(relationship, currentResourceType) {
+        if (relationship.isDisabled === true) {
+            return [];
+        }
+        const perspective = this.getRelationshipPerspectiveForResource(relationship, currentResourceType);
+        if (!perspective) {
+            return [];
+        }
+        const semantics = this.requireResolvedRelationshipSemantics(relationship);
+        // REFERENCE: mutate the pointer from the child side.
+        if (semantics.nature === RelationshipNature.REFERENCE &&
+            perspective === 'resourceType2') {
+            return [
+                ResourceRelationshipBulkAction.SET,
+                ResourceRelationshipBulkAction.CLEAR,
+            ];
+        }
+        // COMPOSITION: create owned nested children from the parent side.
+        if (semantics.nature === RelationshipNature.COMPOSITION &&
+            perspective === 'resourceType1' &&
+            this.resolveRelationshipNestedMutationConfig(relationship, CoreResourceOperation.CREATE)) {
+            return [ResourceRelationshipBulkAction.CREATE];
+        }
+        // ASSOCIATION: manage peer membership while keeping junction persistence
+        // internal to the framework.
+        if (semantics.nature === RelationshipNature.ASSOCIATION &&
+            relationship.jointResourceType) {
+            return [
+                ResourceRelationshipBulkAction.LINK,
+                ResourceRelationshipBulkAction.UNLINK,
+                ResourceRelationshipBulkAction.REPLACE,
+            ];
+        }
+        return [];
+    }
+    /**
+     * Resolve the semantic nature of a relationship.
+     *
+     * Greenfield API: relationship declarations must define `nature` explicitly.
+     * The resolver refuses to derive semantic meaning from low-level fields.
+     */
+    static resolveRelationshipNature(relationship) {
+        if (!relationship.nature) {
+            throw this.createConfigurationError('Relationship declarations must define nature explicitly. ' +
+                'Greenfield relationship semantics no longer infer meaning from jointResourceType or childOperations.');
+        }
+        return {
+            nature: relationship.nature,
+            source: 'explicit',
+        };
+    }
+    static deriveLegacyRelationshipReadModel(nature, childOperations) {
+        switch (nature) {
+            case RelationshipNature.COMPOSITION:
+                return childOperations?.nested?.onRead
+                    ? RelationshipReadModel.EMBEDDED
+                    : RelationshipReadModel.REFERENCE_ONLY;
+            case RelationshipNature.ASSOCIATION:
+                return childOperations?.nested?.onRead
+                    ? RelationshipReadModel.ASSOCIATION_EMBEDDED
+                    : RelationshipReadModel.REFERENCE_ONLY;
+            case RelationshipNature.REFERENCE:
+            default:
+                return RelationshipReadModel.REFERENCE_ONLY;
+        }
+    }
+    static resolveRelationshipReadCalculation(params) {
+        if (params.explicitRead) {
+            return {
+                model: params.explicitRead.model,
+                source: 'explicit',
+            };
+        }
+        if (params.childOperations?.nested?.onRead) {
+            return {
+                model: this.deriveLegacyRelationshipReadModel(params.nature, params.childOperations),
+                source: 'legacy_nested_read_fallback',
+            };
+        }
+        return {
+            model: RelationshipReadModel.REFERENCE_ONLY,
+            source: 'default_reference_only',
+        };
+    }
+    /**
+     * Resolve the internal semantic contract and the current operational
+     * projection used by DTO/backend consumers.
+     *
+     * App developers author relationship topology and `nature`. This method is
+     * where the framework derives the deeper internal handling contract and the
+     * effective low-level `childOperations` shape consumed today.
+     */
+    static resolveRelationshipSemantics(relationship) {
+        const resolvedNature = this.resolveRelationshipNature(relationship);
+        const parsedChildOperations = relationship.childOperations
+            ? ChildOperationsConfigSchema.parse(relationship.childOperations)
+            : undefined;
+        const explicitRead = relationship.read
+            ? RelationshipHandlingReadSettingsSchema.parse(relationship.read)
+            : undefined;
+        this.assertRelationshipSemanticsCoherence(relationship, resolvedNature.nature, parsedChildOperations, explicitRead);
+        const resolvedReadCalculation = this.resolveRelationshipReadCalculation({
+            nature: resolvedNature.nature,
+            childOperations: parsedChildOperations,
+            explicitRead,
+        });
+        const handling = this.deriveRelationshipHandlingContract(resolvedNature.nature, parsedChildOperations, resolvedReadCalculation.model);
+        return {
+            nature: resolvedNature.nature,
+            natureCalculationMode: resolvedNature.source,
+            readCalculationMode: resolvedReadCalculation.source,
+            handling,
+            childOperations: parsedChildOperations,
+        };
+    }
+    /**
+     * Resolve the effective nested mutation projection for the given operation.
+     *
+     * `handling` is the semantic gate; `childOperations` remains the current
+     * detailed operational projection while Step 3/4 finishes converging.
+     */
+    static resolveRelationshipNestedMutationConfig(relationship, operation) {
+        const semantics = this.requireResolvedRelationshipSemantics(relationship);
+        if (semantics.handling.dtoModelMode === RelationshipDtoModel.REFERENCE_HANDLE ||
+            semantics.handling.mutationModelMode === RelationshipMutationModel.NONE) {
+            return undefined;
+        }
+        return (operation === CoreResourceOperation.CREATE ||
+            operation === CoreResourceOperation.CREATE_MANY)
+            ? semantics.childOperations?.nested?.onCreate
+            : semantics.childOperations?.nested?.onUpdate;
+    }
+    /**
+     * Resolve the effective nested read projection.
+     *
+     * The semantic read contract is the gate. The detailed data-mode config still
+     * comes from the current operational projection.
+     */
+    static resolveRelationshipNestedReadConfig(relationship) {
+        const semantics = this.requireResolvedRelationshipSemantics(relationship);
+        if (semantics.handling.dtoModelMode === RelationshipDtoModel.REFERENCE_HANDLE ||
+            semantics.handling.read.model === RelationshipReadModel.REFERENCE_ONLY) {
+            return undefined;
+        }
+        return semantics.childOperations?.nested?.onRead;
+    }
+    /**
+     * Resolve the effective lifecycle-on-parent-delete projection.
+     *
+     * `lifecycleModelMode` is the semantic gate; the detailed delete policy still
+     * comes from the current operational projection.
+     */
+    static resolveRelationshipLifecycleOnParentDeleteConfig(relationship) {
+        const semantics = this.requireResolvedRelationshipSemantics(relationship);
+        if (semantics.handling.lifecycleModelMode === RelationshipLifecycleModel.INDEPENDENT) {
+            return undefined;
+        }
+        return semantics.childOperations?.lifecycle?.onParentDelete;
+    }
+    /**
+     * Compile the developer-authored declaration into the runtime relationship
+     * shape used by the framework.
+     */
+    static compileRelationshipDeclaration(relationship) {
+        return {
+            ...relationship,
+            resolvedSemantics: this.resolveRelationshipSemantics(relationship),
+        };
+    }
+    /**
+     * Ensure a relationship is in the compiled runtime shape.
+     *
+     * This is the startup normalization bridge for places that aggregate
+     * relationships from multiple sources before they are stored on registries or
+     * resource configurations.
+     */
+    static ensureCompiledRelationship(relationship) {
+        const compiledRelationship = this.compileRelationshipDeclaration(relationship);
+        if ('resolvedSemantics' in relationship &&
+            this.hasValidResolvedRelationshipSemantics(relationship.resolvedSemantics) &&
+            this.areResolvedRelationshipSemanticsEquivalent(relationship.resolvedSemantics, compiledRelationship.resolvedSemantics)) {
+            return relationship;
+        }
+        return compiledRelationship;
+    }
+    static ensureCompiledRelationships(relationships) {
+        return relationships.map((relationship) => this.ensureCompiledRelationship(relationship));
+    }
+    /**
+     * Strict runtime reader for already-compiled relationships.
+     *
+     * Use this in hot runtime/startup paths once the relationship graph has passed
+     * through the shared compilation boundary.
+     */
+    static requireResolvedRelationshipSemantics(relationship) {
+        if (!this.hasValidResolvedRelationshipSemantics(relationship.resolvedSemantics)) {
+            throw new Error('Expected ResourceRelationship to carry valid resolvedSemantics. ' +
+                'Make sure the relationship graph passed through the shared startup compilation step.');
+        }
+        return relationship.resolvedSemantics;
+    }
+    /**
+     * Read the stored runtime semantics when present. This keeps current call
+     * sites resilient while Step 3 finishes converging on fully compiled edges.
+     */
+    static getResolvedRelationshipSemantics(relationship) {
+        return this.hasValidResolvedRelationshipSemantics(relationship.resolvedSemantics)
+            ? relationship.resolvedSemantics
+            : this.resolveRelationshipSemantics(relationship);
+    }
+    /**
+     * Derive the engine-facing handling contract from the authored relationship
+     * semantics plus low-level nested/lifecycle settings.
+     *
+     * Keep the semantic layers distinct:
+     * - `RelationshipNature` answers what the relationship means
+     * - the explicit read contract answers the semantic read intent when authored
+     * - the returned contract answers what kind of DTO/mutation/read/lifecycle
+     *   handling the engine should expose
+     *
+     * Documentation rule:
+     * - `REFERENCE` = independent-resource pointer semantics
+     * - `ASSOCIATION` = peer membership/link semantics
+     * - `COMPOSITION` = aggregate-managed nested child semantics
+     *
+     * A frontend capability like `display.interaction.allowQuickCreate` must stay
+     * OUTSIDE this contract:
+     * - reference quick create = create independent resource, then set reference
+     * - association quick create = create independent peer, then link/replace
+     * - composition already owns native nested creation and does not need this
+     *   shortcut to explain its meaning
+     */
+    static deriveRelationshipHandlingContract(nature, childOperations, resolvedReadModel) {
+        const baseContract = {
+            dtoModelMode: RelationshipDtoModel.REFERENCE_HANDLE,
+            mutationModelMode: RelationshipMutationModel.NONE,
+            lifecycleModelMode: RelationshipLifecycleModel.INDEPENDENT,
+            readModelMode: resolvedReadModel,
+            read: {
+                model: resolvedReadModel,
+            },
+        };
+        switch (nature) {
+            case RelationshipNature.COMPOSITION:
+                baseContract.dtoModelMode = RelationshipDtoModel.NESTED_RESOURCE;
+                baseContract.mutationModelMode = RelationshipMutationModel.AGGREGATE_MANAGED;
+                baseContract.lifecycleModelMode = RelationshipLifecycleModel.DEPENDENT;
+                break;
+            case RelationshipNature.ASSOCIATION:
+                baseContract.dtoModelMode = RelationshipDtoModel.ASSOCIATION_HANDLE;
+                baseContract.mutationModelMode = RelationshipMutationModel.ASSOCIATION_MANAGED;
+                baseContract.lifecycleModelMode = RelationshipLifecycleModel.LINK_ONLY;
+                break;
+            case RelationshipNature.REFERENCE:
+            default:
+                break;
+        }
+        const createConfig = childOperations?.nested?.onCreate;
+        const updateConfig = childOperations?.nested?.onUpdate;
+        const lifecycleOnDelete = childOperations?.lifecycle?.onParentDelete;
+        if (createConfig || updateConfig) {
+            baseContract.mutation = {
+                allowParentCreate: Boolean(createConfig),
+                allowParentUpdate: Boolean(updateConfig),
+                allowParentDelete: Boolean(updateConfig?.allowDelete),
+                maxDepth: Math.max(createConfig?.maxDepth ?? 0, updateConfig?.maxDepth ?? 0),
+            };
+        }
+        if (lifecycleOnDelete) {
+            baseContract.lifecycle = {
+                onParentDelete: {
+                    enabled: lifecycleOnDelete.enabled,
+                    mode: lifecycleOnDelete.mode ?? ChildLifecycleMode.IMMEDIATE,
+                    maxDepth: lifecycleOnDelete.maxDepth,
+                },
+            };
+        }
+        return baseContract;
+    }
+    static assertRelationshipSemanticsCoherence(relationship, resolvedNature, childOperations, explicitRead) {
+        const legacyReadModel = this.deriveLegacyRelationshipReadModel(resolvedNature, childOperations);
+        if (resolvedNature === RelationshipNature.ASSOCIATION && !relationship.jointResourceType) {
+            throw new Error('Association semantics require jointResourceType. ' +
+                'Step 3 resolver refuses to treat non-junction relationships as ASSOCIATION.');
+        }
+        if (relationship.jointResourceType && relationship.nature && resolvedNature !== RelationshipNature.ASSOCIATION) {
+            throw new Error('Junction-backed relationships must resolve to ASSOCIATION semantics.');
+        }
+        if (resolvedNature === RelationshipNature.ASSOCIATION && childOperations) {
+            const hasAssociationNestedWrite = Boolean(childOperations.nested?.onCreate || childOperations.nested?.onUpdate);
+            const hasAssociationNestedRead = Boolean(childOperations.nested?.onRead);
+            if (hasAssociationNestedWrite || hasAssociationNestedRead) {
+                throw new Error('ASSOCIATION relationships cannot project nested read or mutation DTOs from the association declaration. ' +
+                    'Declare explicit junction resource operations/views instead of using association-level childOperations.nested.');
+            }
+        }
+        if (resolvedNature === RelationshipNature.REFERENCE && childOperations) {
+            const hasReferenceLifecycle = childOperations.lifecycle?.onParentDelete?.enabled === true;
+            const hasReferenceNestedWrite = Boolean(childOperations.nested?.onCreate || childOperations.nested?.onUpdate);
+            const hasReferenceNestedRead = Boolean(childOperations.nested?.onRead);
+            if (hasReferenceLifecycle || hasReferenceNestedWrite || hasReferenceNestedRead) {
+                throw new Error('REFERENCE relationships cannot project to nested CRUD/read embedding or dependent lifecycle. ' +
+                    'Use COMPOSITION/ASSOCIATION semantics or remove the low-level childOperations settings.');
+            }
+        }
+        if (explicitRead) {
+            if (explicitRead.model === RelationshipReadModel.EMBEDDED &&
+                resolvedNature !== RelationshipNature.COMPOSITION) {
+                throw new Error('EMBEDDED read semantics require nature=COMPOSITION.');
+            }
+            if (explicitRead.model === RelationshipReadModel.ASSOCIATION_EMBEDDED &&
+                resolvedNature !== RelationshipNature.ASSOCIATION) {
+                throw new Error('ASSOCIATION_EMBEDDED read semantics require nature=ASSOCIATION.');
+            }
+            if (childOperations?.nested?.onRead &&
+                explicitRead.model !== legacyReadModel) {
+                throw new Error('Explicit relationship read semantics contradict childOperations.nested.onRead. ' +
+                    'Align the authored read contract with the nested read projection or remove one of them.');
+            }
+        }
+    }
+    /**
+     * M:N expansion is only safe when the declaration maps to one unambiguous edge
+     * per synthetic relationship. A self-referencing junction needs distinct source
+     * and target edge identities, which the current single-declaration model does
+     * not encode.
+     */
+    static assertSupportedManyToManySyntheticExpansion(relationship) {
+        if (relationship.jointResourceType && relationship.resourceType1 === relationship.resourceType2) {
+            throw new Error('Self-referencing MANY-to-MANY relationships cannot be expanded from a single declaration. ' +
+                'Declare explicit junction-resource relationships so source and target edge identity stay explicit.');
+        }
+    }
+    /**
+     * Returns true when a discriminator is structurally usable at runtime.
+     *
+     * A usable discriminator needs both a field name and at least one allowed
+     * value. Truthy-but-empty discriminator objects should not be treated as
+     * activation constraints.
+     */
+    static hasUsableRelationshipDiscriminator(discriminator) {
+        return Boolean(discriminator?.discriminatorField &&
+            discriminator.values &&
+            discriminator.values.length > 0);
+    }
+    /**
+     * Returns true when the relationship carries any runtime activation gate.
+     *
+     * Relationships without a usable discriminator (field + non-empty values) or
+     * a condition are unconditionally active.
+     */
+    static hasRelationshipActivationConstraint(relationship) {
+        return Boolean(this.hasUsableRelationshipDiscriminator(relationship.discriminator) ||
+            relationship.condition);
+    }
+    /**
+     * Check whether parent data matches a relationship discriminator.
+     *
+     * Discriminator values are string-based in the schema, so runtime values are
+     * coerced with `String()` before comparison. Missing/empty discriminators do
+     * not match.
+     */
+    static matchesRelationshipDiscriminator(resource, discriminator) {
+        if (!this.hasUsableRelationshipDiscriminator(discriminator)) {
+            return false;
+        }
+        const fieldValue = resource[discriminator.discriminatorField];
+        return discriminator.values.includes(String(fieldValue));
+    }
+    /**
+     * Resolve whether a relationship is active for a given parent resource.
+     *
+     * Evaluation order is semantic, not caller-specific:
+     * 1. discriminator
+     * 2. condition
+     * 3. unconditional pass
+     *
+     * This keeps backend and frontend consumers aligned while still letting them
+     * choose how to handle missing parent data or thrown condition functions.
+     */
+    static isRelationshipActiveForParent(relationship, parentResource, options = {}) {
+        const { onMissingParentResource = 'exclude', onConditionError = 'throw', } = options;
+        const hasConstraint = this.hasRelationshipActivationConstraint(relationship);
+        if (!parentResource) {
+            return hasConstraint ? onMissingParentResource === 'include' : true;
+        }
+        if (this.hasUsableRelationshipDiscriminator(relationship.discriminator)) {
+            if (!this.matchesRelationshipDiscriminator(parentResource, relationship.discriminator)) {
+                return false;
+            }
+        }
+        if (relationship.condition) {
+            try {
+                if (!relationship.condition(parentResource)) {
+                    return false;
+                }
+            }
+            catch (error) {
+                if (onConditionError === 'exclude') {
+                    return false;
+                }
+                throw error;
+            }
+        }
+        return true;
+    }
+    /**
+     * Filter relationships to the subset that is active for a given parent.
+     */
+    static filterRelationshipsActiveForParent(relationships, parentResource, options) {
+        return relationships.filter((relationship) => this.isRelationshipActiveForParent(relationship, parentResource, options));
+    }
+}
+//# sourceMappingURL=resources.shared.utils.js.map