@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/resources/services/resources-registry.backend.service.js

@@ -11,7 +11,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { injectable, inject } from 'inversify';
-import { coreNotificationBadgeDefinitions, coreShared_ResourcesConfigurations_FactoryMap, coreResourceShared_FieldIdentifier, coreResourceShared_FieldIdentifierPriority, coreSharedResourceRelationship, ResourcesConfigOperationsUrlsBuilderUtils, ResourcesConfigOperationsDtosBuilderUtils, ResourcesConfig_OperationPathUtils, ResourceOperationVariantType, isDefaultUrlBearingOperation, isServiceResolvableDefaultOperation, SERVICE_NATIVE_OPERATION_VARIANT_TYPES, URL_BEARING_OPERATION_VARIANT_TYPES, findSharedPersistenceCollectionRetentionIncoherences, findSharedPersistenceCollectionAdapterIncoherences, ErrorType, ErrorCustomMessageReference, ENGINE_ORGANIZATION_UNIT_NARROWING, collectOrganizationUnitNarrowingViolations, mergeOrganizationUnitNarrowingDeclarations, DEFAULT_PERSISTENCE_ADAPTER, CoreResourceOperation, ResourceParentResourceRequirement, reconcileGeneratedRelationshipBulkOperations, Resources_SharedUtils, isPersistenceAdapter, selectByPersistenceAdapter, dataModeToVariantKey, findDuplicateRelationshipRegistrations, } from '@wildo-ai/saas-models';
+import { coreNotificationBadgeDefinitions, collectNotificationBadgeDeclarationViolations, notificationBadgeIdentityKey, coreShared_ResourcesConfigurations_FactoryMap, coreResourceShared_FieldIdentifier, coreResourceShared_FieldIdentifierPriority, coreSharedResourceRelationship, ResourcesConfigOperationsUrlsBuilderUtils, ResourcesConfigOperationsDtosBuilderUtils, ResourcesConfig_OperationPathUtils, ResourceOperationVariantType, isDefaultUrlBearingOperation, isServiceResolvableDefaultOperation, SERVICE_NATIVE_OPERATION_VARIANT_TYPES, URL_BEARING_OPERATION_VARIANT_TYPES, findSharedPersistenceCollectionRetentionIncoherences, findSharedPersistenceCollectionAdapterIncoherences, ErrorType, ErrorCustomMessageReference, ENGINE_ORGANIZATION_UNIT_NARROWING, collectOrganizationUnitNarrowingViolations, mergeOrganizationUnitNarrowingDeclarations, DEFAULT_PERSISTENCE_ADAPTER, CoreResourceOperation, ResourceParentResourceRequirement, reconcileGeneratedRelationshipBulkOperations, Resources_SharedUtils, isPersistenceAdapter, selectByPersistenceAdapter, dataModeToVariantKey, findDuplicateRelationshipRegistrations, } from '@wildo-ai/saas-models';
 import { backendResourcesConfigurationsFactoryMap } from '../../resources/models/resources-operations.backend.definitions.js';
 import { backendResourcesRelationships } from '../../resources/models/resources-relationships.backend.definitions.js';
 import { BackendResourceFieldIdentifier } from '../../resources/models/resources-types.backend.schemas.js';
@@ -288,6 +288,9 @@ let ResourcesRegistryBackendService = class ResourcesRegistryBackendService {
             // repositories (which apply) — so they cannot disagree about which resources are narrowed.
             organizationUnitNarrowing,
         };
+        // Validate that every badge declaration is coherent, and refuse to start otherwise.
+        this.logDebug('Validating notification badge declarations');
+        this.validateNotificationBadgeDeclarations(this.registry.notificationBadgeDefinitions, allResourceConfigurations);
         // Validate all relationships can resolve FK fields
         this.logDebug('Validating relationship FK field resolution');
         this.validateRelationshipForeignKeyFields(allResourceRelationships, allResourceFieldIdentifiers);
@@ -534,11 +537,36 @@ let ResourcesRegistryBackendService = class ResourcesRegistryBackendService {
      * Resolution is INTERNAL-preferred, then URL-bearing:
      *  1. If the operation declares an `INTERNAL_CALL` default, return it. This
      *     honours author intent for resources whose default for this operation
-     *     is internal-only (`userIdentityLinks.list`) AND for resources that
-     *     declare BOTH an internal and a URL default for the same operation
-     *     (`users.list`, `inboundContacts.update`) — the internal variant is the
-     *     one trusted callers must use; the URL variant is the public/admin
-     *     surface reached via its keyed/route path.
+     *     is internal-only (`userIdentityLinks.list`, `users.list`,
+     *     `inboundContacts.update`) AND for the one resource that declares BOTH
+     *     an internal and a URL default for the same operation — the internal
+     *     variant is the one trusted callers must use; the URL variant is the
+     *     public/admin surface reached via its keyed/route path.
+     *
+     *     **That "BOTH" population is exactly ONE operation: `organizations`
+     *     CREATE.** Measured 2026-09-08 over all 106 non-test
+     *     `*resources-config*.ts` files (653 variant blocks), replicating
+     *     `determineOperationVariantDefault` per variant-type group.
+     *
+     *     This paragraph previously cited `users.list` and `inboundContacts.update`
+     *     as further both-default examples and BOTH were wrong: the former's
+     *     `API_CALL` is `isDefault: false, variantKey: "admin"`, and the latter
+     *     declares no `API_CALL` at all — so neither has a URL-bearing DEFAULT and
+     *     neither is a case where this method chooses between transports. The
+     *     correction is recorded rather than silently applied because the false
+     *     plural made the preference look like a broad, well-trodden policy when it
+     *     decides exactly one operation — which is what made the agent function-tool
+     *     plane's blast radius read as unbounded when it was a single, and severe,
+     *     case (see `9594526e`).
+     *
+     *     ⚠️ **A caller that FACES AN EXTERNAL PRINCIPAL must not use this method.**
+     *     It answers "which variant does a TRUSTED internal caller want", and for
+     *     `organizations` CREATE that is the registration-owned path, which skips the
+     *     creation-policy guard and writes no founding owner. A surface that
+     *     advertises a public operation to an outside caller owes
+     *     {@link getOperationPathDefault} instead, so the operation it authorized and
+     *     advertised is the operation it executes — the invariant the MCP tool plane
+     *     and the agent function-tool factories both keep.
      *  2. Otherwise return the URL-bearing default (`API_CALL` /
      *     `API_CALL_WITH_CALLBACK`) for resources exposed only over HTTP.
      *  3. Otherwise throw `RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND`.
@@ -1032,6 +1060,62 @@ let ResourcesRegistryBackendService = class ResourcesRegistryBackendService {
             };
         }
     }
