@wildo-ai/saas-models 1.0.1 → 1.1.1

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

@@ -3,18 +3,43 @@
  *
  * Reusable operation schemas for bulk actions and common operations
  */
-import { ExpiresInDurationSchema, getZodObjectShape, getZodType, isBackendOnlyField, isDiscriminatorField, isExcludedFromCreate, isExcludedFromUpdate, isSummaryField, isVirtualField, unwrapSchema } from '@wildo-ai/zod-decorators';
+import { ExpiresInDurationSchema, getImpersonalizeMaskValue, getImpersonalizeTreatment, getZodObjectShape, getZodType, isBackendOnlyField, isDiscriminatorField, isExcludedFromCreate, isExcludedFromUpdate, isBusinessKeyField, isZodObject, isSummaryField, isTemplatableFileField, isVirtualField, SingleFileValueSchema, toPatchOptionalField, mainSchemaFieldIsClearable, unwrapSchema, getDataCategories, } 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 { buildImpersonalizeScrubPatch, IMPERSONALIZE_MASK_CONSTANT, isImpersonalizeNeverScrubFloorField, resolveImpersonalizeMaskValue, } from '../compliance/privacy/impersonalization-scrub.shared.utils.js';
+import { RedactionType } from '../compliance/privacy/redaction.shared.schemas.js';
+import { unknownPersonalDataCategories } from '../compliance/privacy/personal-data-category.shared.schemas.js';
+/*
+ * entrypoint-closure-waiver: this root-reachable module imports the external-data AUTHORING
+ * contract, which only `@wildo-ai/saas-models/external-data` publishes (see
+ * `external-data.exports.ts` for why that subpath exists).
+ *
+ * MEASURED SAFE 2026-08-29 by the probe `package-public-entrypoints.md` prescribes — a consumer
+ * importing ONLY the package root, re-exporting these surfaces and deriving their parameter types
+ * so declaration emit must WRITE them rather than alias them, compiled with `declaration: true`:
+ * zero TS2742 / TS2883 / TS7056, and the emitted `.d.ts` names `@wildo-ai/saas-models` with no
+ * `node_modules/...` path anywhere in it.
+ *
+ * The mechanism, so the next reader need not re-derive it: every crossing here is an EXPLICIT
+ * ANNOTATION inside this package, so TypeScript emits a RELATIVE intra-package import in our own
+ * `.d.ts` — which resolves by PATH for any consumer, whatever the exports map says. TS2742 bites
+ * only when TypeScript must INVENT a specifier for an INFERRED type. Re-run the probe if a
+ * root-exported contract here ever starts inferring one.
+ */
+import { HttpApiResourceBindingSchema, HttpApiTransportDialect, assertHttpApiBindingDialectCoherence } from '../http-api-binding/http-api-binding.shared.schemas.js';
+import { ExternalDataDestinationPopulation, ExternalDataFieldCoercion, ExternalDataMappingEntryKind, ExternalDataPipelineDeclarationSchema, assertExternalDataPipelineDeclarationCoherence, } from '../external-data/external-data-pipeline.shared.schemas.js';
 import { HttpMethod } from '../requests/http-requests.shared.js';
 import { ConsumableToken_ConsumptionMode, TokenAuthenticationPolicy } from '../security/authentications/consumable-token.shared.schemas.js';
