@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/resources/utils/resources-config-operations.dtos-builder.utils.js

@@ -1,12 +1,16 @@
 import { z } from 'zod';
+import { markEmbeddedResourceSchema } from '../embedded-resource-mark.shared.utils.js';
 import { CoreResourceOperation } from '../resources.shared.core.definitions.js';
-import { Resources_BulkOperationBaseSchema, DataMode, OPERATION_VARIANT_KEY, createPaginationResponseMetadataSchema, getChildDirectionRelationships, getParentDirectionRelationships, ResourceGeneratedOperationKind } from '../resources-config.shared.schemas.js';
+import { wrapRequestDtoAsBulk, resolveBulkOperationMaxSelection, DataMode, OPERATION_VARIANT_KEY, createPaginationResponseMetadataSchema, DEFAULT_LIST_PAGE_CEILING, DEFAULT_SEARCH_PAGE_CEILING, getChildDirectionRelationships, getParentDirectionRelationships, ResourceGeneratedOperationKind } from '../resources-config.shared.schemas.js';
 import { ResourceRelationshipCardinality, isOneToOneCardinality, isArrayCardinality, getDefaultResponseSchemaForOperation, isOutputEnvelopeOperation, operationShouldHaveRequestDto, DefaultBulkDeleteResponseSchema, CONTEXT_AUTO_POPULATED_FIELD_IDENTIFIERS, createOrUpdateMandatoryDiscardFields } from '../resources.shared.schemas.js';
 import { Resources_SharedUtils } from '../resources.shared.utils.js';
-import { addDiscriminator, getCustomFieldMetadata, ZodDecorator, getZodType, hasZodType, isZodObject, isZodArray, isZodOptional, isZodNullable, isZodDefault, toPatchOptionalField, getZodObjectShape, getZodDefSchemaProperty, getZodDefArrayProperty, getZodDefStringProperty, getZodDefProperty, isZodTypeAny, getEnumValues, isExcludedFromCreate, isExcludedFromUpdate, isVirtualField, isTemplatableFileField, isPrimaryKey, isBackendOnlyField, getBackendOnlyParams, isWriteOnlySecretField, isDiscriminatorField, unwrapSchema, getMergedObjectOrUnionShape, withArrayElement, SCHEMA_METADATA } from '@wildo-ai/zod-decorators';
+import { addDiscriminator, getCustomFieldMetadata, ZodDecorator, getZodType, hasZodType, isZodObject, isZodArray, isZodOptional, isZodNullable, isZodDefault, toPatchOptionalField, getZodObjectShape, getZodDefSchemaProperty, getZodDefArrayProperty, getZodDefStringProperty, getZodDefProperty, isZodTypeAny, getEnumValues, isExcludedFromCreate, isExcludedFromUpdate, isVirtualField, isTemplatableFileField, isPrimaryKey, isBackendOnlyField, getBackendOnlyParams, isWriteOnlySecretField, isDiscriminatorField, unwrapSchema, getMergedObjectOrUnionShape, withArrayElement, markPatchRequestDtoObject, SCHEMA_METADATA } from '@wildo-ai/zod-decorators';
+import { ContextPolicy_ObjectMode, DEFAULT_RELATIONSHIP_CONTEXT_POLICY, } from '../context-policy.shared.schemas.js';
 import { ResourcesSummaryUtils } from './resources-summary.utils.js';
 import { RepositoryDtoBuilderUtils } from './repository-dto-builder.utils.js';
 import { stripTemplatableFileFieldsRecursively as stripTemplatableFileFieldsSchema, } from './templatable-file-fields.shared.utils.js';
+import { widenFileFieldsForPopulatedReads } from './populated-file-fields.shared.utils.js';
+import { describeCaughtError } from '../../errors/caught-error-description.shared.utils.js';
 /**
  * Canonical placeholder shown to clients in place of a `.isWriteOnlySecret()`
  * field's real value. It doubles as the write-back sentinel: when a client
@@ -16,6 +20,22 @@ import { stripTemplatableFileFieldsRecursively as stripTemplatableFileFieldsSche
  * single constant so the output mask and the input sentinel never drift.
  */
 export const WRITE_ONLY_SECRET_MASK = '••••••••';