+    /**
+     * Refuse to start on an incoherent notification-badge declaration.
+     *
+     * ## What this catches, and why the runtime could not
+     *
+     * A badge write used to be addressed by a bare `identifier`, resolved against nothing. Two
+     * declarations were therefore unfalsifiable:
+     *
+     * - an operation naming a badge NO definition declares — the write materialized a counter row
+     *   that no definition described and no screen could render, silently, forever;
+     * - two definitions sharing one `(scope, identifier)` — every lookup answers the first, so the
+     *   second is unreachable while sharing the first's count.
+     *
+     * Neither produces an error at runtime. The write succeeds; the render finds nothing; nobody is
+     * told. So the check belongs where the DECLARATION is, not where the write is, and it fails
+     * CLOSED for the same reason the organization-unit narrowing containment above does: a
+     * misconfiguration that only manifests as a missing number is one nobody chases.
+     *
+     * **What a misconfigured application experiences:** the backend does not come up. Startup throws
+     * a `CONFIGURATION` error naming every violation — the resource and operation that declared the
+     * unresolvable ref, or the duplicated key — beside the keys that ARE registered, so the author
+     * reads the fix off the message rather than deriving it. A typo in a `badgeRef` is a refusal at
+     * the moment it is authored instead of a badge that never appears in production.
+     *
+     * The enumeration is TOTAL over both populations rather than sampled: every registered
+     * definition, and every `notificationBadgeOperations` entry on every operation of every resource
+     * configuration — which is the merged core + application map, so an engine-declared badge is
+     * checked on the same terms as an application-declared one.
+     */
+    validateNotificationBadgeDeclarations(notificationBadgeDefinitions, allResourceConfigurations) {
+        const operationSites = [];
+        for (const [resourceType, resourceConfiguration] of Object.entries(allResourceConfigurations)) {
+            const operations = resourceConfiguration?.operations ?? {};
+            for (const [operationIdentifier, operation] of Object.entries(operations)) {
+                const badgeOperations = operation?.notificationBadgeOperations ?? [];
+                for (const badgeOperation of badgeOperations) {
+                    operationSites.push({ resourceType, operationIdentifier, badgeRef: badgeOperation.badgeRef });
+                }
+            }
+        }
+        const violations = collectNotificationBadgeDeclarationViolations(notificationBadgeDefinitions, operationSites);
+        if (violations.length > 0) {
+            this.logger.error('Notification badge declaration validation failed', { violations });
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: 'Notification badge declarations are incoherent',
+                    reason: 'notification_badge_declaration_violation',
+                    violations,
+                    registeredBadgeKeys: notificationBadgeDefinitions.map(notificationBadgeIdentityKey),
+                },
+            });
+        }
+        this.logDebug(`Validated ${notificationBadgeDefinitions.length} notification badge definition(s) `
+            + `and ${operationSites.length} operation badge reference(s)`);
+    }
     /**
      * Validate that all relationships can resolve their FK fields at startup.
      * This catches configuration errors early (e.g., missing resourceFieldIdentifier).
@@ -1362,7 +1446,7 @@ let ResourcesRegistryBackendService = class ResourcesRegistryBackendService {
                      */
                     const tenancy = config.introspectionBinding?.tenancy;
                     if (tenancy === IntrospectionTenancyStance.SCOPE_FILTER_PUSHDOWN) {
-                        errors.push(`Resource '${resourceType}' declares introspection tenancy 'scope-filter-pushdown', which is not implemented: no introspection behavior accepts a scope argument, so the engine has nothing to push down and the rows would be served unscoped. Declare 'application-structure' if the rows carry no tenant dimension, or do not back this resource with introspection.`);
+                        errors.push(`Resource '${resourceType}' declares introspection tenancy 'scope-filter-pushdown', which is not implemented: no introspection behavior accepts a scope argument, so the engine has nothing to push down and the rows would be served unscoped. Declare 'application-structure' (source-derived rows) or 'application-runtime' (companion runtime projections) if the rows carry no tenant dimension, or do not back this resource with introspection.`);
                     }
                     if (config.retentionPolicy) {
                         errors.push(`Resource '${resourceType}' is INTROSPECTION-backed and declares 'retentionPolicy' — nothing is stored, so there is nothing to retain or purge; remove the policy.`);