@wildo-ai/saas-frontend-lib 1.0.1

package/dist/esm/core/resources/resources-repository.frontend.service.js

@@ -0,0 +1,686 @@
+/**
+ * Resources Repository Frontend Service
+ *
+ * Central entry point for building the frontend resource registry. Orchestrates:
+ * 1. Factory execution — core + custom resource configs are built from their factories
+ * 2. Operation filtering — only API_CALL / API_CALL_WITH_CALLBACK variants are retained
+ * 3. Preset overlay — `ResourceUIBehavior` adds UI-specific config (icons, layouts, etc.)
+ * 4. Schema bridge — `z_clone` schema mutations propagate to auto-derived DTOs
+ * 5. FK resolution map — fieldIdentifier → resourceType, enriched from relationships
+ * 6. URL generation — `initiatorInfos` populated on API_CALL operations
+ * 7. FK validation — all `isForeignKey()` fields must resolve (dev: throws, prod: logs)
+ */
+import { WildoBackendHttpClient_Resources } from '../../core/requests/wildo-http-client-resources.frontend.service.js';
+import { FrontendView_ScopeMode } from '../../core/config/views-frontend.schemas.js';
+import { envLoader } from '../../core/runtime/env-variable-loader.frontend.service.js';
+import { FRONTEND_SCHEMA_KEY } from '../../core/resources/resources.frontend.schemas.js';
+import { ResourcePrimaryScope, coreShared_ResourcesConfigurations_FactoryMap, coreSharedResourceRelationship, coreResourceShared_FieldIdentifier, coreResourceShared_FieldIdentifierPriority, ResourceOperationVariantType, ResourcesConfigOperationsUrlsBuilderUtils, ResourcesConfigOperationsDtosBuilderUtils, ErrorType, ErrorCustomMessageReference, computeSubtreeMap, CoreResourceOperation, deriveRequestDto, ParentDisplay, RelationshipDisplayConfigSchema, reconcileGeneratedRelationshipBulkOperations, Resources_SharedUtils, } from '@wildo-ai/saas-models';
+import { getZodObjectShape, isForeignKeyField, unwrapSchema, getCustomFieldMetadata, addDecorators, ZodDecorator, ForeignKeyDisplayMode } from '@wildo-ai/zod-decorators';
+import { CoreIconRegistry } from '../../core/icons/icon-registry.frontend.definitions.js';
+import { sharedErrorBuilder } from '../../core/errors/errors-builder.frontend.services.js';
+/**
+ * Checks whether a requestDto was auto-derived from mainSchema by comparing
+ * field object references. CREATE DTOs use direct field refs; UPDATE DTOs
+ * wrap fields in `.optional()`. Returns `true` if at least one field shares
+ * a reference with mainSchema — indicating the DTO was auto-generated by
+ * `deriveRequestDto` and should be rebuilt when mainSchema is replaced.
+ */
+function isDtoDerivedFromSchema(requestDto, mainSchema) {
+    try {
+        const dtoShape = getZodObjectShape(requestDto);
+        const mainShape = getZodObjectShape(mainSchema);
+        return Object.entries(dtoShape).some(([key, field]) => {
+            const mainField = mainShape[key];
+            if (!mainField)
+                return false;
+            return field === mainField || unwrapSchema(field) === mainField;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+export class ResourcesRepositoryFrontendService {
+    httpClient;
+    registry = null;
+    isInitialized = false;
+    resourcesHttpClient = null;
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    /**
+     * Build a proper WildoError for resource configuration errors.
+     * Uses the shared error builder (no circular dependency with FrontendResourceUtils).
+     */
+    buildConfigurationError(customMessageReference, context) {
+        const wildoError = sharedErrorBuilder.buildWildoError_Frontend(ErrorType.CONFIGURATION, { customMessageReference, context });
+        const error = new Error(customMessageReference);
+        error.wildoError = wildoError;
+        return error;
+    }
+    /**
+     * Initialize the resource registry.
+     *
+     * ALL backend resources are included in the registry, but only API_CALL and
+     * API_CALL_WITH_CALLBACK operation variants are retained — backend-only variants
+     * (CRON_JOB, BATCH_JOB, INTERNAL_CALL, REPOSITORY_ONLY) are excluded.
+     * The `resourceUIBehavior` overlays UI behavior (icons, sections, layouts, labels,
+     * operation surfaces) on resources it covers. Resources without a preset entry
+     * have no UI presence but remain API-callable.
+     */
+    async initializeResources(customShared_ResourcesConfigurationsFactoryMap, customShared_ResourceFieldIdentifier, customShared_ResourcesRelationships, excludedResourceTypes, resourceUIBehavior) {
+        if (this.isInitialized) {
+            return;
+        }
+        try {
+            const allResourceFieldIdentifiers = {
+                ...customShared_ResourceFieldIdentifier,
+                ...coreResourceShared_FieldIdentifier,
+            };
+            let allResourceRelationships = Resources_SharedUtils.ensureCompiledRelationships([
+                ...(customShared_ResourcesRelationships || []),
+                ...coreSharedResourceRelationship,
+            ]);
+            // Apply factory functions for custom shared resources configurations
+            const customShared_ResourcesConfigurations = {};
+            if (customShared_ResourcesConfigurationsFactoryMap && Object.keys(customShared_ResourcesConfigurationsFactoryMap).length > 0) {
+                Object.entries(customShared_ResourcesConfigurationsFactoryMap).forEach(([resourceType, factory]) => {
+                    if (factory && typeof factory === 'function') {
+                        customShared_ResourcesConfigurations[resourceType] = factory(allResourceRelationships);
+                    }
+                });
+            }
+            // Apply factory functions for core shared resources configurations
+            const coreShared_ResourcesConfigurations = {};
+            if (coreShared_ResourcesConfigurations_FactoryMap && Object.keys(coreShared_ResourcesConfigurations_FactoryMap).length > 0) {
+                Object.entries(coreShared_ResourcesConfigurations_FactoryMap).forEach(([resourceType, factory]) => {
+                    if (factory && typeof factory === 'function') {
+                        coreShared_ResourcesConfigurations[resourceType] = factory(allResourceRelationships);
+                    }
+                });
+            }
+            // Merge all resource configurations
+            let allResourceConfigurations = {
+                ...coreShared_ResourcesConfigurations,
+                ...customShared_ResourcesConfigurations,
+            };
+            // ── Resource Exclusion ─────────────────────────────────────────
+            // Generic mechanism: remove excluded resource types from all 3 layers
+            // (configurations, relationships, field identifiers).
+            // Used for billing-conditional resources when billing is disabled.
+            if (excludedResourceTypes && excludedResourceTypes.size > 0) {
+                // Layer 1: Remove excluded resource configurations
+                allResourceConfigurations = Object.fromEntries(Object.entries(allResourceConfigurations).filter(([resourceType]) => !excludedResourceTypes.has(resourceType)));
+                // Layer 2: Remove relationships that reference excluded types
+                allResourceRelationships = allResourceRelationships.filter((rel) => !excludedResourceTypes.has(rel.resourceType1) && !excludedResourceTypes.has(rel.resourceType2));
+                // Layer 3: Remove excluded field identifiers
+                for (const resourceType of excludedResourceTypes) {
+                    delete allResourceFieldIdentifiers[resourceType];
+                }
+            }
+            const frontendResourceConfigurations = this.buildFrontendResourceConfigurations(allResourceConfigurations, allResourceFieldIdentifiers, resourceUIBehavior);
+            reconcileGeneratedRelationshipBulkOperations(frontendResourceConfigurations, allResourceRelationships, allResourceFieldIdentifiers);
+            ResourcesConfigOperationsDtosBuilderUtils.rebuildResourceConfigurationsOperationDtos(frontendResourceConfigurations);
+            // Build reverse map: fieldIdentifier -> resourceType (e.g., userId -> USERS)
+            // Track shared field identifiers (multiple resource types using the same field id,
+            // e.g. USER_SELF and USERS both use "userId") so the FK collision check allows them.
+            const fieldIdentifierToResourceType = {};
+            const sharedFieldIdentifiers = new Map();
+            for (const [resourceType, fieldIdentifier] of Object.entries(allResourceFieldIdentifiers)) {
+                const existing = fieldIdentifierToResourceType[fieldIdentifier];
+                if (existing && existing !== resourceType) {
+                    if (!sharedFieldIdentifiers.has(fieldIdentifier)) {
+                        sharedFieldIdentifiers.set(fieldIdentifier, new Set([existing]));
+                    }
+                    sharedFieldIdentifiers.get(fieldIdentifier).add(resourceType);
+                }
+                fieldIdentifierToResourceType[fieldIdentifier] = resourceType;
+            }
+            // Enrich the map with explicit foreignKeyField entries from relationships.
+            // This enables FK resolution for non-default fields (e.g., assignedToUserId → USERS).
+            // Convention: resourceType1 = PARENT, foreignKeyField is on the CHILD pointing to PARENT.
+            // Multiple resources may declare the same foreignKeyField (e.g., createdByUserId) as
+            // long as they all participate in relationships with the same counterpart resource type.
+            const fkFieldCounterpart = {};
+            for (const rel of allResourceRelationships) {
+                if (rel.foreignKeyField) {
+                    const existingType = fieldIdentifierToResourceType[rel.foreignKeyField];
+                    if (existingType && existingType !== rel.resourceType1) {
+                        const sharedTypes = sharedFieldIdentifiers.get(rel.foreignKeyField);
+                        if (sharedTypes && sharedTypes.has(rel.resourceType1)) {
+                            continue;
+                        }
+                        const existingCounterpart = fkFieldCounterpart[rel.foreignKeyField];
+                        if (existingCounterpart && existingCounterpart === rel.resourceType2) {
+                            continue;
+                        }
+                        const collisionMessage = `[ResourcesRegistry] FK field "${rel.foreignKeyField}" maps to both ` +
+                            `"${existingType}" and "${rel.resourceType1}". ` +
+                            `Fix the relationship declarations or use distinct foreignKeyField names.`;
+                        console.error(collisionMessage);
+                        if (envLoader.isDevelopment()) {
+                            throw this.buildConfigurationError(ErrorCustomMessageReference.REGISTRY_FK_MAP_COLLISION, { existingType, newType: rel.resourceType1, foreignKeyField: rel.foreignKeyField });
+                        }
+                    }
+                    fieldIdentifierToResourceType[rel.foreignKeyField] = rel.resourceType1;
+                    fkFieldCounterpart[rel.foreignKeyField] = rel.resourceType2;
+                }
+            }
+            // Apply canonical priority for shared field identifiers.
+            // When multiple resource types share the same field identifier (e.g., userId
+            // is shared by USERS and USER_SELF), the canonical type is set here — not by
+            // relationship iteration order.
+            for (const [fieldId, canonicalType] of Object.entries(coreResourceShared_FieldIdentifierPriority)) {
+                if (sharedFieldIdentifiers.has(fieldId)) {
+                    fieldIdentifierToResourceType[fieldId] = canonicalType;
+                }
+            }
+            // Create the frontend registry
+            this.registry = {
+                allResourceFieldIdentifiers: allResourceFieldIdentifiers,
+                fieldIdentifierToResourceType: fieldIdentifierToResourceType,
+                notificationBadgeDefinitions: [],
+                additionalUserNotificationDefinitions: [],
+                resourceRelationships: allResourceRelationships,
+                resourceConfigurations: frontendResourceConfigurations,
+                subtreeMap: computeSubtreeMap(allResourceRelationships),
+            };
+            this.generateUrlsForApiCallOperations(frontendResourceConfigurations, allResourceFieldIdentifiers);
+            // Create the resources HTTP client with the initialized registry
+            this.resourcesHttpClient = new WildoBackendHttpClient_Resources(this.registry, {
+                baseURL: this.httpClient.getBaseURL(),
+                timeout: 30000,
+                enableNetworkQueue: true
+            });
+            // Validate that all FK fields in registered schemas can be resolved.
+            // This catches configuration errors early — before components try to render FK fields.
+            this.validateForeignKeyResolution(frontendResourceConfigurations, fieldIdentifierToResourceType);
+            this.isInitialized = true;
+        }
+        catch (error) {
+            // If it's already a WildoError (from buildConfigurationError), re-throw as-is
+            if (error?.wildoError) {
+                throw error;
+            }
+            throw this.buildConfigurationError(ErrorCustomMessageReference.CONFIGURATION, { message: `Failed to initialize frontend resources: ${error instanceof Error ? error.message : String(error)}` });
+        }
+    }
+    /**
+     * Build the frontend resource configurations from backend configs with preset overlay.
+     *
+     * The registry contains ALL backend resources, but only API_CALL and
+     * API_CALL_WITH_CALLBACK operation variants — backend-only variants (CRON_JOB,
+     * BATCH_JOB, INTERNAL_CALL, REPOSITORY_ONLY) are excluded. The preset is a UI
+     * addon that overlays frontend-specific config (icons, sections, layouts, labels,
+     * operation surface selectors, etc.) on top of backend structural data.
+     *
+     * Three operation categories result from this model:
+     * - **Addressable** — in preset with `isAddressable: true`, has a route/URL
+     * - **Non-addressable** — in preset with `isAddressable: false`, rendered in overlays
+     * - **API-only** — not in preset, `operationFrontendConfig: undefined`, no UI
+     */
+    buildFrontendResourceConfigurations(backendConfigurations, allResourceFieldIdentifiers, preset) {
+        const result = {};
+        // ── Step 1: Seed registry with all resources, retaining only frontend-callable operations.
+        // Backend-only variants (CRON_JOB, BATCH_JOB, INTERNAL_CALL, REPOSITORY_ONLY) are
+        // stripped here — they have no HTTP endpoint and no UI representation.
+        for (const [resourceType, backendConfig] of Object.entries(backendConfigurations)) {
+            result[resourceType] = {
+                ...backendConfig,
+                operations: (backendConfig.operations ?? [])
+                    .filter(op => op.variantType === ResourceOperationVariantType.API_CALL
+                    || op.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK)
+                    .map(op => ({
+                    ...op,
+                    operationFrontendConfig: undefined,
+                })),
+                frontendConfiguration: undefined,
+            };
+        }
+        // ── Step 2: Overlay preset (ResourceUIBehavior) onto seeded resources.
+        // Each preset entry provides resource-level config (icon, sections, labels)
+        // and per-operation frontend config (isAddressable, views, tabs).
+        if (preset) {
+            for (const [resourceType, presetConfig] of Object.entries(preset)) {
+                const entry = result[resourceType];
+                if (!entry) {
+                    console.warn(`[ResourcesRegistry] Frontend preset references resource "${resourceType}" ` +
+                        `which has no backend configuration. Skipping.`);
+                    continue;
+                }
+                const { views: presetViews, relationshipOverrides, compositeViews: authoredCompositeViews, executionViews: authoredExecutionViews, ...resourceLevelConfig } = presetConfig;
+                const frontendSchema = presetConfig[FRONTEND_SCHEMA_KEY];
+                // Schema bridge for z_clone — when `resourceUIBehavior()` attached a cloned
+                // schema (via FRONTEND_SCHEMA_KEY Symbol), replace mainSchema on the resource
+                // and rebuild auto-derived DTOs. This ensures frontend-specific decorator
+                // mutations (e.g., `.isHidden()`, `.enumUI()` on cloned fields) propagate
+                // to CREATE/UPDATE requestDto field schemas. Only DTOs that were auto-derived
+                // from the original mainSchema are rebuilt — custom DTOs are left unchanged.
+                if (frontendSchema && frontendSchema !== entry.mainSchema) {
+                    const oldMainSchema = entry.mainSchema;
+                    entry.mainSchema = frontendSchema;
+                    for (const op of entry.operations) {
+                        if (!op.requestDto)
+                            continue;
+                        // Resolve the effective operation — variants with resourceOperationLike
+                        // behave as their "like" operation for DTO derivation purposes
+                        const effectiveOp = op.resourceOperationLike
+                            ? String(op.resourceOperationLike)
+                            : String(op.operationIdentifier);
+                        if ((effectiveOp === CoreResourceOperation.CREATE || effectiveOp === CoreResourceOperation.UPDATE)
+                            && isDtoDerivedFromSchema(op.requestDto, oldMainSchema)) {
+                            op.requestDto = deriveRequestDto(effectiveOp, frontendSchema, undefined);
+                        }
+                    }
+                }
+                // Apply resource-level config (icon, sections, labels, field addons, etc.)
+                // `relationshipOverrides` is already destructured out — it's a build-time
+                // directive consumed below, not stored on frontendConfiguration.
+                const compiledCompositeViews = this.buildResourceCompositeViewDefinitions(entry.resourcePrimaryScope ?? ResourcePrimaryScope.ORGANIZATIONS, authoredCompositeViews);
+                const compiledExecutionViews = this.buildResourceExecutionViewDefinitions(entry.resourcePrimaryScope ?? ResourcePrimaryScope.ORGANIZATIONS, authoredExecutionViews);
+                entry.frontendConfiguration = {
+                    ...resourceLevelConfig,
+                    ...(compiledCompositeViews.length > 0 && {
+                        compositeViews: compiledCompositeViews,
+                    }),
+                    ...(compiledExecutionViews.length > 0 && {
+                        executionViews: compiledExecutionViews,
+                    }),
+                };
+                // Apply per-operation frontend config — matches preset views keys
+                // to registered API_CALL/API_CALL_WITH_CALLBACK operations
+                if (presetViews) {
+                    for (const [operationKey, opConfig] of presetViews) {
+                        const matchedOp = this.findOperationByPresetKey(entry.operations, operationKey);
+                        if (matchedOp) {
+                            matchedOp.operationFrontendConfig = opConfig;
+                        }
+                    }
+                }
+                // Apply relationship display overrides — clones affected relationships
+                // to avoid mutating shared references across resource buckets.
+                if (relationshipOverrides && relationshipOverrides.length > 0) {
+                    this.resolveRelationshipDisplayOverrides(resourceType, entry.resourceRelationships, relationshipOverrides, allResourceFieldIdentifiers);
+                }
+                this.registerResourceIcon(resourceType, presetConfig.icon);
+            }
+        }
+        // ── Step 3: Derive FK field display from relationship parentDisplay.
+        // For each resource's parentRelationships, set `foreignKeyUI.display`
+        // on the FK schema field based on the relationship's `inChildView.parentDisplay`.
+        // Only fills gaps — explicit `.foreignKeyUI()` on the schema field always wins.
+        for (const [resourceType, entry] of Object.entries(result)) {
+            this.deriveForeignKeyDisplayFromRelationships(resourceType, entry, allResourceFieldIdentifiers);
+        }
+        console.info(`[ResourcesRegistry] Frontend registry built: ` +
+            `${Object.keys(result).length} resource(s) total, ` +
+            `${preset ? Object.keys(preset).length : 0} with UI behavior.`);
+        return result;
+    }
+    /**
+     * Register a resource icon into `CoreIconRegistry.resources`.
+     *
+     * - `string` icon → look up from `CoreIconRegistry.standard` and register if found
+     * - React component → wrap as `IconConfig { icon: component }` and register directly
+     */
+    registerResourceIcon(resourceType, icon) {
+        if (!icon)
+            return;
+        if (typeof icon === 'string') {
+            const standardConfig = CoreIconRegistry.standard.get(icon);
+            if (standardConfig) {
+                CoreIconRegistry.resources?.set(resourceType, standardConfig);
+            }
+        }
+        else {
+            CoreIconRegistry.resources?.set(resourceType, { icon: icon });
+        }
+    }
+    buildResourceCompositeViewDefinitions(primaryScope, compositeViews) {
+        if (!compositeViews) {
+            return [];
+        }
+        return Object.entries(compositeViews).map(([ref, viewComponent]) => ({
+            ref,
+            scope: FrontendView_ScopeMode.RESOURCE,
+            isAddressable: true,
+            operationLike: CoreResourceOperation.READ,
+            primaryScope,
+            viewComponent,
+        }));
+    }
+    buildResourceExecutionViewDefinitions(primaryScope, executionViews) {
+        if (!executionViews) {
+            return [];
+        }
+        return Object.entries(executionViews).map(([ref, executionView]) => ({
+            ref,
+            scope: FrontendView_ScopeMode.RESOURCE,
+            isAddressable: executionView.isAddressable ?? true,
+            operationLike: executionView.operationLike ?? CoreResourceOperation.READ,
+            primaryScope: executionView.primaryScope ?? primaryScope,
+            parentResourcesRequirements: executionView.parentResourcesRequirements,
+            additionalResourceRequirements: executionView.additionalResourceRequirements,
+            anchor: executionView.anchor,
+            viewComponent: executionView.viewComponent,
+            requiredFeatures: executionView.requiredFeatures,
+        }));
+    }
+    /**
+     * Resolve relationship display overrides declared in the frontend preset.
+     *
+     * For each override entry, searches all three relationship buckets
+     * (`parentRelationships`, `childRelationships`, `selfRelationships`) for
+     * a match by target resource type (and optional FK field for disambiguation).
+     *
+     * **Shared reference safety**: Relationship objects are shared across different
+     * resources' buckets (e.g., the same `ResourceRelationship` appears in parent A's
+     * `childRelationships` and child B's `parentRelationships`). To prevent mutations
+     * from leaking, matched relationships are **cloned** before display overrides are applied.
+     */
+    resolveRelationshipDisplayOverrides(resourceType, relationships, overrides, allResourceFieldIdentifiers) {
+        for (const override of overrides) {
+            const candidates = [];
+            // Search childRelationships: current resource is parent, target is child
+            for (let i = 0; i < relationships.childRelationships.length; i++) {
+                const rel = relationships.childRelationships[i];
+                if (rel.resourceType2 === override.target) {
+                    candidates.push({ bucket: relationships.childRelationships, index: i, rel, bucketName: 'childRelationships' });
+                }
+            }
+            // Search parentRelationships: current resource is child, target is parent
+            for (let i = 0; i < relationships.parentRelationships.length; i++) {
+                const rel = relationships.parentRelationships[i];
+                if (rel.resourceType1 === override.target) {
+                    candidates.push({ bucket: relationships.parentRelationships, index: i, rel, bucketName: 'parentRelationships' });
+                }
+            }
+            // Search selfRelationships: both sides are the same type
+            for (let i = 0; i < relationships.selfRelationships.length; i++) {
+                const rel = relationships.selfRelationships[i];
+                if (rel.resourceType1 === override.target) {
+                    candidates.push({ bucket: relationships.selfRelationships, index: i, rel, bucketName: 'selfRelationships' });
+                }
+            }
+            // Narrow by foreignKeyField if provided
+            if (override.foreignKeyField && candidates.length > 0) {
+                const fkFiltered = candidates.filter(({ rel }) => {
+                    const resolvedFk = Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(rel, allResourceFieldIdentifiers)?.fieldIdentifier;
+                    return resolvedFk === override.foreignKeyField;
+                });
+                candidates.length = 0;
+                candidates.push(...fkFiltered);
+            }
+            // Outcome handling
+            if (candidates.length === 0) {
+                if (envLoader.isDevelopment()) {
+                    const availableRels = [
+                        ...relationships.childRelationships.map(r => `${r.resourceType2} (FK: ${Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(r, allResourceFieldIdentifiers)?.fieldIdentifier ?? 'unresolved'})`),
+                        ...relationships.parentRelationships.map(r => `${r.resourceType1} (FK: ${Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(r, allResourceFieldIdentifiers)?.fieldIdentifier ?? 'unresolved'})`),
+                        ...relationships.selfRelationships.map(r => `${r.resourceType1} (FK: ${Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(r, allResourceFieldIdentifiers)?.fieldIdentifier ?? 'unresolved'})`),
+                    ];
+                    console.warn(`[RelationshipDisplay] Resource "${resourceType}" has no relationship with "${override.target}"` +
+                        `${override.foreignKeyField ? ` (FK: ${override.foreignKeyField})` : ''}. ` +
+                        `Available relationships: [${availableRels.join(', ')}]. Override ignored.`);
+                }
+                continue;
+            }
+            if (candidates.length > 1 && !override.foreignKeyField) {
+                if (envLoader.isDevelopment()) {
+                    const fkFields = candidates.map(({ rel }) => Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(rel, allResourceFieldIdentifiers)?.fieldIdentifier ?? 'unresolved');
+                    console.warn(`[RelationshipDisplay] Resource "${resourceType}" has ${candidates.length} relationships ` +
+                        `with "${override.target}" (FK fields: [${fkFields.join(', ')}]). ` +
+                        `Provide foreignKeyField to disambiguate. Override ignored.`);
+                }
+                continue;
+            }
+            if (candidates.length > 1 && override.foreignKeyField) {
+                if (envLoader.isDevelopment()) {
+                    console.warn(`[RelationshipDisplay] Resource "${resourceType}" has ${candidates.length} relationships ` +
+                        `with "${override.target}" even after FK field "${override.foreignKeyField}" filtering. ` +
+                        `Applying to first match.`);
+                }
+            }
+            // Apply override to the first (or only) match — clone to avoid shared reference mutation
+            const { bucket, index, rel } = candidates[0];
+            const cloned = {
+                ...rel,
+                display: rel.display ? { ...rel.display } : undefined,
+            };
+            if (override.inParentView) {
+                cloned.display = {
+                    ...cloned.display,
+                    inParentView: { ...cloned.display?.inParentView, ...override.inParentView },
+                };
+            }
+            if (override.inParentNavigation) {
+                cloned.display = {
+                    ...cloned.display,
+                    inParentNavigation: { ...cloned.display?.inParentNavigation, ...override.inParentNavigation },
+                };
+            }
+            if (override.inChildView) {
+                cloned.display = {
+                    ...cloned.display,
+                    inChildView: { ...cloned.display?.inChildView, ...override.inChildView },
+                };
+            }
+            if (cloned.display) {
+                cloned.display = RelationshipDisplayConfigSchema.parse(cloned.display);
+            }
+            bucket[index] = cloned;
+        }
+    }
+    /**
+     * Derive FK field display config from parent relationship declarations.
+     *
+     * For each `parentRelationship` on a resource, identifies the FK schema field
+     * and sets `foreignKeyUI.display` metadata based on the relationship's
+     * `inChildView.parentDisplay` value.
+     *
+     * Derivation rules (DD-2):
+     * | parentDisplay    | FK mode   | FK linkable | Rationale                            |
+     * |------------------|-----------|-------------|--------------------------------------|
+     * | CONTEXT (default)| LABEL     | true        | Context header handles nav; FK = link|
+     * | BREADCRUMB       | LABEL     | false       | Breadcrumb handles nav; FK = text    |
+     * | BADGE            | LABEL     | false       | Badge handles nav; FK = text         |
+     * | SUMMARY          | SUMMARY   | true        | Both FK and structural show summary  |
+     * | NONE             | ID        | false       | No parent reference; FK = raw ID     |
+     *
+     * **Override priority**: Explicit `.foreignKeyUI()` on the schema field always wins.
+     * The derivation only sets metadata when no `FOREIGN_KEY_UI` decorator exists.
+     */
+    deriveForeignKeyDisplayFromRelationships(resourceType, entry, allResourceFieldIdentifiers) {
+        const { parentRelationships, selfRelationships } = entry.resourceRelationships;
+        // Process both parentRelationships and selfRelationships (self-refs have parent direction too)
+        const allParentRels = [...parentRelationships, ...selfRelationships];
+        for (const rel of allParentRels) {
+            // Self-references without explicit foreignKeyField would resolve to the
+            // resource's own field identifier (= the PK), not the self-referencing FK.
+            if (rel.resourceType1 === rel.resourceType2 && !rel.foreignKeyField) {
+                continue;
+            }
+            // Determine the FK field name for this relationship
+            const fkFieldName = Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(rel, allResourceFieldIdentifiers)?.fieldIdentifier;
+            if (!fkFieldName)
+                continue;
+            // Find the FK field in the schema
+            const shape = getZodObjectShape(entry.mainSchema);
+            if (!shape)
+                continue;
+            const fieldSchema = shape[fkFieldName];
+            if (!fieldSchema || !isForeignKeyField(fieldSchema))
+                continue;
+            // Check if explicit .foreignKeyUI() is already set — explicit wins.
+            // getCustomFieldMetadata traverses wrapper types (optional, nullable, etc.)
+            // so it correctly finds metadata on the inner schema.
+            const existingMetadata = getCustomFieldMetadata(fieldSchema);
+            if (existingMetadata[ZodDecorator.FOREIGN_KEY_UI] !== undefined)
+                continue;
+            // Derive from parentDisplay (after override merge from Phase 1)
+            const parentDisplay = rel.display?.inChildView?.parentDisplay ?? ParentDisplay.CONTEXT;
+            let derivedMode;
+            let derivedLinkable;
+            switch (parentDisplay) {
+                case ParentDisplay.CONTEXT:
+                    derivedMode = ForeignKeyDisplayMode.LABEL;
+                    derivedLinkable = true;
+                    break;
+                case ParentDisplay.BREADCRUMB:
+                    derivedMode = ForeignKeyDisplayMode.LABEL;
+                    derivedLinkable = false;
+                    break;
+                case ParentDisplay.BADGE:
+                    derivedMode = ForeignKeyDisplayMode.LABEL;
+                    derivedLinkable = false;
+                    break;
+                case ParentDisplay.SUMMARY:
+                    derivedMode = ForeignKeyDisplayMode.SUMMARY;
+                    derivedLinkable = true;
+                    break;
+                case ParentDisplay.NONE:
+                    derivedMode = ForeignKeyDisplayMode.ID;
+                    derivedLinkable = false;
+                    break;
+                default:
+                    derivedMode = ForeignKeyDisplayMode.LABEL;
+                    derivedLinkable = true;
+                    break;
+            }
+            // Set FOREIGN_KEY_UI metadata on the schema field
+            const derivedConfig = {
+                display: {
+                    mode: derivedMode,
+                    linkable: derivedLinkable,
+                },
+            };
+            // Write to the unwrapped inner schema to avoid shadowing existing decorators
+            // on wrapper types (optional, nullable, etc.). addDecorators handles merge.
+            const innerSchema = unwrapSchema(fieldSchema);
+            addDecorators(innerSchema, [{ ref: ZodDecorator.FOREIGN_KEY_UI, params: derivedConfig }]);
+        }
+    }
+    /**
+     * Find an operation in the registry that matches a preset `OperationKey`.
+     *
+     * The `operations` array only contains API_CALL / API_CALL_WITH_CALLBACK variants
+     * (filtered in `buildFrontendResourceConfigurations` step 1), so this method is
+     * guaranteed to only match frontend-callable operations.
+     *
+     * Matching rules:
+     * - `string` key → default operation (`isOperationDefault === true` or no `variantKey`),
+     *   preferring non-bulk operations when multiple defaults exist.
+     * - `[string, string]` tuple → variant operation (`variantKey === key[1]`).
+     */
+    findOperationByPresetKey(operations, key) {
+        if (Array.isArray(key)) {
+            const [opId, variantKey] = key;
+            return operations.find((op) => op.operationIdentifier === opId && op.variantKey === variantKey);
+        }
+        // String key — match default/primary operation
+        const candidates = operations.filter((op) => op.operationIdentifier === key && (op.isOperationDefault || !op.variantKey));
+        if (candidates.length === 0)
+            return undefined;
+        if (candidates.length === 1)
+            return candidates[0];
+        // Prefer non-bulk when multiple defaults exist
+        return candidates.find((op) => !op.isBulkOperation) ?? candidates[0];
+    }
+    /**
+     * Generate URLs for API_CALL and API_CALL_WITH_CALLBACK operations.
+     *
+     * Populates `initiatorInfos` on each operation with the computed URL path,
+     * HTTP verb, and path parameters. Called after the registry is seeded but
+     * before the HTTP client is constructed (the client reads URLs from operations).
+     */
+    generateUrlsForApiCallOperations(allResourceConfigurations, allResourceFieldIdentifiers) {
+        for (const [resourceType, resourceConfig] of Object.entries(allResourceConfigurations)) {
+            try {
+                ResourcesConfigOperationsUrlsBuilderUtils.updateOperationUrls(resourceConfig, allResourceFieldIdentifiers);
+            }
+            catch (error) {
+                console.error(`Failed to generate URLs for resource type ${resourceType}:`, error);
+            }
+        }
+    }
+    /**
+     * Get the full registry
+     */
+    getResourcesRegistry() {
+        if (!this.isInitialized) {
+            throw this.buildConfigurationError(ErrorCustomMessageReference.FRONTEND_RESOURCES_NOT_INITIALIZED, { method: 'getResourcesRegistry' });
+        }
+        return this.registry;
+    }
+    /**
+     * Get available resource types (used for initialization logging)
+     */
+    getAvailableResourceTypes() {
+        if (!this.isInitialized) {
+            return [];
+        }
+        return Object.keys(this.registry.resourceConfigurations);
+    }
+    /**
+     * Get registry information for debugging
+     */
+    getRegistryInfo() {
+        if (!this.isInitialized) {
+            return { registeredResourceTypes: [] };
+        }
+        return {
+            registeredResourceTypes: Object.keys(this.registry.resourceConfigurations),
+        };
+    }
+    /**
+     * Get the resources HTTP client for operation execution
+     * This should only be called through ResourceRepositoryContext
+     */
+    getResourcesHttpClient() {
+        if (!this.isInitialized || !this.resourcesHttpClient) {
+            throw this.buildConfigurationError(ErrorCustomMessageReference.FRONTEND_RESOURCES_NOT_INITIALIZED, { method: 'getResourcesHttpClient' });
+        }
+        return this.resourcesHttpClient;
+    }
+    /**
+     * Validate that all isForeignKey() fields in registered schemas can be resolved
+     * to a resource type via the fieldIdentifierToResourceType map (enriched from relationships).
+     *
+     * In development: throws if unresolvable FK fields are found (fail fast).
+     * In production: logs error for monitoring; individual failures surface at point of use.
+     */
+    validateForeignKeyResolution(resourceConfigurations, fieldIdentifierToResourceType) {
+        const unresolvedFKFields = [];
+        for (const [resourceType, config] of Object.entries(resourceConfigurations)) {
+            const shape = getZodObjectShape(config.mainSchema);
+            if (!shape)
+                continue;
+            for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+                const typedSchema = fieldSchema;
+                if (!isForeignKeyField(typedSchema))
+                    continue;
+                const resolved = fieldIdentifierToResourceType[fieldName];
+                if (!resolved) {
+                    unresolvedFKFields.push({ resourceType, fieldName });
+                }
+            }
+        }
+        if (unresolvedFKFields.length > 0) {
+            const details = unresolvedFKFields
+                .map(({ resourceType, fieldName }) => `  - ${resourceType}.${fieldName}`)
+                .join('\n');
+            const message = `[ResourcesRegistry] ${unresolvedFKFields.length} FK field(s) cannot be resolved to a resource type:\n` +
+                `${details}\n` +
+                `Fix: Declare a relationship with the corresponding foreignKeyField.`;
+            // Log error with full context in all environments
+            console.error(message);
+            // In development: throw to fail fast and surface the issue immediately
+            if (envLoader.isDevelopment()) {
+                throw this.buildConfigurationError(ErrorCustomMessageReference.FRONTEND_FK_RESOLUTION_FAILED, { unresolvedFKFields, message });
+            }
+            // In production: error is logged above. Individual component failures will
+            // throw at point of use via resolveResourceTypeForForeignKey().
+        }
+    }
+}
+//# sourceMappingURL=resources-repository.frontend.service.js.map