@wildo-ai/saas-models 1.1.5 → 1.1.7

package/dist/esm/resources/resources-config.shared.factory.js

@@ -1,16 +1,19 @@
 import { ResourceConfiguration_QueueConfigSchema } from '../queue/queues.shared.schemas.js';
+import { markEmbeddedResourceSchema } from './embedded-resource-mark.shared.utils.js';
 import { normalizeScheduledRecoveryPolicy } from '../queue/jobs.shared.schemas.js';
 /**
  * Operations Shared Schemas
  *
  * Reusable operation schemas for bulk actions and common operations
  */
-import { ExpiresInDurationSchema, getImpersonalizeMaskValue, getImpersonalizeTreatment, getZodObjectShape, getZodType, isBackendOnlyField, isDiscriminatorField, isExcludedFromCreate, isExcludedFromUpdate, isBusinessKeyField, isZodObject, isSummaryField, isTemplatableFileField, isUniqueField, isVirtualField, SingleFileValueSchema, toPatchOptionalField, mainSchemaFieldIsClearable, unwrapSchema, getDataCategories, markPatchRequestDtoObject, } from '@wildo-ai/zod-decorators';
+import { ExpiresInDurationSchema, getImpersonalizeMaskValue, getImpersonalizeTreatment, getZodObjectShape, getZodType, isBackendOnlyField, isDiscriminatorField, isExcludedFromCreate, isExcludedFromUpdate, isBusinessKeyField, isZodObject, isSummaryField, isTemplatableFileField, isUniqueField, getUniqueFieldParams, isVirtualField, toPatchOptionalField, z_file, mainSchemaFieldIsClearable, unwrapSchema, getDataCategories, markPatchRequestDtoObject, isDBIndexed, } from '@wildo-ai/zod-decorators';
 import { z } from 'zod';
 import { ErrorType } from '../errors/errors.shared.schemas.js';
-import { ErasureRetentionMode, ResourceDataSubjectKind, RetentionStatus, RetentionStatusSchema } from '../compliance/privacy/impersonalization.shared.schemas.js';
+import { ErasureRetentionMode, ResourceDataSubjectKind, RetentionStatus, RetentionStatusSchema, StatutoryRetentionGround } from '../compliance/privacy/impersonalization.shared.schemas.js';
 import { buildImpersonalizeScrubPatch, collectDeclaredPersonalDataFields, IMPERSONALIZE_MASK_CONSTANT, isImpersonalizeNeverScrubFloorField, resolveImpersonalizeMaskValue, resolveImpersonalizeResetValue, } from '../compliance/privacy/impersonalization-scrub.shared.utils.js';
 import { RedactionType } from '../compliance/privacy/redaction.shared.schemas.js';
+import { DataRetentionClass, RETENTION_STARTED_AT_FIELD_NAME, ResourceRetentionBindingSchema, RetentionStartPoint, } from '../compliance/privacy/retention-schedule.shared.schemas.js';
+import { collectRowTtlPolicies, resolveRetentionStartFieldName } from '../compliance/privacy/retention-binding.shared.utils.js';
 import { unknownPersonalDataCategories } from '../compliance/privacy/personal-data-category.shared.schemas.js';
 /*
  * entrypoint-closure-waiver: this root-reachable module imports the external-data AUTHORING
@@ -30,13 +33,18 @@ import { unknownPersonalDataCategories } from '../compliance/privacy/personal-da
  * root-exported contract here ever starts inferring one.
  */
 import { HttpApiResourceBindingSchema, assertHttpApiBindingDialectCoherence } from '../http-api-binding/http-api-binding.shared.schemas.js';
+import { assertHttpApiWriteDeclarationCoherence, collectHttpApiWriteOperationFacts, resolveHttpApiWriteIdempotencyKeyRequirement, resolveHttpApiWriteVerb, } from './utils/http-api-write-declaration.shared.utils.js';
+import { describeNoSubjectDataStanceContradiction, personalFieldsContradictingNoSubjectDataStance } from './utils/no-subject-data-stance-coherence.shared.utils.js';
 import { HTTP_API_ENGINE_INJECTED_FIELDS, HTTP_API_TENANT_ANCHOR_FIELD, READ_THROUGH_ORGANIZATION_UNIT_FIELD_NAME, } from '../http-api-binding/read-through-engine-anchors.shared.js';
 import { HttpApiTransportDialect } from '../http-api-binding/http-api-transport-dialect.shared.js';
-import { ExternalDataDestinationPopulation, ExternalDataFieldCoercion, ExternalDataMappingEntryKind, ExternalDataPipelineDeclarationSchema, assertExternalDataPipelineDeclarationCoherence, } from '../external-data/external-data-pipeline.shared.schemas.js';
+import { ExternalDataConditionalOutcomeKind, ExternalDataDestinationPopulation, ExternalDataFieldCoercion, ExternalDataFieldOwner, ExternalDataMappingEntryKind, ExternalDataOrphanPolicy, ExternalDataPipelineDeclarationSchema, ExternalDataPipelineDirection, ExternalDataUnmappedValuePolicy, assertExternalDataPipelineDeclarationCoherence, resolveExternalDataFieldOwner, resolveExternalDataRemoteReferenceValueShape, } from '../external-data/external-data-pipeline.shared.schemas.js';
+import { CoreM2MNotificationChannel, CoreUserNotificationChannel, CoreUserNotificationTarget, M2MNotificationDefinitionSchema, UserNotificationDefinitionSchema, } from '../notifications/notifications.shared.schemas.js';
 import { HttpMethod } from '../requests/http-requests.shared.js';
+import { isSubmissionChallengeActionName } from '../security/submission-challenge/submission-challenge.shared.js';
 import { ConsumableToken_ConsumptionMode, TokenAuthenticationPolicy } from '../security/authentications/consumable-token.shared.schemas.js';
