@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

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

@@ -7,17 +7,19 @@
  * 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
+ * 6. URL generation — `initiatorInfos` populated on URL-bearing 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 { listResourceOwnedViewReferences, } from '../../core/config/resource-owned-view-resolution.frontend.utils.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 { FRONTEND_SCHEMA_KEY, } from '../../core/resources/resources.frontend.schemas.js';
+import { ENGINE_RUNTIME_REQUIRED_RESOURCE_TYPES, ResourcePrimaryScope, coreShared_ResourcesConfigurations_FactoryMap, coreSharedResourceRelationship, coreResourceShared_FieldIdentifier, coreResourceShared_FieldIdentifierPriority, ResourceOperationVariantType, ResourceOperationFrontendSurface, ResourcesConfigOperationsUrlsBuilderUtils, ResourcesConfigOperationsDtosBuilderUtils, ErrorType, ErrorCustomMessageReference, computeSubtreeMap, CoreResourceOperation, deriveRequestDto, ParentDisplay, RelationshipDisplayConfigSchema, reconcileGeneratedRelationshipBulkOperations, Resources_SharedUtils, ResourceRelationshipAccessScopeStrategy, coreNotificationBadgeDefinitions, findDuplicateRelationshipRegistrations, } from '@wildo-ai/saas-models';
+import { buildResourceCompositeViewTranslationRef, } from '../../core/config/composite-view.schemas.js';
+import { getZodObjectShape, isForeignKeyField, unwrapSchema, getCustomFieldMetadata, addDecorators, ZodDecorator, ForeignKeyDisplayMode, SCHEMA_METADATA, getFileMetadata, getFieldUIDisplayConfig, declaredFileNatureCanDisplay, FileDisplayPresentation, FileActivationPolicy } from '@wildo-ai/zod-decorators';
 import { sharedErrorBuilder } from '../../core/errors/errors-builder.frontend.services.js';