+function createDtoDerivationMemoScope() {
+    return {
+        networkBoundaryCoercion: new WeakMap(),
+        backendOnlyStrip: new WeakMap(),
+        backendOnlyStripKeepingReturnedAtCreation: new WeakMap(),
+        contextRelative: new WeakMap(),
+        clientContextRelative: new WeakMap(),
+    };
+}
+/** One memo scope per resource configuration object; see {@link DtoDerivationMemoScope}. */
+const DTO_DERIVATION_MEMO_SCOPE_BY_RESOURCE = new WeakMap();
+/**
+ * The scope `createApiParsingSchema` runs in. Its callers parse configuration and wire payloads with
+ * the result; none of them is an operation DTO, so no per-resource overlay can reach it.
+ */
+const API_PARSING_MEMO_SCOPE = createDtoDerivationMemoScope();
 /**
  * Type guard to check if schema is a ZodAny
  * In Zod v4, any schemas have type: "any"
@@ -24,6 +44,23 @@ function isZodAny(schema) {
     return hasZodType(schema, 'any');
 }
 export class ResourcesConfigOperationsDtosBuilderUtils {
+    /**
+     * The memo scope of the resource whose DTOs are being built, or `null` outside a resource build.
+     * The builder is synchronous, so a scope set on entry and restored on exit cannot leak into
+     * another resource's build. See {@link DtoDerivationMemoScope}.
+     */
+    static activeMemoScope = null;
+    /** Run `derive` with `scope` active, restoring whatever was active before. */
+    static withMemoScope(scope, derive) {
+        const previousScope = this.activeMemoScope;
+        this.activeMemoScope = scope;
+        try {
+            return derive();
+        }
+        finally {
+            this.activeMemoScope = previousScope;
+        }
+    }
     /**
      * Carry field/schema decorators across a wrapper or leaf rebuild.
      *
@@ -39,6 +76,34 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
         if (sourceMetadata !== undefined) {
             rebuilt[SCHEMA_METADATA] = sourceMetadata;
         }
+        this.preserveRegistryMetadata(source, rebuilt);
+        return rebuilt;
+    }
+    /**
+     * Carry Zod's own `z.globalRegistry` metadata across a rebuild (#1625).
+     *
+     * That registry is where `.describe()` and `.meta()` live: the description the API reference
+     * publishes, and the mark naming the resource an embedded record belongs to
+     * (`EMBEDDED_RESOURCE_SCHEMA_KEY`). A clone keeps it through Zod's parent link; a fresh
+     * `z.object(...)` does not. So every rebuild here (backend-only stripping, date coercion, omission)
+     * used to publish the rebuilt object undescribed, and a response whose records the DTO builder
+     * rebuilt lost its embedded-record mark. Measured on the generated file-regenerate response: its
+     * `file` and `resource` descriptions and the mark all disappeared before the DTO was used.
+     *
+     * Carried even when fields were omitted: an object's description and the resource its record
+     * belongs to do not depend on which of its fields a DTO exposes. `id` is NOT carried: it names ONE
+     * schema, and Zod refuses to register the same id twice. Nothing is overwritten on a rebuilt schema
+     * that already has its own registration.
+     */
+    static preserveRegistryMetadata(source, rebuilt) {
+        if (source === rebuilt || z.globalRegistry.has(rebuilt))
+            return rebuilt;
+        const registered = z.globalRegistry.get(source);
+        if (registered === undefined)
+            return rebuilt;
+        const { id: _id, ...carried } = registered;
+        if (Object.keys(carried).length > 0)
+            z.globalRegistry.add(rebuilt, carried);
         return rebuilt;
     }
     static buildSchemaWithInheritance(mainSchema, inheritanceDefinition) {
@@ -71,6 +136,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             ? z.object(rebuiltShape).catchall(sourceCatchall)
             : z.object(rebuiltShape);
         if (options?.preserveChecks === false) {
+            this.preserveRegistryMetadata(schema, rebuiltSchema);
             return rebuiltSchema;
         }
         const checks = getZodDefArrayProperty(schema, 'checks');
@@ -101,6 +167,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
         if (sourceMetadata !== undefined) {
             rebuiltSchema[SCHEMA_METADATA] = sourceMetadata;
         }
+        this.preserveRegistryMetadata(schema, rebuiltSchema);
         return rebuiltSchema;
     }
     /**
@@ -137,7 +204,13 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
     }
     static stripTemplatableFileFieldsRecursively(schema) {
         return stripTemplatableFileFieldsSchema(schema, {
-            rebuildObjectSchema: (objectSchema, strippedShape) => this.rebuildObjectSchema(objectSchema, strippedShape, { preserveChecks: false }),
+            rebuildObjectSchema: (objectSchema, strippedShape) => {
+                // Checks and decorator metadata survive when the FIELD SET is unchanged — only a nested field
+                // was replaced, so the object is still what they describe. This passed `preserveChecks: false`
+                // unconditionally, which dropped both on every object above a rewritten field (#989).
+                const fieldSetUnchanged = Object.keys(getZodObjectShape(objectSchema)).every((fieldName) => fieldName in strippedShape);
+                return this.rebuildObjectSchema(objectSchema, strippedShape, { preserveChecks: fieldSetUnchanged });
+            },
         });
     }
     /**
@@ -193,6 +266,17 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
      * @returns Operation with all DTOs pre-computed and stored
      */
     static buildAllOperationDtos(operation, resourceConfig, registry) {
+        // Every operation of one resource shares the resource's derivation memos, and no other
+        // resource can see them — see `DtoDerivationMemoScope` for why the boundary is the resource.
+        let scope = DTO_DERIVATION_MEMO_SCOPE_BY_RESOURCE.get(resourceConfig);
+        if (scope === undefined) {
+            scope = createDtoDerivationMemoScope();
+            DTO_DERIVATION_MEMO_SCOPE_BY_RESOURCE.set(resourceConfig, scope);
+        }
+        return this.withMemoScope(scope, () => this.buildAllOperationDtosInResourceScope(operation, resourceConfig, registry));
+    }
+    /** {@link buildAllOperationDtos}, run inside its resource's memo scope. */
+    static buildAllOperationDtosInResourceScope(operation, resourceConfig, registry) {
         // 1. Apply inheritance to mainSchema (from resourceConfig.inheritenceSchemaDefinition)
         const inheritenceSchemaDefinition = resourceConfig.inheritenceSchemaDefinition;
         const enhancedMainSchema = (inheritenceSchemaDefinition
@@ -410,7 +494,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
         const contextBaseDto = isListOrSearch
             ? this.extractPaginatedCollectionItemDto(responseDto, effectiveOperation)
             : responseDto;
-        const contextDto = this.addRelationshipPlaceholders(contextBaseDto, operation.resourceRelationships, registry);
+        const contextDto = this.addRelationshipPlaceholders(contextBaseDto, operation.resourceRelationships, effectiveOperation, registry, true);
         // 7. Build internalDto base (before variant overrides):
         //    - Start with mainSchema (with inheritance)
         //    - Include backend-only fields (DO NOT strip)
@@ -519,7 +603,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             else if (operation.variantKey === OPERATION_VARIANT_KEY.CONTEXT) {
                 // For CONTEXT variants, build from contextDto versions
                 // contextDto is built from responseDto which already has backend-only stripped, so we need internal version
-                const contextDtoInternal = this.addRelationshipPlaceholders(this.excludeVirtualFieldsFromSchema(enhancedMainSchema), operation.resourceRelationships, registry);
+                const contextDtoInternal = this.addRelationshipPlaceholders(this.excludeVirtualFieldsFromSchema(enhancedMainSchema), operation.resourceRelationships, effectiveOperation, registry);
                 repositoryDto = RepositoryDtoBuilderUtils.deriveRepositoryDto(contextDtoInternal, enhancedMainSchema);
                 if (isListOrSearch) {
                     // Build internalDto for service-layer validation (pagination wrapper with backend-only items)
@@ -557,14 +641,26 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
         }
         requestDto = this.stripTemplatableFileFieldsRecursively(requestDto);
         // 11. Finalize internalDto with network-boundary coercion (dates + money bigints):
-        const internalDtoFinal = this.applyNetworkBoundaryCoercion(internalDtoProcessed);
+        let internalDtoFinal = this.applyNetworkBoundaryCoercion(internalDtoProcessed);
+        // 11b. A SUMMARY or CONTEXT read runs file population, which lays each file's metadata BESIDE the
+        //      stored reference (`file` / `files`, issue #1059). The DTOs that describe those reads — what
+        //      `transformOutput` validates and what the wire carries — declare that optional companion;
+        //      RAW reads never populate and keep the bare reference. Applied AFTER coercion, so the
+        //      companion's own dates are coerced by its own schema rather than by a walker that leaves a
+        //      plain union untouched. The widened field keeps its file metadata, so it is still a FILE field.
+        const isPopulatedReadVariant = operation.variantKey === OPERATION_VARIANT_KEY.SUMMARY
+            || operation.variantKey === OPERATION_VARIANT_KEY.CONTEXT;
+        if (isPopulatedReadVariant) {
+            internalDtoFinal = widenFileFieldsForPopulatedReads(internalDtoFinal);
+            responseDto = widenFileFieldsForPopulatedReads(responseDto);
+        }
         // 12. Return operation with all DTOs stored
         return {
             ...operation,
             requestDto,
             responseDto,
-            summaryDto,
-            contextDto,
+            summaryDto: widenFileFieldsForPopulatedReads(summaryDto),
+            contextDto: widenFileFieldsForPopulatedReads(contextDto),
             internalDto: internalDtoFinal,
             repositoryDto
         };
@@ -605,30 +701,38 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
                 isBulkOperation: false,
                 requestDto: undefined // Clear to force rebuild
             };
-            const underlyingRequestDto = this.buildEnhancedRequestDto(underlyingOperation, effectiveOperation);
-            // Wrap with bulk operation base schema
-            if (underlyingRequestDto && !isZodAny(underlyingRequestDto)) {
-                const underlyingInfo = this.analyzeDtoSchema(underlyingRequestDto);
-                if (underlyingInfo !== '📄 {} (empty object)') {
-                    if (effectiveOperation === CoreResourceOperation.CREATE_MANY) {
-                        return z.object({
-                            data: z.array(underlyingRequestDto),
-                        });
-                    }
-                    if (isZodObject(underlyingRequestDto)) {
-                        return Resources_BulkOperationBaseSchema.extend(getZodObjectShape(underlyingRequestDto));
-                    }
-                    return Resources_BulkOperationBaseSchema.and(underlyingRequestDto);
-                }
-            }
-            return effectiveOperation === CoreResourceOperation.CREATE_MANY
-                ? z.object({
-                    data: z.array(z.object({})),
-                })
-                : Resources_BulkOperationBaseSchema;
+            // The ROW of a batch create is a CREATE row. Rebuilding it as CREATE_MANY would return the
+            // `{ data: row[] }` envelope (see the CREATE_MANY branch below) and this wrap would nest it twice.
+            const underlyingRequestDto = this.buildEnhancedRequestDto(underlyingOperation, effectiveOperation === CoreResourceOperation.CREATE_MANY ? CoreResourceOperation.CREATE : effectiveOperation);
+            // Wrap as the bulk request, WITH this operation's batch limit (`wrapRequestDtoAsBulk`).
+            const hasRowInput = !!underlyingRequestDto
+                && !isZodAny(underlyingRequestDto)
+                && this.analyzeDtoSchema(underlyingRequestDto) !== '📄 {} (empty object)';
+            return wrapRequestDtoAsBulk({
+                rowRequestDto: hasRowInput ? underlyingRequestDto : undefined,
+                maxSelection: resolveBulkOperationMaxSelection(operation),
+                isCreate: effectiveOperation === CoreResourceOperation.CREATE_MANY,
+            });
+        }
+        /*
+         * CREATE_MANY takes a BATCH: `{ data: row[] }`, at most the batch limit (#1551).
+         *
+         * It shared the single-row branch below, so its request was ONE row while `createMany` validates
+         * the whole `{ data: [...] }` payload against this DTO (`validateAndTransformInput`, loose parse)
+         * and then reads `.data` as the rows (`normalizeCreateManyInput`). A resource with any required
+         * field could therefore not be batch-created at all. The envelope is built by the same
+         * `wrapRequestDtoAsBulk` every other batch request uses, so the row shape and the limit have one
+         * construction.
+         */
+        if (effectiveOperation === CoreResourceOperation.CREATE_MANY) {
+            return wrapRequestDtoAsBulk({
+                rowRequestDto: this.createRequestDtoForCreate(operation.mainSchema),
+                maxSelection: resolveBulkOperationMaxSelection(operation),
+                isCreate: true,
+            });
         }
         // For create operations, use decorator-aware DTO building
-        if (effectiveOperation === CoreResourceOperation.CREATE || effectiveOperation === CoreResourceOperation.CREATE_MANY) {
+        if (effectiveOperation === CoreResourceOperation.CREATE) {
             return this.createRequestDtoForCreate(operation.mainSchema);
         }
         // For update operations, use decorator-aware DTO building
@@ -682,7 +786,8 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
         // an operation that declares nothing, which is the 500 this whole change exists to remove, in a
         // new place. SEARCH's repository default stays 50, so its pages sit comfortably inside this.
         if (effectiveOperation === CoreResourceOperation.LIST || effectiveOperation === CoreResourceOperation.SEARCH) {
-            return this.createPaginatedResponseSchema(operation.mainSchema, operation.maxPaginatedResultPerPageLimit ?? 100);
+            return this.createPaginatedResponseSchema(operation.mainSchema, operation.maxPaginatedResultPerPageLimit
+                ?? (effectiveOperation === CoreResourceOperation.SEARCH ? DEFAULT_SEARCH_PAGE_CEILING : DEFAULT_LIST_PAGE_CEILING));
         }
         // Apply operation-specific default patterns
         const defaultResponse = getDefaultResponseSchemaForOperation(effectiveOperation, operation.mainSchema);
@@ -737,7 +842,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
                 const modifiedOptions = options.map(option => this.applyCreateOmissionsToSchema(option));
                 // Recreate discriminated union with modified variants
                 if (modifiedOptions.length >= 2) {
-                    return z.discriminatedUnion(discriminator, modifiedOptions);
+                    return this.preserveRegistryMetadata(mainSchema, z.discriminatedUnion(discriminator, modifiedOptions));
                 }
                 else if (modifiedOptions.length === 1) {
                     return modifiedOptions[0];
@@ -817,7 +922,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             }
         }
         catch (error) {
-            throw new Error(`Failed to create request DTO for CREATE: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`Failed to create request DTO for CREATE: ${describeCaughtError(error)}`);
         }
         return this.stripTemplatableFileFieldsRecursively(schema);
     }
@@ -933,7 +1038,8 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
                 .enum(Array.from(discriminatorValues))
                 .optional();
         }
-        return z.object(mergedShape);
+        // The merged inheritance UPDATE root is written PATCH style like any other UPDATE root (#989).
+        return markPatchRequestDtoObject(z.object(mergedShape));
     }
     /**
      * Extract the concrete discriminator value(s) a union-option's discriminator
@@ -1042,10 +1148,11 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
                     ? strippedField
                     : toPatchOptionalField(strippedField);
             }
-            return z.object(updateShape);
+            // PATCH write rule: the form clears this object's direct fields with an explicit null (#989).
+            return markPatchRequestDtoObject(z.object(updateShape));
         }
         catch (error) {
-            throw new Error(`Failed to create request DTO for UPDATE: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`Failed to create request DTO for UPDATE: ${describeCaughtError(error)}`);
         }
         return this.stripTemplatableFileFieldsRecursively(schema);
     }
