@wildo-ai/saas-models 1.1.2 → 1.1.4

package/dist/esm/resources/resources-config.shared.factory.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, Resources_BulkOperationBaseSchema, Resources_Filter_BaseSchema, Resources_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, isPersistenceAdapter, 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';
@@ -39,6 +39,7 @@ 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 { selectByPersistenceAdapter } from './utils/persistence-adapter-discrimination.shared.utils.js';
 import { isServiceResolvableDefaultOperation, SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES, URL_BEARING_OPERATION_VARIANT_TYPES, } from './utils/resource-operation-type-guards.utils.js';
 // --------------------------------
 // Error Helpers
@@ -139,6 +140,57 @@ const RETENTION_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS = [
         why: 'the see-through read primitive listRetainedAsSystem surfaces retained records via LIST',
     },
 ];
+/**
+ * The operations an `isAnonymizable` resource must expose to the SERVICE dispatch
+ * layer, with the `AnonymousSessionBackendService` primitive that needs each one.
+ *
+ * Sibling of {@link RETENTION_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS} and consumed by
+ * the same TWO halves — presence (is it declared in `coreOperations`?) and
+ * resolvability (does it have a default variant `getServiceOperationPathDefault`
+ * can serve?). A separate constant rather than a shared one, because the two
+ * capabilities demand different operations for different reasons and merging them
+ * would make each entry's `why` unreadable.
+ *
+ * **Each entry is a DISJUNCTION, and that is the whole design decision.** Retention
+ * needs three specific operations, so its constant is a flat list of single ops.
+ * The anonymous-session cleanup needs to DELETE a known id set, and
+ * `deleteOwnedRecords` deliberately serves that with `DELETE_MANY` when the
+ * resource publishes one and per-row `DELETE` otherwise — so demanding
+ * `DELETE_MANY` would force every anonymizable resource to publish a bulk-delete
+ * surface it may not want (`draftNotes`, the only such resource today, publishes
+ * `DELETE` alone), while demanding `DELETE` would refuse a resource that
+ * legitimately publishes only the bulk form. The honest requirement is "at least
+ * one of these resolves", which is exactly what the runtime probes.
+ *
+ * Measured 2026-09-09: before this guard existed, `deleteOwnedRecords` resolved
+ * `DELETE_MANY` unconditionally, so for `draftNotes` the cleanup batch's phase 1
+ * threw on every run — the per-session catch counted an error and the
+ * `ANONYMOUS_USERS` anchor row was never removed. The runtime is now correct; this
+ * constant is what refuses the configuration at boot instead of discovering it at
+ * the first sweep.
+ */
+const ANONYMIZABLE_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS = [
+    {
+        operations: [CoreResourceOperation.LIST],
+        primitive: 'listAnonymousRecords',
+        why: 'the transposition and cleanup lookups list a session\'s rows via LIST',
+    },
+    {
+        operations: [CoreResourceOperation.UPDATE_MANY],
+        primitive: 'reassignOwnership (updateManyAsSystem)',
+        why: 'the anon→user transposition rewrites { userId, anonymousUserId } via updateManyAsSystem',
+    },
+    {
+        operations: [CoreResourceOperation.DELETE_MANY, CoreResourceOperation.DELETE],
+        primitive: 'deleteOwnedRecords',
+        why: 'the expired-session sweep, the DISCARD transposition arm and the REPLACE pre-delete all remove '
+            + 'a known id set, preferring DELETE_MANY and falling back to per-row DELETE',
+    },
+];
+/** Human-readable "A or B" rendering of one requirement group's alternatives. */
+function describeOperationAlternatives(operations) {
+    return operations.length === 1 ? String(operations[0]) : operations.join(' or ');
+}
 function assertOperationPathKeySegment(value, label, operation) {
     if (value.includes(' | ')) {
         throw createConfigurationError(`Operation '${operation}' cannot use ${label} '${value}' because operation path keys reserve the delimiter ' | '`);
@@ -326,15 +378,79 @@ function createGeneratedFileRegenerateOperations(params) {
         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.
+     * A generated document is MATERIALIZED: rendering it writes a FILES metadata row that must
+     * commit in the SAME native transaction as the row that owns it, or a failure between the two
+     * leaves either a dangling document reference or an orphaned blob. So the only question this
+     * guard can honestly ask of a DECLARATION is whether the declared adapter is one that HAS a
+     * transactional local store at all.
+     *
+     * ## What changed, and why the old shape was wrong rather than merely conservative
+     *
+     * This refused every adapter except MongoDB, on the grounds that file metadata was pinned to
+     * MongoDB, so a generated PDF on a PostgreSQL resource would have crossed adapters. That reason
+     * is gone: FILES was un-pinned and now FOLLOWS the application's default adapter
+     * (`files.shared.resources-config.schemas.ts:43-67`), precisely so a resource and its file
+     * metadata share one native transaction. A PostgreSQL application whose FILES is therefore also
+     * PostgreSQL was being refused at authoring time for a boundary that no longer exists.
+     *
+     * The ASYMMETRY was the tell, and it is the reason this could not be left alone: `undefined` —
+     * "follow the application default" — was and is admitted, so the identical resource in the
+     * identical PostgreSQL application was already authorable by SAYING LESS. A guard whose answer
+     * depends on whether a redundant declaration was written is testing the declaration, not the
+     * capability.
+     *
+     * ## What still refuses, and why that half is load-bearing
+     *
+     * `INTROSPECTION` rows are recomputed per read — there is no store and no transaction. `HTTP_API`
+     * rows live in someone else's system and are read-only by construction. Neither can own a
+     * locally-materialized document row, and unlike the PostgreSQL case that is knowable from the
+     * declaration alone, so refusing at authoring time is strictly better than discovering it on the
+     * first write. `getDatabaseServiceForAdapter` says the same thing at runtime, for the same two
+     * adapters, in the same words.
+     *
+     * ## Shape
+     *
+     * Expressed as an exhaustive `PersistenceAdapterCases` map rather than a comparison, so a fifth
+     * backing kind is a COMPILE error here instead of silently inheriting whichever arm an `else`
+     * happened to mean — the failure mode `selectByPersistenceAdapter` exists to remove, and the one
+     * the previous `!== MONGODB` shape genuinely had in the other direction (it would have refused a
+     * future stored adapter without anyone deciding to).
+     *
+     * `isPersistenceAdapter` runs FIRST so an erased or unknown declaration keeps refusing through
+     * `createConfigurationError` with the resource and the field list named, rather than through the
+     * selector's plain `Error`. This factory is a shared-tier authoring surface: its refusals are
+     * read by an application author, and the field list is the actionable half.
+     *
+     * ## What this guard deliberately does NOT decide
+     *
+     * It cannot see the application's default adapter, so it cannot tell whether THIS resource and
+     * FILES resolve to the same store — a resource declaring `POSTGRESQL` inside a MongoDB-default
+     * application is a real cross-adapter boundary and must still be refused. That refusal is made
+     * where the resolved adapters are actually known, at
+     * `services-registry-handler.backend.service.ts` →
+     * `assertGeneratedFileMaterializationCommitsWithRow`, which asks the persistence unit of work
+     * whether `{this resource, FILES-as-ATOMIC}` can commit atomically and throws
+     * `MIXED_PERSISTENCE_ADAPTERS` when it cannot. It gates all three materialization entry points
+     * (create, createMany, regenerate) and, unlike this one, also covers the undeclared case this
+     * guard has always waved through — which is why relaxing here narrows nothing.
      */
-    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 GENERATED_DOCUMENT_MATERIALIZATION_SUPPORT = {
+        [PersistenceAdapter.MONGODB]: true,
+        [PersistenceAdapter.POSTGRESQL]: true,
+        [PersistenceAdapter.INTROSPECTION]: false,
+        [PersistenceAdapter.HTTP_API]: false,
+    };
+    if (params.persistenceAdapter !== undefined) {
+        const declaredAdapter = params.persistenceAdapter;
+        const materializationIsSupported = isPersistenceAdapter(declaredAdapter)
+            && selectByPersistenceAdapter(declaredAdapter, GENERATED_DOCUMENT_MATERIALIZATION_SUPPORT);
+        if (!materializationIsSupported) {
+            throw createConfigurationError(`[${params.resourceIdentifier}] generated PDF file fields require a persistence adapter with a transactional local store, `
+                + `so that the generated file's metadata row commits with the row that owns it `
+                + `(declared adapter: '${String(declaredAdapter)}'; supported: `
+                + `'${PersistenceAdapter.MONGODB}', '${PersistenceAdapter.POSTGRESQL}', or no declaration to follow the application default): `
+                + `${generatedFields.map((field) => field.fieldName).join(', ')}`);
+        }
     }
     const baseUpdateOperation = params.operations.find((operation) => isUrlisableOperationVariantType(operation.variantType)
         && operation.operationIdentifier === CoreResourceOperation.UPDATE
@@ -480,19 +596,35 @@ function normalizeRequiredFeatures(input) {
 // DTO Auto-Derivation Utilities
 // --------------------------------
 /**
- * Fields always excluded from create/update DTOs (system-managed)
- * These are hardcoded because they are universal across all resources.
+ * @wildo_source:part:start saas.models.resource-config.system-managed-fields facet:layer:shared facet:audience:app-developer
+ *
+ * The field names the framework owns. They are removed from every generated CREATE and UPDATE
+ * request contract, for every resource, whatever your schema declares and whatever a caller sends.
+ *
+ * Declaring one of these in a resource schema is fine and often necessary — the framework maintains
+ * the value. What you cannot do is accept it from a client, default it in a form, or require it on a
+ * create: the field is stripped before validation runs, so a form that collects it submits a value
+ * that is discarded, and a schema that requires it rejects every request.
+ *
+ * | field | who writes it |
+ * |---|---|
+ * | `_id` | the persistence layer (or your own `.isPrimaryKey()` field, stored beneath it) |
+ * | `createdAt` / `updatedAt` / `deletedAt` | the repository, on write |
+ * | `createdByUserId` | the repository, stamped from the execution context on CREATE, immutable afterwards |
+ * | `_version_db_doc` | the framework's optimistic-concurrency marker |
  *
- * `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).
+ * The failure this prevents is quiet and was paid for once: a create form validating against a
+ * reserved field that no form collects fails every submit with `expected string, received undefined`,
+ * and the schema looks correct while it does. So the exclusion is unconditional and does not depend
+ * on the resource author remembering `.excludeFromCreate()`.
+ *
+ * ⚠️ A NARROWER set — `_id`, `createdAt`, `updatedAt`, `deletedAt`, `_version_db_doc` — is
+ * additionally *mandatory-discard*: even a trusted in-process system write cannot re-attach those
+ * through `preserveServerInjectedFields`. `createdByUserId` is deliberately not in that set, because
+ * an engine flow creating a row on somebody's behalf legitimately needs to stamp it.
  */
 const SYSTEM_MANAGED_FIELDS = ['_id', 'createdAt', 'updatedAt', 'deletedAt', 'createdByUserId', '_version_db_doc'];
+/** @wildo_source:part:end saas.models.resource-config.system-managed-fields */
 // PRIMARY_SCOPE_FIELD_IDENTIFIERS and getPrimaryScopeFieldIdentifier imported from resources.shared.schemas
 /**
  * Build a CREATE request DTO from the main schema using decorators.
@@ -1453,7 +1585,7 @@ export function createResourceConfiguration_Initialization(params) {
         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.`);
     }
     // The RESOLVED binding, not the authored one. An author writes the schema's INPUT shape
-    // (`HttpApiResourceBindingAuthored`), so defaults like `verifyMetadataAtBoot`, `identityMode` and
+    // (`HttpApiResourceBindingAuthored`), so defaults like `verifyMetadataAtBoot`, `connection` 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.
@@ -1720,11 +1852,18 @@ export function createResourceConfiguration_Initialization(params) {
                 throw e;
             throw createConfigurationError(`[${resourceIdentifier}] isAnonymizable: true but mainSchema is not a ZodObject (cannot validate userId field).`);
         }
-        if (!coreOperations.includes(CoreResourceOperation.LIST)) {
-            throw createConfigurationError(`[${resourceIdentifier}] isAnonymizable: true requires LIST in coreOperations (needed for transposition lookup).`);
-        }
-        if (!coreOperations.includes(CoreResourceOperation.UPDATE_MANY)) {
-            throw createConfigurationError(`[${resourceIdentifier}] isAnonymizable: true requires UPDATE_MANY in coreOperations (needed for transposition batch update).`);
+        // PRESENCE half of the anonymizable operation contract: each requirement group must have at
+        // least one of its alternatives declared at all. The RESOLVABILITY half — that a declared op
+        // has a variant `AnonymousSessionBackendService` can actually dispatch — runs later, once the
+        // operation variants are assembled (search `ANONYMIZABLE_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS`).
+        // Deliberately two checks, exactly as for `retentionPolicy`, because they have two different
+        // fixes: "declare the op" vs "declare it with a service-resolvable variant".
+        for (const { operations: alternatives, primitive, why } of ANONYMIZABLE_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS) {
+            if (alternatives.some((alternative) => coreOperations.includes(alternative))) {
+                continue;
+            }
+            throw createConfigurationError(`[${resourceIdentifier}] isAnonymizable: true requires ${describeOperationAlternatives(alternatives)} ` +
+                `in coreOperations (${primitive}: ${why}).`);
         }
         effectiveMainSchema = mainSchema.extend({
             anonymousUserId: z.string().optional().nullable().isDBIndexed()
@@ -2429,6 +2568,10 @@ export function createResourceConfiguration_Initialization(params) {
                 notificationBadgeOperations: config.notificationBadgeOperations || [],
                 userNotifications,
                 m2mNotifications,
+                // Carried verbatim rather than normalized: it is one authored object with no derived
+                // parts, unlike the notification families above, which the factory stamps with scope and
+                // identifier. `undefined` means the operation consumes no metered product.
+                recordsUsage: config.recordsUsage,
                 // Fields from ResourceConfiguration_OperationVariant_Base
                 variantType: variantParams.variantType,
                 resourceOperationLike: variantParams.resourceOperationLike,
@@ -2950,6 +3093,41 @@ export function createResourceConfiguration_Initialization(params) {
                 `its transport group — a lone variant marked \`isDefault: false\` leaves the group with NO default.`);
         }
     }
+    // ── RESOLVABILITY half of the ANONYMIZABLE operation contract ───────────
+    //
+    // Same two-halves shape as retention above, for the other dynamic-loop capability. The presence
+    // half proved that each requirement group has an alternative DECLARED; this proves one of them
+    // is REACHABLE by `AnonymousSessionBackendService`, whose three primitives
+    // (`listAnonymousRecords` / `updateManyAsSystem` / `deleteOwnedRecords`) all resolve through
+    // `getServiceOperationPathDefault`.
+    //
+    // Runs HERE rather than with the presence half for the same reason retention's does:
+    // `isOperationDefault` is computed by the operations loop above, and it is variant-type-LOCAL —
+    // a lone variant marked `isDefault: false` leaves its transport group with NO default.
+    //
+    // Reads the SAME predicate the resolver applies (`isServiceResolvableDefaultOperation`), and the
+    // same predicate `deleteOwnedRecords` probes with when it chooses between DELETE_MANY and
+    // per-row DELETE — so the guard, the runtime chooser and the resolver cannot disagree.
+    if (isAnonymizable) {
+        for (const { operations: alternatives, primitive, why } of ANONYMIZABLE_REQUIRED_SERVICE_RESOLVABLE_OPERATIONS) {
+            if (alternatives.some((alternative) => operations.some((candidate) => isServiceResolvableDefaultOperation(candidate, alternative)))) {
+                continue;
+            }
+            const declaredVariants = operations
+                .filter((candidate) => alternatives.includes(candidate.operationIdentifier))
+                .map((candidate) => `${String(candidate.operationIdentifier)}/${candidate.variantType}` +
+                `${candidate.variantKey ? `:${candidate.variantKey}` : ''}${candidate.isOperationDefault ? ' (default)' : ''}`);
+            throw createConfigurationError(`[${resourceIdentifier}] isAnonymizable: true requires ${describeOperationAlternatives(alternatives)} ` +
+                `to be SERVICE-RESOLVABLE, but no accepted DEFAULT variant is declared. Declared variants: ` +
+                `[${declaredVariants.length > 0 ? declaredVariants.join(', ') : 'none'}]. The anonymous-session ` +
+                `primitive ${primitive} (${why}) resolves 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 ` +
+                `anonymous session converts or expires. Use ${ResourceOperationVariantType.INTERNAL_CALL} for a ` +
+                `capability that must stay route-less, and make sure it is the default for its transport group.`);
+        }
+    }
     const resourceConfig = {
         isDisabled: params.isDisabled ?? false,
         resourcePrimaryScope,