@wildo-ai/saas-models 1.1.0 → 1.1.2

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

@@ -3,11 +3,11 @@
  *
  * Reusable operation schemas for bulk actions and common operations
  */
-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 { ExpiresInDurationSchema, getImpersonalizeMaskValue, getImpersonalizeTreatment, getZodObjectShape, getZodType, isBackendOnlyField, isDiscriminatorField, isExcludedFromCreate, isExcludedFromUpdate, isBusinessKeyField, isZodObject, isSummaryField, isTemplatableFileField, isUniqueField, 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 { buildImpersonalizeScrubPatch, collectDeclaredPersonalDataFields, IMPERSONALIZE_MASK_CONSTANT, isImpersonalizeNeverScrubFloorField, resolveImpersonalizeMaskValue, resolveImpersonalizeResetValue, } from '../compliance/privacy/impersonalization-scrub.shared.utils.js';
 import { RedactionType } from '../compliance/privacy/redaction.shared.schemas.js';
 import { unknownPersonalDataCategories } from '../compliance/privacy/personal-data-category.shared.schemas.js';
 /*
@@ -31,7 +31,7 @@ import { HttpApiResourceBindingSchema, HttpApiTransportDialect, assertHttpApiBin
 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, createPaginationRequestSchema, createPaginationResponseMetadataSchema, ResourceGeneratedOperationKind, ResourceSystemAccessMode, PersistenceAdapter, SortOrder, ResourceCollectionExportResponseSchema, } from './resources-config.shared.schemas.js';
+import { OPERATION_VARIANT_KEY, Resources_BulkOperationBaseSchema, Resources_Filter_BaseSchema, Resources_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, 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';
@@ -1242,7 +1242,7 @@ export function createResourceSearchQueryRequestSchema(params) {
         Object.entries(fields).forEach(([key, schema]) => {
             // Type-safe schema processing based on schema type
             if (schema instanceof z.ZodDate) {
-                processedFields[key] = Resouces_Filter_DateRangeSchema.optional();
+                processedFields[key] = Resources_Filter_DateRangeSchema.optional();
             }
             else if (schema instanceof z.ZodString) {
                 processedFields[key] = schema.optional();
@@ -1261,7 +1261,7 @@ export function createResourceSearchQueryRequestSchema(params) {
                 processedFields[key] = schema.optional();
             }
         });
-        return Resouces_Filter_BaseSchema.extend(processedFields);
+        return Resources_Filter_BaseSchema.extend(processedFields);
     };
     // Strongly typed sorting schema creation
     const createSortingSchema = (fields) => {
@@ -1295,7 +1295,7 @@ export function createResourceSearchQueryRequestSchema(params) {
         schemaConfig.filters = createFilterSchema(filterFields).optional();
     }
     else {
-        schemaConfig.filters = Resouces_Filter_BaseSchema.optional();
+        schemaConfig.filters = Resources_Filter_BaseSchema.optional();
     }
     // Create the final schema with validation
     const resultSchema = z.object(schemaConfig);
@@ -1452,7 +1452,12 @@ export function createResourceConfiguration_Initialization(params) {
     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) {
+    // The RESOLVED binding, not the authored one. An author writes the schema's INPUT shape
+    // (`HttpApiResourceBindingAuthored`), so defaults like `verifyMetadataAtBoot`, `identityMode` and
+    // `remoteCallSemantics` may be absent from what they typed; every consumer reads the parsed shape
+    // and is entitled to find them. The parse result used to be DISCARDED — harmless only because
+    // authoring demanded every field, which is precisely the burden the authored shape removes.
+    const resolvedHttpApiBinding = httpApiBinding === undefined ? 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('; ')}`);
@@ -1463,7 +1468,8 @@ export function createResourceConfiguration_Initialization(params) {
         catch (error) {
             throw createConfigurationError(`[${resourceIdentifier}] invalid httpApiBinding declaration: ${error instanceof Error ? error.message : String(error)}`);
         }
-    }
+        return bindingParse.data;
+    })();
     /**
      * `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),
@@ -1525,6 +1531,21 @@ export function createResourceConfiguration_Initialization(params) {
         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.`);
         }
+        // ...and `.isUnique()` ON TOP, which is NOT redundant with the line above: the SQL schema
+        // planner derives a UNIQUE constraint from `.isUnique()` and never from `.isBusinessKey()`.
+        // Without it the merge contract is upheld only by our own read-then-write, so two concurrent
+        // runs of one pipeline can leave TWO rows for one remote row — the exact duplication the whole
+        // business-key design exists to prevent, and precisely what a store-level constraint refuses
+        // for free.
+        //
+        // Required rather than suggested because this is an invariant with N call sites (every
+        // destination any application ever declares) and a silent failure mode: nothing misbehaves
+        // until two runs overlap, and by then the duplicate rows already exist. Found by the first
+        // dogfood — the generated migration gave the key a PLAIN index and the omission was invisible
+        // in every test, because a single-threaded upsert merges correctly with or without it.
+        if (!isUniqueField(keyFieldSchema)) {
+            refuse(`remoteKeyLocalField: '${declaration.remoteKeyLocalField}' must ALSO be declared .isUnique(). The schema planner derives a UNIQUE constraint from .isUnique() and NOT from .isBusinessKey(), so without it the store would accept two rows for one remote row whenever two runs overlap — the merge would be enforced only by this engine's read-then-write, never by the database.`);
+        }
         for (const entry of declaration.mapping) {
             const targetSchema = requireMappedTarget(entry.localField, `mapping('${entry.localField}')`);
             if (entry.kind === ExternalDataMappingEntryKind.REMOTE_FIELD) {
@@ -1923,6 +1944,28 @@ export function createResourceConfiguration_Initialization(params) {
                             `declares (format, length, enum membership).`);
                 }
             }
+            else if (treatment === RedactionType.RESET) {
+                /*
+                 * RESET returns the field to its schema default — the treatment for a field that is non-nullable
+                 * WITH a `.default()`, where REMOVE (needs clearable) and MASK (needs a string) both refuse.
+                 *
+                 * The RULES live in `resolveImpersonalizeResetValue`, deliberately, and are NOT restated here: it
+                 * refuses a field with no default, and one that is merely `.optional()` (whose default IS
+                 * undefined, so nothing would be scrubbed). One authority, because a second copy of either check
+                 * would drift from the writer that actually runs them.
+                 *
+                 * What this arm adds is WHERE the failure surfaces. Called here, the refusal is a CONFIGURATION
+                 * error naming the RESOURCE. Left to fall through, the same resolver still runs — via
+                 * `buildImpersonalizeScrubPatch` further down this function — but throws a bare Error naming only
+                 * the field, which boot does not classify as a configuration fault.
+                 */
+                try {
+                    resolveImpersonalizeResetValue(fieldSchema, fieldName);
+                }
+                catch (error) {
+                    throw createConfigurationError(`[${resourceIdentifier}] ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
         }
         // 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
@@ -1951,6 +1994,28 @@ export function createResourceConfiguration_Initialization(params) {
                     `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.`);
             }
+            /*
+             * The SECOND direction, and until 2026-08-31 it did not exist.
+             *
+             * The check above sees a field with a TREATMENT. This one sees a field DECLARED as personal data
+             * and given no treatment — which is the shape a wrong `RETAIN_ONLY` actually takes. Without it,
+             * the cheap mode was also the one that failed silently: a resource whose fields carry
+             * `.dataCategories()` could assert it holds no personal data, pass every gate, and put that
+             * assertion into a governed document. `RETAIN_AND_IMPERSONALIZE` never had the hole — it is
+             * refused when nothing would be scrubbed.
+             *
+             * This catches a CONTRADICTION, not an omission. A resource that classified nothing still passes,
+             * because "nobody declared a category" and "there is no personal data" are indistinguishable
+             * here; that is the category inventory's question. A clean result is not a proof.
+             */
+            const declaredPersonalDataFields = collectDeclaredPersonalDataFields(effectiveMainSchema);
+            if (declaredPersonalDataFields.length > 0) {
+                throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy.mode = RETAIN_ONLY asserts this resource holds no personal data of ` +
+                    `its own, but field(s) [${declaredPersonalDataFields.join(', ')}] declare .dataCategories(). The resource ` +
+                    `cannot both hold personal data and hold none. Use mode = RETAIN_AND_IMPERSONALIZE and give those fields an ` +
+                    `impersonalize treatment, or — if the category is wrong — correct the field. Scope foreign keys and ` +
+                    `createdByUserId are excluded here: they link a row to a person without being personal data the row holds.`);
+            }
         }
         else if (Object.keys(effectiveScrubPatch).length === 0) {
             throw createConfigurationError(`[${resourceIdentifier}] retentionPolicy.mode = RETAIN_AND_IMPERSONALIZE but NO field would actually be ` +
@@ -2375,6 +2440,10 @@ export function createResourceConfiguration_Initialization(params) {
                 collectionExport: variantParams.collectionExport,
                 requiredFeatures: normalizeRequiredFeatures(variantParams.requiredFeatures),
                 riskLevel: variantParams.riskLevel || ResourceOperationRiskLevel.LOW,
+                // Forwarded for the same reason as the flags below: the frontend resources client reads it
+                // off the RUNTIME operation, so dropping it here would leave a declared long-run timeout
+                // silently unapplied and the 30s default cutting the request (issue #237).
+                clientRequestTimeoutMs: variantParams.clientRequestTimeoutMs,
                 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
@@ -2560,11 +2629,11 @@ export function createResourceConfiguration_Initialization(params) {
                                 });
                         }
                         if (apiCallOperationFields.requestDto instanceof z.ZodObject) {
-                            return Resouces_BulkOperationBaseSchema.extend(getZodObjectShape(apiCallOperationFields.requestDto));
+                            return Resources_BulkOperationBaseSchema.extend(getZodObjectShape(apiCallOperationFields.requestDto));
                         }
                         return apiCallOperationFields.requestDto && apiCallOperationFields.requestDto !== z.object({})
-                            ? Resouces_BulkOperationBaseSchema.and(apiCallOperationFields.requestDto)
-                            : Resouces_BulkOperationBaseSchema;
+                            ? Resources_BulkOperationBaseSchema.and(apiCallOperationFields.requestDto)
+                            : Resources_BulkOperationBaseSchema;
                     })();
                     const bulkOperationFields = {
                         ...apiCallOperationFields,
@@ -2636,6 +2705,10 @@ export function createResourceConfiguration_Initialization(params) {
                     resourceOperationLike: defaultApiCallVariant.resourceOperationLike,
                     requiredFeatures: normalizeRequiredFeatures(defaultApiCallVariant.requiredFeatures),
                     riskLevel: defaultApiCallVariant.riskLevel || ResourceOperationRiskLevel.LOW,
+                    // Inherited like riskLevel: an auto-variant is a projection of the default variant. The
+                    // read-shaped projections are unlikely to need it, but inheriting keeps "projection of
+                    // the default" a single consistent rule rather than a per-field accident.
+                    clientRequestTimeoutMs: defaultApiCallVariant.clientRequestTimeoutMs,
                     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 /
@@ -2889,7 +2962,7 @@ export function createResourceConfiguration_Initialization(params) {
         inheritenceSchemaDefinition,
         persistenceAdapter,
         persistenceAdapterIsolation,
-        httpApiBinding,
+        httpApiBinding: resolvedHttpApiBinding,
         introspectionBinding,
         externalDataPipeline,
         isSystemResource,
@@ -2930,7 +3003,7 @@ export function createResourceConfiguration_Initialization(params) {
         inheritenceSchemaDefinition,
         persistenceAdapter,
         persistenceAdapterIsolation,
-        httpApiBinding,
+        httpApiBinding: resolvedHttpApiBinding,
         introspectionBinding,
         externalDataPipeline,
         isSystemResource,