-import { OPERATION_VARIANT_KEY, Resouces_BulkOperationBaseSchema, Resouces_Filter_BaseSchema, Resouces_Filter_DateRangeSchema, Resouces_PaginationRequestSchema, Resouces_PaginationResponseMetadataSchema, SortOrder } from './resources-config.shared.schemas.js';
+import { OPERATION_VARIANT_KEY, Resouces_BulkOperationBaseSchema, Resouces_Filter_BaseSchema, Resouces_Filter_DateRangeSchema, createPaginationRequestSchema, createPaginationResponseMetadataSchema, ResourceGeneratedOperationKind, ResourceSystemAccessMode, PersistenceAdapter, SortOrder, ResourceCollectionExportResponseSchema, } from './resources-config.shared.schemas.js';
 import { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from './resources.shared.core.definitions.js';
-import { PRIMARY_SCOPE_FIELD_IDENTIFIERS, PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE, ResourceOperationRiskLevel, ResourceOperationVariantType, ResourceOperation_ServiceRuntimeMode, ResourceParentResourceRequirement, ResourcePrimaryScope, ResourceRelationshipBulkAction, ResourceRelationshipBulkActionResultSchema, ResourceRelationshipBulkClearOperationRequestSchema, ResourceRelationshipBulkCreateOperationRequestSchema, ResourceRelationshipBulkLinkOperationRequestSchema, ResourceRelationshipBulkReplaceOperationRequestSchema, ResourceRelationshipBulkSetOperationRequestSchema, ResourceRelationshipBulkUnlinkOperationRequestSchema, ResourceRelationshipAccessScopeStrategy, ResourceRelationshipCardinality, ResourceTranspositionPolicy } from './resources.shared.schemas.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';
 import { ResourcesConfigOperationsDtosBuilderUtils } from './utils/resources-config-operations.dtos-builder.utils.js';
 import { ResourcesSummaryUtils } from './utils/resources-summary.utils.js';
+import { collectTemplatableFileFieldPaths, stripTemplatableFileFieldsRecursively } from './utils/templatable-file-fields.shared.utils.js';
+import { isServiceResolvableDefaultOperation, SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES, URL_BEARING_OPERATION_VARIANT_TYPES, } from './utils/resource-operation-type-guards.utils.js';
 // --------------------------------
 // Error Helpers
 // --------------------------------
@@ -22,6 +47,48 @@ import { ResourcesSummaryUtils } from './utils/resources-summary.utils.js';
  * Creates a configuration error with ErrorType.CONFIGURATION
  * Used for resource configuration validation errors at build time
  */
+/**
+ * Reject an `.impersonalizeWith()` treatment declared BELOW the top level of a retention-governed
+ * resource's schema (gate G-FILE / scrub-coverage).
+ *
+ * The impersonalize writer builds its `$set` from the TOP-LEVEL shape only, and file links are stored
+ * under a dotted canonical path (`billingContact.signedMandate`). A nested treatment therefore never
+ * reaches the scrub patch and never matches a linked file's `linkedFieldName`: the row flips to
+ * RETAINED while the nested personal field — and any file beneath it — survive fully intact, with an
+ * audit event asserting the record was impersonalized.
+ *
+ * Recursive scrubbing (dotted-path patches + the matching file-path recursion) is deliberately out of
+ * v1 scope, so this fails at CONFIG BUILD instead of silently under-scrubbing at erasure time. Walks
+ * nested ZodObjects (through optional/nullable/default/array wrappers) and every discriminated-union
+ * option, mirroring how the runtime resolves field paths.
+ */
+function assertNoNestedImpersonalizeTreatment(schema, resourceIdentifier) {
+    const visited = new Set();
+    const walk = (candidate, path, isTopLevel) => {
+        if (!candidate || visited.has(candidate))
+            return;
+        visited.add(candidate);
+        if (!isTopLevel && getImpersonalizeTreatment(candidate) !== undefined) {
+            throw createConfigurationError(`[${resourceIdentifier}] field '${path}' declares an impersonalize treatment, but it is NESTED. ` +
+                `The scrub writes a top-level $set only, so a nested treatment would be silently ignored — the row ` +
+                `would flip to RETAINED with '${path}' (and any file linked under it) fully intact. Move the field to ` +
+                `the top level, or scrub the whole containing field instead (REMOVE on the parent object).`);
+        }
+        const shape = getZodObjectShape(unwrapSchema(candidate) ?? candidate);
+        for (const [childName, childSchema] of Object.entries(shape ?? {})) {
+            walk(childSchema, path ? `${path}.${childName}` : childName, false);
+        }
+    };
+    // Top-level fields are legitimately treatable; only their DESCENDANTS are the problem.
+    const topLevelShape = getZodObjectShape(schema);
+    for (const [fieldName, fieldSchema] of Object.entries(topLevelShape ?? {})) {
+        const unwrapped = unwrapSchema(fieldSchema) ?? fieldSchema;
+        const nestedShape = getZodObjectShape(unwrapped);
+        for (const [childName, childSchema] of Object.entries(nestedShape ?? {})) {
+            walk(childSchema, `${fieldName}.${childName}`, false);
+        }
+    }
+}
 function createConfigurationError(message) {
     const error = new Error(message);
     error.type = ErrorType.CONFIGURATION;
@@ -36,9 +103,51 @@ function createValidationError(message) {
     error.type = ErrorType.VALIDATION;
     return error;
 }
+/**
+ * Reads the shared authority rather than re-listing the members: the URL-bearing
+ * set is consumed by the route-mount gate, the URL/DTO resolver and this factory,
+ * and a variant type added to one copy but not another silently changes which
+ * operations get routes.
+ */
+function isUrlisableOperationVariantType(variantType) {
+    return URL_BEARING_OPERATION_VARIANT_TYPES.includes(variantType);
+}
+/**
+ * The operations a `retentionPolicy` resource must expose to the SERVICE dispatch
+ * layer, with the retention primitive that needs each one.
+ *
+ * Every entry is consumed by BOTH halves of the retention operation contract — the
+ * presence check (is it declared in `coreOperations`?) and the resolvability check
+ * (does it have a default variant `getServiceOperationPathDefault` can serve?) — so
+ * adding a fourth primitive here extends both at once. Listing the ops twice is how
+ * a primitive gets a presence guard and no resolvability guard.
+ */
+const RETENTION_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS = [
+    {
+        operation: CoreResourceOperation.UPDATE_MANY,
+        primitive: 'updateManyAsSystem',
+        why: 'the impersonalize writer scrubs rows in place via updateManyAsSystem',
+    },
+    {
+        operation: CoreResourceOperation.READ,
+        primitive: 'readRetainedAsSystem',
+        why: 'the see-through read primitive readRetainedAsSystem surfaces a single retained record via READ',
+    },
+    {
+        operation: CoreResourceOperation.LIST,
+        primitive: 'listRetainedAsSystem',
+        why: 'the see-through read primitive listRetainedAsSystem surfaces retained records via LIST',
+    },
+];
+function assertOperationPathKeySegment(value, label, operation) {
+    if (value.includes(' | ')) {
+        throw createConfigurationError(`Operation '${operation}' cannot use ${label} '${value}' because operation path keys reserve the delimiter ' | '`);
+    }
+}
 function createGeneratedRelationshipBulkOperations(operations, relevantRelationships, resourceIdentifier, allResourceFieldIdentifiers) {
-    const baseBulkUpdateOperations = operations.filter((operation) => operation.variantType === ResourceOperationVariantType.API_CALL
+    const baseBulkUpdateOperations = operations.filter((operation) => isUrlisableOperationVariantType(operation.variantType)
         && operation.operationIdentifier === CoreResourceOperation.UPDATE
+        && 'isBulkOperation' in operation
         && operation.isBulkOperation === true);
     if (baseBulkUpdateOperations.length > 1) {
         throw createConfigurationError(`[${resourceIdentifier}] generated bulk relationship operations require exactly one API bulk UPDATE base operation, but found ${baseBulkUpdateOperations.length}`);
@@ -82,6 +191,9 @@ function createGeneratedRelationshipBulkOperations(operations, relevantRelations
                 isBulkOperation: true,
                 resourceOperationLike: CoreResourceOperation.UPDATE_MANY,
                 requestDto,
+                // Generated bulk-relationship ops own an explicit request contract (the
+                // bulk action schema above) — preserve it verbatim, never rebuild.
+                hasCustomRequestDto: true,
                 responseDto: ResourceRelationshipBulkActionResultSchema,
                 hasCustomResponseDto: true,
                 basicPrefixOperation: undefined,
@@ -110,9 +222,188 @@ export function reconcileGeneratedRelationshipBulkOperations(resourceConfigurati
         ];
     }
 }
+/**
+ * Derive the CSV/JSON export companion of every LIST/SEARCH operation that declared
+ * `collectionExport`.
+ *
+ * ## Why derived rather than authored
+ *
+ * The export must be exactly as reachable as the listing it exports — never more. Copying the source
+ * operation wholesale and overriding only what must differ makes that structural: an author cannot
+ * give the export wider `roles`, a different parent-scope path, or a laxer variant, because they
+ * never write it. It is the same construction `createGeneratedFileRegenerateOperations` uses one
+ * function above.
+ *
+ * ## What is deliberately CLEARED rather than inherited
+ *
+ * `mcp` is the one that matters. A LIST curated onto an MCP server is a PAGINATED read tool; its
+ * export companion returns the whole result set in a single call, which is a different risk profile.
+ * Spreading the source operation would silently turn "this app declared an export" into "this app
+ * grew a new agent tool that exfiltrates the table", so the flag is dropped and an application that
+ * genuinely wants an agent-callable export has to say so.
+ *
+ * The notification/token fields are cleared for the same reason they are on the regenerate
+ * companion: they describe effects of the SOURCE operation and firing them again on an export would
+ * double-notify.
+ */
+function createGeneratedCollectionExportOperations(params) {
+    const knownOperationIdentifiers = new Set(params.operations.map((operation) => String(operation.operationIdentifier)));
+    const exportOperations = [];
+    for (const operation of params.operations) {
+        const exportConfig = operation.collectionExport;
+        if (!exportConfig) {
+            continue;
+        }
+        const sourceOperationIdentifier = String(operation.operationIdentifier);
+        if (!isUrlisableOperationVariantType(operation.variantType)) {
+            throw createConfigurationError(`[${params.resourceIdentifier}] operation "${sourceOperationIdentifier}" declares collectionExport but is not URL-bearing; an export has no route to live on`);
+        }
+        // The source's CORE verb decides which service call the export re-runs, and it is the only thing
+        // that can: a custom operation carries LIST/SEARCH semantics through `resourceOperationLike`.
+        const sourceCoreOperation = (operation.resourceOperationLike ?? operation.operationIdentifier);
+        if (sourceCoreOperation !== CoreResourceOperation.LIST && sourceCoreOperation !== CoreResourceOperation.SEARCH) {
+            throw createConfigurationError(`[${params.resourceIdentifier}] operation "${sourceOperationIdentifier}" declares collectionExport but is neither LIST nor SEARCH (resolved core operation: ${String(sourceCoreOperation)})`);
+        }
+        // Empty arrays are a startup error, never a silent "offer everything" — the same rule
+        // `mcp.servers` follows, so the declaration always reads as "exactly these".
+        if (!exportConfig.formats || exportConfig.formats.length === 0) {
+            throw createConfigurationError(`[${params.resourceIdentifier}] operation "${sourceOperationIdentifier}" declares collectionExport with no formats; declare at least one, or omit collectionExport entirely`);
+        }
+        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`);
+        }
+        if (exportConfig.maximumExportedRows !== undefined && exportConfig.maximumExportedRows <= 0) {
+            throw createConfigurationError(`[${params.resourceIdentifier}] operation "${sourceOperationIdentifier}" declares a non-positive collectionExport.maximumExportedRows; omit it for no 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`);
+        }
+        knownOperationIdentifiers.add(operationIdentifier);
+        exportOperations.push({
+            ...operation,
+            operationIdentifier,
+            isDefault: false,
+            isOperationDefault: false,
+            isBulkOperation: false,
+            httpVerb: HttpMethod.GET,
+            // Keeps the URL builder treating it as collection-level, and gives a SEARCH export the
+            // `search` segment its source already has — so the two exports of one resource cannot collide.
+            resourceOperationLike: sourceCoreOperation,
+            generatedOperation: {
+                kind: ResourceGeneratedOperationKind.GENERATED_COLLECTION_EXPORT,
+                sourceOperationIdentifier,
+                sourceCoreOperation,
+                export: exportConfig,
+            },
+            // The export takes the SOURCE's query contract (filters, sort, q, pagination) verbatim plus its
+            // own two selectors, so "export what I am looking at" is expressible without a second grammar.
+            responseDto: ResourceCollectionExportResponseSchema,
+            internalDto: ResourceCollectionExportResponseSchema,
+            hasCustomResponseDto: true,
+            // Cleared, not inherited — see this function's docstring.
+            mcp: undefined,
+            collectionExport: undefined,
+            basicPrefixOperation: undefined,
+            notificationBadgeOperations: [],
+            userNotifications: [],
+            m2mNotifications: [],
+            tokenGeneration: undefined,
+            tokenRevocation: undefined,
+        });
+    }
+    return exportOperations;
+}
+function createGeneratedFileRegenerateOperations(params) {
+    const generatedFileDiscoverySchema = params.generatedFileDiscoverySchema ?? params.mainSchema;
+    const collectedFields = collectTemplatableFileFieldPaths(generatedFileDiscoverySchema);
+    const arrayContainedFields = collectedFields.filter((field) => field.isInsideArray);
+    if (arrayContainedFields.length > 0) {
+        throw createConfigurationError(`[${params.resourceIdentifier}] generated PDF file fields inside arrays or dynamic containers are not supported in v1: ${arrayContainedFields.map((field) => field.fieldName).join(', ')}`);
+    }
+    const generatedFields = collectedFields.filter((field) => !field.isInsideArray);
+    if (generatedFields.length === 0) {
+        return [];
+    }
+    /**
+     * Generated PDF file fields are MongoDB-only in v1, so the guard names what IS supported rather
+     * than one adapter that is not: `=== POSTGRESQL` would let any future backing kind slip past as
+     * if it were supported. `undefined` stays admitted — it means "the application's default
+     * adapter", which this shared-tier factory cannot resolve; the backend registry is where an
+     * undeclared adapter gets its concrete answer.
+     */
+    if (params.persistenceAdapter !== undefined && params.persistenceAdapter !== PersistenceAdapter.MONGODB) {
+        throw createConfigurationError(`[${params.resourceIdentifier}] generated PDF file fields are only supported for MongoDB-backed resources in v1 `
+            + `(declared adapter: '${String(params.persistenceAdapter)}'): ${generatedFields.map((field) => field.fieldName).join(', ')}`);
+    }
+    const baseUpdateOperation = params.operations.find((operation) => isUrlisableOperationVariantType(operation.variantType)
+        && operation.operationIdentifier === CoreResourceOperation.UPDATE
+        && 'isBulkOperation' in operation
+        && operation.isBulkOperation !== true
+        && operation.isOperationDefault === true);
+    if (!baseUpdateOperation) {
+        throw createConfigurationError(`[${params.resourceIdentifier}] generated file regenerate operations require a default non-bulk URL-bearing UPDATE operation`);
+    }
+    const knownOperationIdentifiers = new Set(params.operations.map((operation) => String(operation.operationIdentifier)));
+    const responseDto = z.object({
+        file: SingleFileValueSchema,
+        resource: generatedFileDiscoverySchema,
+    });
+    return generatedFields.map(({ fieldName }) => {
+        const operationIdentifier = Resources_SharedUtils.buildGeneratedFileRegenerateOperationIdentifier(fieldName);
+        if (knownOperationIdentifiers.has(operationIdentifier)) {
+            throw createConfigurationError(`[${params.resourceIdentifier}] generated file regenerate operation "${operationIdentifier}" collides with an existing operation identifier`);
+        }
+        knownOperationIdentifiers.add(operationIdentifier);
+        return {
+            ...baseUpdateOperation,
+            operationIdentifier,
+            isDefault: false,
+            isOperationDefault: false,
+            isBulkOperation: false,
+            httpVerb: HttpMethod.POST,
+            resourceOperationLike: CoreResourceOperation.UPDATE,
+            generatedOperation: {
+                kind: ResourceGeneratedOperationKind.GENERATED_FILE_REGENERATE,
+                fieldName,
+            },
+            requestDto: z.object({}),
+            // Generated file-regenerate ops own their request contract: an intentionally
+            // empty body (regeneration is UPDATE-like but takes no input). Preserve it,
+            // do not rebuild from mainSchema decorators.
+            hasCustomRequestDto: true,
+            responseDto,
+            internalDto: responseDto,
+            hasCustomResponseDto: true,
+            basicPrefixOperation: undefined,
+            notificationBadgeOperations: [],
+            userNotifications: [],
+            m2mNotifications: [],
+            tokenGeneration: undefined,
+            tokenRevocation: undefined,
+        };
+    });
+}
 // --------------------------------
 // Token Config Validation
 // --------------------------------
+const BULK_MUTATION_CORE_OPERATIONS = new Set([
+    CoreResourceOperation.CREATE_MANY,
+    CoreResourceOperation.UPDATE_MANY,
+    CoreResourceOperation.DELETE_MANY,
+]);
+const TOKEN_STATE_EFFECT_UNSUPPORTED_CORE_OPERATIONS = new Set([
+    ...BULK_MUTATION_CORE_OPERATIONS,
+    CoreResourceOperation.LIST,
+    CoreResourceOperation.SEARCH,
+    CoreResourceOperation.COUNT,
+]);
+function isCoreBulkMutationOperation(operationIdentifier) {
+    return BULK_MUTATION_CORE_OPERATIONS.has(operationIdentifier);
+}
+function isTokenStateEffectUnsupportedOperation(operationIdentifier) {
+    return TOKEN_STATE_EFFECT_UNSUPPORTED_CORE_OPERATIONS.has(operationIdentifier);
+}
 /**
  * Validates tokenGeneration configuration at build time.
  * Catches common mistakes before the app starts.
@@ -191,8 +482,17 @@ function normalizeRequiredFeatures(input) {
 /**
  * Fields always excluded from create/update DTOs (system-managed)
  * These are hardcoded because they are universal across all resources.
+ *
+ * `createdByUserId` is a reserved audit FK by framework convention: the
+ * repository layer auto-stamps it from the execution context on CREATE
+ * (see RepositoryResource data enrichment) and it is immutable afterwards,
+ * so clients never author it. Request DTOs must omit it even when the app
+ * schema forgets `.excludeFromCreate()` — otherwise create forms validate
+ * against a field no form collects and every submit fails
+ * ("expected string, received undefined"; recovered 2026-06-11 on the
+ * Wonder Todos todoLists create form).
  */
-const SYSTEM_MANAGED_FIELDS = ['_id', 'createdAt', 'updatedAt', 'deletedAt', '_version_db_doc'];
+const SYSTEM_MANAGED_FIELDS = ['_id', 'createdAt', 'updatedAt', 'deletedAt', 'createdByUserId', '_version_db_doc'];
 // PRIMARY_SCOPE_FIELD_IDENTIFIERS and getPrimaryScopeFieldIdentifier imported from resources.shared.schemas
 /**
  * Build a CREATE request DTO from the main schema using decorators.
@@ -211,7 +511,7 @@ const SYSTEM_MANAGED_FIELDS = ['_id', 'createdAt', 'updatedAt', 'deletedAt', '_v
  * @param customExclusions - Additional fields to exclude
  * @returns A new schema with only creatable fields
  */
-function buildCreateRequestDto(mainSchema, customExclusions) {
+export function buildCreateRequestDto(mainSchema, customExclusions) {
     try {
         const shape = getZodObjectShape(mainSchema);
         const createShape = {};
@@ -229,6 +529,10 @@ function buildCreateRequestDto(mainSchema, customExclusions) {
             // Exclude explicitly marked fields
             if (isExcludedFromCreate(typedSchema))
                 continue;
+            // Exclude generated file fields; clients cannot upload or author values
+            // that are materialized by framework-owned operations.
+            if (isTemplatableFileField(typedSchema))
+                continue;
             // NOTE: Backend-only fields are NOT excluded here.
             // isBackendOnly controls response filtering, not request filtering.
             // Backend operations need to set fields like passwordHash directly.
@@ -240,9 +544,9 @@ function buildCreateRequestDto(mainSchema, customExclusions) {
             // Exclude custom exclusions
             if (customExclusions?.includes(fieldName))
                 continue;
-            createShape[fieldName] = fieldSchema;
+            createShape[fieldName] = stripTemplatableFileFieldsRecursively(fieldSchema);
         }
-        return z.object(createShape);
+        return stripTemplatableFileFieldsRecursively(z.object(createShape));
     }
     catch {
         // If schema is not an object, return as-is
@@ -286,6 +590,10 @@ function buildUpdateRequestDto(mainSchema, customExclusions) {
             // Exclude explicitly marked fields
             if (isExcludedFromUpdate(typedSchema))
                 continue;
+            // Exclude generated file fields; explicit regenerate operations own
+            // refreshing these values instead of generic UPDATE payloads.
+            if (isTemplatableFileField(typedSchema))
+                continue;
             // NOTE: Backend-only fields are NOT excluded here.
             // isBackendOnly controls response filtering, not request filtering.
             // Backend operations may need to update fields like passwordHash.
@@ -296,10 +604,12 @@ function buildUpdateRequestDto(mainSchema, customExclusions) {
             // Exclude custom exclusions
             if (customExclusions?.includes(fieldName))
                 continue;
-            // Make field optional for PATCH-style update
-            updateShape[fieldName] = fieldSchema.optional();
+            // Make field optional for PATCH-style update, peeling any `.default()` so
+            // an omitted field is never re-materialized to its default and written
+            // back over the stored value (see `toPatchOptionalField`).
+            updateShape[fieldName] = toPatchOptionalField(stripTemplatableFileFieldsRecursively(fieldSchema));
         }
-        return z.object(updateShape);
+        return stripTemplatableFileFieldsRecursively(z.object(updateShape));
     }
     catch {
         // If schema is not an object, return as-is
@@ -311,7 +621,12 @@ function buildUpdateRequestDto(mainSchema, customExclusions) {
  *
  * - CREATE: Uses buildCreateRequestDto (excludes excludeFromCreate fields)
  * - UPDATE: Uses buildUpdateRequestDto (excludes excludeFromUpdate fields, all partial)
- * - Other operations: Returns mainSchema as-is
+ * - READ/DELETE and custom operations without an explicit DTO: empty object
+ *
+ * This is an early factory placeholder. The final DTO pass in
+ * ResourcesConfigOperationsDtosBuilderUtils applies inherited schemas, the
+ * shared no-body operation policy, and SEARCH query schemas derived from
+ * collection-view metadata.
  *
  * @param operation - The operation identifier
  * @param mainSchema - The main resource schema
@@ -321,7 +636,7 @@ function buildUpdateRequestDto(mainSchema, customExclusions) {
 export function deriveRequestDto(operation, mainSchema, providedDto) {
     // If explicit DTO is provided, use it (for custom operations)
     if (providedDto !== undefined) {
-        return providedDto;
+        return stripTemplatableFileFieldsRecursively(providedDto);
     }
     // Auto-derive based on operation type
     switch (operation) {
@@ -479,6 +794,32 @@ function transformResourceRelationships(resourceRelationships, resourceIdentifie
     // PROCESS MANY-TO-MANY JOINT RESOURCE RELATIONSHIPS
     // ========================================
     const compileSyntheticRelationship = (relationshipDeclaration) => Resources_SharedUtils.compileRelationshipDeclaration(relationshipDeclaration);
+    /**
+     * Build the synthetic **scope-anchored peer-under-scope** edge for an M:N
+     * (scope-required reference search). It makes a target peer `T` addressable
+     * UNDER the other peer `S` for SEARCH/LIST ONLY — e.g.
+     * `/organizations/{organizationId}/users/search` — and tags it with the
+     * junction `J` so the backend (a) scopes the `T` query via a junction subquery
+     * (`T._id ∈ { J.targetFk : J.scopeFk = S_id }` — `T` holds no real FK column
+     * for `S`) and (b) authorizes by `S`-membership instead of `T`'s own scope.
+     * `OPTIONAL_CONTEXT` so the bare `/users/search` (global) route also survives;
+     * `urlOperationScope` keeps this off READ/CREATE/UPDATE/DELETE routes (a
+     * peer-under-scope path is a read-only access pattern).
+     */
+    const buildScopeAnchoredPeerEdge = (scopeType, targetType, junction, isDisabled) => compileSyntheticRelationship({
+        cardinality1: ResourceRelationshipCardinality.ONE, // one scope S
+        cardinality2: ResourceRelationshipCardinality.MANY, // many targets T
+        resourceType1: scopeType, // S — the URL parent (anchor scope)
+        resourceType2: targetType, // T — the searched collection (current peer)
+        nature: RelationshipNature.REFERENCE,
+        parentResourceRequirement: ResourceParentResourceRequirement.OPTIONAL,
+        accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT,
+        isPrimaryScope: false,
+        isDisabled,
+        allowCycle: false,
+        scopeViaJunction: junction,
+        urlOperationScope: [CoreResourceOperation.SEARCH, CoreResourceOperation.LIST],
+    });
     // Find many-to-many relationships with joint resource types (from ALL active relationships,
     // including those with discriminators — a conditional M:N is still an M:N)
     const manyToManyRelationships = activeRelationships.filter(rel => rel.cardinality1 === ResourceRelationshipCardinality.MANY &&
@@ -578,6 +919,9 @@ function transformResourceRelationships(resourceRelationships, resourceIdentifie
                 display: m2mRel.display,
             });
             additionalRelationships.push(relationToJoint);
+            // Scope-anchored read edge: this resource (entity1, the target T) becomes
+            // addressable under entity2 (the scope S) for SEARCH/LIST via the junction.
+            additionalRelationships.push(buildScopeAnchoredPeerEdge(entity2Type, resourceIdentifier, jointResourceType, m2mRel.isDisabled || false));
         }
         else if (resourceIdentifier === entity2Type) {
             // ========================================
@@ -609,6 +953,9 @@ function transformResourceRelationships(resourceRelationships, resourceIdentifie
                 display: m2mRel.display,
             });
             additionalRelationships.push(relationToJoint);
+            // Scope-anchored read edge: this resource (entity2, the target T) becomes
+            // addressable under entity1 (the scope S) for SEARCH/LIST via the junction.
+            additionalRelationships.push(buildScopeAnchoredPeerEdge(entity1Type, resourceIdentifier, jointResourceType, m2mRel.isDisabled || false));
         }
     });
     // Add the additional relationships to the appropriate categories
@@ -851,7 +1198,9 @@ function createResourcePaginatedResponseSchema(params) {
     // Create the result schema with comprehensive validation
     const resultSchema = z.object({
         data: createDataArraySchema(dataSchema),
-        pagination: Resouces_PaginationResponseMetadataSchema
+        // Bounded by the SAME ceiling as the data array above. `limit` reports the page size actually
+        // served, so a stricter bound here rejects pages this very schema just declared valid.
+        pagination: createPaginationResponseMetadataSchema(maxResultsPerPageLimit)
     }).refine(validatePaginatedResponse, {
         message: "Invalid paginated response structure"
     });
@@ -860,8 +1209,23 @@ function createResourcePaginatedResponseSchema(params) {
 // --------------------------------
 // Resource Search Query Request
 // --------------------------------
-function createResourceSearchQueryRequestSchema(params) {
-    const { filterFields, allowedSortFields = [], pagination = true } = params;
+/**
+ * The ONE authority for the `{ pagination, sorting, filters }` argument envelope every
+ * collection-shaped operation accepts.
+ *
+ * Exported rather than factory-private because a second surface needs the identical shape: the MCP
+ * tool adapter advertises this envelope for collection tools whose `requestDto` is empty. A LIST
+ * operation keeps `requestDto: z.object({})` — its filters travel in the QUERY STRING over HTTP, so
+ * giving it a request BODY would misdescribe the REST contract and the generated OpenAPI — yet the
+ * MCP dispatch normalises the very same envelope for it. Advertising had to be fixed without
+ * touching the DTO, and that means this builder is reachable from both places.
+ *
+ * Deriving the shape a second time in the adapter was the rejected alternative: a filter allow-list
+ * that drifts between the surface that ADVERTISES it and the surface that ENFORCES it is precisely
+ * the defect class this envelope already caused once.
+ */
+export function createResourceSearchQueryRequestSchema(params) {
+    const { filterFields, allowedSortFields = [], pagination = true, maxPaginatedResultPerPageLimit } = params;
     // Validate input parameters
     if (filterFields !== undefined && typeof filterFields !== 'object') {
         throw createConfigurationError('Filter fields must be an object');
@@ -913,9 +1277,14 @@ function createResourceSearchQueryRequestSchema(params) {
     };
     // Build the schema dynamically based on parameters
     const schemaConfig = {};
-    // Add pagination if enabled
+    // Add pagination if enabled.
+    //
+    // Built from the operation's ceiling rather than the shared default-bounded constant, so the limit
+    // a caller may REQUEST, the limit the repository will SERVE and the limit the response DTO ACCEPTS
+    // are one number. They were three, and the request side was the strictest — which is why a
+    // declared ceiling above 100 was unreachable over HTTP no matter what the other two allowed.
     if (pagination) {
-        schemaConfig.pagination = Resouces_PaginationRequestSchema.optional();
+        schemaConfig.pagination = createPaginationRequestSchema(maxPaginatedResultPerPageLimit).optional();
     }
     // Add sorting if allowed fields are provided
     if (allowedSortFields && allowedSortFields.length > 0) {
@@ -937,12 +1306,17 @@ function getDefaultHttpVerbForOperation(operation) {
     switch (operation) {
         case CoreResourceOperation.READ:
         case CoreResourceOperation.LIST:
+        case CoreResourceOperation.SEARCH:
+        case CoreResourceOperation.COUNT:
             return HttpMethod.GET;
         case CoreResourceOperation.CREATE:
+        case CoreResourceOperation.CREATE_MANY:
             return HttpMethod.POST;
         case CoreResourceOperation.UPDATE:
+        case CoreResourceOperation.UPDATE_MANY:
             return HttpMethod.PUT;
         case CoreResourceOperation.DELETE:
+        case CoreResourceOperation.DELETE_MANY:
             return HttpMethod.DELETE;
         default:
             return HttpMethod.POST; // Default for unknown operations
@@ -952,16 +1326,31 @@ function getDefaultHttpVerbForOperation(operation) {
  * Determines if an operation variant should be marked as the default operation within its variantType group
  * Handles the complex logic for single vs multiple variants and explicit defaults
  *
- * Rules:
- * 1. If only one variant exists in the group, it becomes default regardless of isDefault value
- * 2. If multiple variants exist in the group and one has isDefault=true, that one becomes default
- * 3. If multiple variants exist in the group and none have isDefault=true, the first one becomes default
- * 4. isDefault=false explicitly excludes an variant from being default
+ * Rules after validation:
+ * 1. If only one variant exists in the group, it becomes the group default UNLESS the author
+ *    explicitly opted it out with `isDefault: false`. An omitted/`undefined` `isDefault` still
+ *    becomes the group default — only an explicit `false` is honored.
+ *
+ *    Rationale: a sole `isDefault: false` variant is a real authoring signal that this transport
+ *    has NO default for the operation. Example: `users.list` declares an `INTERNAL_CALL` default
+ *    plus a single keyed `API_CALL` "admin" variant marked `isDefault: false` — there is no public
+ *    default URL listing, only the admin-keyed one. The prior behavior force-defaulted such a
+ *    variant, which (a) contradicted author intent and (b) produced two `isOperationDefault === true`
+ *    operations for one operation identifier across transport groups (one per group) — a latent
+ *    hazard for any consumer that filters defaults across transports (e.g. a set-filter that matches
+ *    >1 and throws). Honoring the explicit `false` keeps each transport group with at most one
+ *    default and makes the variant resolvable only via its keyed path resolver, which is the intent.
+ *    See `.claude/plans/internal-call-operation-path-resolution.md` (D6 + RESOLUTION).
+ * 2. If multiple variants exist in the group, validation requires exactly one `isDefault=true`.
+ * 3. Fallback selection is kept for direct/test-only callers that bypass factory validation,
+ *    but authored multi-variant groups must never rely on array order.
  */
 function determineOperationVariantDefault(variantsOfSameType, currentVariant) {
-    // Rule 1: Single variant of this type is always default
+    // Rule 1: A single variant of this type is the group default UNLESS the author
+    // explicitly opted out with `isDefault: false`. An omitted/`undefined` `isDefault`
+    // still becomes the default — only an explicit `false` is honored (see JSDoc above).
     if (variantsOfSameType.length === 1) {
-        return true;
+        return currentVariant.isDefault !== false;
     }
     // Rule 2: Find explicit isDefault=true within this variant type group
     const explicitDefaultVariant = variantsOfSameType.find(variant => variant.isDefault === true);
@@ -977,7 +1366,20 @@ function determineOperationVariantDefault(variantsOfSameType, currentVariant) {
     // Fallback: if all variants have isDefault=false, first one becomes default anyway
     return currentVariant === variantsOfSameType[0];
 }
-const RESERVED_OPERATION_VARIANT_KEYS = new Set(['isDefault', 'noVariantKey']);
+const RESERVED_OPERATION_VARIANT_KEYS = new Set([
+    'isdefault',
+    'novariantkey',
+]);
+const AUTO_OPERATION_VARIANT_KEYS = new Set([
+    OPERATION_VARIANT_KEY.SUMMARY,
+    OPERATION_VARIANT_KEY.CONTEXT,
+]);
+function isDataModeVariantKeyAllowedForOperation(operation, variant) {
+    const effectiveOperation = variant.resourceOperationLike ?? operation;
+    return effectiveOperation === CoreResourceOperation.READ
+        || effectiveOperation === CoreResourceOperation.LIST
+        || effectiveOperation === CoreResourceOperation.SEARCH;
+}
 // --------------------------------
 // Resources Shared Configuration
 // --------------------------------
@@ -987,7 +1389,195 @@ const RESERVED_OPERATION_VARIANT_KEYS = new Set(['isDefault', 'noVariantKey']);
  * the isBackendOnly decorator in mainSchema and are stripped at the service layer.
  */
 export function createResourceConfiguration_Initialization(params) {
-    const { mainSchema, resourceIdentifier, resourceFieldIdentifier, resourceRelationships, inheritenceSchemaDefinition, isSystemResource = false, isAnonymizable = false, transpositionPolicy, persistenceAdapter, coreOperations, customOperation, operationsConfiguration, } = params;
+    const { mainSchema, resourceIdentifier, resourceFieldIdentifier, resourceRelationships, inheritenceSchemaDefinition, isSystemResource = false, 
+    // Defaulted TRUE — the safe direction. A resource that never considered whether its primary key
+    // names the caller keeps the identity-coherence refusal; only a deliberate `false` relaxes it.
+    primaryKeyIdentifiesInitiator = true, 
+    // Fail-closed default: a resource that does not author `systemAccessPolicy`
+    // gets an explicit all-verbs-FORBIDDEN policy, so the resolved config is
+    // self-documenting and every system-context primitive
+    // (`readAsSystem`/`listAsSystem` and the trusted
+    // `createAsSystem`/`updateAsSystem`/`updateManyAsSystem` writes) rejects it
+    // by default.
+    systemAccessPolicy = {
+        read: ResourceSystemAccessMode.FORBIDDEN,
+        list: ResourceSystemAccessMode.FORBIDDEN,
+        create: ResourceSystemAccessMode.FORBIDDEN,
+        update: ResourceSystemAccessMode.FORBIDDEN,
+        updateMany: ResourceSystemAccessMode.FORBIDDEN,
+    }, isAnonymizable = false, transpositionPolicy, retentionPolicy, dataSubjectPolicy, portabilityPolicy, 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:
+     * - `HTTP_API` without a binding is a resource whose rows live "somewhere over HTTP" with no
+     *   target, key, identity or erasure story — nothing downstream can repair that;
+     * - a binding on a platform-backed resource is a declaration nothing will ever read, i.e. a
+     *   config that LOOKS externally bound and silently is not.
+     * The binding's CONTENT is validated here too (Zod parse) so a malformed declaration names its
+     * defect at the factory, not at boot. (ETL plan Step 3; registration-time checks that need the
+     * RESOLVED adapter or the live registry — scope expressibility, retention/anonymizable/scope-root
+     * refusals — live in the backend registry validation, which structurally cannot run here.)
+     */
+    if (persistenceAdapter === PersistenceAdapter.HTTP_API && httpApiBinding === undefined) {
+        throw createConfigurationError(`[${resourceIdentifier}] persistenceAdapter 'http-api' requires the companion 'httpApiBinding' declaration (provider, dialect, key fields, identity, tenancy, erasure).`);
+    }
+    if (persistenceAdapter === PersistenceAdapter.INTROSPECTION && introspectionBinding === undefined) {
+        throw createConfigurationError(`[${resourceIdentifier}] persistenceAdapter 'introspection' requires an 'introspectionBinding' naming the companion behavior whose output becomes this resource's rows.`);
+    }
+    if (introspectionBinding !== undefined && persistenceAdapter !== PersistenceAdapter.INTROSPECTION) {
+        throw createConfigurationError(`[${resourceIdentifier}] 'introspectionBinding' is declared but persistenceAdapter is '${String(persistenceAdapter ?? 'undeclared (application default)')}' — a binding on a stored resource would never be read. Declare persistenceAdapter: 'introspection' or remove the binding.`);
+    }
+    if (httpApiBinding !== undefined && persistenceAdapter !== PersistenceAdapter.HTTP_API) {
+        throw createConfigurationError(`[${resourceIdentifier}] 'httpApiBinding' is declared but persistenceAdapter is '${String(persistenceAdapter ?? 'undeclared (application default)')}' — a binding on a platform-backed resource would never be read. Declare persistenceAdapter: 'http-api' or remove the binding.`);
+    }
+    /**
+     * `persistenceAdapterIsolation` alongside `HTTP_API` is REFUSED, because the claim it makes is
+     * one the adapter has already settled — so honouring it would be honouring nothing.
+     *
+     * The declaration exists to buy a resource admission past the one-adapter rule when it disagrees
+     * with the application default: its author asserts the resource takes part in no cross-adapter
+     * atomic write, and the resources registry admits it and logs the admitted set. An `HTTP_API`
+     * resource is admitted by that same rule WITHOUT any such assertion, on the adapter's own nature —
+     * it is not a second platform store, it owns no transactions, and it cannot be an application
+     * default. The registry's exemption is therefore ordered BEFORE the isolation branch and returns
+     * first, so on an `HTTP_API` resource the isolation claim is never read.
+     *
+     * Silently ignoring it is the outcome worth preventing. An author who writes the field believes
+     * they have bought something, and every later reader believes the resource's admission depends on
+     * it — so a future change to the isolation door would look like it affected this resource when it
+     * could not. A field whose absence and presence are indistinguishable is worse than a rejected
+     * one; this is the same reasoning as the sibling refusal directly above, where a binding on a
+     * platform-backed resource is refused precisely because nothing would ever read it.
+     */
+    if (persistenceAdapter === PersistenceAdapter.HTTP_API && persistenceAdapterIsolation !== undefined) {
+        throw createConfigurationError(`[${resourceIdentifier}] 'persistenceAdapterIsolation' is declared alongside persistenceAdapter 'http-api', where it is never read — an http-api resource is admitted past the one-adapter rule on the adapter's own nature, not on an isolation claim. Remove the isolation declaration.`);
+    }
+    if (httpApiBinding !== undefined) {
+        const bindingParse = HttpApiResourceBindingSchema.safeParse(httpApiBinding);
+        if (!bindingParse.success) {
+            throw createConfigurationError(`[${resourceIdentifier}] invalid httpApiBinding declaration: ${bindingParse.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ')}`);
+        }
+        try {
+            assertHttpApiBindingDialectCoherence(bindingParse.data);
+        }
+        catch (error) {
+            throw createConfigurationError(`[${resourceIdentifier}] invalid httpApiBinding declaration: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * `externalDataPipeline` — the inbound ETL pipeline on an ordinary LOCAL resource (partial-resource
+     * coverage v3; PR-3/PR-4). Validated at AUTHORING like `httpApiBinding` above: shape (Zod),
+     * schema-independent coherence (`assertExternalDataPipelineDeclarationCoherence` — S1 tenancy
+     * confinement, unique mapping targets, coercion×dialect), the source binding's own dialect
+     * coherence, and every mainSchema-dependent rule:
+     *
+     *  - the pipeline is FORBIDDEN on an HTTP_API-adapter resource (a virtual resource IS the
+     *    remote side — chaining a pipeline onto read-through would re-create the composite v1
+     *    rejected);
+     *  - `remoteKeyLocalField` exists, is a STRING, and is declared `.isBusinessKey()` +
+     *    `excludeFromCreate` + `excludeFromUpdate` — SYNC's idempotent upsert keys on it and no
+     *    caller may mint or move it (boot-CHECKED, not factory-mutated: the app author sees the
+     *    truth in their own schema file);
+     *  - every mapped local field exists and is `excludeFromCreate`/`excludeFromUpdate`
+     *    (remote-authoritative — D-P5), and a non-`required` REMOTE_FIELD target must ACCEPT
+     *    ABSENCE (optional/nullable/default wrapper), or an absent remote value would have nowhere
+     *    honest to land (v3.1 §3);
+     *  - `ISO_STRING_TO_DATE` targets must be date fields;
+     *  - `population: CLOSED` refuses declared caller CREATE operations (D-P8) — INCLUDING a custom
+     *    operation that is create-shaped through `resourceOperationLike`. Enumerating only
+     *    `coreOperations` was the earlier, narrower form and it was a real hole: a custom operation
+     *    is exactly where an author expresses "mint a row my own way", so it is the likeliest way
+     *    into a CLOSED population, not an exotic one.
+     */
+    const externalDataPipeline = params.externalDataPipeline === undefined ? undefined : (() => {
+        const refuse = (message) => {
+            throw createConfigurationError(`[${resourceIdentifier}] invalid externalDataPipeline declaration: ${message}`);
+        };
+        if (persistenceAdapter === PersistenceAdapter.HTTP_API) {
+            refuse("an HTTP_API-adapter (virtual) resource cannot ALSO declare a pipeline — it IS the remote side; declare the pipeline on the LOCAL destination resource instead.");
+        }
+        const declarationParse = ExternalDataPipelineDeclarationSchema.safeParse(params.externalDataPipeline);
+        if (!declarationParse.success) {
+            refuse(declarationParse.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; '));
+        }
+        const declaration = declarationParse.data;
+        try {
+            assertExternalDataPipelineDeclarationCoherence(declaration);
+            assertHttpApiBindingDialectCoherence(declaration.binding);
+        }
+        catch (error) {
+            refuse(error instanceof Error ? error.message : String(error));
+        }
+        const shape = getZodObjectShape(mainSchema);
+        const requireMappedTarget = (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}: local field '${fieldName}' must be declared .excludeFromCreate() and .excludeFromUpdate() — it is REMOTE-AUTHORITATIVE (written only by the pipeline), and the exclusion is also what renders it read-only end to end (DTO → UI).`);
+            }
+            return fieldSchema;
+        };
+        const keyFieldSchema = requireMappedTarget(declaration.remoteKeyLocalField, 'remoteKeyLocalField');
+        if (!(unwrapSchema(keyFieldSchema) instanceof z.ZodString)) {
+            refuse(`remoteKeyLocalField: '${declaration.remoteKeyLocalField}' must be a STRING field — it stores the synthesized remote id.`);
+        }
+        if (!isBusinessKeyField(keyFieldSchema)) {
+            refuse(`remoteKeyLocalField: '${declaration.remoteKeyLocalField}' must be declared .isBusinessKey() — SYNC's idempotent upsert keys on it, and the business-key declaration is what makes the load MERGE instead of duplicate.`);
+        }
+        for (const entry of declaration.mapping) {
+            const targetSchema = requireMappedTarget(entry.localField, `mapping('${entry.localField}')`);
+            if (entry.kind === ExternalDataMappingEntryKind.REMOTE_FIELD) {
+                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).`);
+                }
+                if (entry.coercion === ExternalDataFieldCoercion.ISO_STRING_TO_DATE && !(unwrapSchema(targetSchema) instanceof z.ZodDate)) {
+                    refuse(`mapping('${entry.localField}'): coercion ISO_STRING_TO_DATE targets a date field.`);
+                }
+                // ⚠ Odoo spells ABSENT values as literal `false` (v3.1 §3 / PR-8), so on an Odoo source
+                // the false→null coercion is the DEFAULT — resolved HERE, at authoring time, because this
+                // is the one place the destination field's type is known: a genuine BOOLEAN target keeps
+                // its `false` (Odoo booleans really are `false`), everything else would otherwise persist
+                // a literal `false` into a string/date/number field. The runtime transform then applies
+                // only RESOLVED coercions and carries no schema knowledge.
+                if (declaration.binding.dialect === HttpApiTransportDialect.ODOO_JSONRPC
+                    && entry.coercion === ExternalDataFieldCoercion.NONE
+                    && !(unwrapSchema(targetSchema) instanceof z.ZodBoolean)) {
+                    entry.coercion = ExternalDataFieldCoercion.ODOO_FALSE_AS_NULL;
+                }
+            }
+        }
+        if (declaration.population === ExternalDataDestinationPopulation.CLOSED) {
+            // Enumerate by the operation's EFFECTIVE semantics, never by its identifier: a CORE operation
+            // is its own semantics, while a CUSTOM one declares them per variant through
+            // `resourceOperationLike` (the same resolution `isDataModeVariantKeyAllowedForOperation`
+            // uses). Both sources are unioned because neither sees the other's members — `coreOperations`
+            // can name an operation with no authored configuration entry, and `operationsConfiguration`
+            // is where a custom operation exists at all.
+            const createShaped = new Set([
+                CoreResourceOperation.CREATE,
+                CoreResourceOperation.CREATE_MANY,
+            ]);
+            const declaredCreates = new Set();
+            for (const operation of coreOperations) {
+                if (createShaped.has(operation))
+                    declaredCreates.add(String(operation));
+            }
+            for (const [operationKey, operationConfig] of Object.entries((operationsConfiguration ?? {}))) {
+                const variants = operationConfig?.variants ?? [];
+                const effectiveOperations = variants.length > 0
+                    ? variants.map((variant) => variant.resourceOperationLike ?? operationKey)
+                    : [operationKey];
+                if (effectiveOperations.some((effective) => createShaped.has(effective))) {
+                    declaredCreates.add(operationKey);
+                }
+            }
+            if (declaredCreates.size > 0) {
+                refuse(`population CLOSED: every row comes from the pipeline, so caller CREATE operations (${[...declaredCreates].sort().join(', ')}) are refused — declare population: OPEN if users may mint rows beside the synced ones. A CUSTOM operation counts when a variant declares a create-shaped resourceOperationLike.`);
+            }
+        }
+        return declaration;
+    })();
     const normalizedResourceRelationships = Resources_SharedUtils.ensureCompiledRelationships(resourceRelationships);
     // ========================================
     // VALIDATE DECORATOR COMBINATIONS
@@ -997,30 +1587,97 @@ export function createResourceConfiguration_Initialization(params) {
     // ========================================
     // DERIVE RESOURCE PRIMARY SCOPE
     // ========================================
-    // Find relationships involving this specific resource (as parent or child)
+    //
+    // Two derivation signals are permitted (no silent default). A third
+    // mechanism — polymorphic factories — is mechanically a special case of (2):
+    //
+    // 1. SELF-ANCHOR — the resource itself is one of the canonical scope roots
+    //    (USERS, ORGANIZATIONS, APPLICATION, ANONYMOUS_USERS). The PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE
+    //    map encodes that bijection.
+    //
+    // 2. FLAGGED RELATIONSHIP — exactly one relationship involving this resource
+    //    has `isPrimaryScope: true`. The rel-factory enforces that the flag can
+    //    only be set on a parent (not a child-side) and that the parent resolves
+    //    to a known scope-root in the primaryScopeMap, so reading
+    //    `primaryScopeRelationship.primaryScope` here always yields a valid enum.
+    //
+    // 3. POLYMORPHIC VARIANT (special case of 2) — resources built via
+    //    `createPolymorphicResourceConfigurations(...)` (e.g. SSO connections,
+    //    billing accounts, subscriptions, M2M webhooks). The polymorphic factory
+    //    auto-injects an `isPrimaryScope: true` rel per declared variant, so each
+    //    variant resolves through path (2) without the author having to re-declare
+    //    the anchor manually. If you reach the throw below for a polymorphic
+    //    resource, the variant declaration is missing its scope mapping — fix
+    //    the polymorphic config, NOT the registry rel list.
+    //
+    // If no derivation signal is present we THROW. The framework cannot quietly
+    // assume a scope: scope drives auth, notifications, execution context, URL
+    // routing, and cross-tenant isolation. A wrong default would be a silent
+    // security regression. Every resource author MUST declare scope explicitly
+    // via one of the three signals above.
+    //
+    // Migration: if you hit this throw, add a STANDALONE primary rel from the
+    // owning scope-root (e.g. `ORGANIZATIONS → yourResource`,
+    // `USERS → yourResource`, `APPLICATION → yourResource`) with
+    // `accessScopeStrategy: STANDALONE` and `isPrimaryScope: true`. STANDALONE
+    // keeps the rel inert for URL routing while declaring the structural
+    // ownership anchor — see `resources-relationships.shared.factory.ts` Guard 1.
+    const selfScopeEntry = Object.entries(PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE).find(([, coreType]) => coreType === resourceIdentifier);
     const relevantRelationships = normalizedResourceRelationships.filter(rel => rel.resourceType1 === resourceIdentifier || rel.resourceType2 === resourceIdentifier);
-    // Find the resource relationship with isPrimaryScope=true for this resource
     const primaryScopeRelationship = relevantRelationships.find(rel => rel.isPrimaryScope === true);
     let resourcePrimaryScope;
-    if (primaryScopeRelationship?.primaryScope) {
+    if (selfScopeEntry) {
+        resourcePrimaryScope = selfScopeEntry[0];
+    }
+    else if (primaryScopeRelationship?.primaryScope) {
         resourcePrimaryScope = primaryScopeRelationship.primaryScope;
     }
     else {
-        // Check if this resource IS itself a primary scope anchor
-        // (e.g., USERS, ORGANIZATIONS, APPLICATION, ANONYMOUS_USERS)
-        const selfScopeEntry = Object.entries(PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE).find(([, coreType]) => coreType === resourceIdentifier);
-        if (selfScopeEntry) {
-            resourcePrimaryScope = selfScopeEntry[0];
-        }
-        else {
-            resourcePrimaryScope = ResourcePrimaryScope.ORGANIZATIONS;
-        }
+        throw createConfigurationError(`[${resourceIdentifier}] Cannot derive resourcePrimaryScope.\n` +
+            `\n` +
+            `A resource configuration MUST declare its primary scope via one of:\n` +
+            `  (1) Self-anchor — the resource itself is a canonical scope root\n` +
+            `      (USERS, ORGANIZATIONS, APPLICATION, ANONYMOUS_USERS).\n` +
+            `  (2) Flagged relationship — exactly one parent relationship carries\n` +
+            `      \`isPrimaryScope: true\` (parent resolves to a known scope root).\n` +
+            `  (3) Polymorphic variant — resources built via\n` +
+            `      \`createPolymorphicResourceConfigurations(...)\` get an\n` +
+            `      \`isPrimaryScope: true\` rel auto-injected per variant. If you\n` +
+            `      reach this throw for a polymorphic resource, your variant\n` +
+            `      declaration is missing its scope mapping — fix the polymorphic\n` +
+            `      config, NOT the registry rel list.\n` +
+            `\n` +
+            `No signal was found for resource '${resourceIdentifier}'.\n` +
+            `\n` +
+            `Fix: add a primary-anchor relationship in the registry. For an internal\n` +
+            `resource that should NOT be URL-routed under its scope parent, use:\n` +
+            `\n` +
+            `  createResourcesRelationship(\n` +
+            `    CoreResourceType.ORGANIZATIONS, '${resourceIdentifier}',\n` +
+            `    ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,\n` +
+            `    {\n` +
+            `      accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.STANDALONE,\n` +
+            `      isPrimaryScope: true,\n` +
+            `      nature: RelationshipNature.REFERENCE,\n` +
+            `      contextPolicy: { enabled: false },\n` +
+            `    }\n` +
+            `  )\n` +
+            `\n` +
+            `For a routable child resource, drop the STANDALONE strategy and add\n` +
+            `\`isPrimaryScope: true\` to the existing parent relationship.\n` +
+            `\n` +
+            `Background: the framework no longer falls back to a silent ORGANIZATIONS\n` +
+            `default — primary scope drives auth, notifications, execution context,\n` +
+            `URL routing, and cross-tenant isolation, so a wrong default would be a\n` +
+            `silent security regression. See \`resources-config.shared.factory.ts\`\n` +
+            `(DERIVE RESOURCE PRIMARY SCOPE) for the full rationale.`);
     }
     // ========================================
     // isAnonymizable VALIDATION & ENRICHMENT (W7.3a)
     // ========================================
     let effectiveMainSchema = mainSchema;
     let effectiveResourceRelationships = normalizedResourceRelationships;
+    let effectiveSystemAccessPolicy = systemAccessPolicy;
     if (isAnonymizable) {
         if (resourcePrimaryScope !== ResourcePrimaryScope.USER_SELF) {
             throw createConfigurationError(`[${resourceIdentifier}] isAnonymizable: true requires primaryScope USER_SELF, got ${resourcePrimaryScope}.`);
@@ -1063,6 +1720,424 @@ export function createResourceConfiguration_Initialization(params) {
                 : undefined,
         });
         effectiveResourceRelationships = [...normalizedResourceRelationships, anonymousRelationship];
+        // ── Derive the transposition system-access grant (W7.3a) ──────────────
+        //
+        // Anonymous→user ownership transposition (`AnonymousSessionBackendService`)
+        // rewrites `{ userId, anonymousUserId }` across every anonymizable resource
+        // via `SystemAccessBackendService.updateManyAsSystem`. That primitive is
+        // fail-closed on `systemAccessPolicy.updateMany` PER RESOURCE, and both FKs
+        // it writes are context-auto-populated names the client-shaped request DTO
+        // strips — so WITHOUT the grant the transposition would either throw
+        // `CONFIGURATION` (fail-closed) or silently no-op, stranding the converting
+        // user's rows under the anonymous id until the cleanup batch deletes them
+        // (user-visible data loss).
+        //
+        // This grant is DERIVED, not authored, precisely because it is not an
+        // incidental capability: it is THE mechanism `isAnonymizable` exists to
+        // enable. The factory already REQUIRES `UPDATE_MANY` in `coreOperations`
+        // above "for transposition batch update"; that core operation is
+        // unreachable by the transposition service without this system-access
+        // opt-in, so deriving it here COMPLETES an existing coupling rather than
+        // inventing a new one — and removes a guaranteed per-app footgun (every
+        // app marking a resource `isAnonymizable` would otherwise have to remember
+        // the grant, and the engine core ships zero anonymizable resources to model
+        // it from).
+        //
+        // Distinct from the `systemAccessPolicy` ⟂ `isSystemResource` separation
+        // documented on the policy type: `isSystemResource` is a broad, ACL-
+        // orthogonal marker (framework infra does NOT imply an ACL bypass is
+        // acceptable), whereas `isAnonymizable` has a single, specific engine
+        // behaviour that requires exactly `updateManyAsSystem`. The derived value
+        // is materialised into the RESOLVED config below (not hidden in factory
+        // control flow), so specs, audits, and `assertSystemAccessAllowed` all see
+        // `updateMany: ALLOWED`. Any explicitly-authored `systemAccessPolicy` on an
+        // anonymizable resource is preserved for its other verbs; only `updateMany`
+        // is forced ALLOWED (a transposition-required resource cannot opt out of
+        // its own transposition).
+        //
+        // FAIL-LOUD (not silent-override): if the author EXPLICITLY declared
+        // `updateMany: FORBIDDEN`, that contradicts `isAnonymizable` (the resource
+        // asks for transposition yet forbids the only primitive that performs it).
+        // Silently flipping it to ALLOWED would erase an explicit security
+        // declaration — dishonest. Throw instead. We read the RAW authored policy
+        // (`params.systemAccessPolicy`), NOT the destructured value: an unauthored
+        // policy is defaulted to all-verbs-FORBIDDEN above, and forcing THAT to
+        // ALLOWED is the intended, non-contradictory derive (the common case). Only
+        // a hand-written `updateMany: FORBIDDEN` is the contradiction we reject.
+        if (params.systemAccessPolicy?.updateMany === ResourceSystemAccessMode.FORBIDDEN) {
+            throw createConfigurationError(`[${resourceIdentifier}] isAnonymizable: true requires systemAccessPolicy.updateMany = ALLOWED ` +
+                `(anonymous→user transposition rewrites { userId, anonymousUserId } via updateManyAsSystem), but ` +
+                `this resource explicitly authored updateMany: FORBIDDEN. A transposition-required resource cannot ` +
+                `opt out of its own transposition — remove the explicit FORBIDDEN (the grant is derived automatically) ` +
+                `or drop isAnonymizable.`);
+        }
+        effectiveSystemAccessPolicy = {
+            ...systemAccessPolicy,
+            updateMany: ResourceSystemAccessMode.ALLOWED,
+        };
+    }
+    // ========================================
+    // retentionPolicy VALIDATION & ENRICHMENT (impersonalization-on-erasure)
+    // ========================================
+    //
+    // Mirror of the isAnonymizable branch above, for the OTHER trusted-write axis:
+    // on erasure a retention-governed resource is impersonalized-and-retained
+    // (personal fields scrubbed via `updateManyAsSystem`, row KEPT) instead of
+    // hard-deleted. Injects the per-record `retentionStatus` marker and derives the
+    // system-access grants the capability requires. RESOURCE-level: the per-edge
+    // trigger (`onParentDelete.strategy = IMPERSONALIZE_AND_RETAIN`) and per-field scrub
+    // (`.impersonalizeWith()`) are declared separately.
+    if (retentionPolicy?.mode) {
+        // PRESENCE half of the retention operation contract: each required op must be declared at all.
+        // The RESOLVABILITY half — that the declared op has a variant the retention primitives can
+        // actually dispatch — runs later, once the operation variants are assembled (search
+        // `RETENTION_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS`). Deliberately two checks, because they have
+        // two different fixes: "declare the op" vs "declare it with a service-resolvable variant".
+        for (const { operation: requiredOperation, why } of RETENTION_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS) {
+            if (!coreOperations.includes(requiredOperation)) {
+                throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy requires ${requiredOperation} in coreOperations (${why}).`);
+            }
+        }
+        // Guard (framework-quality): `retentionStatus` / `impersonalizedAt` are framework-reserved
+        // injected names. Zod-4 `.extend()` SILENTLY OVERWRITES a duplicate key, so a resource that
+        // already declares one would have its own field clobbered on opt-in — fail loud instead. The
+        // same `getZodObjectShape` call also yields a friendly config error if `mainSchema` is not a
+        // ZodObject (the marker cannot be injected into a non-object schema).
+        // EXPLICIT object check. (Do NOT rely on `getZodObjectShape` throwing — it returns `{}` for a
+        // union, so a try/catch around it is dead code and the real failure surfaces later as an
+        // undiagnosable `effectiveMainSchema.extend is not a function`.)
+        if (!isZodObject(effectiveMainSchema)) {
+            throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy requires a ZodObject mainSchema (cannot inject the ` +
+                `retentionStatus marker into a non-object schema — polymorphic/union mainSchemas are not yet supported).`);
+        }
+        const existingShape = getZodObjectShape(effectiveMainSchema);
+        for (const reservedField of ['retentionStatus', 'impersonalizedAt']) {
+            if (existingShape[reservedField]) {
+                throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy injects a reserved '${reservedField}' field, but this ` +
+                    `resource already declares one. Rename that field or drop retentionPolicy (the marker is factory-injected).`);
+            }
+        }
+        // ========================================
+        // IMPERSONALIZE TREATMENT VALIDATION — fail loud at CONFIG BUILD, not on the erasure path.
+        // ========================================
+        //
+        // The impersonalize writer scrubs via `updateManyAsSystem`, whose STRICT update-DTO parse runs
+        // over the scrub patch. A treatment the declared field schema cannot accept therefore throws
+        // INSIDE the parent-delete transaction and ROLLS BACK the erasure — the worst possible moment to
+        // discover a config mistake. Every check below is a pure `safeParse` against the AUTHORED field
+        // schema, so it catches every axis at once without a type taxonomy:
+        //
+        //  - REMOVE writes `null`, which the field-clearing contract resolves into either a stored null
+        //    (null-accepting field) or a removed key (merely `.optional()`). Both are what REMOVE asks
+        //    for, so the requirement is that the field be CLEARABLE — i.e. not required and not
+        //    `.default()`-wrapped, since a default's output type is non-optional.
+        //    HISTORY, because this comment justified a stricter guard for months: update DTOs used to
+        //    be made `.optional()` and NEVER `.nullable()`, so a non-nullish field really did reject
+        //    the scrub, and the capability was non-functional for every non-nullable field. That
+        //    changed when `toPatchOptionalField` began admitting null for clearable fields; the guard
+        //    below was left demanding `.nullish()` and so failed startup on valid declarations.
+        //  - MASK writes the field's EFFECTIVE mask value — its own `maskValue` override, or
+        //    `IMPERSONALIZE_MASK_CONSTANT`. Beyond the obvious number/date/enum/boolean mismatches, the
+        //    default constant also fails CONSTRAINED strings — `z.email()`, `z.uuid()`, `.min(n)` — i.e.
+        //    exactly the PII fields most likely to be masked, which is why the override exists. A
+        //    "MASK is string-only" rule would NOT be sufficient. An override is validated against the
+        //    field's own schema here, and is rejected outright on a non-MASK treatment (nothing would
+        //    write it).
+        //  - A resource that opts into retentionPolicy but declares ZERO treatments would flip rows to
+        //    `RETAINED` with every personal field intact: a compliance-grade lie (it LOOKS erased).
+        for (const [fieldName, fieldSchema] of Object.entries(existingShape)) {
+            const treatment = getImpersonalizeTreatment(fieldSchema);
+            if (treatment === undefined)
+                continue;
+            // Floor fields are never scrubbed, so their schema need not accept a scrub value. Reuse the
+            // writer's own floor predicate — one authority, so the guard can never drift from the scrub.
+            if (isImpersonalizeNeverScrubFloorField(fieldName))
+                continue;
+            // D1 allows SEVERING the person-link (`userId` / `anonymousUserId`) — but only when a NON-person
+            // scope survives to anchor the retained row. If the person-link IS the resource's primary scope,
+            // nulling it strips the row's only tenant anchor: contextual scoping can no longer reach it, so
+            // the retained record becomes invisible even to the audited see-through path that retention
+            // exists to serve (retained-but-unreachable ≠ retained).
+            const severedScope = FIELD_IDENTIFIER_TO_PRIMARY_SCOPE[fieldName];
+            if (treatment === RedactionType.REMOVE &&
+                severedScope !== undefined &&
+                severedScope === resourcePrimaryScope) {
+                throw createConfigurationError(`[${resourceIdentifier}] field '${fieldName}' declares impersonalize treatment REMOVE, but it is this ` +
+                    `resource's PRIMARY scope ('${severedScope}'). Severing the primary-scope link would leave the retained ` +
+                    `row with no tenant anchor — unreachable through contextual scoping, including the audited see-through ` +
+                    `read. Keep the primary-scope link (use KEEP) and scrub the personal FIELDS instead.`);
+            }
+            // NOTE ON UNIQUE-INDEXED FIELDS (gate G-BKEY): a scrub writes the SAME value to every row in
+            // the batch (`null` for REMOVE, one shared mask constant for MASK), which on a plain unique
+            // index would collide (E11000) and abort the erasure. That is NOT rejected here, because the
+            // schema layer scopes every unique index on a retention-governed resource to NON-RETAINED rows
+            // (`partialFilterExpression`, see `buildRetentionPartialFilterExpression`): the scrubbed rows
+            // become RETAINED in the same write, leave the index, and therefore cannot collide — the same
+            // property that stops a retained row from permanently locking out re-creation of its key.
+            // ⚠️ This guard's absence DEPENDS on that partial index. If the partial filter is ever removed,
+            // a treatment on a unique field becomes an erasure-aborting defect again.
+            // A maskValue is meaningful ONLY under MASK — no other treatment writes it. Declaring one
+            // elsewhere means the author believes a specific value will be stored while the writer would
+            // null the field (REMOVE) or leave it untouched (KEEP): the declaration and the behaviour
+            // disagree, which is the same class of silent compliance lie the zero-scrub guard prevents.
+            // Checked BEFORE the per-treatment branches, and independently of them — as an arm of that
+            // if/else chain it would be unreachable for exactly the treatments it needs to reject.
+            if (treatment !== RedactionType.MASK && getImpersonalizeMaskValue(fieldSchema) !== undefined) {
+                throw createConfigurationError(`[${resourceIdentifier}] field '${fieldName}' declares an impersonalize maskValue but its treatment is ` +
+                    `'${treatment}', not MASK — nothing would ever write that value. Use MASK to store it, or drop the maskValue.`);
+            }
+            if (treatment === RedactionType.REMOVE) {
+                // REMOVE writes `null`, and the field-clearing contract decides what that PERSISTS as: a
+                // null-accepting field stores the null, a merely-`.optional()` field has the key removed.
+                // Either outcome is what REMOVE asks for, so the requirement is CLEARABILITY, not
+                // null-acceptance.
+                //
+                // This guard used to demand `.nullish()` and justify it with "update DTOs are made
+                // .optional(), never .nullable()". That was true when it was written and is not any more —
+                // `toPatchOptionalField` now admits null for every clearable field. Left unchanged, the
+                // guard rejected a perfectly valid `.optional()` + REMOVE declaration at CONFIG BUILD, i.e.
+                // it failed application startup, and explained the refusal with a rule that no longer
+                // exists.
+                if (!mainSchemaFieldIsClearable(fieldSchema)) {
+                    throw createConfigurationError(`[${resourceIdentifier}] field '${fieldName}' declares impersonalize treatment REMOVE, which clears the ` +
+                        `field, but the field is required (or carries a \`.default()\`, whose output type is non-optional). A ` +
+                        `field that must always hold a value cannot be scrubbed by removal — declare it \`.optional()\` or ` +
+                        `\`.nullish()\`, or use MASK to overwrite it with a placeholder instead.`);
+                }
+            }
+            else if (treatment === RedactionType.MASK) {
+                // Validate the EFFECTIVE value — the field's own `maskValue` override when it declares one,
+                // the framework constant otherwise — resolved through the SAME helper the scrub writer uses,
+                // so a config that passes here cannot produce a write the update DTO rejects mid-erasure.
+                const effectiveMaskValue = resolveImpersonalizeMaskValue(fieldSchema);
+                if (!fieldSchema.safeParse(effectiveMaskValue).success) {
+                    throw createConfigurationError(effectiveMaskValue === IMPERSONALIZE_MASK_CONSTANT
+                        ? `[${resourceIdentifier}] field '${fieldName}' declares impersonalize treatment MASK, but its schema ` +
+                            `rejects the default mask constant '${IMPERSONALIZE_MASK_CONSTANT}'. That constant is an unconstrained ` +
+                            `string, so a number/date/enum/boolean — or a CONSTRAINED string such as z.email()/z.uuid()/.min(n) — ` +
+                            `cannot hold it. Either declare a field-specific value the schema accepts ` +
+                            `(\`.impersonalizeWith(MASK, { maskValue: '...' })\`), or use REMOVE on a \`.nullish()\` field.`
+                        : `[${resourceIdentifier}] field '${fieldName}' declares impersonalize treatment MASK with ` +
+                            `maskValue '${effectiveMaskValue}', but its own schema rejects that value. The mask is written ` +
+                            `verbatim through the strict update-DTO parse, so it must satisfy every constraint the field ` +
+                            `declares (format, length, enum membership).`);
+                }
+            }
+        }
+        // Count what the WRITER would actually scrub, not what was merely declared. `KEEP` treatments and
+        // treatments on never-scrub floor fields are both skipped by `buildImpersonalizeScrubPatch`, so
+        // counting declarations would let a resource satisfy this guard with a patch that is EMPTY — rows
+        // flipping to RETAINED with every field intact, which is precisely the compliance lie the guard
+        // exists to prevent. Deriving the count from the writer keeps ONE authority for "what gets scrubbed".
+        // FAIL LOUD on a NESTED treatment. Both the guard above and the writer walk TOP-LEVEL keys only
+        // (`getMergedObjectOrUnionShape` merges union options; it does not descend into nested objects, and
+        // `getMetadataRecursive` traverses wrappers but never a ZodObject's shape). So a
+        // `.impersonalizeWith()` declared on a nested field — `billingContact.email`, or a nested
+        // `z_file()` — is SILENTLY IGNORED: the row flips to RETAINED while that field, and any file linked
+        // under its dotted path, survive intact. That is the compliance lie this whole block exists to
+        // prevent, reached through a door the top-level walk cannot see. Recursive scrubbing is deliberately
+        // out of v1 scope, so an unscrubable nested treatment must be a BOOT ERROR rather than a silent skip.
+        assertNoNestedImpersonalizeTreatment(effectiveMainSchema, resourceIdentifier);
+        // The two modes assert OPPOSITE things about this resource's fields, so each fails loud on the
+        // other's shape. Neither is a warning: a mismatch here means the config claims something about
+        // personal data that the runtime would not honour.
+        const effectiveScrubPatch = buildImpersonalizeScrubPatch(effectiveMainSchema);
+        if (retentionPolicy.mode === ErasureRetentionMode.RETAIN_ONLY) {
+            // RETAIN_ONLY asserts "this resource holds no personal data of its own". A treatment contradicts
+            // that claim — and would be silently ignored at erasure time, since RETAIN_ONLY writes only the
+            // markers. Fail rather than let the declaration and the behaviour disagree.
+            if (Object.keys(effectiveScrubPatch).length > 0) {
+                throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy.mode = RETAIN_ONLY asserts this resource holds no personal data of ` +
+                    `its own, but field(s) [${Object.keys(effectiveScrubPatch).join(', ')}] declare an impersonalize treatment. ` +
+                    `Those treatments would never run. Use mode = RETAIN_AND_IMPERSONALIZE to actually scrub them, or remove them.`);
+            }
+        }
+        else if (Object.keys(effectiveScrubPatch).length === 0) {
+            throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy.mode = RETAIN_AND_IMPERSONALIZE but NO field would actually be ` +
+                `scrubbed (KEEP treatments and treatments on never-scrub floor fields such as scope FKs / createdByUserId ` +
+                `do not count). Erasure would flip rows to RETAINED with every personal field intact — a record ` +
+                `that looks scrubbed but is not. Mark at least one non-floor personal field REMOVE or MASK, or — if this ` +
+                `resource genuinely holds no personal data of its own — declare mode = RETAIN_ONLY instead.`);
+        }
+        // Inject the per-record retention marker. Server-managed (excluded from client
+        // create/update, hidden), DB-indexed for the hidden-by-default filter predicate
+        // + the future disposal clock. Defaults to ACTIVE; only the impersonalize writer
+        // flips it to RETAINED via updateManyAsSystem (which re-attaches verb-excluded
+        // fields after the strict parse — see deriveTrustedSystemWritePreservedFields).
+        effectiveMainSchema = effectiveMainSchema.extend({
+            retentionStatus: RetentionStatusSchema
+                .default(RetentionStatus.ACTIVE)
+                .isDBIndexed()
+                .excludeFromCreate()
+                .excludeFromUpdate()
+                .isHidden(),
+            impersonalizedAt: z.date()
+                .optional()
+                .isDBIndexed()
+                .excludeFromCreate()
+                .excludeFromUpdate()
+                .isHidden(),
+        });
+        // Derive the impersonalization system-access grants (parallel to the
+        // isAnonymizable updateMany derive above): `updateMany` for the in-place scrub,
+        // `seeRetained` for the audited see-through read of retained rows. FAIL-LOUD, not
+        // silent-override: if the author EXPLICITLY declared either verb FORBIDDEN, that
+        // contradicts retentionPolicy (the resource asks to be retained-and-scrubbed yet
+        // forbids the only primitive that performs / audits it). We read the RAW authored
+        // policy (`params.systemAccessPolicy`) — an unauthored policy defaults to
+        // all-verbs-FORBIDDEN, and deriving THAT to ALLOWED is the intended common case.
+        if (params.systemAccessPolicy?.updateMany === ResourceSystemAccessMode.FORBIDDEN) {
+            throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy requires systemAccessPolicy.updateMany = ALLOWED ` +
+                `(the impersonalize writer scrubs in place via updateManyAsSystem), but this resource explicitly ` +
+                `authored updateMany: FORBIDDEN. Remove it (the grant is derived automatically) or drop retentionPolicy.`);
+        }
+        if (params.systemAccessPolicy?.seeRetained === ResourceSystemAccessMode.FORBIDDEN) {
+            throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy requires systemAccessPolicy.seeRetained = ALLOWED ` +
+                `(the audited see-through read of retained rows), but this resource explicitly authored ` +
+                `seeRetained: FORBIDDEN. Remove it (the grant is derived automatically) or drop retentionPolicy.`);
+        }
+        effectiveSystemAccessPolicy = {
+            ...effectiveSystemAccessPolicy,
+            updateMany: ResourceSystemAccessMode.ALLOWED,
+            seeRetained: ResourceSystemAccessMode.ALLOWED,
+        };
+    }
+    // ── 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
+    // at once, and the contract's errors are the more specific ones ("declare UPDATE_MANY", "rename
+    // your reserved field"). Running this first masked them, so an author fixing a missing operation
+    // was told to declare a data-subject policy instead.
+    //
+    // Paired with `retentionPolicy` in BOTH directions, because a retention-governed resource is
+    // exactly one that `eraseSubjectAsSystem` accepts as a subject (the orchestrator refuses a subject
+    // with no retention policy), and a `dataSubjectPolicy` on anything else describes an erasure that
+    // can never happen.
+    //
+    // Undeclared is REFUSED rather than defaulted: there is no safe default. Assuming
+    // NO_PRINCIPAL would silently drop a real person's session revocation; assuming a linked
+    // principal would revoke whoever a user foreign key happens to name — on `TODOS` that is the
+    // author, the assignee and the escalation contact, none of whom is the data subject. Refusing is
+    // what forces the decision, matching the subject-EXPORT model's treatment of an undeclared resource.
+    if (retentionPolicy?.mode && !dataSubjectPolicy) {
+        throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy requires a dataSubjectPolicy. A retention-governed ` +
+            `resource can be passed to eraseSubjectAsSystem as a data subject, so it must declare WHOSE ` +
+            `SESSION an erasure ends: ResourceDataSubjectKind.NO_PRINCIPAL (nobody's — either an ordinary ` +
+            `record whose user foreign keys name actors rather than the subject, OR a person with no ` +
+            `account such as a CRM contact or a lead), SELF_PRINCIPAL (the row is the person and its own ` +
+            `id is the session principal), or LINKED_PRINCIPAL with sessionPrincipalField (the person ` +
+            `signs in as a different USERS row). Note this is NOT "is the row about a person" — that is ` +
+            `answered by retentionPolicy.mode. This is never inferred from a user foreign key — doing so ` +
+            `would revoke the sessions of owners and assignees instead of the subject.`);
+    }
+    if (dataSubjectPolicy && !retentionPolicy?.mode) {
+        throw createConfigurationError(`[${resourceIdentifier}] dataSubjectPolicy requires retentionPolicy. Without one this resource ` +
+            `can never be an erasure subject (eraseSubjectAsSystem refuses a subject that is not ` +
+            `retention-governed), so the declaration would describe an erasure that cannot happen.`);
+    }
+    if (dataSubjectPolicy) {
+        const namesPrincipalField = dataSubjectPolicy.kind === ResourceDataSubjectKind.LINKED_PRINCIPAL;
+        if (namesPrincipalField && !dataSubjectPolicy.sessionPrincipalField) {
+            throw createConfigurationError(`[${resourceIdentifier}] dataSubjectPolicy.kind = LINKED_PRINCIPAL requires ` +
+                `sessionPrincipalField — the field naming the USERS row whose session an erasure of this row ` +
+                `must end. Without it the erasure has no principal to revoke and the declaration would be inert.`);
+        }
+        if (!namesPrincipalField && dataSubjectPolicy.sessionPrincipalField) {
+            throw createConfigurationError(`[${resourceIdentifier}] dataSubjectPolicy.sessionPrincipalField is only valid under ` +
+                `kind = LINKED_PRINCIPAL (got '${dataSubjectPolicy.kind}'). Under SELF_PRINCIPAL the row's own ` +
+                `id IS the principal, and under NO_PRINCIPAL there is no principal at all — so naming a ` +
+                `field here is a contradiction, not a redundancy.`);
+        }
+        // The named link must not ALSO be scrubbed. This is a COHERENCE guard, not a prerequisite of the
+        // revocation: the principal is resolved BEFORE the scrub (a post-commit read is impossible — the
+        // row is RETAINED and hidden by then, and the only see-through door demands a privileged human),
+        // so a scrubbed field would still be readable when it matters. It is refused because declaring one
+        // field to be BOTH the link to a person and personal data to destroy is a contradiction, and it
+        // leaves the retained row unable to say whose session was ended.
+        //
+        // Derived from the WRITER (`buildImpersonalizeScrubPatch`) rather than from a treatment count —
+        // the same discipline the zero-scrub guard uses, because only the writer knows which declarations
+        // actually produce a scrub.
+        if (namesPrincipalField && mainSchema instanceof z.ZodObject) {
+            const principalField = dataSubjectPolicy.sessionPrincipalField;
+            if (!(principalField in mainSchema.shape)) {
+                throw createConfigurationError(`[${resourceIdentifier}] dataSubjectPolicy.sessionPrincipalField = '${principalField}' is not ` +
+                    `a top-level field of this resource's mainSchema.`);
+            }
+            if (principalField in buildImpersonalizeScrubPatch(mainSchema)) {
+                throw createConfigurationError(`[${resourceIdentifier}] dataSubjectPolicy.sessionPrincipalField = '${principalField}' is ` +
+                    `SCRUBBED by the erasure (it carries an .impersonalizeWith() treatment the writer acts on). A ` +
+                    `field cannot be both the link naming this person's login and personal data to destroy — the ` +
+                    `retained row would be left unable to say whose session was ended. Remove the treatment from ` +
+                    `that field (a user id is a link, not personal data of this row) or name a different field.`);
+            }
+        }
+        // The system LIST grant the principal lookup needs.
+        //
+        // `eraseSubjectAsSystem` resolves the principal by reading the subject rows through
+        // `listAsSystem`, which fail-closes on `systemAccessPolicy.list`. The retention derivation grants
+        // only `updateMany` + `seeRetained`, and an unauthored policy is all-verbs-FORBIDDEN — so without
+        // this the lookup would throw, be swallowed as best-effort, resolve to NO principals, and the
+        // erased person's session would quietly survive. That is the exact failure this whole capability
+        // exists to close, so the grant is derived from the declaration that requires it.
+        //
+        // Reads the RAW authored policy (`params.systemAccessPolicy`) — an unauthored policy defaults to
+        // all-verbs-FORBIDDEN, and deriving THAT to ALLOWED is the intended common case.
+        //
+        // Scoped to LINKED_PRINCIPAL deliberately: SELF_PRINCIPAL needs no read (the subject ids ARE the
+        // user ids) and NO_PRINCIPAL reads nothing at all, so neither earns a widened system surface.
+        if (namesPrincipalField) {
+            if (params.systemAccessPolicy?.list === ResourceSystemAccessMode.FORBIDDEN) {
+                throw createConfigurationError(`[${resourceIdentifier}] dataSubjectPolicy.kind = LINKED_PRINCIPAL requires ` +
+                    `systemAccessPolicy.list = ALLOWED (the erasure reads the subject rows to resolve the session ` +
+                    `principal), but this resource explicitly authored list: FORBIDDEN. Remove it (the grant is ` +
+                    `derived automatically) or declare a different dataSubjectPolicy.kind.`);
+            }
+            effectiveSystemAccessPolicy = {
+                ...effectiveSystemAccessPolicy,
+                list: ResourceSystemAccessMode.ALLOWED,
+            };
+        }
+    }
+    // ========================================
+    // DATA-CATEGORY VOCABULARY VALIDATION
+    // ========================================
+    //
+    // `.dataCategories()` stores opaque strings: `zod-decorators` sits BELOW this package and cannot
+    // import `PersonalDataCategory`, so its chokepoint can only check that non-empty strings were
+    // declared. This is the layer that owns the enum, so this is where membership is checked.
+    //
+    // UNCONDITIONAL, unlike the impersonalize guards above — those run only inside `retentionPolicy`
+    // because a treatment is meaningless without one. A data category is meaningful on any resource:
+    // a hard-deleted resource still HOLDS personal data while it exists, and a privacy notice must
+    // enumerate it. Gating this on retentionPolicy would silently exempt exactly the resources that
+    // opted out of retention.
+    //
+    // A typo'd category is worse than an undeclared one and that is why this is a BOOT ERROR rather
+    // than a warning: `'contact_details'` (underscore) is not a member, so the field would be counted
+    // as CATEGORIZED by the gap report — it carries a declaration — while contributing nothing to the
+    // notice's category list. The field disappears from the inventory while looking annotated in the
+    // schema, which is the failure this whole capability exists to prevent.
+    //
+    // TOP-LEVEL fields only, deliberately matching `resolveResourcePersonalDataCategories`: a nested
+    // declaration is invisible to the reader, so validating it here would certify a value nothing
+    // consumes. Unlike a nested `.impersonalizeWith()` — which is a boot error because the row would
+    // flip to RETAINED with the field intact — a nested category breaks nothing at runtime; it simply
+    // never reaches a notice.
+    if (isZodObject(effectiveMainSchema)) {
+        for (const [fieldName, fieldSchema] of Object.entries(getZodObjectShape(effectiveMainSchema))) {
+            const declared = getDataCategories(fieldSchema);
+            if (declared === undefined)
+                continue;
+            const unknownCategories = unknownPersonalDataCategories(declared);
+            if (unknownCategories.length > 0) {
+                throw createConfigurationError(`[${resourceIdentifier}] field '${fieldName}' declares data categor${unknownCategories.length === 1 ? 'y' : 'ies'} ` +
+                    `[${unknownCategories.join(', ')}] that ${unknownCategories.length === 1 ? 'is' : 'are'} not a PersonalDataCategory member. ` +
+                    `A value outside the vocabulary counts the field as CATEGORIZED — so it is excluded from the ` +
+                    `uncategorized-field gap report — while contributing nothing to the privacy notice's category list. ` +
+                    `Use a PersonalDataCategory member, or drop the declaration if the field holds no personal data.`);
+            }
+        }
     }
     // ========================================
     // TRANSFORM RESOURCE RELATIONSHIPS
@@ -1091,6 +2166,7 @@ export function createResourceConfiguration_Initialization(params) {
     const enableListContext = autoVariantsList.enableContext !== false; // default true
     // Process operation configurations
     for (const [operation, config] of Object.entries(operationsConfiguration)) {
+        assertOperationPathKeySegment(String(operation), 'operation identifier', String(operation));
         // Validate isDefault logic by grouping variants by their variantType
         const variantsByType = new Map();
         // Group variants by their type
@@ -1100,9 +2176,12 @@ export function createResourceConfiguration_Initialization(params) {
             }
             variantsByType.get(variant.variantType).push(variant);
         });
-        // Validate each variant type group
+        // Validate each variant type group. URL-bearing variants form a shared
+        // operation identity space (`API_CALL` and `API_CALL_WITH_CALLBACK` are
+        // both selected by operation/default/key at many call sites), so their
+        // default/key invariants are validated as one combined group below.
         for (const [variantType, variantsGroup] of variantsByType.entries()) {
-            if (variantsGroup.length > 1) {
+            if (!isUrlisableOperationVariantType(variantType) && variantsGroup.length > 1) {
                 const explicitDefaults = variantsGroup.filter((variant) => variant.isDefault === true);
                 if (explicitDefaults.length === 0) {
                     throw createConfigurationError(`Operation '${operation}' with multiple ${variantType} variants must have at least one with isDefault=true`);
@@ -1111,31 +2190,79 @@ export function createResourceConfiguration_Initialization(params) {
                     throw createConfigurationError(`Operation '${operation}' with multiple ${variantType} variants cannot declare more than one with isDefault=true`);
                 }
             }
-            if (variantType === ResourceOperationVariantType.API_CALL) {
-                const seenVariantKeys = new Set();
-                let seenNonDefaultWithoutVariantKey = false;
+            if (isUrlisableOperationVariantType(variantType)) {
                 for (const variant of variantsGroup) {
-                    if (variant.variantKey && RESERVED_OPERATION_VARIANT_KEYS.has(variant.variantKey)) {
-                        throw createConfigurationError(`Operation '${operation}' cannot use reserved variantKey '${variant.variantKey}'`);
+                    // 🔒 Fail-closed guard: a URL-bearing variant with an EMPTY roles array
+                    // is not "skip the role check" — it is a guaranteed 403. The runtime gate
+                    // (`AuthorizationsBackendService.validateOperationRoles`) evaluates
+                    // `roles.some(...)`, and `[].some()` is always false, so EVERY caller is
+                    // denied. There is no legitimate empty-roles URL operation: public ops use
+                    // `APP_PUBLIC`, anonymous ops use `APP_ANONYMOUS`, user-self ops use
+                    // `APP_USER` (row ownership is enforced separately by the scope authorizer).
+                    // Catch the mistake at config-build time instead of shipping a dead endpoint.
+                    // (INTERNAL_CALL / REPOSITORY_ONLY variants are exempt — not URL-bearing, so
+                    // this loop never sees them; their empty roles are inert.)
+                    if (!variant.roles || variant.roles.length === 0) {
+                        throw createConfigurationError(`Operation '${operation}' has a URL-bearing (${variantType}) variant with an empty roles array. ` +
+                            `An empty roles array is fail-CLOSED: the authorization gate evaluates roles.some(...), which is ` +
+                            `always false for [], so every caller is denied (403). Specify at least one role — e.g. ` +
+                            `CORE_APP_ROLES.APP_USER (user-self / any authenticated user), CORE_APP_ROLES.APP_PUBLIC (public), ` +
+                            `CORE_APP_ROLES.APP_ANONYMOUS (anonymous), or the appropriate ORG/APP role.`);
                     }
-                    const willBeDefault = determineOperationVariantDefault(variantsGroup, variant);
-                    if (willBeDefault) {
-                        continue;
+                    if (variant.variantKey) {
+                        assertOperationPathKeySegment(variant.variantKey, 'variantKey', String(operation));
                     }
-                    if (!variant.variantKey) {
-                        if (seenNonDefaultWithoutVariantKey) {
-                            throw createConfigurationError(`Operation '${operation}' cannot declare more than one non-default ${variantType} variant without a variantKey`);
-                        }
-                        seenNonDefaultWithoutVariantKey = true;
-                        continue;
+                    if (variant.variantKey && RESERVED_OPERATION_VARIANT_KEYS.has(variant.variantKey.toLowerCase())) {
+                        throw createConfigurationError(`Operation '${operation}' cannot use reserved variantKey '${variant.variantKey}'`);
+                    }
+                    if (variant.variantKey && AUTO_OPERATION_VARIANT_KEYS.has(variant.variantKey.toLowerCase())
+                        && variant.variantKey !== variant.variantKey.toLowerCase()) {
+                        throw createConfigurationError(`Operation '${operation}' must use canonical lowercase variantKey '${variant.variantKey.toLowerCase()}' for generated variant semantics`);
                     }
-                    if (seenVariantKeys.has(variant.variantKey)) {
-                        throw createConfigurationError(`Operation '${operation}' cannot declare duplicate variantKey '${variant.variantKey}' within ${variantType} variants`);
+                    if (variant.variantKey && AUTO_OPERATION_VARIANT_KEYS.has(variant.variantKey.toLowerCase())
+                        && !isDataModeVariantKeyAllowedForOperation(String(operation), variant)) {
+                        throw createConfigurationError(`Operation '${operation}' cannot use data-mode variantKey '${variant.variantKey}' unless it is READ, LIST, or SEARCH-like`);
                     }
-                    seenVariantKeys.add(variant.variantKey);
                 }
             }
         }
+        const urlisableVariants = config.variants.filter((variant) => isUrlisableOperationVariantType(variant.variantType));
+        const explicitUrlisableDefaults = urlisableVariants.filter((variant) => variant.isDefault === true);
+        if (urlisableVariants.length > 1) {
+            if (explicitUrlisableDefaults.length === 0) {
+                throw createConfigurationError(`Operation '${operation}' with multiple URL-bearing variants must have exactly one with isDefault=true`);
+            }
+            if (explicitUrlisableDefaults.length > 1) {
+                throw createConfigurationError(`Operation '${operation}' cannot declare more than one default URL-bearing variant across API_CALL and API_CALL_WITH_CALLBACK`);
+            }
+        }
+        // A single URL-bearing variant is the URL default UNLESS the author explicitly set
+        // `isDefault: false` — mirrors `determineOperationVariantDefault` Rule 1 so the stored
+        // `isOperationDefault` flag and this validation set never disagree. When the opt-out is
+        // honored, the sole `isDefault: false` URL variant is treated as non-default here, which
+        // correctly routes it through the "non-default URL-bearing variant must declare a
+        // variantKey" check below — a sole opted-out URL variant with no variantKey would
+        // otherwise be unresolvable by BOTH the default and the keyed path resolver.
+        const urlisableDefaultVariants = urlisableVariants.length === 1
+            ? urlisableVariants.filter((variant) => variant.isDefault !== false)
+            : explicitUrlisableDefaults;
+        const urlisableVariantKeys = new Set();
+        for (const variant of urlisableVariants) {
+            const willBeDefault = urlisableDefaultVariants.includes(variant);
+            if (variant.variantKey) {
+                const normalizedVariantKey = variant.variantKey.toLowerCase();
+                if (urlisableVariantKeys.has(normalizedVariantKey)) {
+                    throw createConfigurationError(`Operation '${operation}' cannot reuse variantKey '${variant.variantKey}' across URL-bearing variants`);
+                }
+                urlisableVariantKeys.add(normalizedVariantKey);
+            }
+            if (willBeDefault) {
+                continue;
+            }
+            if (!variant.variantKey) {
+                throw createConfigurationError(`Operation '${operation}' cannot declare a non-default URL-bearing variant without a variantKey`);
+            }
+        }
         // Process parent resource access scope strategy overrides for this operation
         const operationResourceRelationships = processParentResourceAccessScopeStrategyOverrides(processedResourceRelationships, availableParentResourceTypes, config.parentResourceAccessScopeStrategyOverrides || [], operation);
         // Process user notifications using helper function
@@ -1146,15 +2273,47 @@ export function createResourceConfiguration_Initialization(params) {
         config.variants.forEach((variantParams, variantIndex) => {
             // Note: Cascading delete is now handled via childOperations.lifecycle.onParentDelete on relationships
             // No longer processed at operation variant level
-            // Determine if this variant is the default within its type group
+            // Determine if this variant is the operation default. URL-bearing
+            // variants share one default/key identity space across API and callback
+            // transports; non-URL transports keep variant-type-local defaults.
             const variantsOfSameType = variantsByType.get(variantParams.variantType) || [];
-            const isOperationDefault = determineOperationVariantDefault(variantsOfSameType, variantParams);
+            const isOperationDefault = isUrlisableOperationVariantType(variantParams.variantType)
+                ? determineOperationVariantDefault(urlisableVariants, variantParams)
+                : determineOperationVariantDefault(variantsOfSameType, variantParams);
             // Determine effective operation for DTO derivation
             // For custom operations, use resourceOperationLike if it maps to CREATE or UPDATE
             const isCustomOperation = !coreOperations.includes(operation);
             const effectiveOperationForDto = isCustomOperation
                 ? (variantParams.resourceOperationLike || operation)
                 : operation;
+            // ── 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
+            // 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
+            // (`service_resource_transformation_failed`). Warn — do NOT throw: a custom
+            // op that legitimately returns a bare id / `{ count }` is valid, so this is
+            // a misconfiguration signal, not an invariant. Surfacing it at registry
+            // build beats discovering it on first invocation.
+            //
+            // Scope note: this deliberately does NOT cover UPDATE / CREATE / READ
+            // borrowing. Those verbs' default response IS the resource object, which is
+            // correct for the many custom mutation ops that return the mutated entity —
+            // a static check cannot tell those from the (rarer) ones that return a
+            // non-resource shape (e.g. `{ url }`, `{ message }`). Those are guarded by
+            // an authored `customResponseDto` + the built-operation DTO tests instead.
+            if (isCustomOperation && !variantParams.customResponseDto
+                && (variantParams.resourceOperationLike === CoreResourceOperation.DELETE
+                    || variantParams.resourceOperationLike === CoreResourceOperation.DELETE_MANY
+                    || variantParams.resourceOperationLike === CoreResourceOperation.COUNT)) {
+                console.warn(`[wildo:resource-config] Custom operation "${String(resourceIdentifier)}.${String(operation)}" `
+                    + `borrows ${String(variantParams.resourceOperationLike)} via resourceOperationLike but declares no `
+                    + `customResponseDto. It will inherit that verb's default response envelope, which almost never `
+                    + `matches a custom operation's output and will fail output validation (HTTP 500) at invocation. `
+                    + `Declare a customResponseDto matching the operation's true return shape.`);
+            }
             // Auto-derive requestDto from decorators if not explicitly provided
             const derivedRequestDto = deriveRequestDto(effectiveOperationForDto, effectiveMainSchema, variantParams.requestDto);
             // Auto-derive responseDto based on operation type
@@ -1166,7 +2325,8 @@ export function createResourceConfiguration_Initialization(params) {
                 if (variantParams.customResponseDto) {
                     return variantParams.customResponseDto;
                 }
-                if (operation === CoreResourceOperation.LIST) {
+                if (operation === CoreResourceOperation.LIST
+                    || variantParams.resourceOperationLike === CoreResourceOperation.LIST) {
                     return derivedSummarySchema;
                 }
                 if (operation === CoreResourceOperation.SEARCH
@@ -1194,6 +2354,12 @@ export function createResourceConfiguration_Initialization(params) {
                 serviceRuntimeMode: config.serviceRuntimeMode || ResourceOperation_ServiceRuntimeMode.INLINE,
                 requestDto: derivedRequestDto, // Temporary - will be replaced by buildAllOperationDtos
                 responseDto: operationResponseDto, // Temporary - will be replaced by buildAllOperationDtos
+                // When the variant supplied an explicit `requestDto`, it is an author-owned
+                // contract the DTO builder must preserve verbatim. Otherwise `derivedRequestDto`
+                // is an auto-derived TEMPORARY placeholder built from the base object (before
+                // inheritance is known), so the builder must rebuild it — as a per-variant union
+                // for inheritance resources. See `hasCustomRequestDto` in the operation schema.
+                hasCustomRequestDto: !!variantParams.requestDto,
                 hasCustomResponseDto: !!variantParams.customResponseDto,
                 notificationBadgeOperations: config.notificationBadgeOperations || [],
                 userNotifications,
@@ -1201,14 +2367,51 @@ export function createResourceConfiguration_Initialization(params) {
                 // Fields from ResourceConfiguration_OperationVariant_Base
                 variantType: variantParams.variantType,
                 resourceOperationLike: variantParams.resourceOperationLike,
+                generatedOperation: variantParams.generatedOperation,
+                // Forwarded here rather than inside the collection-view enrichment below, which is an
+                // explicit ALLOW-LIST reached only by LIST/SEARCH-shaped variants. Copying it there would
+                // make a `collectionExport` declared on the wrong verb vanish silently; copying it here
+                // lets it reach `createGeneratedCollectionExportOperations`, which refuses it by name.
+                collectionExport: variantParams.collectionExport,
                 requiredFeatures: normalizeRequiredFeatures(variantParams.requiredFeatures),
                 riskLevel: variantParams.riskLevel || ResourceOperationRiskLevel.LOW,
                 roles: variantParams.roles,
+                // Forwarded, not defaulted: the startup guard and the request-time refusal both read it
+                // off the RUNTIME operation. This block re-lists variant fields rather than spreading
+                // them, so a new variant field that is not added here is silently dropped between
+                // authoring and runtime.
+                unimplementedAcknowledgement: variantParams.unimplementedAcknowledgement,
+                // Forwarded for the same reason: `enforceStepUpAuth` reads it off the RUNTIME operation, so
+                // an unforwarded flag would leave the authored requirement silently unenforced — the exact
+                // failure mode the flag exists to prevent.
+                requiresStepUpAuthentication: variantParams.requiresStepUpAuthentication,
+                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.
+                admitsCrossSubjectUserAdministration: variantParams.admitsCrossSubjectUserAdministration,
+                // Forwarded for the same reason again: the post-commit audit emission reads it off the
+                // RUNTIME operation. Dropping it would either lose an authored below-floor opt-in (a silent
+                // audit gap) or lose an authored suppression (a duplicate row next to a purpose-built event).
+                auditableEvent: variantParams.auditableEvent,
+                mcp: variantParams.mcp,
                 customServiceImplementationModes: variantParams.customServiceImplementationModes || [],
-                basicPrefixOperation: variantParams.basicPrefixOperation
+                basicPrefixOperation: variantParams.basicPrefixOperation,
+                // Travels WITH `basicPrefixOperation` — it declares which of that hook's fields survive the
+                // repository's strict re-parse even when the caller also sent them. Dropping it here would
+                // silently reduce the hook to the added-key inference it exists to correct.
+                authoritativeFields: variantParams.authoritativeFields,
+                // Forwarded for the same reason as its siblings above: the write-integrity guard reads the
+                // per-variant reference POLICY off the RUNTIME operation. Dropping it here degrades every
+                // variant to the relationship's baseline membership — so an authored `qualifyingStatuses` /
+                // `requiredRoles` / `false` would be silently inert while the config claims otherwise. (This
+                // is not hypothetical: it shipped that way once, and the e2e caught it as a PENDING and a
+                // REVOKED partnership both admitting a share.)
+                referenceConstraints: variantParams.referenceConstraints,
             };
-            if (variantParams.variantType === ResourceOperationVariantType.API_CALL) {
+            if (isUrlisableOperationVariantType(variantParams.variantType)) {
                 const apiCallParams = variantParams;
+                const isCallbackVariant = apiCallParams.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK;
+                const callbackParams = apiCallParams;
                 // Determine if this is a custom operation and get the operation to check
                 const isCustomOperation = !coreOperations.includes(operation);
                 const operationToCheck = isCustomOperation ? apiCallParams.resourceOperationLike : operation;
@@ -1217,6 +2420,22 @@ export function createResourceConfiguration_Initialization(params) {
                 if (haveBulkOperation && (operationToCheck === CoreResourceOperation.READ || operationToCheck === CoreResourceOperation.LIST)) {
                     throw createConfigurationError(`Operation '${operation}' cannot have bulk operations (read and list are not bulkable)`);
                 }
+                const tokenStateSideEffects = [
+                    ...(apiCallParams.tokenGeneration ? ['tokenGeneration'] : []),
+                    ...(apiCallParams.tokenRevocation ? ['tokenRevocation'] : []),
+                ];
+                if (tokenStateSideEffects.length > 0
+                    && (haveBulkOperation
+                        || isTokenStateEffectUnsupportedOperation(operationToCheck))) {
+                    throw createConfigurationError(`Operation '${operation}' cannot combine collection/bulk result semantics with ${tokenStateSideEffects.join(' and ')}. `
+                        + 'Token generation and revocation each require one canonical related resource state; collection, aggregate, and '
+                        + 'bulk operations do not expose a single related resource identity. Split the token side effect into a singular '
+                        + 'operation or remove the collection/bulk variant.');
+                }
+                if (apiCallParams.tokenRevocation && operationToCheck === CoreResourceOperation.CREATE) {
+                    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.');
+                }
                 // Determine HTTP verb - for custom operations, use resourceOperationLike
                 let httpVerb;
                 if (isCustomOperation) {
@@ -1237,7 +2456,6 @@ export function createResourceConfiguration_Initialization(params) {
                 if (apiCallParams.tokenRevocation) {
                     validateTokenRevocationConfig(apiCallParams.tokenRevocation, resourceIdentifier, operation);
                 }
-                // Create API_CALL operation fields
                 const apiCallOperationFields = {
                     ...baseOperationFields,
                     httpVerb,
@@ -1246,9 +2464,20 @@ export function createResourceConfiguration_Initialization(params) {
                     tokenAuthentication: apiCallParams.tokenAuthentication,
                     tokenGeneration: apiCallParams.tokenGeneration,
                     tokenRevocation: apiCallParams.tokenRevocation,
+                    // Per-endpoint rate-limit policy: forwarded from the
+                    // builder params to the resolved operation. Read at runtime by
+                    // `RateLimitBackendService.checkPolicyForVariant` at the controller
+                    // pre-flight seam. `undefined` means the global HTTP limiter is the
+                    // only gate for this route.
+                    rateLimit: apiCallParams.rateLimit,
                     enabledCondition: apiCallParams.enabledCondition,
                     isDefault: apiCallParams.isDefault,
-                    variantKey: apiCallParams.variantKey
+                    variantKey: apiCallParams.variantKey,
+                    ...(isCallbackVariant ? {
+                        callbackUrl: callbackParams.callbackUrl,
+                        callbackTimeout: callbackParams.callbackTimeout ?? 300,
+                        callbackRetryAttempts: callbackParams.callbackRetryAttempts ?? 3,
+                    } : {}),
                 };
                 // ── Collection-view enrichment ──────────────────────────────────
                 // When an operation is SEARCH-like or LIST-like (by identity or resourceOperationLike),
@@ -1259,7 +2488,6 @@ export function createResourceConfiguration_Initialization(params) {
                     || variantParams.resourceOperationLike === CoreResourceOperation.LIST;
                 if (isSearchLike) {
                     const pageSize = variantParams.pageSize ?? 20;
-                    const displayMode = variantParams.displayMode ?? 'cards';
                     const isSearchable = variantParams.isSearchable !== false;
                     const searchableFields = variantParams.searchableFields || [];
                     const searchableOptions = variantParams.searchableOptions || { caseSensitive: false, fullMatchOnly: false };
@@ -1275,7 +2503,10 @@ export function createResourceConfiguration_Initialization(params) {
                     const searchQueryRequestSchema = createResourceSearchQueryRequestSchema({
                         filterFields,
                         allowedSortFields: sortFields,
-                        pagination: true
+                        pagination: true,
+                        // The SAME value the response schema below is built from. That equality is the point:
+                        // request, repository and response must agree on one ceiling.
+                        maxPaginatedResultPerPageLimit
                     });
                     const paginatedResponseSchema = createResourcePaginatedResponseSchema({
                         dataSchema: derivedSummarySchema,
@@ -1284,7 +2515,6 @@ export function createResourceConfiguration_Initialization(params) {
                     });
                     Object.assign(apiCallOperationFields, {
                         pageSize,
-                        displayMode,
                         isSearchable,
                         searchableFields,
                         searchableOptions,
@@ -1299,9 +2529,12 @@ export function createResourceConfiguration_Initialization(params) {
                 if (isListLike) {
                     const listEnrichment = {
                         pageSize: variantParams.pageSize ?? 20,
-                        displayMode: variantParams.displayMode ?? 'cards',
                         searchEnabled: variantParams.searchEnabled ?? true,
                         filtersEnabled: variantParams.filtersEnabled ?? true,
+                        // LIST has one pagination authority. Keep the effective ceiling on the resolved
+                        // operation so request/response DTO construction, repositories, auto-generated
+                        // SUMMARY/CONTEXT variants and API-reference projection all observe the same value.
+                        maxPaginatedResultPerPageLimit: variantParams.maxPaginatedResultPerPageLimit ?? 100,
                     };
                     if (variantParams.filterFields !== undefined) {
                         listEnrichment.filterFields = variantParams.filterFields;
@@ -1357,23 +2590,23 @@ export function createResourceConfiguration_Initialization(params) {
         // ========================================
         // Only process auto-variants for READ and LIST core operations
         if (operation === CoreResourceOperation.READ || operation === CoreResourceOperation.LIST) {
-            // Reuse the flattened default API operation so auto-variants inherit the same
+            // Reuse the flattened default URL-bearing operation so auto-variants inherit the same
             // resolved default identity as the rest of the resource config.
             const defaultApiCallVariant = [...operations].reverse().find((candidate) => (candidate.operationIdentifier === operation
-                && candidate.variantType === ResourceOperationVariantType.API_CALL
+                && isUrlisableOperationVariantType(candidate.variantType)
                 && candidate.isOperationDefault === true
                 && !('isBulkOperation' in candidate && candidate.isBulkOperation === true)));
             if (!defaultApiCallVariant) {
                 // Skip auto-variants if no default variant exists
                 continue;
             }
+            const defaultListCollectionFields = defaultApiCallVariant;
             // Check which variants already exist
-            const existingVariantKeys = new Set(operations
-                .filter((candidate) => (candidate.operationIdentifier === operation
-                && candidate.variantType === ResourceOperationVariantType.API_CALL
+            const existingVariantKeys = new Set(operations.filter((candidate) => (candidate.operationIdentifier === operation
+                && isUrlisableOperationVariantType(candidate.variantType)
                 && candidate.variantKey
                 && !('isBulkOperation' in candidate && candidate.isBulkOperation === true)))
-                .map((candidate) => candidate.variantKey));
+                .map((candidate) => candidate.variantKey.toLowerCase()));
             // Helper to create auto-variant operation
             // Note: DTOs will be pre-computed by buildAllOperationDtos() after all operations are created.
             // We set temporary DTOs here for type compatibility, but they will be replaced.
@@ -1390,26 +2623,83 @@ export function createResourceConfiguration_Initialization(params) {
                     isOperationDefault: false, // Auto-variants are never operation default
                     serviceRuntimeMode: config.serviceRuntimeMode || ResourceOperation_ServiceRuntimeMode.INLINE,
                     requestDto: defaultApiCallVariant.requestDto || deriveRequestDto(operation, effectiveMainSchema, undefined), // Temporary - will be replaced by buildAllOperationDtos
+                    // Forwarded for the same reason as `unimplementedAcknowledgement` below: an auto-variant
+                    // is a projection of the default variant, so it inherits that variant's request contract
+                    // and must report the same provenance. Dropping it would make a projection of an
+                    // AUTHORED contract look auto-derived to the request-contract-breadth guard.
+                    hasCustomRequestDto: defaultApiCallVariant.hasCustomRequestDto ?? !!defaultApiCallVariant.requestDto,
                     responseDto, // Temporary - will be replaced by buildAllOperationDtos
                     notificationBadgeOperations: config.notificationBadgeOperations || [],
                     userNotifications,
                     m2mNotifications,
-                    variantType: ResourceOperationVariantType.API_CALL,
+                    variantType: defaultApiCallVariant.variantType,
                     resourceOperationLike: defaultApiCallVariant.resourceOperationLike,
                     requiredFeatures: normalizeRequiredFeatures(defaultApiCallVariant.requiredFeatures),
                     riskLevel: defaultApiCallVariant.riskLevel || ResourceOperationRiskLevel.LOW,
                     roles: defaultApiCallVariant.roles, // Inherit roles from default variant
+                    // Inherited for the same reason as roles: an auto-variant is a projection of the
+                    // default variant, so if the default is a known implementation gap its SUMMARY /
+                    // CONTEXT derivatives are equally unserviceable and must refuse identically.
+                    unimplementedAcknowledgement: defaultApiCallVariant.unimplementedAcknowledgement,
+                    // Inherited for the same reason: an auto-variant is a projection of the default variant,
+                    // so a SUMMARY / CONTEXT derivative of a step-up-gated operation must demand the same
+                    // proof. (Today the auto-variants are read-shaped and `enforceStepUpAuth` exempts reads
+                    // anyway — inheriting keeps that a property of the exemption list rather than an accident
+                    // of this projection.)
+                    requiresStepUpAuthentication: defaultApiCallVariant.requiresStepUpAuthentication,
+                    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
+                    // subjects the operation it projects is admitted to administer.
+                    admitsCrossSubjectUserAdministration: defaultApiCallVariant.admitsCrossSubjectUserAdministration,
+                    // Inherited for the same reason: an auto-variant is a projection of the default variant,
+                    // so it must make the same audit claim. Inheriting a `suppressGenericEvent` matters most —
+                    // the purpose-built event that supersedes the default covers its projections too, and a
+                    // projection that dropped the suppression would write the duplicate row the flag prevents.
+                    auditableEvent: defaultApiCallVariant.auditableEvent,
+                    mcp: defaultApiCallVariant.mcp, // Inherit MCP exposure from default variant (non-default variants aren't MCP-enumerated anyway)
                     customServiceImplementationModes: defaultApiCallVariant.customServiceImplementationModes || [],
                     basicPrefixOperation: defaultApiCallVariant.basicPrefixOperation,
-                    httpVerb: getDefaultHttpVerbForOperation(operation),
+                    // Inherited alongside the hook itself — an auto-variant that ran the prefix without its
+                    // ownership declaration would drop the very field the hook exists to force.
+                    authoritativeFields: defaultApiCallVariant.authoritativeFields,
+                    // Inherited for the same reason as `roles`: an auto-variant is a PROJECTION of the default
+                    // variant, so it must confine a written reference exactly as the operation it projects does.
+                    // (Read-shaped auto-variants write nothing today, so this is inert for them — inheriting
+                    // keeps that a property of what they DO rather than an accident of this projection.)
+                    referenceConstraints: defaultApiCallVariant.referenceConstraints,
+                    httpVerb: defaultApiCallVariant.httpVerb,
                     isApiKeyAccessDisabled: defaultApiCallVariant.isApiKeyAccessDisabled || false,
                     isBulkOperation: false,
                     tokenAuthentication: defaultApiCallVariant.tokenAuthentication,
                     tokenGeneration: defaultApiCallVariant.tokenGeneration,
                     tokenRevocation: defaultApiCallVariant.tokenRevocation,
+                    // Auto-variants (READ.summary, READ.context, LIST.summary, …)
+                    // inherit the default variant's rate-limit policy by design — a
+                    // single declaration on the default URL-bearing variant covers all
+                    // derived auto-variants. Authors who need a per-variant override
+                    // declare the variant explicitly instead of relying on auto-generation.
+                    rateLimit: defaultApiCallVariant.rateLimit,
                     enabledCondition: defaultApiCallVariant.enabledCondition,
                     isDefault: isDefault,
-                    variantKey: variantKey
+                    variantKey: variantKey,
+                    ...(operation === CoreResourceOperation.LIST ? {
+                        // A generated representation changes only the response DATA SHAPE. It remains the same
+                        // collection operation, so its query contract must be identical to the canonical default
+                        // variant. Otherwise selecting SUMMARY or CONTEXT silently removes filters, sorting or
+                        // the authored page ceiling from the public contract.
+                        pageSize: defaultListCollectionFields.pageSize,
+                        searchEnabled: defaultListCollectionFields.searchEnabled,
+                        filtersEnabled: defaultListCollectionFields.filtersEnabled,
+                        filterFields: defaultListCollectionFields.filterFields,
+                        sortFields: defaultListCollectionFields.sortFields,
+                        maxPaginatedResultPerPageLimit: defaultListCollectionFields.maxPaginatedResultPerPageLimit,
+                    } : {}),
+                    ...(defaultApiCallVariant.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK ? {
+                        callbackUrl: defaultApiCallVariant.callbackUrl,
+                        callbackTimeout: defaultApiCallVariant.callbackTimeout,
+                        callbackRetryAttempts: defaultApiCallVariant.callbackRetryAttempts,
+                    } : {}),
                 };
                 // ── Build-time validation for auto-variant token configs ──
                 if (defaultApiCallVariant.tokenGeneration) {
@@ -1432,19 +2722,19 @@ export function createResourceConfiguration_Initialization(params) {
             }
             // Generate LIST.summary variant
             if (operation === CoreResourceOperation.LIST && enableListSummary && !existingVariantKeys.has(OPERATION_VARIANT_KEY.SUMMARY)) {
-                // For LIST operations, wrap summary schema in pagination structure using shared schema
-                const summaryResponseDto = z.object({
-                    data: z.array(derivedSummarySchema),
-                    pagination: Resouces_PaginationResponseMetadataSchema
+                const summaryResponseDto = createResourcePaginatedResponseSchema({
+                    dataSchema: derivedSummarySchema,
+                    validateArrayConstraints: true,
+                    maxResultsPerPageLimit: defaultListCollectionFields.maxPaginatedResultPerPageLimit,
                 });
                 operations.push(createAutoVariantOperation(OPERATION_VARIANT_KEY.SUMMARY, summaryResponseDto, false));
             }
             // Generate LIST.context variant
             if (operation === CoreResourceOperation.LIST && enableListContext && !existingVariantKeys.has(OPERATION_VARIANT_KEY.CONTEXT)) {
-                // For LIST operations, wrap context schema in pagination structure using shared schema
-                const contextResponseDto = z.object({
-                    data: z.array(effectiveMainSchema),
-                    pagination: Resouces_PaginationResponseMetadataSchema
+                const contextResponseDto = createResourcePaginatedResponseSchema({
+                    dataSchema: effectiveMainSchema,
+                    validateArrayConstraints: true,
+                    maxResultsPerPageLimit: defaultListCollectionFields.maxPaginatedResultPerPageLimit,
                 });
                 operations.push(createAutoVariantOperation(OPERATION_VARIANT_KEY.CONTEXT, contextResponseDto, false));
             }
@@ -1491,6 +2781,102 @@ export function createResourceConfiguration_Initialization(params) {
         ...coreResourceShared_FieldIdentifier,
         [resourceIdentifier]: resourceFieldIdentifier,
     }));
+    const generatedFileDiscoverySchema = ResourcesConfigOperationsDtosBuilderUtils.buildSchemaWithInheritance(effectiveMainSchema, inheritenceSchemaDefinition);
+    operations.push(...createGeneratedFileRegenerateOperations({
+        operations,
+        resourceIdentifier,
+        resourceFieldIdentifier,
+        mainSchema: effectiveMainSchema,
+        generatedFileDiscoverySchema,
+        persistenceAdapter,
+    }));
+    // AFTER the file-regenerate companions, and over the same fully-assembled set: a generated
+    // relationship-bulk operation is never a LIST/SEARCH, so ordering cannot change the outcome — but
+    // deriving from the complete set means a future generated LIST would be covered without a second
+    // call site to remember.
+    operations.push(...createGeneratedCollectionExportOperations({
+        operations,
+        resourceIdentifier,
+    }));
+    // ── Fail-closed guard: no anonymous BULK MUTATION (W7.3a hardening) ─────
+    //
+    // An anonymous caller may legitimately be granted single-record CREATE / READ
+    // / LIST / UPDATE / DELETE (e.g. draft-notes lead capture), but a bulk MUTATION
+    // (CREATE_MANY / UPDATE_MANY / DELETE_MANY) granted to `APP_ANONYMOUS` is an
+    // unauthenticated mass-write surface — a whole-collection destructive footgun
+    // no app should be able to author by accident. The framework provided ZERO
+    // enforcement here (only a non-blocking "isAnonymizable without any anon op"
+    // warning existed), so this fails closed at config-build time. Read-shaped
+    // collection ops (LIST / SEARCH / COUNT) are intentionally NOT flagged —
+    // anonymous listing of one's own anonymous rows is a supported pattern.
+    //
+    // Runs over the FULLY-assembled operation set (authored + generated
+    // relationship-bulk + file-regenerate) so a generated bulk op that inherited
+    // anonymous roles from its base is caught too. Zero violations exist today.
+    for (const operation of operations) {
+        // A resource op is a bulk MUTATION iff EITHER its identifier is a core bulk
+        // verb (create_many / update_many / delete_many) OR it carries the
+        // `isBulkOperation` flag. The flag is sufficient on its own: the factory
+        // rejects `haveBulkOperation` on READ / LIST above ("read and list are not
+        // bulkable"), so `isBulkOperation === true` is GUARANTEED to be a mutation —
+        // it covers the opt-in bulk UPDATE/DELETE companions AND the generated
+        // relationship-bulk ops (whose `operationIdentifier` is a relationship id,
+        // not a core verb, so clause 1 alone would miss them). `operationIdentifier`
+        // is the (core | custom) op union and `isBulkOperation` exists only on some
+        // variants of the discriminated union — narrow with `in` and compare by
+        // string value (enum members ARE their string values); the CronJob variant
+        // carries neither.
+        const isBulkMutation = isCoreBulkMutationOperation(operation.operationIdentifier)
+            || ('isBulkOperation' in operation && operation.isBulkOperation === true);
+        if (isBulkMutation && operation.roles.includes('APP_ANONYMOUS')) {
+            throw createConfigurationError(`[${resourceIdentifier}] operation '${String(operation.operationIdentifier)}' grants APP_ANONYMOUS on a ` +
+                `bulk MUTATION (create_many / update_many / delete_many). Unauthenticated mass-write is forbidden — ` +
+                `anonymous access is only permitted on single-record operations (and read-shaped collection ops: ` +
+                `list / search / count). Remove APP_ANONYMOUS from this operation's roles.`);
+        }
+    }
+    // ── RESOLVABILITY half of the retention operation contract ──────────────
+    //
+    // The presence half ran with the other `retentionPolicy` validations above: it proved
+    // UPDATE_MANY / READ / LIST are declared. Being DECLARED is not the same as being REACHABLE,
+    // and the gap between the two is a config that boots green and breaks on the first erasure.
+    //
+    // All three retention primitives resolve their operation through
+    // `ResourcesRegistryBackendService.getServiceOperationPathDefault`, which admits ONLY the
+    // variant types in `SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES` and only when the variant is
+    // the operation DEFAULT. `REPOSITORY_ONLY` is route-less exactly like `INTERNAL_CALL` — so it
+    // is the natural-looking choice for "the capability without a new HTTP surface" — but it is
+    // deliberately excluded there and served by the separate `getRepositoryOperationPathDefault`
+    // transport. A `REPOSITORY_ONLY` UPDATE_MANY therefore satisfied the presence check and then
+    // failed to resolve mid-erasure. That is not hypothetical: the `USERS` opt-in shipped it, every
+    // config test passed, and only a completion review caught it.
+    //
+    // Runs HERE, not with the presence half, because `isOperationDefault` is computed by the
+    // operations loop above (it is variant-type-LOCAL — a lone variant marked `isDefault: false`
+    // yields NO default for its transport group, which this check must see). Reads the SAME
+    // predicate the resolver applies, so a config this guard accepts is a config the resolver can
+    // serve, by construction rather than by two lists agreeing.
+    if (retentionPolicy?.mode) {
+        for (const { operation: requiredOperation, primitive } of RETENTION_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS) {
+            if (operations.some((candidate) => isServiceResolvableDefaultOperation(candidate, requiredOperation))) {
+                continue;
+            }
+            const declaredVariants = operations
+                .filter((candidate) => candidate.operationIdentifier === requiredOperation)
+                .map((candidate) => `${candidate.variantType}${candidate.variantKey ? `:${candidate.variantKey}` : ''}` +
+                `${candidate.isOperationDefault ? ' (default)' : ''}`);
+            throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy requires ${requiredOperation} to be SERVICE-RESOLVABLE, but it ` +
+                `declares no DEFAULT variant of an accepted type. Declared variants: ` +
+                `[${declaredVariants.length > 0 ? declaredVariants.join(', ') : 'none'}]. The retention primitive ` +
+                `${primitive} resolves this operation through getServiceOperationPathDefault, which accepts only ` +
+                `[${SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES.join(', ')}] and only the operation default. ` +
+                `REPOSITORY_ONLY is route-less but is served by the SEPARATE getRepositoryOperationPathDefault ` +
+                `transport, so it passes the "operation exists" check and then FAILS TO RESOLVE the moment an ` +
+                `erasure runs. Use ${ResourceOperationVariantType.INTERNAL_CALL} for a capability that must stay ` +
+                `route-less (it is both route-less and service-resolvable), and make sure it is the default for ` +
+                `its transport group — a lone variant marked \`isDefault: false\` leaves the group with NO default.`);
+        }
+    }
     const resourceConfig = {
         isDisabled: params.isDisabled ?? false,
         resourcePrimaryScope,
@@ -1502,11 +2888,29 @@ export function createResourceConfiguration_Initialization(params) {
         resourceRelationships: processedResourceRelationships,
         inheritenceSchemaDefinition,
         persistenceAdapter,
+        persistenceAdapterIsolation,
+        httpApiBinding,
+        introspectionBinding,
+        externalDataPipeline,
         isSystemResource,
+        primaryKeyIdentifiesInitiator,
+        systemAccessPolicy: effectiveSystemAccessPolicy,
         isAnonymizable,
         transpositionPolicy: isAnonymizable
             ? (transpositionPolicy ?? ResourceTranspositionPolicy.ADD)
             : ResourceTranspositionPolicy.ADD,
+        // Normalize (mirror transpositionPolicy): the RESOLVED retentionPolicy is present IFF the resource
+        // opted in. An absent `mode` is an opt-in-shaped opt-out that injects no marker
+        // and derives no grants, so it must NOT ship a truthy resolved value — else a consumer doing
+        // `if (config.retentionPolicy)` would treat a non-opted-in resource as retention-governed.
+        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,
+        // 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,
         operations: operations // Temporary - will be replaced
     };
     // Pre-compute all DTOs for each operation using buildAllOperationDtos
@@ -1525,12 +2929,28 @@ export function createResourceConfiguration_Initialization(params) {
         resourceRelationships: processedResourceRelationships,
         inheritenceSchemaDefinition,
         persistenceAdapter,
+        persistenceAdapterIsolation,
+        httpApiBinding,
+        introspectionBinding,
+        externalDataPipeline,
         isSystemResource,
+        primaryKeyIdentifiesInitiator,
+        systemAccessPolicy: effectiveSystemAccessPolicy,
         isAnonymizable,
         transpositionPolicy: isAnonymizable
             ? (transpositionPolicy ?? ResourceTranspositionPolicy.ADD)
             : ResourceTranspositionPolicy.ADD,
+        // Normalize (mirror transpositionPolicy): resolved retentionPolicy present IFF opted-in — see the
+        // internal resourceConfig object above for the full rationale.
+        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,
+        // 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,
         operations: operationsWithDtos
     };
 }
-//# sourceMappingURL=resources-config.shared.factory.js.map
+//# sourceMappingURL=resources-config.shared.factory.js.map