@wildo-ai/saas-frontend-lib 1.1.9 → 1.1.11

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

@@ -3,7 +3,7 @@
  *
  * 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
+ * 2. Operation filtering — only API_CALL 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
@@ -14,18 +14,19 @@ import { WildoBackendHttpClient_Resources } from '../../core/requests/wildo-http
 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 { 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, describeCaughtError } from '@wildo-ai/saas-models';
+import { FRONTEND_DECLARED_SCHEMA_KEY, 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, describeCaughtError, resourceInheritanceVariantSchemas } from '@wildo-ai/saas-models';
 import { buildResourceCompositeViewTranslationRef, } from '../../core/config/composite-view.schemas.js';
-import { getZodObjectShape, isForeignKeyField, getSchemaType, FieldSchemaType, unwrapSchema, getCustomFieldMetadata, addDecorators, ZodDecorator, ForeignKeyDisplayMode, SCHEMA_METADATA, getFileMetadata, getFieldUIDisplayConfig, declaredFileNatureCanDisplay, FileDisplayPresentation, FileActivationPolicy } from '@wildo-ai/zod-decorators';
+import { getZodObjectShape, isForeignKeyField, getSchemaType, FieldSchemaType, unwrapSchema, getCustomFieldMetadata, addDecorators, withObjectFields, mapSchemaChildren, 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';
+import { composeUiBehaviorPresentation } from '../../core/resources/ui-behavior-presentation.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
  * 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.
+ * `deriveRequestDto` and should be rebuilt when the presentation is composed onto mainSchema.
  */
 function isDtoDerivedFromSchema(requestDto, mainSchema) {
     try {
@@ -46,14 +47,13 @@ function isDtoDerivedFromSchema(requestDto, mainSchema) {
  * 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`.
+ * the ui-behavior's presentation is composed onto `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`)
+ * are decorated COPIES of the schema's fields (#1308), which `resourceUIBehavior` composes
+ * into the schema it presents. `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
@@ -108,7 +108,7 @@ function isDtoDerivedFromSchema(requestDto, mainSchema) {
  * @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) {
+function overlayUiBehaviorFieldDecorators(dto, frontendSchema, declaredFieldInstances) {
     if (!dto)
         return;
     // Union-aware shape resolution — identical to `getFieldSchema`'s, so the field instances
@@ -125,13 +125,20 @@ function overlayUiBehaviorFieldDecorators(dto, frontendSchema) {
         // DTO field IS the decorated schema instance (decorators already present, nothing to do).
         if (!frontendField || !dtoField || dtoField === frontendField)
             continue;
+        /*
+         * Never a DECLARED instance (#1308): it belongs to the resource configuration, and often to other resources.
+         * The presented main schema and its composed variants put a decorated copy wherever the ui-behavior decorated a
+         * field, so a declared instance in a derived DTO is a field the ui-behavior left alone.
+         */
+        if (declaredFieldInstances.has(dtoField))
+            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).
+        // stale value for one (a re-wrapped clone of the field as declared, before its `fields` decoration).
         const needsSync = Object.keys(frontendMeta).some((key) => !(key in dtoMeta) || dtoMeta[key] !== frontendMeta[key]);
         if (!needsSync)
             continue;
@@ -189,11 +196,17 @@ const REFERENCE_IDENTITY_DECORATORS = [ZodDecorator.IS_FOREIGN_KEY, ZodDecorator
  */
 function carryReferenceIdentityOntoCustomRequestDto(requestDto, resourceSchema) {
     if (!requestDto || !resourceSchema)
-        return;
+        return requestDto;
     const dtoShape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(requestDto, { commonOnly: false });
     const resourceShape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(resourceSchema, { commonOnly: false });
     if (!dtoShape || !resourceShape)
-        return;
+        return requestDto;
+    /*
+     * Carried onto COPIES, swapped into a rebuilt DTO (#1308): the author's field is often a module-level schema the
+     * author shares between operations, or a constant other resources hold, so writing its metadata in place would
+     * declare it a reference everywhere it is used.
+     */
+    const carriedFields = new Map();
     for (const [fieldName, dtoField] of Object.entries(dtoShape)) {
         const resourceField = resourceShape[fieldName];
         if (!dtoField || !resourceField)
@@ -210,14 +223,137 @@ function carryReferenceIdentityOntoCustomRequestDto(requestDto, resourceSchema)
             if (key in resourceMeta)
                 carried[key] = resourceMeta[key];
         }
-        // `as any` for the symbol-keyed metadata write — same idiom as `overlayUiBehaviorFieldDecorators`.
-        dtoField[SCHEMA_METADATA] = { ...getCustomFieldMetadata(dtoField), ...carried };
+        const copy = addDecorators(dtoField, []);
+        copy[SCHEMA_METADATA] = { ...getCustomFieldMetadata(dtoField), ...carried };
+        carriedFields.set(dtoField, copy);
+    }
+    return carriedFields.size === 0 ? requestDto : substituteSchemaInstances(requestDto, carriedFields);
+}
+/**
+ * `schema` rebuilt with every instance `substitutions` names replaced, at any depth (object fields, wrappers, array
+ * elements, union options, …): the instances themselves are never written. Returns `schema` when nothing under it is
+ * substituted. A node met again while it is being rebuilt (a recursive schema) is left as it is at that back-edge.
+ */
+function substituteSchemaInstances(schema, substitutions) {
+    const rebuilt = new Map();
+    const inProgress = new Set();
+    const visit = (node) => {
+        const substitute = substitutions.get(node);
+        if (substitute)
+            return substitute;
+        const known = rebuilt.get(node);
+        if (known)
+            return known;
+        if (inProgress.has(node))
+            return node;
+        inProgress.add(node);
+        const result = mapSchemaChildren(node, visit);
+        inProgress.delete(node);
+        rebuilt.set(node, result);
+        return result;
+    };
+    return visit(schema);
+}
+/**
+ * Which DECLARED instances the presentation replaced, and with what: the declared and presented schemas walked in
+ * parallel (object fields by key, wrapper inner types, array elements, union options by position), recording every
+ * pair whose instances differ. A custom DTO built from the declared schema (`variant.extend(...)`, `.pick(...)`)
+ * holds those declared instances, and used to read the ui-behavior's decorations off them because a decorator
+ * wrote onto them; substituting the presented copies gives it the same reading without the write (#1308).
+ */
+function collectPresentationSubstitutions(declared, presented, into) {
+    if (!declared || !presented || declared === presented || typeof declared !== 'object' || typeof presented !== 'object')
+        return;
+    const declaredDefinition = declared._zod?.def;
+    const presentedDefinition = presented._zod?.def;
+    if (!declaredDefinition || !presentedDefinition || declaredDefinition.type !== presentedDefinition.type)
+        return;
+    if (into.has(declared))
+        return;
+    into.set(declared, presented);
+    if (declaredDefinition.type === 'object') {
+        const declaredShape = declaredDefinition.shape;
+        const presentedShape = presentedDefinition.shape;
+        for (const key of Object.keys(declaredShape))
+            collectPresentationSubstitutions(declaredShape[key], presentedShape[key], into);
+        return;
     }
+    for (const key of ['innerType', 'element', 'valueType', 'in', 'out']) {
+        collectPresentationSubstitutions(declaredDefinition[key], presentedDefinition[key], into);
+    }
+    const declaredOptions = declaredDefinition.options;
+    const presentedOptions = presentedDefinition.options;
+    if (Array.isArray(declaredOptions) && Array.isArray(presentedOptions) && declaredOptions.length === presentedOptions.length) {
+        declaredOptions.forEach((option, index) => collectPresentationSubstitutions(option, presentedOptions[index], into));
+    }
+}
+/**
+ * The inheritance definition with every variant schema passed through `map` — REBUILT, never written in place, since
+ * the definition comes from the shared resource configuration (#1308). The same object comes back when nothing changed.
+ */
+function mapInheritedVariantSchemas(definition, map) {
+    if (definition === undefined)
+        return undefined;
+    let changed = false;
+    const inheritedSchemas = definition.inheritedSchemas.map((inherited) => {
+        const schema = map(inherited.schema);
+        const nested = mapInheritedVariantSchemas(inherited.inheritenceSchemaDefinition, map);
+        if (schema === inherited.schema && nested === inherited.inheritenceSchemaDefinition)
+            return inherited;
+        changed = true;
+        return { ...inherited, schema, ...(nested !== undefined ? { inheritenceSchemaDefinition: nested } : {}) };
+    });
+    return changed ? { ...definition, inheritedSchemas } : definition;
+}
+/**
+ * Every top-level field INSTANCE a resource declares: its main schema's and every inheritance variant's. These are
+ * shared with the resource configuration (and often with other resources), so nothing on the frontend may write to
+ * them (#1308).
+ */
+function collectDeclaredFieldInstances(mainSchema, definition, into) {
+    for (const field of Object.values(getZodObjectShape(mainSchema) ?? {}))
+        into.add(field);
+    for (const inherited of definition?.inheritedSchemas ?? []) {
+        collectDeclaredFieldInstances(inherited.schema, inherited.inheritenceSchemaDefinition, into);
+    }
+}
+/**
+ * Give every inheritance variant the ui-behavior's `fields` decorations the main schema now presents (#1308).
+ *
+ * The bridge composes the presentation onto the main schema (#2918), but each variant schema still holds the
+ * resource's declared field instances, and the DTO builder builds a variant's union option as `base.extend(variant.shape)`: a variant that
+ * restates a base field would put the undecorated declaration back. So for each field the presentation decorated
+ * (its instance differs from the declared one): a variant holding the DECLARED instance takes the presented copy; a
+ * variant that REDECLARES the field keeps its own declaration, as a copy carrying the presentation's metadata on top
+ * (the presentation wins per key, as the DTO overlay always did). Rebuilt, never written in place.
+ */
+function composePresentedFieldsIntoVariants(definition, declaredMainSchema, presentedMainSchema) {
+    if (definition === undefined || presentedMainSchema === declaredMainSchema)
+        return definition;
+    // Only an OBJECT main schema has a per-field presentation to give: composing a union's would hand every variant the
+    // whole presented union (the helper's fallback for a schema it cannot compose by key).
+    const isObject = (schema) => schema._zod?.def?.type === 'object';
+    if (!isObject(declaredMainSchema) || !isObject(presentedMainSchema))
+        return definition;
+    // A variant that is not an object schema has no field to compose into, and keeps its declaration.
+    return mapInheritedVariantSchemas(definition, (variantSchema) => isObject(variantSchema)
+        ? composeUiBehaviorPresentation(variantSchema, declaredMainSchema, presentedMainSchema)
+        : variantSchema);
 }
 export class ResourcesRepositoryFrontendService {
     httpClient;
     registry = null;
     isInitialized = false;
+    /**
+     * Per resource, the field instances its configuration DECLARES, recorded before the schema bridge composes the
+     * presentation onto its schema. The DTO overlay never writes to one of these: they are shared state (#1308).
+     */
+    declaredFieldInstancesByResource = new Map();
+    /**
+     * Per resource, the declared instances its presentation replaced and their presented copies
+     * (`collectPresentationSubstitutions`), applied to the resource's CUSTOM DTOs after the rebuild.
+     */
+    presentationSubstitutionsByResource = new Map();
     resourcesHttpClient = null;
     constructor(httpClient) {
         this.httpClient = httpClient;
@@ -235,8 +371,8 @@ export class ResourcesRepositoryFrontendService {
     /**
      * 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
+     * ALL backend resources are included in the registry, but only API_CALL
+     * 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
@@ -312,7 +448,13 @@ export class ResourcesRepositoryFrontendService {
             // ── 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.
+            // Used by a frontend that is not an application to drop core vocabulary it has no business
+            // showing (the application-creation workbench, `excludedResourceTypes` on its start options);
+            // no application passes a set (measured 2026-10-20). NOT the backend's feature-gated removal:
+            // that one (`withoutFeatureGatedCoreResources`, `@wildo-ai/saas-backend-lib`, #3005) is decided by
+            // the billing and lifecycle configuration and shared by startup, the evidence collector and the
+            // committed-programme gate. A frontend library cannot import the backend library, and the two
+            // sets are different decisions, so the steps are repeated here rather than shared.
             //
             // 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
@@ -344,7 +486,7 @@ export class ResourcesRepositoryFrontendService {
             // 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
+            // `fields` decorations' wrapper 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
@@ -352,6 +494,7 @@ export class ResourcesRepositoryFrontendService {
             // MUST run after the rebuild, or it is silently discarded. See
             // `overlayUiBehaviorFieldDecorators` for the rationale.
             this.overlayUiBehaviorDtoDecorators(frontendResourceConfigurations, resourceUIBehavior);
+            this.substitutePresentationIntoCustomDtos(frontendResourceConfigurations);
             // A custom request DTO that names one of the resource's foreign keys collects a REFERENCE, and
             // must render as one (the searchable picker, not a text box). Every resource, preset or not:
             // the identity lives on the schema, not in the ui-behavior. See
@@ -433,7 +576,7 @@ export class ResourcesRepositoryFrontendService {
         for (const entry of Object.values(resourceConfigurations)) {
             for (const op of entry.operations ?? []) {
                 if (op.hasCustomRequestDto) {
-                    carryReferenceIdentityOntoCustomRequestDto(op.requestDto, entry.mainSchema);
+                    op.requestDto = carryReferenceIdentityOntoCustomRequestDto(op.requestDto, entry.mainSchema);
                 }
             }
         }
@@ -445,7 +588,7 @@ export class ResourcesRepositoryFrontendService {
      *
      * 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
+     * mainSchema, producing fresh field instances that lose the `fields` wrapper metadata on
      * every re-wrapped (optional / array / compound) field. Running the overlay inside
      * `buildFrontendResourceConfigurations` would be silently discarded by that rebuild.
      *
@@ -461,6 +604,74 @@ export class ResourcesRepositoryFrontendService {
      * overlaid READ view renders ROW — an inconsistency between the two surfaces of the SAME
      * field. See `overlayUiBehaviorFieldDecorators` for per-field mechanics and parse-safety.
      */
+    /**
+     * Replace a resource's schemas with the ones the frontend PRESENTS — the one door every such replacement goes through
+     * (#1308), because a replacement owes three things and each was once forgotten at one of its sites:
+     *
+     * - the entry's `mainSchema` and `inheritenceSchemaDefinition`;
+     * - every operation whose own `mainSchema` is still the replaced one: the DTO rebuild derives from
+     *   `operation.mainSchema` (`buildAllOperationDtosInResourceScope`), so an operation left on the declared schema
+     *   rebuilt every DTO from undecorated fields. These operation objects are this registry's copies (step 1);
+     * - the SUBSTITUTIONS a custom DTO reads the presentation through (`collectPresentationSubstitutions`), CHAINED with
+     *   any recorded before, so a declared field the ui-behavior decorated and the FK derivation then decorated again
+     *   maps to the final copy.
+     */
+    presentSchemas(resourceType, entry, next) {
+        const previousMainSchema = entry.mainSchema;
+        const previousInheritance = entry.inheritenceSchemaDefinition;
+        if (next.mainSchema === previousMainSchema && next.inheritenceSchemaDefinition === previousInheritance)
+            return;
+        const writable = entry;
+        writable.mainSchema = next.mainSchema;
+        writable.inheritenceSchemaDefinition = next.inheritenceSchemaDefinition;
+        for (const op of entry.operations ?? []) {
+            if (op.mainSchema === previousMainSchema)
+                op.mainSchema = next.mainSchema;
+        }
+        const step = new Map();
+        collectPresentationSubstitutions(previousMainSchema, next.mainSchema, step);
+        const pairVariants = (before, after) => {
+            before?.inheritedSchemas.forEach((inherited, index) => {
+                const presented = after?.inheritedSchemas[index];
+                collectPresentationSubstitutions(inherited.schema, presented?.schema, step);
+                pairVariants(inherited.inheritenceSchemaDefinition, presented?.inheritenceSchemaDefinition);
+            });
+        };
+        pairVariants(previousInheritance, next.inheritenceSchemaDefinition);
+        if (step.size === 0)
+            return;
+        const chained = new Map();
+        for (const [declared, presented] of this.presentationSubstitutionsByResource.get(resourceType) ?? []) {
+            chained.set(declared, step.get(presented) ?? presented);
+        }
+        for (const [replaced, replacement] of step) {
+            if (!chained.has(replaced))
+                chained.set(replaced, replacement);
+        }
+        this.presentationSubstitutionsByResource.set(resourceType, chained);
+    }
+    /**
+     * Every resource's AUTHOR-OWNED DTOs rebuilt with its recorded substitutions, after the DTO rebuild (#1308).
+     *
+     * A custom DTO is the author's shape, so it is never overlaid; but where it holds the resource's declared instances
+     * it reads them as the resource presents them — the ui-behavior's `fields`, the derived foreign-key display — as it
+     * did when those were written onto the declared instances. Every resource, with or without a ui-behavior: the
+     * foreign-key derivation presents a copy for each of them.
+     */
+    substitutePresentationIntoCustomDtos(resourceConfigurations) {
+        for (const [resourceType, substitutions] of this.presentationSubstitutionsByResource) {
+            const entry = resourceConfigurations[resourceType];
+            if (!entry?.operations)
+                continue;
+            for (const op of entry.operations) {
+                for (const [hasCustom, key] of [['hasCustomResponseDto', 'responseDto'], ['hasCustomResponseDto', 'contextDto'], ['hasCustomRequestDto', 'requestDto']]) {
+                    const dto = op[key];
+                    if (op[hasCustom] && dto)
+                        op[key] = substituteSchemaInstances(dto, substitutions);
+                }
+            }
+        }
+    }
     overlayUiBehaviorDtoDecorators(resourceConfigurations, preset) {
         if (!preset)
             return;
@@ -468,29 +679,30 @@ export class ResourcesRepositoryFrontendService {
             const frontendSchema = presetConfig[FRONTEND_SCHEMA_KEY];
             if (!frontendSchema)
                 continue;
+            const declared = this.declaredFieldInstancesByResource.get(resourceType) ?? new Set();
             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);
+                    overlayUiBehaviorFieldDecorators(op.responseDto, frontendSchema, declared);
+                    overlayUiBehaviorFieldDecorators(op.contextDto, frontendSchema, declared);
                 }
                 // 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.requestDto, frontendSchema, declared);
                 }
-                overlayUiBehaviorFieldDecorators(op.summaryDto, frontendSchema);
+                overlayUiBehaviorFieldDecorators(op.summaryDto, frontendSchema, declared);
             }
         }
     }
     /**
      * 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,
+     * The registry contains ALL backend resources, but only API_CALL
+     * 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.
@@ -514,12 +726,13 @@ export class ResourcesRepositoryFrontendService {
             result[resourceType] = {
                 ...backendConfig,
                 operations: (backendConfig.operations ?? [])
-                    .filter(op => op.variantType === ResourceOperationVariantType.API_CALL
-                    || op.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK)
+                    .filter(op => op.variantType === ResourceOperationVariantType.API_CALL)
                     .map(op => ({
                     ...op,
                     operationFrontendConfig: undefined,
                 })),
+                // A resource with no ui-behavior keeps none: `frontendConfiguration` means "has a ui-behavior" (the launcher reads
+                // it so). Its records are still named, from `recordLabelFields`, by `FrontendResourceUtils.frontendResourceLabelDefinitionOf`.
                 frontendConfiguration: undefined,
             };
         }
@@ -536,15 +749,18 @@ 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 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.)
+                const declaredFieldInstances = new Set();
+                collectDeclaredFieldInstances(entry.mainSchema, entry.inheritenceSchemaDefinition, declaredFieldInstances);
+                this.declaredFieldInstancesByResource.set(resourceType, declaredFieldInstances);
+                // Schema bridge — the ui-behavior PRESENTS a schema (FRONTEND_SCHEMA_KEY): the schema it
+                // was declared over (FRONTEND_DECLARED_SCHEMA_KEY) with its `fields` decorations composed
+                // in, a copy whenever it declares any (a decorator returns a copy since #1308). What that
+                // changes is composed onto the resource's own mainSchema (#2918), so the operation-DTO
+                // rebuild (`rebuildResourceConfigurationsOperationDtos`, run from `initialize` right after
+                // this method) derives every DTO from the DECORATED schema, and the CREATE/UPDATE
+                // requestDto is rebuilt here too. Only DTOs auto-derived from the original mainSchema are
+                // rebuilt — custom DTOs get the presentation by substitution. A ui-behavior with no
+                // `fields` presents the schema it was given, and then nothing changes.
                 //
                 // NOTE: the per-field `fields` decorator overlay does NOT live here. Every DTO
                 // produced in this method is subsequently REBUILT from scratch by
@@ -554,22 +770,48 @@ export class ResourcesRepositoryFrontendService {
                 // `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;
-                        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);
+                    // #2918: the presentation is composed ONTO the resource's schema, never swapped in for it. The ui-behavior was
+                    // declared over the schema its author held, and the factory's schema adds fields to it (a polymorphic variant's
+                    // parent key, `retentionStatus`, …) and re-decorates some (a variant's business keys); swapping the presented
+                    // schema in dropped all of those from every DTO the frontend derives. A preset built by hand names no declared
+                    // schema, and is read as declared over the resource's own.
+                    const declaredSchema = (presetConfig[FRONTEND_DECLARED_SCHEMA_KEY] ?? oldMainSchema);
+                    const presentedMainSchema = composeUiBehaviorPresentation(oldMainSchema, declaredSchema, frontendSchema, { objectLevel: true });
+                    this.presentSchemas(resourceType, entry, {
+                        mainSchema: presentedMainSchema,
+                        inheritenceSchemaDefinition: composePresentedFieldsIntoVariants(entry.inheritenceSchemaDefinition, oldMainSchema, presentedMainSchema),
+                    });
+                    if (presentedMainSchema !== oldMainSchema) {
+                        for (const op of entry.operations) {
+                            if (!op.requestDto)
+                                continue;
+                            const effectiveOp = op.resourceOperationLike
+                                ? String(op.resourceOperationLike)
+                                : String(op.operationIdentifier);
+                            // Never an author-owned request DTO: a `.pick(...)` of the schema shares its fields, and replacing it would put
+                            // every field of the resource on a form its author narrowed. It gets the presentation by substitution instead.
+                            if ((effectiveOp === CoreResourceOperation.CREATE || effectiveOp === CoreResourceOperation.UPDATE)
+                                && !op.hasCustomRequestDto
+                                && isDtoDerivedFromSchema(op.requestDto, oldMainSchema)) {
+                                op.requestDto = deriveRequestDto(effectiveOp, presentedMainSchema, 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.
+                // #2775: a record has ONE name on every surface. `recordLabelFields` is the name the backend can read (a chat
+                // answer, a Teams search result), so a resource declaring it names its records by it here too; a ui-behavior
+                // label beside it would be a second name, shown in the application and never in the chat. Refused, as one record
+                // under two names nobody can see disagree is the defect (Salesforce's Record Name and ServiceNow's display value
+                // are the same rule: one display name per record, declared on the model, read by every surface).
+                if ((entry.recordLabelFields?.length ?? 0) > 0 && resourceLevelConfig.getFrontendResourceLabel !== undefined) {
+                    throw new Error(`[ResourcesRegistry] Resource "${resourceType}" names its records twice: \`recordLabelFields\` ` +
+                        `(${entry.recordLabelFields.join(', ')}) and its ui-behavior's getFrontendResourceLabel. A record has one name, ` +
+                        `which a chat shows too: remove getFrontendResourceLabel (the application names it by recordLabelFields), or ` +
+                        `remove recordLabelFields if the resource has no chat command that names its records.`);
+                }
                 const compiledCompositeViews = this.buildResourceCompositeViewDefinitions(resourceType, entry.resourcePrimaryScope ?? ResourcePrimaryScope.ORGANIZATIONS, authoredCompositeViews);
                 const compiledExecutionViews = this.buildResourceExecutionViewDefinitions(entry.resourcePrimaryScope ?? ResourcePrimaryScope.ORGANIZATIONS, authoredExecutionViews);
                 entry.frontendConfiguration = {
@@ -582,7 +824,7 @@ export class ResourcesRepositoryFrontendService {
                     }),
                 };
                 // Apply per-operation frontend config — matches preset views keys
-                // to registered API_CALL/API_CALL_WITH_CALLBACK operations. Authored
+                // to registered API_CALL operations. Authored
                 // `iconOverride` rides along on `operationFrontendConfig`; the
                 // `IconRegistryBridge` reads it from each operation at render time
                 // and surfaces it into `CoreIconRegistry.operationResources`.
@@ -643,6 +885,7 @@ export class ResourcesRepositoryFrontendService {
                 if (op.operationFrontendConfig.surface === ResourceOperationFrontendSurface.API_ONLY) {
                     const cfg = op.operationFrontendConfig;
                     const hasViewField = cfg.actionVisibility !== undefined ||
+                        cfg.runtimeAvailability !== undefined ||
                         cfg.actionPlacement !== undefined ||
                         cfg.actionPresentation !== undefined ||
                         cfg.actionVariant !== undefined ||
@@ -881,19 +1124,6 @@ export class ResourcesRepositoryFrontendService {
             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;
@@ -924,23 +1154,48 @@ export class ResourcesRepositoryFrontendService {
                     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 }]);
+            /*
+             * Every copy of the FK field (#2455): the base's, and a variant's that re-declares it. A variant-only relationship
+             * key is refused at boot, so the base always holds one; a variant copy that re-declares it renders through the same
+             * derived display, or a row of that variant would show the key the base copy hides.
+             *
+             * Written as a decorated COPY of the field, swapped into a rebuilt row schema (#1308). The derivation used to
+             * decorate the field's inner schema in place, and an FK leaf is often SHARED across resources: the first resource
+             * to derive wrote its display onto the shared leaf, and every later resource then read that as an explicit
+             * `.foreignKeyUI()` and kept the first resource's display, whatever its own relationship said.
+             */
+            const deriveRow = (rowSchema) => {
+                const shape = getZodObjectShape(rowSchema);
+                const fieldSchema = shape?.[fkFieldName];
+                if (!fieldSchema || !isForeignKeyField(fieldSchema))
+                    return rowSchema;
+                // An explicit `.foreignKeyUI()` wins. getCustomFieldMetadata traverses wrappers (optional, nullable, …).
+                if (getCustomFieldMetadata(fieldSchema)[ZodDecorator.FOREIGN_KEY_UI] !== undefined)
+                    return rowSchema;
+                // Decorated on the field as declared: the copy merges with its existing metadata and mirrors onto a private
+                // copy of its inner schema, so readers that unwrap first see it too.
+                const derivedField = addDecorators(fieldSchema, [{ ref: ZodDecorator.FOREIGN_KEY_UI, params: derivedConfig }]);
+                return withObjectFields(rowSchema, { [fkFieldName]: derivedField });
+            };
+            // Through the one door that also repoints the operations the DTO rebuild reads and records the substitution a
+            // custom DTO reads the derived display through (#1308): replacing `mainSchema` alone left every rebuilt DTO on
+            // the declared field.
+            this.presentSchemas(resourceType, entry, {
+                mainSchema: deriveRow(entry.mainSchema),
+                inheritenceSchemaDefinition: mapInheritedVariantSchemas(entry.inheritenceSchemaDefinition, deriveRow),
+            });
         }
     }
     /**
      * Find an operation in the registry that matches a preset `OperationKey`.
      *
-     * The `operations` array only contains API_CALL / API_CALL_WITH_CALLBACK variants
+     * The `operations` array only contains API_CALL variants
      * (filtered in `buildFrontendResourceConfigurations` step 1), so this method is
      * guaranteed to only match frontend-callable operations.
      *
@@ -982,7 +1237,7 @@ export class ResourcesRepositoryFrontendService {
         });
     }
     /**
-     * Generate URLs for API_CALL and API_CALL_WITH_CALLBACK operations.
+     * Generate URLs for API_CALL operations.
      *
      * Populates `initiatorInfos` on each operation with the computed URL path,
      * HTTP verb, and path parameters. Called after the registry is seeded but
@@ -1066,6 +1321,7 @@ export class ResourcesRepositoryFrontendService {
         // 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])),
+            variantSchemasByResourceType: Object.fromEntries(Object.entries(resourceConfigurations).map(([resourceType, config]) => [resourceType, resourceInheritanceVariantSchemas(config.inheritenceSchemaDefinition)])),
             fieldIdentifierToResourceType,
         });
         if (unresolvedFKFields.length > 0) {
@@ -1103,10 +1359,13 @@ export class ResourcesRepositoryFrontendService {
     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)) {
+            // Every schema a row can have (#2455): a variant file field's broken policy is a configuration error too.
+            const fieldEntries = [config.mainSchema, ...resourceInheritanceVariantSchemas(config.inheritenceSchemaDefinition)]
+                .flatMap((rowSchema) => Object.entries(getZodObjectShape(rowSchema) ?? {}));
+            const judged = new Set();
+            for (const [fieldName, fieldSchema] of fieldEntries) {
+                if (judged.has(fieldName))
+                    continue;
                 const typedSchema = fieldSchema;
                 const fileMetadata = getFileMetadata(typedSchema);
                 if (!fileMetadata?.nature)
@@ -1122,6 +1381,7 @@ export class ResourcesRepositoryFrontendService {
                 // `undefined` = FileNature.ALL = undecidable here; the runtime tier owns it.
                 if (declaredFileNatureCanDisplay(fileMetadata.nature) !== false)
                     continue;
+                judged.add(fieldName);
                 offendingFields.push({
                     resourceType,
                     fieldName,