@@ -1066,7 +1173,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
                 const modifiedOptions = options.map(option => this.applyVirtualFieldExclusionToSchema(option));
                 // Recreate discriminated union with modified variants
                 if (modifiedOptions.length >= 2) {
-                    return z.discriminatedUnion(discriminator, modifiedOptions);
+                    return this.preserveRegistryMetadata(mainSchema, z.discriminatedUnion(discriminator, modifiedOptions));
                 }
                 else if (modifiedOptions.length === 1) {
                     return modifiedOptions[0];
@@ -1099,7 +1206,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             }
         }
         catch (error) {
-            throw new Error(`Failed to exclude virtual fields from schema: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`Failed to exclude virtual fields from schema: ${describeCaughtError(error)}`);
         }
         return schema;
     }
@@ -1878,9 +1985,11 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
                 _id: z.never().optional()
             });
             // UPDATE DTO should have _id as required
-            const updateWithRequiredId = childUpdateDto.extend({
+            // `.extend()` returns a fresh object without the child UPDATE DTO's metadata; its PATCH write
+            // rule has to survive, or a form reads the update branch as written whole (#989).
+            const updateWithRequiredId = this.preserveSchemaMetadata(childUpdateDto, childUpdateDto.extend({
                 _id: z.string()
-            });
+            }));
             return z.union([updateWithRequiredId, createWithoutId]);
         }
         // Fallback: use UPDATE DTO
@@ -1930,7 +2039,8 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             return baseDto;
         }
         if (isZodObject(baseDto)) {
-            return baseDto.extend(extensionShape);
+            // Carry the base DTO's metadata (its PATCH write rule among it) across the extension (#989).
+            return this.preserveSchemaMetadata(baseDto, baseDto.extend(extensionShape));
         }
         const zodType = getZodType(baseDto);
         if (zodType === 'union') {
@@ -1938,11 +2048,11 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             const unionOptions = getZodDefArrayProperty(baseDto, 'options');
             if (discriminator && unionOptions && unionOptions.length > 0) {
                 const extendedOptions = unionOptions.map((option) => isZodObject(option)
-                    ? option.extend(extensionShape)
+                    ? this.preserveSchemaMetadata(option, option.extend(extensionShape))
                     : option);
                 if (extendedOptions.every((option) => isZodObject(option))) {
                     if (extendedOptions.length >= 2) {
-                        return z.discriminatedUnion(discriminator, extendedOptions);
+                        return this.preserveRegistryMetadata(baseDto, z.discriminatedUnion(discriminator, extendedOptions));
                     }
                     if (extendedOptions.length === 1) {
                         return extendedOptions[0];
@@ -1997,7 +2107,8 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             const childConfig = resourceRegistry.get(compiledRel.resourceType2);
             if (!childConfig)
                 continue;
-            const childSchema = this.buildNestedChildSchema(compiledRel, nestedConfig, operation, childConfig.mainSchema, resourceRegistry);
+            // A nested write carries records of the CHILD resource, so it is described by the child (#1625).
+            const childSchema = markEmbeddedResourceSchema(this.buildNestedChildSchema(compiledRel, nestedConfig, operation, childConfig.mainSchema, resourceRegistry), String(compiledRel.resourceType2));
             // Add nested field (array for 1:N/N:N, object for 1:1)
             nestedFields[fieldName] = isArrayCardinality(compiledRel.cardinality2)
                 ? z.array(childSchema).optional()
@@ -2033,7 +2144,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             const childConfig = resourceRegistry.get(compiledRel.resourceType2);
             if (!childConfig)
                 continue;
-            const childSchema = this.getChildSchemaForDataMode(childConfig.mainSchema, readConfig.dataMode);
+            const childSchema = markEmbeddedResourceSchema(this.getChildSchemaForDataMode(childConfig.mainSchema, readConfig.dataMode), String(compiledRel.resourceType2));
             // Add nested field (array for 1:N/N:N, object for 1:1)
             nestedFields[fieldName] = isArrayCardinality(compiledRel.cardinality2)
                 ? z.array(childSchema).optional()
@@ -2140,6 +2251,32 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
      * @returns New schema without backend-only fields
      */
     static stripBackendOnlyFields(schema, options) {
+        /*
+         * Memoized by input identity within the active resource scope, per effective mode (#1587;
+         * see {@link DtoDerivationMemoScope}). The two options only ever act
+         * TOGETHER — a field is kept for `isReturnedAtCreation` exactly when both are set for CREATE —
+         * so they collapse to one boolean, and the walk is otherwise a pure function of the schema.
+         * Without the memo every operation rebuilt its nested objects afresh, which also defeated the
+         * network-boundary coercion memo downstream: that one is keyed by identity too, and a fresh
+         * nested object is never a hit.
+         */
+        const keepsReturnedAtCreation = options?.respectIsReturnedAtCreation === true
+            && options.operationType === CoreResourceOperation.CREATE;
+        const scope = this.activeMemoScope;
+        if (scope === null)
+            return this.stripBackendOnlyFieldsUncached(schema, options);
+        const memo = keepsReturnedAtCreation
+            ? scope.backendOnlyStripKeepingReturnedAtCreation
+            : scope.backendOnlyStrip;
+        const cached = memo.get(schema);
+        if (cached !== undefined)
+            return cached;
+        const stripped = this.stripBackendOnlyFieldsUncached(schema, options);
+        memo.set(schema, stripped);
+        return stripped;
+    }
+    /** The uncached walk behind {@link stripBackendOnlyFields}; recursion goes through the memo. */
+    static stripBackendOnlyFieldsUncached(schema, options) {
         // Handle discriminated unions - strip from all variants
         const zodType = getZodType(schema);
         if (zodType === 'union') {
@@ -2149,12 +2286,25 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
                 const strippedOptions = unionOptions.map((option) => this.stripBackendOnlyFields(option, options));
                 // Recreate discriminated union with modified variants
                 if (strippedOptions.length >= 2) {
-                    return z.discriminatedUnion(discriminator, strippedOptions);
+                    return this.preserveRegistryMetadata(schema, z.discriminatedUnion(discriminator, strippedOptions));
                 }
                 else if (strippedOptions.length === 1) {
                     return strippedOptions[0];
                 }
             }
+            // A PLAIN union is stripped option by option too. The context placeholder for a related
+            // record is exactly this shape — `z.union([typedRelative, untypedRelative])`, with the typed
+            // branch built from the related resource's full schema so the service-layer DTO can carry its
+            // backend-only fields. Returning it unchanged left those fields in the CLIENT response DTO, so
+            // the API reference published e.g. `application.ownerOrganizationSerializationToken` on every
+            // context read that embeds the application (#1625).
+            if (!discriminator && unionOptions && unionOptions.length >= 2) {
+                const strippedOptions = unionOptions.map((option) => this.stripBackendOnlyFields(option, options));
+                if (strippedOptions.every((option, index) => option === unionOptions[index])) {
+                    return schema;
+                }
+                return this.preserveRegistryMetadata(schema, z.union(strippedOptions));
+            }
             return schema;
         }
         // Handle arrays - strip from array element schema.
@@ -2260,7 +2410,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
      * ```
      */
     static createApiParsingSchema(schema) {
-        return this.applyNetworkBoundaryCoercion(schema);
+        return this.withMemoScope(API_PARSING_MEMO_SCOPE, () => this.applyNetworkBoundaryCoercion(schema));
     }
     /**
      * Recursively transpose the two network-boundary leaf types that do NOT survive
@@ -2302,8 +2452,36 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
      *
      * @param schema - Schema to transform (typically a database/internal schema with z.date()/z.bigint())
      * @returns New schema with coerced dates + string-accepting bigints
+     *
+     * **Memoized by input identity, and idempotent (#1587).** The walk is a pure function of the
+     * schema instance it is given, and the registry calls it on the SAME sub-schemas over and over:
+     * one registry build made 263,963 calls over 69,771 distinct inputs, 14,627 of them on a schema
+     * this function had itself just produced (`responseDtoInternal` coerced, then coerced again).
+     * Every call that reached an object containing a date rebuilt that object, so 146,352 calls
+     * returned a NEW tree. Zod 4 classic installs ~40 closures on every instance, which is why one
+     * resource registry retained ~735 MB, and why a platform process holding two of them outgrew a
+     * 2 GB heap and died in INIT.
+     *
+     * Every metadata write in this builder targets a freshly created instance, so sharing a coerced
+     * output among one resource's DTOs is safe. The memo is scoped to that resource, and why it must
+     * not be wider is on {@link DtoDerivationMemoScope}.
      */
     static applyNetworkBoundaryCoercion(schema) {
+        const memo = this.activeMemoScope?.networkBoundaryCoercion;
+        if (memo === undefined)
+            return this.coerceNetworkBoundaryLeaves(schema);
+        const cached = memo.get(schema);
+        if (cached !== undefined)
+            return cached;
+        const coerced = this.coerceNetworkBoundaryLeaves(schema);
+        memo.set(schema, coerced);
+        // A coerced schema is a fixed point: its dates are already `z.coerce.date()` (whose type still
+        // reads `date`, which is what made re-coercion rebuild everything) and its bigints are pipes.
+        memo.set(coerced, coerced);
+        return coerced;
+    }
+    /** The uncached walk behind {@link applyNetworkBoundaryCoercion}; recursion goes through the memo. */
+    static coerceNetworkBoundaryLeaves(schema) {
         // Handle discriminated unions - transform dates in all variants
         const zodType = getZodType(schema);
         if (zodType === 'union') {
@@ -2312,7 +2490,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             if (discriminator && unionOptions && unionOptions.length > 0) {
                 const transformedOptions = unionOptions.map((option) => this.applyNetworkBoundaryCoercion(option));
                 if (transformedOptions.length >= 2) {
-                    return z.discriminatedUnion(discriminator, transformedOptions);
+                    return this.preserveRegistryMetadata(schema, z.discriminatedUnion(discriminator, transformedOptions));
                 }
                 else if (transformedOptions.length === 1) {
                     return transformedOptions[0];
@@ -2432,7 +2610,7 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
                 // Extract summary from each variant and rebuild union
                 const summaryOptions = unionOptions.map((option) => this.extractSummaryFields(option)).filter(opt => opt !== null && opt !== undefined);
                 if (summaryOptions.length >= 2) {
-                    return z.discriminatedUnion(discriminator, summaryOptions);
+                    return this.preserveRegistryMetadata(schema, z.discriminatedUnion(discriminator, summaryOptions));
                 }
                 else if (summaryOptions.length === 1) {
                     return summaryOptions[0];
@@ -2480,23 +2658,183 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
                 });
             }
             catch (error) {
-                throw new Error(`Failed to derive summary schema for object: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to derive summary schema for object: ${describeCaughtError(error)}`);
             }
         }
         // For other schema types (primitives, etc.), return as-is
         return schema;
     }
+    /**
+     * The schema ONE populated context relative (a parent, or a child row) is described by.
+     *
+     * ## Why a typed schema, and why this shape (#1189)
+     *
+     * A populated relative used to be `z.record(z.string(), z.any())`, which types every embedded
+     * value as `any`. `applyNetworkBoundaryCoercion` has nothing to walk inside that, so every
+     * `z.date()` and `z.bigint()` leaf INSIDE an embed stayed in its wire form — an ISO string, or a
+     * decimal string for a money amount — while the value's declared type said `Date` / `bigint`.
+     *
+     * Measured 2026-09-15: on sign-in, `privacy.consentDecidedAt` reached the frontend as a string
+     * inside `userSelfPreferences` (a 1:1 child of the USER_SELF context read). The preferences event
+     * validated it against the in-memory `z.date()` and the whole event was dropped, so language,
+     * regional, theme and consent preferences all failed to reach their providers.
+     *
+     * ## The schema can only ADD coercion — never a refusal, never a strip
+     *
+     * Three properties, each load-bearing:
+     *
+     * - **Every field is OPTIONAL** (`.partial()`). What an embed actually carries depends on the
+     *   producer's projection and on `objectMode`, so a REQUIRED field would turn a response that
+     *   parses today into a hard validation failure — strictly worse than an uncoerced string.
+     * - **Unknown keys PASS THROUGH** (`.loose()`). Declaring a shape must not strip what the shape
+     *   does not mention. `z.object({ _id })` was tried for parents and dropped every SUMMARY/FULL
+     *   field they carried (#579); this keeps that class unrepresentable.
+     * - **The shape follows the relationship's resolved `objectMode`**, so a SUMMARY embed is typed by
+     *   the related resource's summary fields and a FULL embed by its whole schema. The
+     *   per-operation override is honoured, because these DTOs are built per operation.
+     *
+     * Falls back to the untyped record — i.e. exactly the previous behaviour — whenever the related
+     * schema cannot be read: an ID_ONLY relative (a bare reference has no leaf to coerce), a registry
+     * that does not hold the related resource, or a related schema that is not a plain object. The
+     * factory pass builds DTOs against an EMPTY registry, so it takes that fallback for everything and
+     * the typed form appears at `rebuildResourceConfigurationsOperationDtos`, which every serving and
+     * documenting consumer runs.
+     *
+     * A POLYMORPHIC relative is typed by its base object, so the variants' own fields pass through
+     * loose and uncoerced. That is a partial improvement rather than a regression, and it is the same
+     * fallback reasoning: a discriminated union has no `.partial()`.
+     *
+     * @param relatedResourceType - The resource on the other side of the relationship
+     * @param contextPolicy - That relationship's context policy (its `objectMode` decides the shape)
+     * @param effectiveOperation - The operation these DTOs are being built for, for `operationOverrides`
+     * @param registry - Resource registry; empty during the factory pass
+     * @returns A single-object schema for one relative (callers wrap it in `.optional()` / `z.array`)
+     */
+    static buildContextRelativeObjectSchema(relatedResourceType, contextPolicy, effectiveOperation, registry, stripBackendOnly = false) {
+        // Zod 4 requires key and value schemas for z.record
+        const untypedRelative = z.record(z.string(), z.any());
+        // Every placeholder is marked as an embedded `relatedResourceType` record (#1625). Marked HERE,
+        // inside the memo, because `.meta()` clones: marked at the call site, each context DTO received
+        // its own outer instance and the sharing the memo exists for (#1587) never reached the DTO. The
+        // mark reads only `relatedResourceType`, which the memo key (its main schema) already fixes.
+        const mark = (relative) => markEmbeddedResourceSchema(relative, String(relatedResourceType));
+        const objectMode = contextPolicy?.operationOverrides?.[effectiveOperation]?.objectMode
+            ?? contextPolicy?.objectMode
+            ?? DEFAULT_RELATIONSHIP_CONTEXT_POLICY.objectMode;
+        // ID_ONLY carries a bare reference: no fetch, so no leaf to coerce.
+        if (objectMode === ContextPolicy_ObjectMode.ID_ONLY) {
+            return mark(untypedRelative);
+        }
+        const relatedMainSchema = registry.get(relatedResourceType)?.mainSchema;
+        if (!relatedMainSchema || !isZodObject(relatedMainSchema)) {
+            return mark(untypedRelative);
+        }
+        /*
+         * Memoized by (related main schema, resolved objectMode, stripBackendOnly) — the only three inputs
+         * the shape below reads (#1587, #1625); the flag selects the memo map rather than keying it. It is built per operation × relationship, so the same summary derivation,
+         * coercion and union were rebuilt for every operation of every resource that embeds a relative:
+         * 107 MB of one resource registry's heap. Callers only ever WRAP the result (`.optional()`,
+         * `z.array`), never write to it, so within the active resource scope one instance serves every
+         * placeholder that asks for it.
+         */
+        const memoScope = this.activeMemoScope;
+        const memo = stripBackendOnly ? memoScope?.clientContextRelative : memoScope?.contextRelative;
+        if (memo === undefined)
+            return mark(this.composeContextRelativeObjectSchema(relatedMainSchema, objectMode, untypedRelative, stripBackendOnly));
+        let byObjectMode = memo.get(relatedMainSchema);
+        const cachedRelative = byObjectMode?.get(objectMode);
+        if (cachedRelative !== undefined)
+            return cachedRelative;
+        if (byObjectMode === undefined) {
+            byObjectMode = new Map();
+            memo.set(relatedMainSchema, byObjectMode);
+        }
+        const composedRelative = mark(this.composeContextRelativeObjectSchema(relatedMainSchema, objectMode, untypedRelative, stripBackendOnly));
+        byObjectMode.set(objectMode, composedRelative);
+        return composedRelative;
+    }
+    /** The uncached shape behind {@link buildContextRelativeObjectSchema}. */
+    static composeContextRelativeObjectSchema(relatedMainSchema, objectMode, untypedRelative, stripBackendOnly) {
+        let relativeSchema = relatedMainSchema;
+        if (objectMode === ContextPolicy_ObjectMode.SUMMARY) {
+            // Mirrors the summary DTO's own derivation, including its fallback: a resource that marks NO
+            // summary field is served its whole object, so the embed must be typed by the whole schema
+            // too. The emptiness test deliberately runs on a derivation WITHOUT `_id` — `includeId` adds
+            // it unconditionally, so asking the id-bearing shape whether it is empty always answers no,
+            // and every such resource would be typed `{ _id }` with its every other leaf left uncoerced.
+            const summaryFieldsOnly = ResourcesSummaryUtils.deriveSummarySchema(relatedMainSchema, {
+                includeId: false,
+                includeForeignKeys: false,
+            });
+            if (Object.keys(getZodObjectShape(summaryFieldsOnly)).length > 0) {
+                relativeSchema = ResourcesSummaryUtils.deriveSummarySchema(relatedMainSchema, {
+                    includeId: true,
+                    includeForeignKeys: false,
+                });
+            }
+        }
+        // The CLIENT placeholder drops the related resource's backend-only fields, stripped here BEFORE
+        // coercion because coercion rebuilds wrappers and can erase the `isBackendOnly` mark the strip
+        // reads. The client context DTO is assembled AFTER the response DTO's own strip pass, so nothing
+        // later would remove them, and the API reference published them (#1625). The service-layer
+        // placeholder keeps them. Runtime parsing is unchanged either way: the typed branch is `.loose()`
+        // and the union falls back to any record, so this changes what the contract DECLARES.
+        if (stripBackendOnly) {
+            relativeSchema = this.stripBackendOnlyFields(relativeSchema);
+        }
+        // Coerced HERE rather than left to a later pass: the CONTEXT variant's `responseDto` IS this
+        // `contextDto`, and nothing re-coerces it after the variant override (step 10).
+        const coercedRelativeSchema = this.applyNetworkBoundaryCoercion(relativeSchema);
+        if (!isZodObject(coercedRelativeSchema)) {
+            return untypedRelative;
+        }
+        // Backend-only fields are kept on the SERVICE-layer placeholder (`stripBackendOnly: false`): it
+        // types the `internalDto`, where they legitimately appear, and declaring them means their dates
+        // are coerced too. The client placeholder was stripped above.
+        const typedRelative = coercedRelativeSchema.partial().loose();
+        // The union is what makes "can only ADD coercion" true rather than nearly true.
+        //
+        // `.partial()` reaches the TOP level only, so a nested object inside the related schema keeps
+        // its required leaves. An embed that omits one — a projection this builder cannot see, an
+        // application's own resource shaped differently from its schema — would then turn a response
+        // that parses today into a hard validation failure, and a whole context read would be refused
+        // over a field nobody reads. Trying the typed schema FIRST and falling back to the untyped
+        // record bounds the worst case at exactly the previous behaviour: uncoerced, never rejected.
+        return z.union([typedRelative, untypedRelative]);
+    }
     /**
      * Add relationship placeholders to schema for context DTO.
-     * Placeholders are optional fields: parentResourceType?: { _id: string }
+     * Placeholders are optional and named by `Resources_SharedUtils.resolveRelationshipObjectIdentity`
+     * — the same authority `ResourcePopulationBackendService.populateForContext` names them with.
+     * Each one's SHAPE comes from {@link buildContextRelativeObjectSchema}.
      *
      * @param schema - Base schema
      * @param relationships - Resource relationships configuration
+     * @param effectiveOperation - Operation these DTOs are for, for per-operation context overrides
      * @param registry - Resource registry for type resolution
      * @returns Schema with relationship placeholders added
      */
-    static addRelationshipPlaceholders(schema, relationships, registry) {
-        // Only add placeholders to object schemas
+    static addRelationshipPlaceholders(schema, relationships, effectiveOperation, registry, stripBackendOnly = false) {
+        // A POLYMORPHIC resource's response is a discriminated union: every variant carries the same
+        // relationships, so every variant gets the same placeholders, and the union is rebuilt with the
+        // discriminator it had — the pattern `excludeVirtualFieldsFromSchema` already uses. Returning a
+        // union unchanged (the previous behaviour) left its context DTO with NO placeholder at all, so
+        // `internalDto.parse` and the response serializer stripped every populated child and parent of,
+        // e.g., Wonder Todos' `todos` — and the generated API reference documented its context as the
+        // plain read response. A union WITHOUT a discriminator has no rebuild this builder can promise,
+        // so it stays as-is.
+        if (getZodType(schema) === 'union') {
+            const discriminator = getZodDefStringProperty(schema, 'discriminator');
+            const options = getZodDefArrayProperty(schema, 'options');
+            if (discriminator && options && options.length > 0) {
+                const withPlaceholders = options.map((option) => this.addRelationshipPlaceholders(option, relationships, effectiveOperation, registry, stripBackendOnly));
+                return withPlaceholders.length >= 2
+                    ? this.preserveRegistryMetadata(schema, z.discriminatedUnion(discriminator, withPlaceholders))
+                    : withPlaceholders[0];
+            }
+            return schema;
+        }
+        // Otherwise only object schemas carry placeholders
         if (!isZodObject(schema)) {
             return schema;
         }
@@ -2511,10 +2849,13 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             const fieldName = this.getRelationshipObjectFieldName(relationship, relationship.resourceType1, ResourceRelationshipCardinality.ONE, registry);
             // Only add if field doesn't already exist (avoid conflicts)
             if (!shape[fieldName]) {
-                // Placeholder format: parentResourceType?: { _id: string }
-                placeholderFields[fieldName] = z.object({
-                    _id: z.string()
-                }).optional();
+                // A parent carries what its contextPolicy's `objectMode` fetched — a bare reference for
+                // ID_ONLY, the parent's summary fields for SUMMARY (the default), its whole object for FULL
+                // — and the placeholder is typed from that same mode, optional-everywhere and loose (#1189).
+                // It was once `z.object({ _id })`, which stripped every SUMMARY/FULL field even under the
+                // right name: no parent object had ever reached a client, on any resource (#579). That is
+                // why the typed form below can only ever ADD coercion.
+                placeholderFields[fieldName] = this.buildContextRelativeObjectSchema(relationship.resourceType1, relationship.contextPolicy, effectiveOperation, registry, stripBackendOnly).optional();
             }
         }
         // Add child relationship placeholders (includes self-refs acting as children)
@@ -2537,9 +2878,10 @@ export class ResourcesConfigOperationsDtosBuilderUtils {
             const isOneToOne = isOneToOneCardinality(relationship.cardinality2);
             // Only add if field doesn't already exist (avoid conflicts)
             if (!shape[fieldName]) {
-                // Use a passthrough schema to allow any fields from the child
-                // Zod 4 requires key and value schemas for z.record
-                const childPlaceholder = z.record(z.string(), z.any());
+                // Typed from the child's own schema by the relationship's resolved `objectMode`, with every
+                // field optional and unknown keys passed through, so the declaration coerces the child's
+                // date and money leaves without being able to strip or refuse anything (#1189).
+                const childPlaceholder = this.buildContextRelativeObjectSchema(relationship.resourceType2, relationship.contextPolicy, effectiveOperation, registry, stripBackendOnly);
                 if (isOneToOne) {
                     // 1:1: single object (optional)
                     placeholderFields[fieldName] = childPlaceholder.optional();