-import { OPERATION_VARIANT_KEY, wrapRequestDtoAsBulk, resolveBulkOperationMaxSelection, Resources_Filter_BaseSchema, Resources_Filter_DateRangeSchema, Resources_Filter_NumberRangeSchema, isResourcesFilterNumberRangeSchema, createPaginationRequestSchema, DEFAULT_LIST_PAGE_CEILING, DEFAULT_SEARCH_PAGE_CEILING, createPaginationResponseMetadataSchema, ResourceGeneratedOperationKind, ResourceSystemAccessMode, PersistenceAdapter, isPersistenceAdapter, SortOrder, ResourceCollectionExportResponseSchema, } from './resources-config.shared.schemas.js';
+import { OPERATION_VARIANT_KEY, wrapRequestDtoAsBulk, resolveBulkOperationMaxSelection, Resources_Filter_BaseSchema, Resources_Filter_DateRangeSchema, Resources_Filter_NumberRangeSchema, isResourcesFilterNumberRangeSchema, createPaginationRequestSchema, DEFAULT_LIST_PAGE_CEILING, DEFAULT_SEARCH_PAGE_CEILING, createPaginationResponseMetadataSchema, ResourceGeneratedOperationKind, ResourceSystemAccessMode, PersistenceAdapter, isPersistenceAdapter, SortOrder, ResourceCollectionExportFormat, ResourceCollectionExportRowScope, ResourceCollectionExportResponseSchema, getResourcesFilterPresenceTarget, } from './resources-config.shared.schemas.js';
 import { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from './resources.shared.core.definitions.js';
+import { requestSchemaCarriesField } from './utils/request-schema-field-carriage.shared.utils.js';
 import { PRIMARY_SCOPE_FIELD_IDENTIFIERS, PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE, FIELD_IDENTIFIER_TO_PRIMARY_SCOPE, RelationshipNature, ResourceOperationRiskLevel, ResourceOperationVariantType, ResourceOperation_ServiceRuntimeMode, ResourceParentResourceRequirement, ResourcePrimaryScope, ResourceRelationshipBulkAction, ResourceRelationshipBulkActionResultSchema, ResourceRelationshipBulkClearOperationRequestSchema, ResourceRelationshipBulkCreateOperationRequestSchema, ResourceRelationshipBulkLinkOperationRequestSchema, ResourceRelationshipBulkReplaceOperationRequestSchema, ResourceRelationshipBulkSetOperationRequestSchema, ResourceRelationshipBulkUnlinkOperationRequestSchema, ResourceRelationshipAccessScopeStrategy, ResourceRelationshipCardinality, ResourceTranspositionPolicy } from './resources.shared.schemas.js';
 import { createResourcesRelationship } from './resources-relationships.shared.factory.js';
 import { Resources_SharedUtils } from './resources.shared.utils.js';
@@ -45,7 +53,7 @@ import { ResourcesSummaryUtils } from './utils/resources-summary.utils.js';
 import { collectTemplatableFileFieldPaths, stripTemplatableFileFieldsRecursively } from './utils/templatable-file-fields.shared.utils.js';
 import { selectByPersistenceAdapter } from './utils/persistence-adapter-discrimination.shared.utils.js';
 import { isServiceResolvableDefaultOperation, SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES, URL_BEARING_OPERATION_VARIANT_TYPES, } from './utils/resource-operation-type-guards.utils.js';
-import { describeCaughtError } from '../errors/errors.shared.utils.js';
+import { describeCaughtError } from '../errors/caught-error-description.shared.utils.js';
 // --------------------------------
 // Error Helpers
 // --------------------------------
@@ -100,6 +108,94 @@ function createConfigurationError(message) {
     error.type = ErrorType.CONFIGURATION;
     return error;
 }
+/**
+ * Whether a dotted path names a field of the resource, descending through nested objects.
+ *
+ * Dotted because the PostgreSQL filter sanitizer admits a `field.sub` path under a planned JSONB root,
+ * so a filter or sort key may legitimately address a nested field. Each segment is unwrapped
+ * (optional, default, nullable) before its shape is read.
+ */
+function schemaHasFieldPath(shape, path) {
+    let current = shape;
+    for (const segment of path.split('.')) {
+        const field = current?.[segment];
+        if (!field)
+            return false;
+        const unwrapped = (unwrapSchema(field) ?? field);
+        current = isZodObject(unwrapped) ? getZodObjectShape(unwrapped) : undefined;
+    }
+    return true;
+}
+/**
+ * Refuse a collection operation whose `filterFields`, `sortFields` or own-field `searchableFields` name
+ * something the resource does not have (#1806, #1952).
+ *
+ * Both lists are passed to the repository VERBATIM — the filter allow-list and the sort allow-list are
+ * the declared names, nothing else — so a name that is not a field compiles into a condition on a
+ * column that does not exist. On MongoDB that matches nothing and answers an empty page; on PostgreSQL
+ * a filter fails on a missing column and a sort is silently dropped. Either way the caller gets a wrong
+ * answer with no error saying the filter is unsupported, and the published API reference advertises a
+ * query parameter that cannot work. Four such names had shipped when this was written: `role` on the
+ * organization-member searches (the field is `roles`), `joinedAt` there and on the user searches (no
+ * such field), and `hasExpiration` on six credential searches (a question about `expiresAt`, which
+ * nothing translated).
+ *
+ * A filter key is admitted when it names a field, or when it is a presence filter
+ * (`createResourcesFilterPresenceSchema`) whose TARGET names one — that is the one declared
+ * translation there is. A function-valued entry — the old "filter-ref transformer" slot — is refused:
+ * nothing ever applied it, so its key reached the database untranslated, which is this defect again.
+ *
+ * `searchableFields` joined the check with #1952: an own-field name reaches the repository verbatim like the
+ * other two, and `ORGANIZATIONS`' SEARCH had shipped `email`, a field an organization does not have — every
+ * organization search then failed on PostgreSQL (`column "email" does not exist`) while MongoDB quietly
+ * matched nothing. A RELATIONAL entry is checked for its `localField`, the half that lives on this resource;
+ * its `relatedJoinField` and `fields` belong to the related resource, which is not known here, and a related
+ * resource that cannot be resolved already contributes nothing at query time (the fail-safe documented on
+ * `SearchableRelationDescriptor`). `_id` is refused as a searchable field even though it is a field: search is a
+ * substring match, and MongoDB stores `_id` as an ObjectId and refuses a regex on it, so the search would answer
+ * 500 there. A row is found by id through a READ or an `_id` filter.
+ *
+ * Checked against the EFFECTIVE schema, after the framework injects its own fields, because those are
+ * the fields a row actually carries.
+ */
+function assertCollectionFieldsNameResourceFields(params) {
+    const { resourceIdentifier, operationLabel, schemaShape, filterFields, sortFields, searchableFields } = params;
+    for (const [key, declaration] of Object.entries(filterFields ?? {})) {
+        if (typeof declaration === 'function') {
+            throw createConfigurationError(`Resource "${resourceIdentifier}" ${operationLabel}: filter "${key}" is a function. Filter-ref transformers are not supported — nothing applies them, so the key would reach the database untranslated. `
+                + 'Declare the field\'s Zod type, or `createResourcesFilterPresenceSchema(<field>)` for a "has <field>" filter.');
+        }
+        const presenceTarget = getResourcesFilterPresenceTarget(declaration);
+        if (presenceTarget !== undefined) {
+            if (!schemaHasFieldPath(schemaShape, presenceTarget)) {
+                throw createConfigurationError(`Resource "${resourceIdentifier}" ${operationLabel}: presence filter "${key}" asks about "${presenceTarget}", which is not a field of the resource.`);
+            }
+            continue;
+        }
+        if (!schemaHasFieldPath(schemaShape, key)) {
+            throw createConfigurationError(`Resource "${resourceIdentifier}" ${operationLabel}: filter "${key}" is not a field of the resource, so it would match nothing. `
+                + 'Name a field, or declare `createResourcesFilterPresenceSchema(<field>)` for a "has <field>" filter.');
+        }
+    }
+    for (const field of sortFields ?? []) {
+        if (!schemaHasFieldPath(schemaShape, field)) {
+            throw createConfigurationError(`Resource "${resourceIdentifier}" ${operationLabel}: sort field "${field}" is not a field of the resource, so sorting by it would be ignored.`);
+        }
+    }
+    for (const entry of searchableFields ?? []) {
+        const ownField = typeof entry === 'string' ? entry : undefined;
+        const localField = entry && typeof entry === 'object' ? entry.localField : undefined;
+        if (ownField === '_id') {
+            throw createConfigurationError(`Resource "${resourceIdentifier}" ${operationLabel}: "_id" cannot be a searchable field. Search is a substring match, and MongoDB refuses a regex on an ObjectId; find a row by id with a READ or an \`_id\` filter.`);
+        }
+        if (ownField !== undefined && !schemaHasFieldPath(schemaShape, ownField)) {
+            throw createConfigurationError(`Resource "${resourceIdentifier}" ${operationLabel}: searchable field "${ownField}" is not a field of the resource, so a search on it fails on PostgreSQL and matches nothing on MongoDB.`);
+        }
+        if (typeof localField === 'string' && !schemaHasFieldPath(schemaShape, localField)) {
+            throw createConfigurationError(`Resource "${resourceIdentifier}" ${operationLabel}: relational searchable entry joins on "${localField}", which is not a field of the resource.`);
+        }
+    }
+}
 /**
  * Creates a validation error with ErrorType.VALIDATION
  * Used for runtime data validation errors
@@ -118,6 +214,30 @@ function createValidationError(message) {
 function isUrlisableOperationVariantType(variantType) {
     return URL_BEARING_OPERATION_VARIANT_TYPES.includes(variantType);
 }
+/**
+ * Refuse a `submissionChallenge` declaration the runtime could never honour (#1985).
+ *
+ * - On a variant that receives no HTTP request (INTERNAL_CALL, a cron or batch job, REPOSITORY_ONLY), no caller can send
+ *   the `x-submission-challenge-response` header, and such a variant is reached by the server rather than by a visitor.
+ *   The declaration would say "protected" while refusing every unauthenticated execution.
+ * - An action outside the captcha vendor's grammar would be minted by no vendor, so every token for it would be refused
+ *   and only the proof of work could answer: a protection that silently loses half of itself.
+ *
+ * Thrown while the resource configuration is BUILT, so the application cannot start with either shape. The INLINE
+ * requirement is checked at application start instead, because the runtime mode can be set after this factory runs.
+ */
+function assertSubmissionChallengeDeclaration(operation, variantType, declaration) {
+    if (declaration === undefined)
+        return;
+    if (!isUrlisableOperationVariantType(variantType)) {
+        throw createConfigurationError(`Operation '${operation}' declares a submission challenge on a '${variantType}' variant. Only a variant reached by an `
+            + 'HTTP request can receive the challenge answer; declare it on the API_CALL variant a visitor calls.');
+    }
+    if (!isSubmissionChallengeActionName(declaration.action)) {
+        throw createConfigurationError(`Operation '${operation}' declares the submission-challenge action '${String(declaration.action)}'. An action is 1 to 100 `
+            + 'letters, digits, underscores or slashes, the only names a captcha vendor mints tokens for.');
+    }
+}
 /**
  * The operations a `retentionPolicy` resource must expose to the SERVICE dispatch
  * layer, with the retention primitive that needs each one.
@@ -280,7 +400,7 @@ export function reconcileGeneratedRelationshipBulkOperations(resourceConfigurati
     }
 }
 /**
- * Derive the CSV/JSON export companion of every LIST/SEARCH operation that declared
+ * Derive the file-export companion of every LIST/SEARCH operation that declared
  * `collectionExport`.
  *
  * ## Why derived rather than authored
@@ -329,9 +449,27 @@ function createGeneratedCollectionExportOperations(params) {
         if (!exportConfig.rowScopes || exportConfig.rowScopes.length === 0) {
             throw createConfigurationError(`[${params.resourceIdentifier}] operation "${sourceOperationIdentifier}" declares collectionExport with no rowScopes; declare at least one, or omit collectionExport entirely`);
         }
+        // A PDF is rendered by a template, so declaring the format without naming one leaves the export
+        // nothing to render with; naming one without the format is a declaration nothing reads (#1645).
+        const offersPdf = exportConfig.formats.includes(ResourceCollectionExportFormat.PDF);
+        if (offersPdf && !exportConfig.pdfTemplateId?.trim()) {
+            throw createConfigurationError(`[${params.resourceIdentifier}] operation "${sourceOperationIdentifier}" offers the PDF collection-export format but names no pdfTemplateId; a PDF export is rendered by a template`);
+        }
+        if (!offersPdf && exportConfig.pdfTemplateId !== undefined) {
+            throw createConfigurationError(`[${params.resourceIdentifier}] operation "${sourceOperationIdentifier}" names collectionExport.pdfTemplateId but does not offer the PDF format; add ResourceCollectionExportFormat.PDF or remove the template id`);
+        }
         if (exportConfig.maximumExportedRows !== undefined && exportConfig.maximumExportedRows <= 0) {
             throw createConfigurationError(`[${params.resourceIdentifier}] operation "${sourceOperationIdentifier}" declares a non-positive collectionExport.maximumExportedRows; omit it for no ceiling`);
         }
+        // A PDF cannot stream: the template lays out every row at once, in memory, before a byte is sent. So a
+        // whole-set PDF must declare how many rows it will hold — an unbounded one is an allocation any
+        // caller with the listing's roles can make as large as the table (#1645). CSV and JSON stream and
+        // keep their optional ceiling.
+        if (offersPdf
+            && exportConfig.rowScopes.includes(ResourceCollectionExportRowScope.FULL_RESULT_SET)
+            && exportConfig.maximumExportedRows === undefined) {
+            throw createConfigurationError(`[${params.resourceIdentifier}] operation "${sourceOperationIdentifier}" offers a whole-set PDF export without collectionExport.maximumExportedRows; a PDF is built in memory from every row, so it must declare its ceiling`);
+        }
         const operationIdentifier = Resources_SharedUtils.buildGeneratedCollectionExportOperationIdentifier(sourceOperationIdentifier);
         if (knownOperationIdentifiers.has(operationIdentifier)) {
             throw createConfigurationError(`[${params.resourceIdentifier}] generated collection export operation "${operationIdentifier}" collides with an existing operation identifier`);
@@ -467,8 +605,19 @@ function createGeneratedFileRegenerateOperations(params) {
     }
     const knownOperationIdentifiers = new Set(params.operations.map((operation) => String(operation.operationIdentifier)));
     const responseDto = z.object({
-        file: SingleFileValueSchema,
-        resource: generatedFileDiscoverySchema,
+        /*
+         * A FILE value, marked as one (`z_file()`), not the bare `SingleFileValueSchema` shape. The shape alone is a plain
+         * `{ fileId, updatedAt }` object, so every label walk read it as a nested object of two fields: the application
+         * labelling planner planned `fields.file.fileId` and `fields.file.updatedAt` for every resource carrying a generated
+         * PDF, words no screen reads (#1959). Marked, it classifies as `FieldSchemaType.FILE` like the field it was
+         * regenerated from, and is labelled — and displayed — as one file. Generated files are PDFs (`generation` pins that
+         * mime type on the source field), so the response says the same; the `generation` block itself names one template
+         * and cannot describe a DTO shared by every generated field of the resource.
+         */
+        file: z_file({ allowedMimeTypes: 'PDF' }).describe('The newly generated file.'),
+        // The record is this resource's own, so its fields are described by its specification (#1625).
+        resource: markEmbeddedResourceSchema(generatedFileDiscoverySchema, String(params.resourceIdentifier))
+            .describe('The record after the regenerated file was stored on it.'),
     });
     return generatedFields.map(({ fieldName }) => {
         const operationIdentifier = Resources_SharedUtils.buildGeneratedFileRegenerateOperationIdentifier(fieldName);
@@ -1262,16 +1411,53 @@ function processUserNotifications(userNotifications, resourceIdentifier, operati
             identifierParts.push(notification.level);
         }
         const autoGeneratedIdentifier = identifierParts.join("_");
-        return {
+        const processed = {
             ...notification,
             identifier: autoGeneratedIdentifier,
             primaryScope: resourcePrimaryScope
         };
+        assertUserNotificationDeclarationIsDeliverable(processed, resourceIdentifier, operationIdentifier);
+        return processed;
     });
 }