+import { AutomatedLayoutFrontendUtils } from '../../core/automated-layout/automated-layout.frontend.utils.js';
 /**
  * Checks whether a requestDto was auto-derived from mainSchema by comparing
  * field object references. CREATE DTOs use direct field refs; UPDATE DTOs
@@ -40,6 +42,108 @@ function isDtoDerivedFromSchema(requestDto, mainSchema) {
         return false;
     }
 }
+/**
+ * Re-establishes the per-field UI-behavior `fields` decorators on an auto-derived
+ * operation DTO — both the **display** DTOs (`responseDto` / `summaryDto` / `contextDto`)
+ * and the **request** DTO (`requestDto`, the edit-form input schema) — after
+ * `frontendSchema` replaces `mainSchema`.
+ *
+ * ## Why this exists — the reference-severance trap
+ *
+ * Resource UI-behavior `fields` (e.g. `sh.status.enumUI(...)`, `sh.checklist.arrayUI(...)`)
+ * are applied by **mutating the shared schema shape field's metadata in place** at
+ * module-evaluation time (see `resourceUIBehavior` → `applySingleDecorator`, which writes
+ * back to `field[SCHEMA_METADATA]`). `frontendSchema` (attached via `FRONTEND_SCHEMA_KEY`)
+ * therefore carries every `fields` decorator on its shape.
+ *
+ * Every operation DTO the frontend reads, however — the READ/LIST **display** schema
+ * (`operation.responseDto` / `summaryDto` / `contextDto`) AND the edit-form input schema
+ * (`operation.requestDto`) — is re-derived by the DTO builder, applying transforms (date
+ * coercion, backend-only stripping, nested-children; and for `requestDto`, create/update
+ * field pruning + `.optional()` PATCH wrapping) that **re-wrap** optional / array /
+ * compound fields into fresh instances. A `fields` decorator only reached the DTO when the
+ * DTO field happened to be the *same object reference* as the schema field — true for bare
+ * non-optional scalars (e.g. `title`), false for any re-wrapped field (an OPTIONAL
+ * `checklist` array, an optional/defaulted enum, …). That accidental reference-sharing
+ * channel is fragile and silently dropped decorators on exactly the fields that depend on
+ * them (inline-editable arrays, optional enum badges).
+ *
+ * The `requestDto` is NOT exempt: array fields are always rebuilt into a fresh `z.array(…)`
+ * (`stripTemplatableFileFieldsRecursively` — the array branch has no "unchanged element →
+ * keep instance" guard, unlike record/map/set), so an `arrayUI({ objectItemLayout })` on
+ * the edit-form `checklist` was severed and the form fell back to the CARD item layout
+ * while the overlaid READ view rendered ROW. Hence this overlay runs over `requestDto` too.
+ * See `.claude/plans/array-element-authoring.md` Step 4.
+ *
+ * ## What it does
+ *
+ * For each field the DTO shares (by name) with `frontendSchema`, it syncs the DTO field's
+ * decorator metadata to the authoritative post-`fields` schema field. UI decorators are
+ * **pure metadata** (no Zod refinement), so the DTO's *parse* contract is unaffected —
+ * for `responseDto`/`contextDto` (which validate incoming HTTP responses) date coercion,
+ * backend-only absence and nested children all remain intact; for `requestDto` (which
+ * validates edit-form input before submit) the create/update pruning and PATCH optionality
+ * are equally untouched. Only symbol-keyed `[SCHEMA_METADATA]` is written.
+ *
+ * ## Discriminated-union DTOs
+ *
+ * Field resolution uses `getObjectLikeFieldShape` — the SAME resolver `getFieldSchema`
+ * (and therefore `DisplayField`) uses — so it walks **discriminated-union** DTOs. The
+ * default READ DTO of a polymorphic resource (e.g. todos, whose `recurringType` is a
+ * `.isDiscriminator()`) is a `ZodDiscriminatedUnion`, for which the object-only
+ * `getZodObjectShape` returns nothing — the original cause of this overlay silently
+ * skipping the very resources that need it. The union merge keeps field instances by
+ * reference, so mutating the resolved field's metadata is exactly what the display reads.
+ *
+ * Eligibility (auto-derived vs custom author-owned) is decided by the CALLER via the
+ * operation's `hasCustomResponseDto` / `hasCustomRequestDto` flags — NOT by
+ * `isDtoDerivedFromSchema`, which is both union-blind and unreliable once the DTO builder
+ * clones field instances.
+ *
+ * Per-field guards retained here:
+ * - Fields with no resource-schema counterpart are skipped.
+ * - Fields whose DTO instance IS the decorated schema instance are skipped (already correct).
+ * - Only fields whose authoritative metadata actually differs are written.
+ *
+ * @param dto - The operation DTO to overlay (no-op when undefined / not object-like).
+ * @param frontendSchema - The `FRONTEND_SCHEMA_KEY` schema carrying `fields` decorators.
+ */
+function overlayUiBehaviorFieldDecorators(dto, frontendSchema) {
+    if (!dto)
+        return;
+    // Union-aware shape resolution — identical to `getFieldSchema`'s, so the field instances
+    // we mutate are the very ones the display reads back (the union merge keeps references).
+    // Returns undefined for non-object-like schemas (e.g. a `{ data, pagination }` LIST wrapper
+    // exposes only `data`/`pagination`, which never match resource field names anyway).
+    const dtoShape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(dto, { commonOnly: false });
+    const frontendShape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(frontendSchema, { commonOnly: false });
+    if (!dtoShape || !frontendShape)
+        return;
+    for (const [fieldName, dtoField] of Object.entries(dtoShape)) {
+        const frontendField = frontendShape[fieldName];
+        // Skip fields with no resource-schema counterpart, and the bare-scalar case where the
+        // DTO field IS the decorated schema instance (decorators already present, nothing to do).
+        if (!frontendField || !dtoField || dtoField === frontendField)
+            continue;
+        const frontendMeta = getCustomFieldMetadata(frontendField);
+        if (Object.keys(frontendMeta).length === 0)
+            continue;
+        const dtoMeta = getCustomFieldMetadata(dtoField);
+        // `frontendSchema` is the authoritative post-`fields` truth for every field of an
+        // auto-derived DTO. Sync when the DTO field is missing a decorator key OR carries a
+        // stale value for one (a re-wrapped clone made before the in-place `fields` mutation).
+        const needsSync = Object.keys(frontendMeta).some((key) => !(key in dtoMeta) || dtoMeta[key] !== frontendMeta[key]);
+        if (!needsSync)
+            continue;
+        // Write the merged metadata onto the DTO field's read node. `getCustomFieldMetadata`
+        // traverses wrappers, so seeding with `dtoMeta` (the DTO field's current effective
+        // metadata) preserves anything the DTO build placed on a deeper node; the
+        // frontendSchema field wins on overlap. Values are read-only display config shared
+        // within the single owning resource — no deep clone required.
+        // `as any` for the symbol-keyed metadata write — same idiom as `applySingleDecorator`.
+        dtoField[SCHEMA_METADATA] = { ...dtoMeta, ...frontendMeta };
+    }
+}
 export class ResourcesRepositoryFrontendService {
     httpClient;
     registry = null;
@@ -68,7 +172,7 @@ export class ResourcesRepositoryFrontendService {
      * 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) {
+    async initializeResources(customShared_ResourcesConfigurationsFactoryMap, customShared_ResourceFieldIdentifier, customShared_ResourcesRelationships, excludedResourceTypes, resourceUIBehavior, customNotificationBadgeDefinitions) {
         if (this.isInitialized) {
             return;
         }
@@ -77,10 +181,41 @@ export class ResourcesRepositoryFrontendService {
                 ...customShared_ResourceFieldIdentifier,
                 ...coreResourceShared_FieldIdentifier,
             };
-            let allResourceRelationships = Resources_SharedUtils.ensureCompiledRelationships([
+            const assembledResourceRelationships = [
                 ...(customShared_ResourcesRelationships || []),
                 ...coreSharedResourceRelationship,
-            ]);
+            ];
+            // ── DUPLICATE-EDGE GUARD (fail-closed, mirrors the backend registry) ─────
+            //
+            // This registry has only TWO sources, so it cannot reproduce the backend's
+            // "same list through two slots" fold. It CAN still receive an intra-list
+            // duplicate, because the app's shared relationship list is itself a
+            // `modules.flatMap(...)` — a module registered twice, or two modules
+            // declaring the same edge, lands the edge twice here. The frontend and
+            // backend module registries are authored independently, so a frontend-only
+            // duplicate is reachable.
+            //
+            // The frontend is where several of the non-benign consequences live: form
+            // semantics throw in development (and silently lose the field in
+            // production) on duplicate relationship-object field identity, quick-create
+            // affordances and PARENT_CONTEXT_SINGLETON / complete-association addressing
+            // modes are dropped by ambiguity checks, and a nested child section renders
+            // twice with a duplicated React key. Fail closed at assembly instead, where
+            // the message can name the edge.
+            //
+            // Checked pre-compilation on the AUTHORED declarations, for the same reason
+            // the backend does: `ensureCompiledRelationships` may preserve pre-resolved
+            // semantics on one copy and recompile the other.
+            const duplicateRelationshipRegistrations = findDuplicateRelationshipRegistrations(assembledResourceRelationships);
+            if (duplicateRelationshipRegistrations.length > 0) {
+                throw this.buildConfigurationError(ErrorCustomMessageReference.CONFIGURATION, {
+                    message: `${duplicateRelationshipRegistrations.length} relationship edge(s) registered more than once:\n` +
+                        duplicateRelationshipRegistrations.map((duplicate) => `  • ${duplicate.message}`)
+                            .join('\n'),
+                    duplicatedEdges: duplicateRelationshipRegistrations.map((duplicate) => `${String(duplicate.parentResourceType)} → ${String(duplicate.childResourceType)} (×${duplicate.occurrences})`),
+                });
+            }
+            let allResourceRelationships = Resources_SharedUtils.ensureCompiledRelationships.call(Resources_SharedUtils, assembledResourceRelationships, allResourceFieldIdentifiers);
             // Apply factory functions for custom shared resources configurations
             const customShared_ResourcesConfigurations = {};
             if (customShared_ResourcesConfigurationsFactoryMap && Object.keys(customShared_ResourcesConfigurationsFactoryMap).length > 0) {
@@ -108,78 +243,76 @@ export class ResourcesRepositoryFrontendService {
             // 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) {
+            //
+            // The engine's own runtime floor is subtracted first and REFUSED loudly: see
+            // `ENGINE_RUNTIME_REQUIRED_RESOURCE_TYPES` for why honouring such an exclusion breaks
+            // authentication rather than a feature. Refusing here — at the one place exclusion is applied
+            // — is what makes the floor unbypassable, instead of a rule each application must remember.
+            const refusedExclusions = [...(excludedResourceTypes ?? [])].filter((resourceType) => ENGINE_RUNTIME_REQUIRED_RESOURCE_TYPES.has(resourceType));
+            if (refusedExclusions.length > 0) {
+                console.warn(`[ResourcesRepository] Refusing to exclude ${refusedExclusions.join(', ')}: the engine's own `
+                    + 'runtime reads these to restore an authenticated session, so honouring the exclusion would make '
+                    + 'login succeed and then immediately bounce back to the login form. They stay registered.');
+            }
+            const effectiveExcludedResourceTypes = refusedExclusions.length > 0
+                ? new Set([...(excludedResourceTypes ?? [])].filter((resourceType) => !ENGINE_RUNTIME_REQUIRED_RESOURCE_TYPES.has(resourceType)))
+                : excludedResourceTypes;
+            if (effectiveExcludedResourceTypes && effectiveExcludedResourceTypes.size > 0) {
                 // Layer 1: Remove excluded resource configurations
-                allResourceConfigurations = Object.fromEntries(Object.entries(allResourceConfigurations).filter(([resourceType]) => !excludedResourceTypes.has(resourceType)));
+                allResourceConfigurations = Object.fromEntries(Object.entries(allResourceConfigurations).filter(([resourceType]) => !effectiveExcludedResourceTypes.has(resourceType)));
                 // Layer 2: Remove relationships that reference excluded types
-                allResourceRelationships = allResourceRelationships.filter((rel) => !excludedResourceTypes.has(rel.resourceType1) && !excludedResourceTypes.has(rel.resourceType2));
+                allResourceRelationships = allResourceRelationships.filter((rel) => !effectiveExcludedResourceTypes.has(rel.resourceType1) && !effectiveExcludedResourceTypes.has(rel.resourceType2));
                 // Layer 3: Remove excluded field identifiers
-                for (const resourceType of excludedResourceTypes) {
+                for (const resourceType of effectiveExcludedResourceTypes) {
                     delete allResourceFieldIdentifiers[resourceType];
                 }
             }
+            this.normalizeResourceConfigurationRelationships(allResourceConfigurations, allResourceFieldIdentifiers);
             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;
-                }
-            }
+            // Re-apply ui-behavior `fields` decorators onto the freshly-rebuilt operation DTOs.
+            // The rebuild above re-derives every DTO from each resource's (decorated) mainSchema
+            // but re-wraps optional/array/compound fields into fresh instances — severing the
+            // in-place `fields` metadata for exactly those fields (an OPTIONAL inline-editable
+            // `checklist` array, an optional/defaulted enum badge, …). This restores them on every
+            // DTO the frontend reads: the DISPLAY DTOs (responseDto/summaryDto/contextDto) the
+            // read/list views resolve `ctx.schema` from, AND the edit-form requestDto (so
+            // `objectItemLayout` and other array `fields` survive on the UPDATE/CREATE form).
+            // MUST run after the rebuild, or it is silently discarded. See
+            // `overlayUiBehaviorFieldDecorators` for the rationale.
+            this.overlayUiBehaviorDtoDecorators(frontendResourceConfigurations, resourceUIBehavior);
+            // Reverse map fieldIdentifier → REFERENCED resourceType — built by THE shared
+            // implementation (Resources_SharedUtils.buildFieldIdentifierToResourceTypeMap).
+            // This repository and the backend registry service used to carry hand-kept
+            // copies of this logic; a semantic change to FK resolution now lands once.
+            const fieldIdentifierToResourceType = Resources_SharedUtils.buildFieldIdentifierToResourceTypeMap({
+                allResourceFieldIdentifiers,
+                allResourceRelationships,
+                getMainSchema: (resourceType) => frontendResourceConfigurations[resourceType]?.mainSchema,
+                fieldIdentifierPriority: coreResourceShared_FieldIdentifierPriority,
+                onForeignKeyCollision: ({ foreignKeyField, existingType, referencedResourceType }) => {
+                    console.error(`[ResourcesRegistry] FK field "${foreignKeyField}" is reused by different holders ` +
+                        `referencing "${existingType}" and "${referencedResourceType}". ` +
+                        `Keeping "${existingType}". Use distinct foreignKeyField names to disambiguate.`);
+                },
+            });
+            // Derive the scope-required reference-search junctions (e.g. (users ←
+            // organizations) via organizationMembers) — mirrors the backend registry
+            // so the picker scopes its searches exactly how the backend filters +
+            // authorizes them.
+            const manyToManyScopeJunctions = Resources_SharedUtils.buildManyToManyScopeJunctionMap(allResourceRelationships, allResourceFieldIdentifiers);
             // Create the frontend registry
             this.registry = {
                 allResourceFieldIdentifiers: allResourceFieldIdentifiers,
                 fieldIdentifierToResourceType: fieldIdentifierToResourceType,
-                notificationBadgeDefinitions: [],
+                manyToManyScopeJunctions,
+                // Framework-shipped badge definitions ∪ app-custom (threaded from the
+                // frontend bootstrap's ApplicationInitializationConfig, R8).
+                notificationBadgeDefinitions: [
+                    ...coreNotificationBadgeDefinitions,
+                    ...(customNotificationBadgeDefinitions ?? []),
+                ],
                 additionalUserNotificationDefinitions: [],
                 resourceRelationships: allResourceRelationships,
                 resourceConfigurations: frontendResourceConfigurations,
@@ -195,6 +328,8 @@ export class ResourcesRepositoryFrontendService {
             // 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.validateResourceOwnedViewRefUniqueness(frontendResourceConfigurations);
+            this.validateFileDisplayPolicyCoherence(frontendResourceConfigurations);
             this.isInitialized = true;
         }
         catch (error) {
@@ -205,6 +340,63 @@ export class ResourcesRepositoryFrontendService {
             throw this.buildConfigurationError(ErrorCustomMessageReference.CONFIGURATION, { message: `Failed to initialize frontend resources: ${error instanceof Error ? error.message : String(error)}` });
         }
     }
+    normalizeResourceConfigurationRelationships(allResourceConfigurations, allResourceFieldIdentifiers) {
+        for (const resourceConfig of Object.values(allResourceConfigurations)) {
+            resourceConfig.resourceRelationships = {
+                parentRelationships: Resources_SharedUtils.ensureCompiledRelationships.call(Resources_SharedUtils, resourceConfig.resourceRelationships.parentRelationships, allResourceFieldIdentifiers),
+                childRelationships: Resources_SharedUtils.ensureCompiledRelationships.call(Resources_SharedUtils, resourceConfig.resourceRelationships.childRelationships, allResourceFieldIdentifiers),
+                selfRelationships: Resources_SharedUtils.ensureCompiledRelationships.call(Resources_SharedUtils, resourceConfig.resourceRelationships.selfRelationships, allResourceFieldIdentifiers),
+            };
+        }
+    }
+    /**
+     * Re-applies ui-behavior `fields` decorators onto the rebuilt operation DTOs the frontend
+     * reads — both the DISPLAY DTOs (`responseDto` / `summaryDto` / `contextDto`) and the
+     * edit-form REQUEST DTO (`requestDto`).
+     *
+     * MUST run AFTER `rebuildResourceConfigurationsOperationDtos`: that rebuild's
+     * `buildAllOperationDtos` pass re-derives every DTO from each resource's (decorated)
+     * mainSchema, producing fresh field instances that lose the in-place `fields` metadata on
+     * every re-wrapped (optional / array / compound) field. Running the overlay inside
+     * `buildFrontendResourceConfigurations` would be silently discarded by that rebuild.
+     *
+     * Scoped to resources that declared a ui-behavior preset (every preset entry carries the
+     * `FRONTEND_SCHEMA_KEY` decorated schema). The response/context overlay is gated by the
+     * operation's `hasCustomResponseDto` flag and the request overlay by `hasCustomRequestDto`,
+     * so author-owned custom DTOs are untouched. `summaryDto` is always a framework projection
+     * of the resource schema.
+     *
+     * The `requestDto` leg matters because an `arrayUI({ objectItemLayout })` (and every other
+     * array/compound `fields` decorator) is severed by the array-rebuild in the DTO builder;
+     * without this leg the edit form loses ROW item layout and falls back to CARD while the
+     * overlaid READ view renders ROW — an inconsistency between the two surfaces of the SAME
+     * field. See `overlayUiBehaviorFieldDecorators` for per-field mechanics and parse-safety.
+     */
+    overlayUiBehaviorDtoDecorators(resourceConfigurations, preset) {
+        if (!preset)
+            return;
+        for (const [resourceType, presetConfig] of Object.entries(preset)) {
+            const frontendSchema = presetConfig[FRONTEND_SCHEMA_KEY];
+            if (!frontendSchema)
+                continue;
+            const entry = resourceConfigurations[resourceType];
+            if (!entry?.operations)
+                continue;
+            for (const op of entry.operations) {
+                if (!op.hasCustomResponseDto) {
+                    overlayUiBehaviorFieldDecorators(op.responseDto, frontendSchema);
+                    overlayUiBehaviorFieldDecorators(op.contextDto, frontendSchema);
+                }
+                // The edit form (`ResourceAutomatedForm`) resolves its field schemas from
+                // `requestDto`; the create/update DTO builder rebuilt its array/compound fields
+                // fresh, so restore the `fields` decorators here for auto-derived request DTOs.
+                if (!op.hasCustomRequestDto) {
+                    overlayUiBehaviorFieldDecorators(op.requestDto, frontendSchema);
+                }
+                overlayUiBehaviorFieldDecorators(op.summaryDto, frontendSchema);
+            }
+        }
+    }
     /**
      * Build the frontend resource configurations from backend configs with preset overlay.
      *
@@ -214,10 +406,15 @@ export class ResourcesRepositoryFrontendService {
      * 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
+     * Every operation ends the build with an explicit frontend SURFACE
+     * (`ResourceOperationFrontendSurface`) on its `operationFrontendConfig` — see
+     * Step 2.5:
+     * - **ADDRESSABLE** — preset `addressable()`; has a route/URL + action button
+     * - **EMBEDDED** — preset `notAddressable()`; non-addressable view rendered within a host (overlay/composite/nested)
+     * - **API_ONLY** — preset `apiOnly()`, the operation's `defaultFrontendPosture`,
+     *   or the default for any operation no preset surfaces; headless (callable via
+     *   httpClient, no UI). Read the surface via `isOperationAddressable()` /
+     *   `isOperationHeadless()`, never by config presence.
      */
     buildFrontendResourceConfigurations(backendConfigurations, allResourceFieldIdentifiers, preset) {
         const result = {};
@@ -239,7 +436,7 @@ export class ResourcesRepositoryFrontendService {
         }
         // ── 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).
+        // and per-operation frontend config (surface, views, tabs).
         if (preset) {
             for (const [resourceType, presetConfig] of Object.entries(preset)) {
                 const entry = result[resourceType];
@@ -250,20 +447,28 @@ export class ResourcesRepositoryFrontendService {
                 }
                 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.
+                // Schema bridge for z_clone — when `resourceUIBehavior()` attached a DISTINCT cloned
+                // schema (via FRONTEND_SCHEMA_KEY Symbol), replace mainSchema on the resource so the
+                // operation-DTO rebuild (`rebuildResourceConfigurationsOperationDtos`, run from
+                // `initialize` right after this method) derives every DTO from the DECORATED schema,
+                // and rebuild the CREATE/UPDATE requestDto here too. Only DTOs auto-derived from the
+                // original mainSchema are rebuilt — custom DTOs are left unchanged. (For the common
+                // same-instance case — ui-behavior decorated the backend schema in place, e.g. Wonder
+                // Todos — `frontendSchema === entry.mainSchema` already, so mainSchema is decorated
+                // without replacement.)
+                //
+                // NOTE: the per-field `fields` decorator overlay does NOT live here. Every DTO
+                // produced in this method is subsequently REBUILT from scratch by
+                // `rebuildResourceConfigurationsOperationDtos` (its `buildAllOperationDtos` pass
+                // re-wraps optional/array/compound fields into fresh instances), which would discard
+                // any overlay applied now. The overlay therefore runs AFTER that rebuild — see
+                // `overlayUiBehaviorDtoDecorators`, invoked from `initialize`.
                 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);
@@ -276,7 +481,7 @@ export class ResourcesRepositoryFrontendService {
                 // 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 compiledCompositeViews = this.buildResourceCompositeViewDefinitions(resourceType, entry.resourcePrimaryScope ?? ResourcePrimaryScope.ORGANIZATIONS, authoredCompositeViews);
                 const compiledExecutionViews = this.buildResourceExecutionViewDefinitions(entry.resourcePrimaryScope ?? ResourcePrimaryScope.ORGANIZATIONS, authoredExecutionViews);
                 entry.frontendConfiguration = {
                     ...resourceLevelConfig,
@@ -288,7 +493,10 @@ export class ResourcesRepositoryFrontendService {
                     }),
                 };
                 // Apply per-operation frontend config — matches preset views keys
-                // to registered API_CALL/API_CALL_WITH_CALLBACK operations
+                // to registered API_CALL/API_CALL_WITH_CALLBACK operations. Authored
+                // `iconOverride` rides along on `operationFrontendConfig`; the
+                // `IconRegistryBridge` reads it from each operation at render time
+                // and surfaces it into `CoreIconRegistry.operationResources`.
                 if (presetViews) {
                     for (const [operationKey, opConfig] of presetViews) {
                         const matchedOp = this.findOperationByPresetKey(entry.operations, operationKey);
@@ -302,7 +510,67 @@ export class ResourcesRepositoryFrontendService {
                 if (relationshipOverrides && relationshipOverrides.length > 0) {
                     this.resolveRelationshipDisplayOverrides(resourceType, entry.resourceRelationships, relationshipOverrides, allResourceFieldIdentifiers);
                 }
-                this.registerResourceIcon(resourceType, presetConfig.icon);
+                // Resource-level icon rides on `entry.frontendConfiguration.icon`
+                // (spread above from `resourceLevelConfig`, which keeps every
+                // `ResourceUIBehaviorConfig` field that isn't `views` / `relationshipOverrides`
+                // / `compositeViews` / `executionViews`). The `IconRegistryBridge`
+                // walks the registry and populates `CoreIconRegistry.resources` from
+                // this field. No side-effecting registration call needed here.
+            }
+        }
+        // ── Step 2.5: Resolve the frontend SURFACE for every operation.
+        // After the preset overlay, any operation without an explicit surface falls
+        // back to its backend-authored `defaultFrontendPosture`, else a per-kind default
+        // (BULK ops → EMBEDDED so the bulk bar isn't emptied; else API_ONLY headless —
+        // callable via httpClient, no UI). This makes the third tier an
+        // explicit `surface` on every operation rather than an implicit `undefined`,
+        // so the surface is auditable end-to-end (spec distillation, navigation,
+        // action bars all read it via `isOperationAddressable()`/`isOperationHeadless()`).
+        //
+        // It also fail-closes the one illegal combination the `apiOnly()` factory
+        // signature cannot catch on a hand-written literal: an API_ONLY operation must
+        // carry NO view fields (a headless operation has no action button, layout,
+        // icon, or custom view).
+        for (const [resourceType, entry] of Object.entries(result)) {
+            for (const op of entry.operations) {
+                if (op.operationFrontendConfig === undefined) {
+                    // Default for an unsurfaced operation: its backend-authored
+                    // `defaultFrontendPosture`, else a per-kind default. BULK operations are
+                    // auto-generated (`DELETE_MANY`/`UPDATE_MANY` + generated relationship bulk
+                    // ops) and can NEVER be authored in a preset — preset `views` keys resolve
+                    // to the non-bulk variant — yet they DO render, in the bulk action bar. So
+                    // they default to EMBEDDED (a view rendered in a host), not API_ONLY;
+                    // otherwise the action-bar headless filter would empty the entire bulk bar.
+                    // Non-bulk unsurfaced operations default to API_ONLY (truly headless — no
+                    // preset gave them a view).
+                    op.operationFrontendConfig = {
+                        surface: op.defaultFrontendPosture
+                            ?? (op.isBulkOperation
+                                ? ResourceOperationFrontendSurface.EMBEDDED
+                                : ResourceOperationFrontendSurface.API_ONLY),
+                    };
+                    continue;
+                }
+                if (op.operationFrontendConfig.surface === ResourceOperationFrontendSurface.API_ONLY) {
+                    const cfg = op.operationFrontendConfig;
+                    const hasViewField = cfg.actionVisibility !== undefined ||
+                        cfg.actionPlacement !== undefined ||
+                        cfg.actionPresentation !== undefined ||
+                        cfg.actionVariant !== undefined ||
+                        cfg.customView !== undefined ||
+                        cfg.displayPresetOverride !== undefined ||
+                        (cfg.navigationOverrides?.length ?? 0) > 0 ||
+                        cfg.displayPriority !== undefined ||
+                        cfg.iconOverride !== undefined ||
+                        cfg.collectionDisplayConfig !== undefined ||
+                        cfg.hasDescription !== undefined;
+                    if (hasViewField) {
+                        throw new Error(`[ResourcesRegistry] Operation "${String(op.operationIdentifier)}" on resource ` +
+                            `"${resourceType}" declares surface API_ONLY (headless) but carries view-only ` +
+                            `frontend config (action/layout/icon/customView). A headless operation has no UI ` +
+                            `surface — drop the view fields, or change its surface to ADDRESSABLE/EMBEDDED.`);
+                    }
+                }
             }
         }
         // ── Step 3: Derive FK field display from relationship parentDisplay.
@@ -317,36 +585,20 @@ export class ResourcesRepositoryFrontendService {
             `${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) {
+    buildResourceCompositeViewDefinitions(resourceType, primaryScope, compositeViews) {
         if (!compositeViews) {
             return [];
         }
-        return Object.entries(compositeViews).map(([ref, viewComponent]) => ({
+        return Object.entries(compositeViews).map(([ref, authoredView]) => ({
             ref,
+            translationRef: buildResourceCompositeViewTranslationRef(resourceType, ref),
             scope: FrontendView_ScopeMode.RESOURCE,
             isAddressable: true,
-            operationLike: CoreResourceOperation.READ,
+            operationLike: authoredView.operationLike ?? CoreResourceOperation.READ,
             primaryScope,
-            viewComponent,
+            sectionRefs: authoredView.sectionRefs,
+            viewComponent: authoredView.viewComponent,
+            icon: authoredView.icon,
         }));
     }
     buildResourceExecutionViewDefinitions(primaryScope, executionViews) {
@@ -357,13 +609,29 @@ export class ResourcesRepositoryFrontendService {
             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,
+            surfaceInOperations: executionView.surfaceInOperations,
+            participations: executionView.participations,
             viewComponent: executionView.viewComponent,
             requiredFeatures: executionView.requiredFeatures,
+            // View-local i18n label declarations must survive the authoring→compiled
+            // mapping: the companion labelling collector reads `executionView.labels`
+            // off the compiled definition to generate
+            // `views.execution.resources.<res>.<ref>.<labelRef>`. Dropping it here
+            // (this map lists fields explicitly, it does not spread) silently strips
+            // the whole custom-label set — the keys never reach generation.
+            labels: executionView.labels,
+            // Same survival requirement as `labels`: the IconRegistryBridge reads
+            // `icon` off the compiled definition (`view-execution-{ref}` custom key).
+            icon: executionView.icon,
+            // Same again for the launcher presentation: `ResourceLayout_InsertedViews`
+            // reads `launcher` off the COMPILED definition to decide which host slot
+            // renders this view's entry point (and how). Dropped here, every view
+            // would silently fall back to the framework default placement.
+            launcher: executionView.launcher,
         }));
     }
     /**
@@ -402,6 +670,32 @@ export class ResourcesRepositoryFrontendService {
                     candidates.push({ bucket: relationships.selfRelationships, index: i, rel, bucketName: 'selfRelationships' });
                 }
             }
+            // Filter out STANDALONE candidates.
+            //
+            // STANDALONE relationships are pure structural metadata — they declare
+            // primary-scope ownership or M:N expansion anchoring but are intentionally
+            // OFF the URL surface (no nested route, no parent-context view). The
+            // `RelationshipDisplayOverride` carries navigation / child-view / interaction,
+            // `inParentNavigation`, `inChildView` — none of which apply to a
+            // relationship that has no parent-context surface. Keeping STANDALONE
+            // candidates in the disambiguation set produces spurious "duplicate FK"
+            // warnings on registries where the user-facing M:N expansion peer→junction
+            // edge coexists with a STANDALONE primary-scope anchor (canonical case:
+            // ORGANIZATIONS → ORGANIZATION_MEMBERS).
+            //
+            // Self-relationships and OPTIONAL_CONTEXT/REQUIRES_CONTEXT relationships
+            // are kept — they all have at least one URL/view surface the override
+            // can attach to.
+            if (candidates.length > 1) {
+                const surfaced = candidates.filter(({ rel }) => rel.accessScopeStrategy !== ResourceRelationshipAccessScopeStrategy.STANDALONE);
+                if (surfaced.length > 0) {
+                    candidates.length = 0;
+                    candidates.push(...surfaced);
+                }
+                // If filtering would eliminate all candidates (every match is STANDALONE),
+                // keep the originals and let the downstream warning paths handle it —
+                // the override is meaningless but we still want a visible signal.
+            }
             // Narrow by foreignKeyField if provided
             if (override.foreignKeyField && candidates.length > 0) {
                 const fkFiltered = candidates.filter(({ rel }) => {
@@ -447,12 +741,6 @@ export class ResourcesRepositoryFrontendService {
                 ...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,
@@ -568,8 +856,9 @@ export class ResourcesRepositoryFrontendService {
      * 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` key → explicit default operation (`isOperationDefault === true`),
+     *   falling back to the no-variant-key shape only for older operation objects
+     *   that do not carry a default marker.
      * - `[string, string]` tuple → variant operation (`variantKey === key[1]`).
      */
     findOperationByPresetKey(operations, key) {
@@ -577,14 +866,31 @@ export class ResourcesRepositoryFrontendService {
             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));
+        // String key — match the explicit default first. No-key fallback is only
+        // for older/generated operation objects that predate `isOperationDefault`.
+        const sameIdentifierOperations = operations.filter((op) => op.operationIdentifier === key);
+        const explicitDefaultCandidates = sameIdentifierOperations.filter((op) => op.isOperationDefault === true);
+        const candidates = explicitDefaultCandidates.length > 0
+            ? explicitDefaultCandidates
+            : sameIdentifierOperations.filter((op) => !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];
+        const nonBulkCandidates = candidates.filter((op) => op.isBulkOperation !== true);
+        if (nonBulkCandidates.length === 1) {
+            return nonBulkCandidates[0];
+        }
+        throw this.buildConfigurationError(ErrorCustomMessageReference.CONFIGURATION, {
+            operationIdentifier: key,
+            candidateVariants: candidates.map((op) => ({
+                variantType: op.variantType,
+                variantKey: op.variantKey,
+                isOperationDefault: op.isOperationDefault,
+                isBulkOperation: op.isBulkOperation,
+            })),
+            message: 'Frontend preset operation key resolves to multiple URL-bearing variants. Use an explicit [operationIdentifier, variantKey] tuple or make the default operation identity unique.',
+        });
     }
     /**
      * Generate URLs for API_CALL and API_CALL_WITH_CALLBACK operations.
@@ -642,6 +948,22 @@ export class ResourcesRepositoryFrontendService {
         }
         return this.resourcesHttpClient;
     }
+    /**
+     * Get the base application HTTP client.
+     *
+     * This is the SAME instance exposed app-wide as `useApplication().httpClient`
+     * (the repository is constructed with it), and it is DISTINCT from the
+     * specialized resources client returned by {@link getResourcesHttpClient}.
+     * Resource-integrated file operations (upload / metadata / delete via
+     * `FormFieldFile`) run through this base client, so the auth token / renewal
+     * handler / consumable token must be mirrored onto it too — otherwise those
+     * file requests are sent unauthenticated. Exposed so the registry's auth-token
+     * fan-out can reach it from the single seam that already tokens the resources
+     * client.
+     */
+    getApplicationHttpClient() {
+        return this.httpClient;
+    }
     /**
      * Validate that all isForeignKey() fields in registered schemas can be resolved
      * to a resource type via the fieldIdentifierToResourceType map (enriched from relationships).
@@ -650,21 +972,13 @@ export class ResourcesRepositoryFrontendService {
      * 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 });
-                }
-            }
-        }
+        // The sweep itself is shared (Resources_SharedUtils) so the app-creation
+        // verification lane runs the SAME check headless after compose/coding
+        // mutations, instead of this being the first place the defect can surface.
+        const unresolvedFKFields = Resources_SharedUtils.collectUnresolvableForeignKeyFields({
+            mainSchemasByResourceType: Object.fromEntries(Object.entries(resourceConfigurations).map(([resourceType, config]) => [resourceType, config.mainSchema])),
+            fieldIdentifierToResourceType,
+        });
         if (unresolvedFKFields.length > 0) {
             const details = unresolvedFKFields
                 .map(({ resourceType, fieldName }) => `  - ${resourceType}.${fieldName}`)
@@ -682,5 +996,98 @@ export class ResourcesRepositoryFrontendService {
             // throw at point of use via resolveResourceTypeForForeignKey().
         }
     }
+    /**
+     * TIER 1 of the file display guard — the STATIC half, decided at registry build.
+     *
+     * A file field whose schema declares a NARROW `FileNature` has a knowable answer to
+     * "can this be displayed?": IMAGE/VIDEO/AUDIO/PDF have displayers, OFFICE and
+     * ARCHIVE do not. So a policy asking to RENDER such a file — `THUMBNAIL` / `FULL`
+     * presentation, or `OVERLAY` activation — is either satisfiable forever or broken
+     * forever, and the broken case is a configuration error rather than something to
+     * discover at render time as a blank frame.
+     *
+     * `FileNature.ALL` is deliberately NOT judged here: the MIME type only exists once
+     * a file does, so that case is genuinely undecidable statically and is owned by the
+     * runtime tier (`resolveFileDisplayPolicy`), which degrades deterministically.
+     * This is the same static/runtime reachability split the lazy-boundary work uses.
+     */
+    validateFileDisplayPolicyCoherence(resourceConfigurations) {
+        const offendingFields = [];
+        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;
+                const fileMetadata = getFileMetadata(typedSchema);
+                if (!fileMetadata?.nature)
+                    continue;
+                const displayParams = getFieldUIDisplayConfig(typedSchema);
+                if (!displayParams)
+                    continue;
+                const wantsRender = displayParams.presentation !== undefined
+                    && displayParams.presentation !== FileDisplayPresentation.CARD;
+                const wantsOverlay = displayParams.activation?.policy === FileActivationPolicy.OVERLAY;
+                if (!wantsRender && !wantsOverlay)
+                    continue;
+                // `undefined` = FileNature.ALL = undecidable here; the runtime tier owns it.
+                if (declaredFileNatureCanDisplay(fileMetadata.nature) !== false)
+                    continue;
+                offendingFields.push({
+                    resourceType,
+                    fieldName,
+                    nature: String(fileMetadata.nature),
+                    requested: wantsRender ? `presentation ${displayParams.presentation}` : 'activation overlay',
+                });
+            }
+        }
+        if (offendingFields.length === 0)
+            return;
+        const details = offendingFields
+            .map(({ resourceType, fieldName, nature, requested }) => `  - ${resourceType}.${fieldName} (nature ${nature}) requests ${requested}`)
+            .join('\n');
+        const message = `[ResourcesRegistry] ${offendingFields.length} file field(s) request a display no displayer can satisfy:\n` +
+            `${details}\n` +
+            `Fix: use presentation CARD (with a DOWNLOAD/NEW_TAB activation) for natures that have no viewer, ` +
+            `or widen the declared FileNature if the field genuinely holds displayable files.`;
+        console.error(message);
+        if (envLoader.isDevelopment()) {
+            throw this.buildConfigurationError(ErrorCustomMessageReference.FRONTEND_FK_RESOLUTION_FAILED, { offendingFields, message });
+        }
+    }
+    /**
+     * Validate that each resource-owned special view ref is unique within its
+     * resource-local namespace.
+     *
+     * `RESOURCE_VIEW` references are family-agnostic by design, so chart,
+     * composite, and execution declarations must not reuse the same `viewRef`.
+     */
+    validateResourceOwnedViewRefUniqueness(resourceConfigurations) {
+        for (const resourceType of Object.keys(resourceConfigurations)) {
+            const viewsByRef = new Map();
+            for (const view of listResourceOwnedViewReferences({
+                resourceType,
+                registry: {
+                    resourceConfigurations,
+                },
+            })) {
+                const existing = viewsByRef.get(view.viewRef) ?? [];
+                existing.push(view);
+                viewsByRef.set(view.viewRef, existing);
+            }
+            for (const [viewRef, matches] of viewsByRef.entries()) {
+                if (matches.length <= 1) {
+                    continue;
+                }
+                const declaredFamilies = matches
+                    .map((match) => match.family)
+                    .join(', ');
+                throw this.buildConfigurationError(ErrorCustomMessageReference.CONFIGURATION, {
+                    component: 'ResourcesRepositoryFrontendService.validateResourceOwnedViewRefUniqueness',
+                    message: `Resource "${resourceType}" declares resource-owned view ref "${viewRef}" multiple times (${declaredFamilies}). RESOURCE_VIEW refs must be unique per resource-owned view namespace.`,
+                });
+            }
+        }
+    }
 }
-//# sourceMappingURL=resources-repository.frontend.service.js.map
+//# sourceMappingURL=resources-repository.frontend.service.js.map