+/**
+ * Refuse a declared user notification the dispatcher could never deliver (#1874).
+ *
+ * `UserNotificationDefinitionSchema` states what is deliverable — a channel the dispatcher has an arm for, and a
+ * `userRoles` filter only on a target that reads it (#495) — but no build step ever parsed a declaration against it,
+ * so both rules held only in the type system and a test. A notification on an unknown channel (`'slack'`) was
+ * accepted and every dispatch sent nothing, visible only at debug level. Parsing here makes the same rule hold for
+ * every configuration, typed or not, at the moment it is built — the way the factory already refuses a filter,
+ * sort or search field that names nothing.
+ */
+function assertUserNotificationDeclarationIsDeliverable(notification, resourceIdentifier, operationIdentifier) {
+    const parsed = UserNotificationDefinitionSchema.safeParse(notification);
+    if (parsed.success)
+        return;
+    const declared = notification;
+    const problems = parsed.error.issues.map((issue) => `${issue.path.join('.') || '(notification)'}: ${issue.message}`).join('; ');
+    // A channel or target outside its vocabulary fails every member of the channel union, and Zod reports that as one
+    // path-less "Invalid input" — so those two are named from the value itself, with the members that would be valid.
+    const channelIsKnown = Object.values(CoreUserNotificationChannel).includes(declared.channel);
+    const targetIsKnown = Object.values(CoreUserNotificationTarget).includes(declared.target);
+    const reason = !channelIsKnown
+        ? `no delivery exists for channel '${String(declared.channel)}'. A channel must be one of ${quoteMembers(CoreUserNotificationChannel)}`
+        : !targetIsKnown
+            ? `'${String(declared.target)}' is not a notification target. A target must be one of ${quoteMembers(CoreUserNotificationTarget)}`
+            : problems;
+    throw createConfigurationError(`Operation '${resourceIdentifier}_${operationIdentifier}' declares a user notification (target '${String(declared.target)}', channel '${String(declared.channel)}') that cannot be delivered: ${reason}.`);
+}
+/** `'a', 'b', 'c'` — the members of a closed vocabulary, as a refusal names them. */
+function quoteMembers(vocabulary) {
+    return Object.values(vocabulary).map((member) => `'${member}'`).join(', ');
+}
 /**
  * Processes M2M notifications by auto-generating identifiers
  * Format: ${resourceIdentifier}_${operationIdentifier}_${channel}
+ *
+ * Each declaration is parsed against `M2MNotificationDefinitionSchema` and an undeliverable channel is refused
+ * here, when the configuration is built. It used to be accepted and to throw "not implemented" at dispatch — after
+ * the write, where the throw also skipped every later M2M notification of the same operation.
  */
 function processM2MNotifications(m2mNotifications, resourceIdentifier, operationIdentifier) {
     return m2mNotifications.map(notification => {
@@ -1281,10 +1467,17 @@ function processM2MNotifications(m2mNotifications, resourceIdentifier, operation
             operationIdentifier,
             notification.channel
         ].join("_");
-        return {
+        const processed = {
             ...notification,
             identifier: autoGeneratedIdentifier
         };
+        const parsed = M2MNotificationDefinitionSchema.safeParse(processed);
+        if (!parsed.success) {
+            throw createConfigurationError(`Operation '${resourceIdentifier}_${operationIdentifier}' declares an M2M notification on channel '${String(notification.channel)}' that cannot be delivered: `
+                + `${parsed.error.issues.map((issue) => `${issue.path.join('.') || '(notification)'}: ${issue.message}`).join('; ')}. `
+                + `A channel must be one of ${quoteMembers(CoreM2MNotificationChannel)}.`);
+        }
+        return processed;
     });
 }
 // --------------------------------
@@ -1590,7 +1783,10 @@ export function createResourceConfiguration_Initialization(params) {
     // lane", which is true of almost every resource — a default here would make every resource claim
     // to be one. The bindings are validated at boot, not here: this factory has the declaration but
     // not the registry, and a name resolves against the resource's own schema and operations.
-    subjectErasureLane, transpositionPolicy, retentionPolicy, dataSubjectPolicy, portabilityPolicy, persistenceAdapter, persistenceAdapterIsolation, httpApiBinding, introspectionBinding, coreOperations, customOperation, operationsConfiguration, } = params;
+    subjectErasureLane, transpositionPolicy, retentionPolicy, dataSubjectPolicy, retentionBinding: authoredRetentionBinding, portabilityPolicy, 
+    // #1598: `true` makes every row of this resource a CASE a model call can be attributed to. No default
+    // beyond `false`: a case is a product decision, and an unset flag means the resource is not one.
+    workUnit = false, persistenceAdapter, persistenceAdapterIsolation, httpApiBinding, introspectionBinding, coreOperations, customOperation, operationsConfiguration, } = params;
     /**
      * HTTP_API ↔ binding coherence — enforced at AUTHORING, both directions, because each half
      * alone is a contradiction the backend could only discover later and worse:
@@ -1699,7 +1895,13 @@ export function createResourceConfiguration_Initialization(params) {
         catch (error) {
             refuse(describeCaughtError(error));
         }
+        // #1679 / #1690 — whether the binding may open writes is the declaration's own coherence (an INBOUND pipeline
+        // refuses them, an OUTBOUND one requires them), checked above by `assertExternalDataPipelineDeclarationCoherence`.
         const shape = getZodObjectShape(mainSchema);
+        if (declaration.direction === ExternalDataPipelineDirection.OUTBOUND) {
+            validateExternalDataOutboundDeclarationAgainstSchema(declaration, shape, params.externalDataPipeline, refuse);
+            return declaration;
+        }
         const requireMappedTarget = (fieldName, context) => {
             const fieldSchema = shape[fieldName];
             if (!fieldSchema)
@@ -1759,9 +1961,38 @@ export function createResourceConfiguration_Initialization(params) {
                 refuse(`${label}: '${partitionField}' must be optional or nullable. A row whose remote partition field is unset is SHARED — it belongs to every caller and to no unit — and this stamp lands null on it, so a required target rejects exactly the rows every caller is entitled to see.`);
             }
         }
+        /*
+         * #1723 — a BIDIRECTIONAL pipeline's fields each have an OWNER, and the ownership rules follow it: a REMOTE field is
+         * the system of record's (excluded from caller writes, exactly as on an INBOUND pipeline); a LOCAL or BOTH field is
+         * the application's too, so callers must be able to write it — excluding it from both create and update would make
+         * the pipeline send a value nobody decided, the OUTBOUND rule.
+         */
+        const requireSentTarget = (fieldName, context) => {
+            const fieldSchema = shape[fieldName];
+            if (!fieldSchema)
+                refuse(`${context}: local field '${fieldName}' does not exist on mainSchema.`);
+            if (isExcludedFromCreate(fieldSchema) && isExcludedFromUpdate(fieldSchema)) {
+                refuse(`${context}: '${fieldName}' is sent to the system of record (owner LOCAL or BOTH) and is declared .excludeFromCreate() and `
+                    + '.excludeFromUpdate(), so no caller can ever set it and the pipeline would send a value nobody decided. Let callers write it, or declare it owner: REMOTE.');
+            }
+            return fieldSchema;
+        };
+        if (declaration.direction === ExternalDataPipelineDirection.BIDIRECTIONAL) {
+            // Rows born locally have no remote key until their create is sent, and "no key" must stay out of the unique index
+            // on every store: absent, never null (MongoDB indexes an explicit null) — the OUTBOUND rule (#2039 review).
+            if (keyFieldSchema.safeParse(null).success) {
+                refuse(`remoteKeyLocalField: '${declaration.remoteKeyLocalField}' accepts null. Declare it .optional(), not .nullable(): its unique index ignores a row with no key only while "no key" is ABSENT.`);
+            }
+            if (declaration.population === ExternalDataDestinationPopulation.OPEN && unwrapSchema(keyFieldSchema) === keyFieldSchema) {
+                refuse(`remoteKeyLocalField: '${declaration.remoteKeyLocalField}' must be optional — population OPEN lets rows be born here, and such a row has no remote key until its create is sent.`);
+            }
+        }
         for (const entry of declaration.mapping) {
-            const targetSchema = requireMappedTarget(entry.localField, `mapping('${entry.localField}')`);
-            if (entry.kind === ExternalDataMappingEntryKind.REMOTE_FIELD) {
+            const owner = resolveExternalDataFieldOwner(entry);
+            const targetSchema = owner === ExternalDataFieldOwner.REMOTE
+                ? requireMappedTarget(entry.localField, `mapping('${entry.localField}')`)
+                : requireSentTarget(entry.localField, `mapping('${entry.localField}')`);
+            if (entry.kind === ExternalDataMappingEntryKind.REMOTE_FIELD && owner !== ExternalDataFieldOwner.LOCAL) {
                 if (!entry.required && unwrapSchema(targetSchema) === targetSchema) {
                     refuse(`mapping('${entry.localField}'): a non-required remote field can be ABSENT on a row, and absence lands as null — the target must be optional/nullable/defaulted, or declare required: true (absent rows are then rejected and reported per row).`);
                 }
@@ -1780,6 +2011,31 @@ export function createResourceConfiguration_Initialization(params) {
                     entry.coercion = ExternalDataFieldCoercion.ODOO_FALSE_AS_NULL;
                 }
             }
+            /*
+             * #1684 — a REMOTE_REFERENCE writes a LOCAL foreign key, resolved after the load.
+             *
+             * STRING, because the value is a local row id (a pipeline target) or a synthesized key (a virtual
+             * target), and both are strings. ABSENCE-CAPABLE, because an empty remote reference and an unresolved
+             * one both leave it empty — a required target would make every row whose parent is not loaded yet
+             * unwritable. The relationship half (the field IS a declared foreign key to the target) is checked
+             * below, once relationships are compiled; whether the target is a pipeline destination or a virtual
+             * resource on the same system of record needs the TARGET's configuration, which only the resources
+             * registry holds, so it is refused at startup.
+             *
+             * The value shape defaults from the dialect HERE, like the Odoo false→null coercion above: this is the
+             * one place both the dialect and the author's silence are known, and the runtime reads only the
+             * resolved value.
+             */
+            if (entry.kind === ExternalDataMappingEntryKind.REMOTE_REFERENCE) {
+                if (!(unwrapSchema(targetSchema) instanceof z.ZodString)) {
+                    refuse(`mapping('${entry.localField}'): a REMOTE_REFERENCE writes a local foreign key, so its target must be a STRING field.`);
+                }
+                if (unwrapSchema(targetSchema) === targetSchema) {
+                    refuse(`mapping('${entry.localField}'): a REMOTE_REFERENCE leaves its foreign key EMPTY while the reference is empty or its target is not loaded yet, so the field must be optional or nullable.`);
+                }
+                entry.valueShape = resolveExternalDataRemoteReferenceValueShape(entry, declaration.binding.dialect);
+            }
+            validateExternalDataExpressionAgainstTarget(entry, targetSchema, declaration.binding.dialect, refuse);
         }
         if (declaration.population === ExternalDataDestinationPopulation.CLOSED) {
             // Enumerate by the operation's EFFECTIVE semantics, never by its identifier: a CORE operation
@@ -1960,6 +2216,34 @@ export function createResourceConfiguration_Initialization(params) {
         }
     }
     // ========================================
+    // HTTP_API × WRITES — what a writable read-through resource must declare (#1679)
+    // ========================================
+    //
+    // Everything decidable from this one file: the verbs the binding opens against the operations that
+    // perform them, no bulk write, INLINE only, no `Idempotency-Key: accepted`. (The erasure-stance rule
+    // that used to sit here is the #2010 check just above, which covers reads as well.) The rules and their reasons live on
+    // `assertHttpApiWriteDeclarationCoherence`. What needs the saas configuration (the instance's
+    // partition field) or the engine's dialect registry (whether the dialect can write at all) is
+    // checked at boot registration instead.
+    if (resolvedHttpApiBinding !== undefined) {
+        // #2010: a read-through resource's fields ARE the remote row's, so personal-data categories on them contradict a
+        // NO_SUBJECT_DATA stance whether or not the binding writes. The rule and its remedy live on the util.
+        const personalFields = personalFieldsContradictingNoSubjectDataStance({ stance: resolvedHttpApiBinding.erasure.stance, mainSchema });
+        if (personalFields.length > 0) {
+            throw createConfigurationError(`[${resourceIdentifier}] invalid httpApiBinding erasure stance: ${describeNoSubjectDataStanceContradiction({ system: resolvedHttpApiBinding.system, personalFields })}`);
+        }
+        try {
+            assertHttpApiWriteDeclarationCoherence({
+                binding: resolvedHttpApiBinding,
+                operations: collectHttpApiWriteOperationFacts(coreOperations, operationsConfiguration),
+                mainSchema,
+            });
+        }
+        catch (error) {
+            throw createConfigurationError(`[${resourceIdentifier}] invalid httpApiBinding write declaration: ${describeCaughtError(error)}`);
+        }
+    }
+    // ========================================
     // EXTERNAL-DATA PIPELINE × PRIMARY SCOPE — the destination is ORGANIZATIONS-owned, and the ENGINE
     // supplies the tenant
     // ========================================
@@ -1996,6 +2280,20 @@ export function createResourceConfiguration_Initialization(params) {
     // `application-creation-directive.md` sets for a refusal. None of them asks anyone to decide
     // anything: each names the one shape that works.
     if (externalDataPipeline !== undefined) {
+        // #2010: the fields a pipeline copies are what its source holds, so personal-data categories on them contradict
+        // a NO_SUBJECT_DATA stance on its binding. A CONSTANT entry reads nothing from the source; an unmapped field is
+        // the application's own. The same fields the privacy notice's source statement counts.
+        const copiedFields = new Set(externalDataPipeline.mapping
+            .filter((entry) => entry.kind !== ExternalDataMappingEntryKind.CONSTANT)
+            .map((entry) => entry.localField));
+        const copiedPersonalFields = personalFieldsContradictingNoSubjectDataStance({
+            stance: externalDataPipeline.binding.erasure.stance,
+            mainSchema,
+            sourcedFields: copiedFields,
+        });
+        if (copiedPersonalFields.length > 0) {
+            throw createConfigurationError(`[${resourceIdentifier}] invalid externalDataPipeline erasure stance: ${describeNoSubjectDataStanceContradiction({ system: externalDataPipeline.binding.system, personalFields: copiedPersonalFields })}`);
+        }
         const pipelineDestinationRefusal = (reason) => {
             throw createConfigurationError(`[${resourceIdentifier}] invalid externalDataPipeline declaration: ${reason}
 `
@@ -2093,6 +2391,32 @@ export function createResourceConfiguration_Initialization(params) {
          * create-shaped custom operations, and the admission of a declared caller CREATE. Those pins live
          * in `external-data-pipeline-coherence.test.ts` and still pass.
          */
+        /*
+         * (g) #1684 — every REMOTE_REFERENCE writes the foreign key of a DECLARED relationship to its target.
+         *
+         * The relationship is what makes the written value a foreign key to the rest of the framework — a
+         * picker, a nested read, a cascade — rather than a string that happens to hold a row id. So a reference
+         * whose local field is not the `foreignKeyField` of a relationship between this resource and the target
+         * would write a value nothing treats as a link: refused. A self-reference (Odoo `res.partner.parent_id`)
+         * is a relationship whose two ends are this resource.
+         *
+         * Checked here, where relationships are compiled; the target's own kind (pipeline destination or virtual
+         * resource on the same system of record) and the orphan-cascade acknowledgement need the TARGET's
+         * configuration and are refused at startup by the resources registry.
+         */
+        for (const entry of externalDataPipeline.mapping) {
+            if (entry.kind !== ExternalDataMappingEntryKind.REMOTE_REFERENCE)
+                continue;
+            const declaresEdge = relevantRelationships.some((relationship) => relationship.foreignKeyField === entry.localField
+                && (relationship.resourceType1 === entry.targetResourceType || relationship.resourceType2 === entry.targetResourceType)
+                && (relationship.resourceType1 === resourceIdentifier || relationship.resourceType2 === resourceIdentifier));
+            if (!declaresEdge) {
+                throw createConfigurationError(`[${resourceIdentifier}] invalid externalDataPipeline declaration: mapping('${entry.localField}') is a REMOTE_REFERENCE to `
+                    + `'${entry.targetResourceType}', and no relationship between '${String(resourceIdentifier)}' and '${entry.targetResourceType}' `
+                    + `names '${entry.localField}' as its foreignKeyField. Declare the relationship (a self-reference is a relationship whose two `
+                    + 'ends are this resource) so the resolved value is a foreign key the rest of the framework follows, not a bare id.');
+            }
+        }
     }
     // ========================================
     // isAnonymizable VALIDATION & ENRICHMENT (W7.3a)
@@ -2489,6 +2813,153 @@ export function createResourceConfiguration_Initialization(params) {
             seeRetained: ResourceSystemAccessMode.ALLOWED,
         };
     }
+    // ========================================
+    // retentionBinding VALIDATION & ENRICHMENT (#1613 — how long a row is kept)
+    // ========================================
+    //
+    // A separate axis from `retentionPolicy` above: that one is what an ERASURE does to a row, this one
+    // is how long the row lives. Every refusal here is about the binding being UNENFORCEABLE as written —
+    // a clock that reads a field the row does not have, or two retention authorities on one row — and
+    // each names the exact fix, because the alternative is a period the application publishes and the
+    // sweep silently cannot honour.
+    //
+    // assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — a declared retention class is refused at
+    // configuration build unless the sweep can actually compute when each row expires.
+    // A tenant's rows never expire by `.ttl()` (#1634). MongoDB deletes a TTL row itself, with no application code
+    // running, so no legal hold, cascade or file release could ever reach it — and a hold on an organization claims
+    // to suspend EVERY deletion of that organization's data. `.ttl()` is for application-scoped framework plumbing
+    // (job executions, job payloads); a tenant resource binds a retention class, whose sweep asks the hold.
+    if (resourcePrimaryScope === ResourcePrimaryScope.ORGANIZATIONS) {
+        const tenantTtlFields = collectRowTtlPolicies(effectiveMainSchema).map((policy) => policy.fieldName);
+        if (tenantTtlFields.length > 0) {
+            throw createConfigurationError(`[${resourceIdentifier}] is scoped to an organization and declares .ttl() on [${tenantTtlFields.join(', ')}]. ` +
+                `A tenant's rows are never expired by the database's own TTL, which no legal hold can suspend: bind a ` +
+                `retentionBinding instead (its sweep deletes through the service layer and skips held rows).`);
+        }
+    }
+    let retentionBinding;
+    if (authoredRetentionBinding !== undefined) {
+        const parsedBinding = ResourceRetentionBindingSchema.safeParse(authoredRetentionBinding);
+        if (!parsedBinding.success) {
+            throw createConfigurationError(`[${resourceIdentifier}] retentionBinding is invalid: ${parsedBinding.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ')}.`);
+        }
+        retentionBinding = parsedBinding.data;
+        if (!isZodObject(effectiveMainSchema)) {
+            throw createConfigurationError(`[${resourceIdentifier}] retentionBinding requires a ZodObject mainSchema: the retention clock is a field of the row.`);
+        }
+        const bindingShape = getZodObjectShape(effectiveMainSchema);
+        // One row, one retention authority. `.ttl()` expires the row by a fixed number of seconds, and on
+        // MongoDB natively with no application code running — so no cascade, file release or hold could
+        // ever run for it. Two authorities on one row also means two answers to "when does this go".
+        const ttlFields = collectRowTtlPolicies(effectiveMainSchema).map((policy) => policy.fieldName);
+        if (ttlFields.length > 0) {
+            throw createConfigurationError(`[${resourceIdentifier}] declares BOTH retentionBinding (${retentionBinding.retentionClass}) and .ttl() on ` +
+                `[${ttlFields.join(', ')}]. One row takes one retention authority: remove the .ttl() and let the class ` +
+                `period apply (the retention sweep deletes through the service layer, so cascades, files and RAG chunks ` +
+                `go with the row), or drop retentionBinding if this is framework plumbing that holds no business data.`);
+        }
+        const namesClosureField = retentionBinding.closureFieldName !== undefined;
+        const isClosureEvent = retentionBinding.startPoint === RetentionStartPoint.CLOSURE_EVENT;
+        if (isClosureEvent !== namesClosureField) {
+            throw createConfigurationError(isClosureEvent
+                ? `[${resourceIdentifier}] retentionBinding.startPoint CLOSURE_EVENT requires closureFieldName: the date field ` +
+                    `whose value is the closure instant. While it is null the row never expires.`
+                : `[${resourceIdentifier}] retentionBinding.closureFieldName is only meaningful with startPoint CLOSURE_EVENT ` +
+                    `(got ${retentionBinding.startPoint}). Remove it, or use CLOSURE_EVENT.`);
+        }
+        if (retentionBinding.startPoint === RetentionStartPoint.SCOPE_DELETED) {
+            // The clock is the ORGANIZATION's deletion, so the row must name an organization.
+            if (!bindingShape.organizationId) {
+                throw createConfigurationError(`[${resourceIdentifier}] retentionBinding.startPoint SCOPE_DELETED counts from the row's organization being ` +
+                    `marked for deletion, but this resource has no organizationId field. Use CREATED, LAST_UPDATED or CLOSURE_EVENT.`);
+            }
+            if (bindingShape[RETENTION_STARTED_AT_FIELD_NAME]) {
+                throw createConfigurationError(`[${resourceIdentifier}] retentionBinding SCOPE_DELETED injects a reserved '${RETENTION_STARTED_AT_FIELD_NAME}' ` +
+                    `field, but this resource already declares one. Rename that field (the retention clock is factory-injected).`);
+            }
+            // The ONE stored retention instant. Nothing on the row records when its organization was marked,
+            // and the organization row itself is destroyed by the purge, so the purge stamps it here first.
+            // Server-owned in every direction: no caller can author it on create or update, it never leaves the
+            // backend, and it is indexed because the sweep queries it on every run.
+            effectiveMainSchema = effectiveMainSchema.extend({
+                [RETENTION_STARTED_AT_FIELD_NAME]: z.date()
+                    .optional()
+                    .isDBIndexed()
+                    .excludeFromCreate()
+                    .excludeFromUpdate()
+                    .isBackendOnly()
+                    .isHidden(),
+            });
+        }
+        else {
+            // Every other start point READS an instant the row already carries, so that field must exist,
+            // be a date, and — for the closure field the author chose — be indexed (the sweep queries it on
+            // every run). `createdAt`/`updatedAt` are indexed by convention and maintained by both adapters.
+            const startFieldName = resolveRetentionStartFieldName(retentionBinding);
+            const startFieldSchema = bindingShape[startFieldName];
+            if (!startFieldSchema || getZodType(unwrapSchema(startFieldSchema)) !== 'date') {
+                throw createConfigurationError(`[${resourceIdentifier}] retentionBinding.startPoint ${retentionBinding.startPoint} reads the row's ` +
+                    `'${startFieldName}', which must be a date field of this resource${startFieldSchema ? ' (it is not a date)' : ' (it does not exist)'}.` +
+                    (isClosureEvent ? ' Name a z.date() field that is set when the record closes.' : ` Declare ${startFieldName}: z.date() on the schema.`));
+            }
+            if (isClosureEvent && !isDBIndexed(startFieldSchema)) {
+                throw createConfigurationError(`[${resourceIdentifier}] retentionBinding closure field '${startFieldName}' must be .isDBIndexed(): the ` +
+                    `retention sweep selects expired rows by it on every run, and an unindexed scan grows with the table.`);
+            }
+        }
+    }
+    // ========================================
+    // retentionPolicy.statutoryRetention (#1635 — a statute keeps the row through an erasure)
+    // ========================================
+    //
+    // Read AFTER both axes above are resolved, because every rule here is a relation BETWEEN them: the
+    // ground lives on the erasure treatment (`retentionPolicy`), and the period it lasts for lives on the
+    // binding (`retentionBinding`). Each refusal names the declaration that would make it true.
+    //
+    // assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — a row kept through an erasure on a statutory ground
+    // must be bound to the period that ground lasts for, and to a start point whose clock a restricted row can reach.
+    const statutoryRetention = retentionPolicy?.mode ? retentionPolicy.statutoryRetention : undefined;
+    if (retentionBinding?.retentionClass === DataRetentionClass.BUSINESS_RECORDS && !statutoryRetention) {
+        // Invariant 1 of #1635. A BUSINESS_RECORDS row is kept because the law says so; without the ground an
+        // erasure would treat it as the author's choice (or, with no retentionPolicy at all, reach it through the
+        // delete cascade's default) and could not tell the data subject why it was kept or until when.
+        throw createConfigurationError(`[${resourceIdentifier}] binds retention class BUSINESS_RECORDS, whose period is a statutory minimum, but declares no ` +
+            `retentionPolicy.statutoryRetention. Declare retentionPolicy: { mode, statutoryRetention: { ground: ` +
+            `StatutoryRetentionGround.LEGAL_OBLIGATION, rationale: '<the statute>' } } (and a dataSubjectPolicy), so a subject ` +
+            `erasure RESTRICTS these rows until their period ends instead of deleting records the law requires kept. If no ` +
+            `statute applies, bind RESOURCE_DATA instead.`);
+    }
+    if (statutoryRetention) {
+        if (!Object.values(StatutoryRetentionGround).includes(statutoryRetention.ground)) {
+            throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy.statutoryRetention.ground '${String(statutoryRetention.ground)}' is not a ` +
+                `StatutoryRetentionGround (${Object.values(StatutoryRetentionGround).join(', ')}).`);
+        }
+        if (typeof statutoryRetention.rationale !== 'string' || statutoryRetention.rationale.trim().length === 0) {
+            throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy.statutoryRetention.rationale is empty. Name the statute that requires these ` +
+                `rows kept — an operator answering a data subject has to be able to say which law, and a ground with no law named ` +
+                `is a claim nobody can check.`);
+        }
+        if (retentionBinding?.retentionClass !== DataRetentionClass.BUSINESS_RECORDS) {
+            // The PERIOD the ground lasts for is the BUSINESS_RECORDS class period: without that binding there is no end,
+            // and a statutory ground with no end is a standing retention nobody decided.
+            throw createConfigurationError(`[${resourceIdentifier}] declares retentionPolicy.statutoryRetention but ${retentionBinding ? `binds ${retentionBinding.retentionClass}` : 'declares no retentionBinding'}. ` +
+                `A statutory ground lasts for the statutory period, which is dataRetention[BUSINESS_RECORDS]: bind ` +
+                `retentionBinding: { retentionClass: DataRetentionClass.BUSINESS_RECORDS, startPoint: RetentionStartPoint.END_OF_CALENDAR_YEAR }.`);
+        }
+        if (retentionBinding.startPoint === RetentionStartPoint.CLOSURE_EVENT || retentionBinding.startPoint === RetentionStartPoint.LAST_UPDATED) {
+            // Both clocks are ones a RESTRICTED row cannot keep honestly. A restricted row is frozen — every ordinary write is
+            // refused — so a CLOSURE_EVENT row that is still open when its subject is erased can never be closed, and would be
+            // kept forever. And the restriction is itself a write, which moves `updatedAt`, so a LAST_UPDATED clock would be
+            // RESTARTED by the very erasure that reports when it ends. Neither is how a statute counts: HGB §257(5) and
+            // AO §147(4) count from the end of the calendar year.
+            throw createConfigurationError(`[${resourceIdentifier}] declares retentionPolicy.statutoryRetention with retentionBinding.startPoint ` +
+                `${retentionBinding.startPoint}, a clock a restricted row cannot keep: ` +
+                (retentionBinding.startPoint === RetentionStartPoint.CLOSURE_EVENT
+                    ? `an erasure freezes the row, so a record still open when its subject is erased could never be closed and would be kept forever. `
+                    : `the restriction write moves updatedAt, so the erasure would restart the period it reports. `) +
+                `Use END_OF_CALENDAR_YEAR (how commercial and tax statutes count), CREATED, or SCOPE_DELETED.`);
+        }
+    }
     // ── dataSubjectPolicy: WHO the row is, and whose session an erasure ends ──────────────────────
     //
     // Placed AFTER the retention operation contract on purpose: a config can be wrong in several ways
@@ -2643,13 +3114,19 @@ export function createResourceConfiguration_Initialization(params) {
      * and a row of a partition no operator has assigned (E3). Declaring it required would make both
      * states illegal in a contract that serves them.
      *
-     * ## Both are excluded from CREATE and UPDATE
+     * ## Neither can be changed, and only the unit can be NAMED — on a create (#1679)
+     *
+     * `organizationId` is excluded from CREATE and UPDATE, for the reason the pipeline lane states about
+     * its own tenant stamp: a caller who could send it could hand rows to another organization, and one
+     * who could update it could move them. The owner is the application's, never a caller's.
      *
-     * For the reason the pipeline lane states about its own tenant stamp: a caller who could send this
-     * field could hand rows to another organization, and one who could update it could move them.
-     * Writes are refused on an HTTP_API resource anyway, so this is the second lock rather than the
-     * first — and it is the one that keeps the fields out of the request DTOs, where they would read
-     * as something a client is invited to supply.
+     * `organizationUnitId` is excluded from UPDATE for the same reason — a row's partition never moves —
+     * and is ADMITTED on CREATE, because on a writable resource it is how a caller says which unit's
+     * partition a new row belongs to. It is never sent to the remote system: the repository resolves the
+     * unit to its assigned partition key, checks it against the caller's grant, and writes the PARTITION
+     * field itself (#1679). A member confined to one unit need not send it at all; an organization-wide
+     * caller, or a member of several units, must. On a resource with no CREATE operation the admission is
+     * inert, since there is no create DTO for it to appear in.
      */
     if (persistenceAdapter === PersistenceAdapter.HTTP_API) {
         // EXPLICIT object check, for the reason the retention injection above records: `getZodObjectShape`
@@ -2724,8 +3201,9 @@ export function createResourceConfiguration_Initialization(params) {
              */
             [READ_THROUGH_ORGANIZATION_UNIT_FIELD_NAME]: z.string()
                 .optional()
-                .excludeFromCreate()
-                .excludeFromUpdate(),
+                .excludeFromUpdate()
+                // Described here because no application authors this field (#1625): every read-through resource gets it.
+                .describe('The organization unit that owns the part of the external system this record lives in. Absent for a record every unit shares, or one in a part no unit has been assigned. On a create it names the unit the new record goes to; it never changes afterwards.'),
         });
     }
     if (isZodObject(effectiveMainSchema)) {
@@ -2895,7 +3373,7 @@ export function createResourceConfiguration_Initialization(params) {
             // ── Dev-time guardrail: custom op borrowing a NON-object envelope verb ──
             // A custom operation that borrows DELETE / DELETE_MANY / COUNT via
             // `resourceOperationLike` inherits that verb's DEFAULT response envelope
-            // (`{ id, deletedAt? }` / `{ deletedIds, deletedCount }` / `{ count }`) as
+            // (`{ id }` / `{ deletedIds, deletedCount }` / `{ count }`) as
             // its responseDto AND internalDto. That envelope is almost never what a
             // custom op actually returns, so at runtime the service output fails
             // `transformOutput`'s `internalDto.parse` → HTTP 500
@@ -3009,8 +3487,15 @@ export function createResourceConfiguration_Initialization(params) {
                 // failure mode the flag exists to prevent.
                 requiresStepUpAuthentication: variantParams.requiresStepUpAuthentication,
                 // Forwarded for the same reason: the controller, the service tier and the frontend client all read it off the
-                // RUNTIME operation, so an unforwarded declaration would refuse every keyed request as undeclared.
-                idempotencyKey: variantParams.idempotencyKey,
+                // RUNTIME operation, so an unforwarded declaration would refuse every keyed request as undeclared. On a
+                // read-through WRITE it is DERIVED as REQUIRED (#1679): a remote write cannot be rolled back, so every retry
+                // must replay the first outcome — see `resolveHttpApiWriteIdempotencyKeyRequirement`.
+                idempotencyKey: resolveHttpApiWriteIdempotencyKeyRequirement(variantParams.idempotencyKey, persistenceAdapter === PersistenceAdapter.HTTP_API
+                    && resolveHttpApiWriteVerb(isCustomOperation ? (variantParams.resourceOperationLike ?? operation) : operation) !== undefined),
+                // Forwarded for the same reason (#1985): `doOperation` asks the challenge off the RUNTIME operation, and the OpenAPI
+                // projector documents the header from it. An unforwarded declaration would leave a public form unprotected while
+                // its configuration says otherwise. A bulk twin inherits it with the rest of these fields.
+                submissionChallenge: variantParams.submissionChallenge,
                 admitsCrossTenantPlatformAdministration: variantParams.admitsCrossTenantPlatformAdministration,
                 // Same forwarding obligation as its cross-tenant sibling: the authorizer reads this off the
                 // RUNTIME operation, so dropping it here would silently re-close the admin surface.
@@ -3038,6 +3523,7 @@ export function createResourceConfiguration_Initialization(params) {
                 // REVOKED partnership both admitting a share.)
                 referenceConstraints: variantParams.referenceConstraints,
             };
+            assertSubmissionChallengeDeclaration(String(operation), variantParams.variantType, variantParams.submissionChallenge);
             if (isUrlisableOperationVariantType(variantParams.variantType)) {
                 const apiCallParams = variantParams;
                 const isCallbackVariant = apiCallParams.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK;
@@ -3080,6 +3566,35 @@ export function createResourceConfiguration_Initialization(params) {
                     throw createConfigurationError(`Operation '${operation}' cannot revoke tokens before a CREATE operation because no current resource state exists. `
                         + 'Move token revocation to an operation that addresses an existing resource.');
                 }
+                /*
+                 * (After the token-state checks, so a declaration that breaks both is told about the token rule too.)
+                 *
+                 * A client-facing core UPDATE_MANY or DELETE_MANY is a route that can never succeed, so it is refused
+                 * (#1793).
+                 *
+                 * This loop builds it as a NON-bulk operation (`isBulkOperation: false` below) mounted on the
+                 * collection path, and only a bulk operation has its selector lifted out of the body — `_ids` by the
+                 * service's `doOperation`, `_match` by the controller. So no request shape can reach
+                 * `updateMany` / `deleteMany` with a target, and the route answers every call with
+                 * `service_resource_validation_failed`. Measured on a running stack against an escalation-policy
+                 * collection before its variant moved: `{}`, `{ _ids: [...] }`, a filter and a field patch were all
+                 * refused, while GET on the same collection answered 200.
+                 *
+                 * The two working doors are named in the message: INTERNAL_CALL keeps the operation as the service
+                 * capability retention scrubs and anonymous-ownership transfer call with an explicit target, and a
+                 * `haveBulkOperation: true` variant on UPDATE / DELETE (or a custom operation) is the client bulk door,
+                 * with its selector, its max-selection limit and its place in the bulk bar. Scoped to the CORE
+                 * identifiers: a custom operation that borrows `resourceOperationLike: UPDATE_MANY` has its own request
+                 * and implementation and is unaffected. CREATE_MANY's `{ data: row[] }` form works and is untouched.
+                 */
+                if (!isCustomOperation
+                    && (operation === CoreResourceOperation.UPDATE_MANY || operation === CoreResourceOperation.DELETE_MANY)) {
+                    throw createConfigurationError(`Operation '${operation}' cannot be declared ${apiCallParams.variantType}: a client-facing core ${operation} is mounted `
+                        + 'as a non-bulk route, no selector ever reaches it, and it refuses every request. '
+                        + `Declare it ${ResourceOperationVariantType.INTERNAL_CALL} for a service-side capability, or give `
+                        + `${operation === CoreResourceOperation.UPDATE_MANY ? CoreResourceOperation.UPDATE : CoreResourceOperation.DELETE} `
+                        + 'a `haveBulkOperation: true` variant for a client bulk action.');
+                }
                 // Determine HTTP verb - for custom operations, use resourceOperationLike
                 let httpVerb;
                 if (isCustomOperation) {
@@ -3133,6 +3648,16 @@ export function createResourceConfiguration_Initialization(params) {
                     || variantParams.resourceOperationLike === CoreResourceOperation.SEARCH;
                 const isListLike = operation === CoreResourceOperation.LIST
                     || variantParams.resourceOperationLike === CoreResourceOperation.LIST;
+                if (isSearchLike || isListLike) {
+                    assertCollectionFieldsNameResourceFields({
+                        resourceIdentifier: String(resourceIdentifier),
+                        operationLabel: `operation "${String(operation)}"${apiCallParams.variantKey ? ` (variant "${apiCallParams.variantKey}")` : ''}`,
+                        schemaShape: getZodObjectShape(effectiveMainSchema),
+                        filterFields: variantParams.filterFields,
+                        sortFields: variantParams.sortFields,
+                        searchableFields: isSearchLike ? variantParams.searchableFields : undefined,
+                    });
+                }
                 if (isSearchLike) {
                     const pageSize = variantParams.pageSize ?? 20;
                     const isSearchable = variantParams.isSearchable !== false;
@@ -3141,12 +3666,9 @@ export function createResourceConfiguration_Initialization(params) {
                     const rawFilterFields = variantParams.filterFields || {};
                     const sortFields = variantParams.sortFields || [];
                     const maxPaginatedResultPerPageLimit = variantParams.maxPaginatedResultPerPageLimit || DEFAULT_SEARCH_PAGE_CEILING;
-                    const filterFields = {};
-                    Object.entries(rawFilterFields).forEach(([key, value]) => {
-                        if (typeof value !== 'function') {
-                            filterFields[key] = value;
-                        }
-                    });
+                    // Every entry is a Zod type by now: `assertCollectionFieldsNameResourceFields` refused the
+                    // function-valued slot above.
+                    const filterFields = rawFilterFields;
                     const searchQueryRequestSchema = createResourceSearchQueryRequestSchema({
                         filterFields,
                         allowedSortFields: sortFields,
@@ -3160,6 +3682,12 @@ export function createResourceConfiguration_Initialization(params) {
                         validateArrayConstraints: true,
                         maxResultsPerPageLimit: maxPaginatedResultPerPageLimit
                     });
+                    // An author's `customResponseDto` wins here exactly as it does for every other operation
+                    // (`deriveResponseDto` above). This block used to overwrite it with the generated schema and
+                    // stamp `hasCustomResponseDto: false`, so a searchable variant silently lost the contract it
+                    // declared — found when inbound deliveries declared one to keep the raw payload out of a page
+                    // (#1596). A custom DTO must carry the same page ceiling as this variant.
+                    const customSearchResponseDto = variantParams.customResponseDto;
                     Object.assign(apiCallOperationFields, {
                         pageSize,
                         isSearchable,
@@ -3169,8 +3697,8 @@ export function createResourceConfiguration_Initialization(params) {
                         sortFields,
                         maxPaginatedResultPerPageLimit,
                         searchQueryRequestSchema,
-                        responseDto: paginatedResponseSchema,
-                        hasCustomResponseDto: false,
+                        responseDto: customSearchResponseDto ?? paginatedResponseSchema,
+                        hasCustomResponseDto: customSearchResponseDto !== undefined,
                     });
                 }
                 if (isListLike) {
@@ -3315,6 +3843,8 @@ export function createResourceConfiguration_Initialization(params) {
                     requiresStepUpAuthentication: defaultApiCallVariant.requiresStepUpAuthentication,
                     // Inherited like step-up: an auto-variant projects the default variant's contract, header included.
                     idempotencyKey: defaultApiCallVariant.idempotencyKey,
+                    // Inherited like the Idempotency-Key: a projection of a protected operation asks the same challenge (#1985).
+                    submissionChallenge: defaultApiCallVariant.submissionChallenge,
                     admitsCrossTenantPlatformAdministration: defaultApiCallVariant.admitsCrossTenantPlatformAdministration,
                     // Inherited for the same reason as the cross-tenant flag: an auto-variant is a PROJECTION of
                     // the default operation and must make the same addressing claim, or it would refuse the very
@@ -3560,6 +4090,25 @@ export function createResourceConfiguration_Initialization(params) {
                 `its transport group — a lone variant marked \`isDefault: false\` leaves the group with NO default.`);
         }
     }
+    // ── RESOLVABILITY of the retention-class sweep's delete (#1613) ───────────
+    //
+    // The class sweep deletes expired rows through the SERVICE layer — so cascades, file release and RAG
+    // chunk removal run — preferring a DELETE_MANY and falling back to per-row DELETE, exactly the
+    // anonymous-session cleanup's disjunction. A binding with neither resolvable would boot green and then
+    // fail the first sweep that found an expired row, which is a published period nothing can enforce.
+    if (retentionBinding) {
+        const deleteAlternatives = [CoreResourceOperation.DELETE_MANY, CoreResourceOperation.DELETE];
+        if (!deleteAlternatives.some((alternative) => operations.some((candidate) => isServiceResolvableDefaultOperation(candidate, alternative)))) {
+            const declaredVariants = operations
+                .filter((candidate) => deleteAlternatives.includes(candidate.operationIdentifier))
+                .map((candidate) => `${String(candidate.operationIdentifier)}/${candidate.variantType}${candidate.isOperationDefault ? ' (default)' : ''}`);
+            throw createConfigurationError(`[${resourceIdentifier}] retentionBinding requires DELETE_MANY or DELETE to be SERVICE-RESOLVABLE: the retention ` +
+                `sweep deletes expired rows through the service layer so cascades, files and RAG chunks go with them. ` +
+                `Declared variants: [${declaredVariants.length > 0 ? declaredVariants.join(', ') : 'none'}]. Declare one as the ` +
+                `default ${ResourceOperationVariantType.INTERNAL_CALL} variant (route-less and service-resolvable); ` +
+                `REPOSITORY_ONLY is served by a different transport and does not resolve.`);
+        }
+    }
     // ── RESOLVABILITY half of the ANONYMIZABLE operation contract ───────────
     //
     // Same two-halves shape as retention above, for the other dynamic-loop capability. The presence
@@ -3625,11 +4174,14 @@ export function createResourceConfiguration_Initialization(params) {
         retentionPolicy: retentionPolicy?.mode ? retentionPolicy : undefined,
         // Paired with `retentionPolicy` by the guards above, so these two are present together or not at all.
         dataSubjectPolicy: retentionPolicy?.mode ? dataSubjectPolicy : undefined,
+        // Validated and parsed above, so the resolved value is exactly the strict-parsed declaration.
+        retentionBinding,
         // Normalize (mirror retentionPolicy): the resolved portabilityPolicy is present IFF the
         // resource actually declared a default. An absent `defaultProvenance` is a policy-shaped
         // opt-out, and shipping a truthy-but-empty object would make an Art. 20 export believe a
         // default exists and silently include fields nobody classified.
         portabilityPolicy: portabilityPolicy?.defaultProvenance ? portabilityPolicy : undefined,
+        workUnit,
         operations: operations // Temporary - will be replaced
     };
     // Pre-compute all DTOs for each operation using buildAllOperationDtos
@@ -3637,6 +4189,27 @@ export function createResourceConfiguration_Initialization(params) {
     // If needed, the registry can be passed as a parameter to the factory function
     const resourceRegistry = new Map();
     const operationsWithDtos = operations.map(operation => ResourcesConfigOperationsDtosBuilderUtils.buildAllOperationDtos(operation, resourceConfig, resourceRegistry));
+    // ── A closure clock is SERVER-OWNED (#1613 review F1) ─────────────────
+    //
+    // `CLOSURE_EVENT` deletes a row the declared period after its closure date. If ANY client-routed
+    // operation's request can carry that date, a caller can backdate it and the next sweep deletes an OPEN
+    // record — without DELETE permission and without the period passing. Checked HERE, against the FINAL
+    // request DTOs, so it covers every shape uniformly: create, create_many, update, update_many and every
+    // custom operation with its own request schema (a "close" operation taking the date is the same hole).
+    // Route-less variants (INTERNAL_CALL, REPOSITORY_ONLY) are the owning code's own writes and pass; the
+    // handlers that own the field declare it in `authoritativeFields`. `isNotEditable()` enforces nothing here.
+    if (retentionBinding?.startPoint === RetentionStartPoint.CLOSURE_EVENT && retentionBinding.closureFieldName) {
+        const closureFieldName = retentionBinding.closureFieldName;
+        const clientRouted = new Set([ResourceOperationVariantType.API_CALL, ResourceOperationVariantType.API_CALL_WITH_CALLBACK]);
+        const writers = operationsWithDtos.filter((operation) => clientRouted.has(operation.variantType) && requestSchemaCarriesField(operation.requestDto, closureFieldName));
+        if (writers.length > 0) {
+            throw createConfigurationError(`[${resourceIdentifier}] retentionBinding closure field '${closureFieldName}' is writable by a client-routed ` +
+                `${[...new Set(writers.map((writer) => String(writer.operationIdentifier)))].join('/')}: a caller could backdate ` +
+                `it and the retention sweep would delete an open record. Mark it .excludeFromCreate().excludeFromUpdate(), keep it ` +
+                `out of any custom request schema, and set it in the owning handlers, declaring it in authoritativeFields so their ` +
+                `write survives the re-parse.`);
+        }
+    }
     return {
         isDisabled: params.isDisabled ?? false,
         resourcePrimaryScope,
@@ -3665,12 +4238,219 @@ export function createResourceConfiguration_Initialization(params) {
         retentionPolicy: retentionPolicy?.mode ? retentionPolicy : undefined,
         // Paired with `retentionPolicy` by the guards above, so these two are present together or not at all.
         dataSubjectPolicy: retentionPolicy?.mode ? dataSubjectPolicy : undefined,
+        // Validated and parsed above, so the resolved value is exactly the strict-parsed declaration.
+        retentionBinding,
         // Normalize (mirror retentionPolicy): the resolved portabilityPolicy is present IFF the
         // resource actually declared a default. An absent `defaultProvenance` is a policy-shaped
         // opt-out, and shipping a truthy-but-empty object would make an Art. 20 export believe a
         // default exists and silently include fields nobody classified.
         portabilityPolicy: portabilityPolicy?.defaultProvenance ? portabilityPolicy : undefined,
+        workUnit,
         operations: operationsWithDtos
     };
 }
+/**
+ * Why a declared constant cannot be written to a local field, or `null` when it can (#1685). The field's own Zod type
+ * decides: an enum takes only its members, a string / number / boolean field only that primitive. Any other field
+ * type cannot be checked from here, and an expression writing an unchecked value is refused rather than trusted.
+ */
+function describeExternalDataConstantMisfit(value, targetSchema) {
+    const inner = unwrapSchema(targetSchema);
+    if (inner instanceof z.ZodEnum) {
+        const members = inner.options;
+        return members.includes(value) ? null : `${JSON.stringify(value)} is not a member of the field's enum (${members.map((member) => JSON.stringify(member)).join(', ')})`;
+    }
+    if (inner instanceof z.ZodString)
+        return typeof value === 'string' ? null : `${JSON.stringify(value)} is not a string`;
+    if (inner instanceof z.ZodNumber)
+        return typeof value === 'number' ? null : `${JSON.stringify(value)} is not a number`;
+    if (inner instanceof z.ZodBoolean)
+        return typeof value === 'boolean' ? null : `${JSON.stringify(value)} is not a boolean`;
+    return `a declared value cannot be checked against this field's type (${getZodType(inner)})`;
+}
+/**
+ * The destination-schema half of an OUTBOUND pipeline's coherence (#1690) — the arrows of the INBOUND rules reversed.
+ *
+ *  - every SENT field (a mapping entry's `localField`) exists and is the application's own: a field declared
+ *    `.excludeFromCreate()` AND `.excludeFromUpdate()` is one no caller can ever set, so sending it would send a value
+ *    nobody decided. (Excluded from one of the two is fine — a field set once on create and never changed is common.)
+ *  - `remoteKeyLocalField` exists, is a STRING, ACCEPTS ABSENCE (a row is created locally before the system of record
+ *    has assigned it a key) and is excluded from create and update: the engine writes it, once, from the create's
+ *    answer, and a caller that could write it could point a local row at any remote record. No `.isBusinessKey()` or
+ *    `.isUnique()` is required: nothing upserts on it, and the engine never writes one key to two rows.
+ *  - `partitionUnitLocalField`, when declared, exists, is a STRING and accepts absence — the unit a row belongs to,
+ *    which decides the partition it is created in. A row with no unit is not sent on a partitioned instance.
+ *  - a REMOTE_REFERENCE's local foreign key is a STRING that accepts absence (it is the caller's link, possibly empty),
+ *    and its value shape is resolved from the dialect exactly as for an inbound entry, because the reverse translation
+ *    sends the target's key in that shape.
+ *  - `population` and `orphanPolicy` describe an INBOUND load and are refused when AUTHORED with anything but their
+ *    default. Both carry defaults, so the parsed declaration cannot tell a written value from an omitted one; the
+ *    authored object can. A value EQUAL to the default is let through, because a declaration that was parsed once
+ *    already (a configuration re-materialized from its own parsed pipeline) carries both, and it declares nothing an
+ *    inbound load would read differently.
+ */
+function validateExternalDataOutboundDeclarationAgainstSchema(declaration, shape, authored, refuse) {
+    const defaults = { population: ExternalDataDestinationPopulation.CLOSED, orphanPolicy: ExternalDataOrphanPolicy.REPORT };
+    for (const field of ['population', 'orphanPolicy']) {
+        if (authored[field] !== undefined && authored[field] !== defaults[field]) {
+            refuse(`${field}: describes the rows an INBOUND pass loads, and an OUTBOUND pipeline loads none — it sends the destination's own rows. Remove it.`);
+        }
+    }
+    const requireStringAcceptingAbsence = (fieldName, context) => {
+        const fieldSchema = shape[fieldName];
+        if (!fieldSchema)
+            refuse(`${context}: local field '${fieldName}' does not exist on mainSchema.`);
+        if (!(unwrapSchema(fieldSchema) instanceof z.ZodString))
+            refuse(`${context}: '${fieldName}' must be a STRING field.`);
+        if (unwrapSchema(fieldSchema) === fieldSchema)
+            refuse(`${context}: '${fieldName}' must be optional or nullable — a row can exist locally without it.`);
+        return fieldSchema;
+    };
+    const keySchema = requireStringAcceptingAbsence(declaration.remoteKeyLocalField, 'remoteKeyLocalField');
+    /*
+     * ONE RECORD, ONE ROW (#2039 review) — made a property of the STORE rather than of each code path that writes the key.
+     *
+     * A remote key names one record of the system of record, so two local rows holding it would each send their edits to
+     * that record, overwriting each other's. The pass cannot make that (the system of record mints a fresh key per create),
+     * but an operator's answer to an unknown create can, and a check at the door is a read-then-write any concurrent writer
+     * slips past. A UNIQUE index cannot be slipped past, on any path.
+     *
+     * It must IGNORE rows with no key yet — every row before its first send has none. `.isUnique()` gives exactly that on
+     * both stores: its default is sparse, which MongoDB builds as a sparse (or, on a retention-governed resource, a
+     * `$exists`-partial) unique index and PostgreSQL plans with NULLs distinct. MongoDB's one blind spot is an EXPLICIT null,
+     * which a sparse index still indexes — so the field must also refuse null: `.optional()`, never `.nullable()`, which
+     * makes "absent" the only empty state a validated write can store.
+     *
+     * Checked rather than applied by the factory, for the inbound rule's reason (the same field there must be declared
+     * `.isUnique()`, "boot-CHECKED, not factory-mutated"): the application's own schema file shows the index it gets, and
+     * the migration its planner writes is the one its author reads.
+     */
+    const uniqueParams = getUniqueFieldParams(keySchema);
+    if (uniqueParams === undefined || uniqueParams.sparse === false || (uniqueParams.scope !== undefined && uniqueParams.scope !== 'global') || uniqueParams.compoundWith !== undefined) {
+        refuse(`remoteKeyLocalField: '${declaration.remoteKeyLocalField}' must be declared .isUnique() — one remote record, one local row: two rows holding `
+            + 'one key would each overwrite the other\'s record. Plain `.isUnique()` (global, sparse, the default) ignores the rows not yet sent.');
+    }
+    if (keySchema.safeParse(null).success) {
+        refuse(`remoteKeyLocalField: '${declaration.remoteKeyLocalField}' accepts null. Declare it .optional(), not .nullable(): its unique index ignores a row `
+            + 'with no key only while "no key" is ABSENT — MongoDB indexes an explicit null, so a second unsent row would collide with the first.');
+    }
+    if (!isExcludedFromCreate(keySchema) || !isExcludedFromUpdate(keySchema)) {
+        refuse(`remoteKeyLocalField: '${declaration.remoteKeyLocalField}' must be declared .excludeFromCreate() and .excludeFromUpdate() — the engine `
+            + 'writes it once, from the key the system of record answers a create with, and a caller that could write it could point a local row '
+            + 'at any remote record.');
+    }
+    if (declaration.partitionUnitLocalField !== undefined) {
+        requireStringAcceptingAbsence(declaration.partitionUnitLocalField, 'partitionUnitLocalField');
+    }
+    for (const entry of declaration.mapping) {
+        const context = `mapping('${entry.localField}')`;
+        const fieldSchema = shape[entry.localField];
+        if (!fieldSchema)
+            refuse(`${context}: local field '${entry.localField}' does not exist on mainSchema.`);
+        if (isExcludedFromCreate(fieldSchema) && isExcludedFromUpdate(fieldSchema)) {
+            refuse(`${context}: '${entry.localField}' is declared .excludeFromCreate() and .excludeFromUpdate(), so no caller can ever set it and an OUTBOUND `
+                + 'pipeline would send a value nobody decided. A field this pipeline SENDS is the application\'s own: let callers write it.');
+        }
+        if (entry.kind === ExternalDataMappingEntryKind.REMOTE_REFERENCE) {
+            requireStringAcceptingAbsence(entry.localField, context);
+            entry.valueShape = resolveExternalDataRemoteReferenceValueShape(entry, declaration.binding.dialect);
+        }
+    }
+}
+/**
+ * The destination-schema half of a declared expression's validation (#1685): what the local field must be for the
+ * expression to write it — and, for a plain CONSTANT, whether the constant fits an enum or primitive field. The schema-independent half (duplicate codes, identity arithmetic, a concatenation of
+ * literals) is `assertExternalDataPipelineDeclarationCoherence`'s.
+ *
+ * Runs where every other mapping target is checked — the resource factory, at module load, i.e. at startup — so a
+ * renamed enum member, a mistyped constant or an expression pointed at the wrong kind of field stops the boot with
+ * the entry named, instead of rejecting every row of every run. A remote field that does not exist cannot be known
+ * here, offline; the extraction requests every field an expression reads, so the SOURCE refuses it on the first run
+ * (Odoo raises "Invalid field", an OData service refuses an unknown `$select` property) rather than every row landing
+ * null.
+ *
+ * Also RESOLVES, as for a `REMOTE_FIELD` entry, Odoo's absent-as-false coercion on a `CONDITIONAL` outcome that
+ * copies a remote field: this is the one place the dialect and the target type are both known.
+ */
+function validateExternalDataExpressionAgainstTarget(entry, targetSchema, dialect, refuse) {
+    const at = `mapping('${entry.localField}')`;
+    const inner = unwrapSchema(targetSchema);
+    const acceptsAbsence = inner !== targetSchema;
+    // `required` exists on every expression but CONDITIONAL, whose strict shape refuses it — so only the others may
+    // be told to declare it.
+    const requireAbsenceCapable = (why) => {
+        if (acceptsAbsence)
+            return;
+        refuse(entry.kind === ExternalDataMappingEntryKind.CONDITIONAL
+            ? `${at}: ${why}, so the field must be optional or nullable.`
+            : `${at}: ${why}, so the field must be optional or nullable — or declare required: true (such rows are then rejected and reported).`);
+    };
+    switch (entry.kind) {
+        /*
+         * A CONSTANT, checked where a check is possible (#1685 review): a member the enum does not have, or a value of the
+         * wrong primitive type, fails the boot rather than every row's load. A field of another type (a date, an object)
+         * is left alone: a constant cannot express one, and refusing it would refuse declarations nothing proves wrong.
+         */
+        case ExternalDataMappingEntryKind.CONSTANT: {
+            if (inner instanceof z.ZodEnum || inner instanceof z.ZodString || inner instanceof z.ZodNumber || inner instanceof z.ZodBoolean) {
+                const misfit = describeExternalDataConstantMisfit(entry.constant, targetSchema);
+                if (misfit !== null)
+                    refuse(`${at}.constant: ${misfit}.`);
+            }
+            return;
+        }
+        case ExternalDataMappingEntryKind.ENUM_MAP: {
+            if (!(inner instanceof z.ZodEnum))
+                refuse(`${at}: an ENUM_MAP writes a member of a local enum, so its target must be an enum field.`);
+            for (const { remoteValue, localValue } of entry.values) {
+                const misfit = describeExternalDataConstantMisfit(localValue, targetSchema);
+                if (misfit !== null)
+                    refuse(`${at}.values: the code ${JSON.stringify(remoteValue)} maps to ${misfit}.`);
+            }
+            if (entry.unmapped.policy === ExternalDataUnmappedValuePolicy.USE_DEFAULT) {
+                const misfit = describeExternalDataConstantMisfit(entry.unmapped.localValue, targetSchema);
+                if (misfit !== null)
+                    refuse(`${at}.unmapped.localValue: ${misfit}.`);
+            }
+            if (!entry.required)
+                requireAbsenceCapable('an absent remote code lands null');
+            return;
+        }
+        case ExternalDataMappingEntryKind.CONCATENATION:
+            if (!(inner instanceof z.ZodString))
+                refuse(`${at}: a CONCATENATION writes a string, so its target must be a string field.`);
+            if (!entry.required)
+                requireAbsenceCapable('a row whose every remote part is absent lands null');
+            return;
+        case ExternalDataMappingEntryKind.ARITHMETIC:
+            if (!(inner instanceof z.ZodNumber))
+                refuse(`${at}: an ARITHMETIC entry writes a number, so its target must be a number field.`);
+            if (!entry.required)
+                requireAbsenceCapable('an absent remote value lands null');
+            return;
+        case ExternalDataMappingEntryKind.CONDITIONAL: {
+            const outcomes = [...entry.cases.map((entryCase) => entryCase.then), entry.otherwise];
+            for (const outcome of outcomes) {
+                if (outcome.kind === ExternalDataConditionalOutcomeKind.CONSTANT) {
+                    const misfit = describeExternalDataConstantMisfit(outcome.constant, targetSchema);
+                    if (misfit !== null)
+                        refuse(`${at}: an outcome writes ${misfit}.`);
+                    continue;
+                }
+                requireAbsenceCapable(`the outcome copying '${outcome.remoteField}' lands null when that field is absent`);
+                // As for a REMOTE_FIELD entry: the timestamp coercion produces a Date, so it targets a date field.
+                if (outcome.coercion === ExternalDataFieldCoercion.ISO_STRING_TO_DATE && !(inner instanceof z.ZodDate)) {
+                    refuse(`${at}: the outcome copying '${outcome.remoteField}' declares ISO_STRING_TO_DATE, which targets a date field.`);
+                }
+                // Odoo's false→null default, resolved as for a REMOTE_FIELD entry: a genuine boolean target keeps its false.
+                if (dialect === HttpApiTransportDialect.ODOO_JSONRPC && outcome.coercion === ExternalDataFieldCoercion.NONE && !(inner instanceof z.ZodBoolean)) {
+                    outcome.coercion = ExternalDataFieldCoercion.ODOO_FALSE_AS_NULL;
+                }
+            }
+            return;
+        }
+        default:
+            return;
+    }
+}
 //# sourceMappingURL=resources-config.shared.factory.js.map