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

package/dist/esm/base-classes/services/repositories/http-api/http-api-resource-repository.backend.service.js

@@ -16,14 +16,16 @@
  * IS `null` — that is a genuine "no row".
  */
 import { CoreResourceOperation, ErrorType, HttpApiResourceIdError, PRIMARY_SCOPE_TO_FIELD_IDENTIFIER, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, ResourceOperationsUtils, resolveHttpApiKeyComponents, } from '@wildo-ai/saas-models';
-import { HttpApiErasureStance, HttpApiTenancyStance, HttpApiTransportDialect, } from '@wildo-ai/saas-models/external-data';
+import { HttpApiErasureStance, HttpApiTenancyStance, HttpApiTransportDialect, isHttpApiRestOperationReference, } from '@wildo-ai/saas-models/external-data';
 import { ErrorCustomMessageReference } from '@wildo-ai/saas-models';
+import { AuditObservationKind, emitAuditObservation, } from '../../../../monitoring/observability/audit-observation-emission.backend.js';
 import { HttpApiTransportError, } from './http-api-transport.backend.js';
 import { HttpApiReadClient, defaultHttpApiFetch } from './http-api-read-client.backend.js';
 import { HttpApiTranslationRefusal, translateHttpApiReadInputs, } from './http-api-filter-translation.backend.js';
 import { compileODataCollectionRead, compileODataCountRead, compileODataKeyAddressedRead, } from './odata-query-compiler.backend.js';
 import { RestJsonTranslationRefusal, compileRestJsonCollectionRead, compileRestJsonDeclaredErasure, compileRestJsonKeyAddressedRead, } from './rest-json-query-compiler.backend.js';
 import { HttpApiRemoteContractError, projectHttpApiRemoteRow, resolveHttpApiResultPath, } from './http-api-row-projection.backend.js';
+import { projectProviderOperationOntoReadSurface } from './http-api-rest-operation-reference.backend.js';
 import { compileOdooCanonicalDelete, compileOdooCollectionRead, compileOdooCountRead, compileOdooKeyAddressedRead, } from './odoo-jsonrpc-compiler.backend.js';
 import { HttpApiProviderAccessError, } from './http-api-provider-access.backend.js';
 /**
@@ -55,18 +57,27 @@ export class HttpApiResourceRepositoryBackendService {
     providerAccessResolver;
     fetchImpl;
     auditLogsResolver;
+    metricsResolver;
     resourceConfiguration;
     binding;
     operationsMap = new Map();
     readClient;
     logDebug;
-    constructor(resourceType, logger, errorBuilder, resourceRegistry, providerAccessResolver, fetchImpl = defaultHttpApiFetch, auditLogsResolver) {
+    constructor(resourceType, logger, errorBuilder, resourceRegistry, providerAccessResolver, fetchImpl = defaultHttpApiFetch, auditLogsResolver, 
+    /**
+     * The loss counter behind {@link recordReadThroughAccess}, resolved the same way and for the
+     * same reason as the audit seam beside it: this class is built with `new`, holds no container,
+     * and must construct in a unit harness that binds neither. A thunk rather than the recorder
+     * itself so nothing is resolved on the happy path — see the seam's own type.
+     */
+    metricsResolver) {
         this.logger = logger;
         this.errorBuilder = errorBuilder;
         this.resourceRegistry = resourceRegistry;
         this.providerAccessResolver = providerAccessResolver;
         this.fetchImpl = fetchImpl;
         this.auditLogsResolver = auditLogsResolver;
+        this.metricsResolver = metricsResolver;
         this.resourceConfiguration = this.resourceRegistry.getResourceConfiguration(resourceType);
         const binding = this.resourceConfiguration.httpApiBinding;
         if (!binding) {
@@ -108,7 +119,11 @@ export class HttpApiResourceRepositoryBackendService {
         ResourcesConfig_OperationPathUtils.validateOperationRepositoryPathKey(operationRepositoryPathKey);
         const operation = this.operationsMap.get(operationRepositoryPathKey);
         if (!operation) {
-            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+            // The TYPE now agrees with the LABEL this site already carried. It declared
+            // `ErrorCustomMessageReference.CONFIGURATION` with `reason: 'operation_not_found_on_http_api_repository'`
+            // and typed the same call `NOT_FOUND` — the classification and the label contradicting each
+            // other in one expression, where an author had clearly worked out which one was true.
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
                 customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
                 context: {
                     reason: 'operation_not_found_on_http_api_repository',
@@ -376,14 +391,37 @@ export class HttpApiResourceRepositoryBackendService {
             pagination,
         });
     }
-    restOperationSpec(member) {
+    /**
+     * The ONE place a REST_JSON read member becomes a compilable spec — and, since S3a (#331), the
+     * one place a CATALOGUE REFERENCE is resolved into one.
+     *
+     * Async because a reference loads the provider's catalogue, which is lazy by contract. All four
+     * call sites were already inside async methods, so this cost nothing at the boundary; what it
+     * buys is that a reference is resolved at the same chokepoint an inline spec is read, so no
+     * compiler and no caller ever learns which form the binding used.
+     *
+     * Resolved per call rather than cached here: the resolver memoizes the CATALOGUE (which is the
+     * expensive part), and caching the projected spec as well would put a second copy of provider
+     * state in every repository instance for no measurable gain.
+     */
+    async restOperationSpec(member) {
         if (this.binding.dialect !== HttpApiTransportDialect.REST_JSON)
             return undefined;
-        const spec = this.binding.operations[member];
-        if (!spec) {
+        const declaration = this.binding.operations[member];
+        if (!declaration) {
             throw new RestJsonTranslationRefusal(`This REST_JSON binding declares no '${member}' operation — the member is refused for this binding, never emulated.`);
         }
-        return spec;
+        if (!isHttpApiRestOperationReference(declaration))
+            return declaration;
+        if (typeof this.providerAccessResolver.resolveProviderOperation !== 'function') {
+            // Named rather than a TypeError three frames down: an operator can act on this sentence.
+            throw new RestJsonTranslationRefusal(`The '${member}' member references provider operation '${declaration.providerOperationId}', and the configured provider-access resolver `
+                + 'cannot load a provider catalogue. Wire the production resolver, or state the operation inline on the binding.');
+        }
+        const operation = await this.providerAccessResolver.resolveProviderOperation(this.binding.providerRef, declaration.providerOperationId, declaration.domain);
+        return projectProviderOperationOntoReadSurface({
+            reference: declaration, operation, providerRef: this.binding.providerRef, member,
+        });
     }
     async executeKeyAddressedRead(executionContext, resourceId) {
         let body;
@@ -400,7 +438,7 @@ export class HttpApiResourceRepositoryBackendService {
             return rows.length > 0 ? rows[0] : null;
         }
         else {
-            const spec = this.restOperationSpec('read');
+            const spec = await this.restOperationSpec('read');
             const compiled = compileRestJsonKeyAddressedRead(this.binding, spec, resourceId);
             const response = await this.readClient.restJsonReadOrNull(executionContext, compiled);
             if (response === null)
@@ -418,7 +456,7 @@ export class HttpApiResourceRepositoryBackendService {
         if (this.binding.dialect === HttpApiTransportDialect.ODOO_JSONRPC) {
             return this.expectRowArray(await this.readClient.odooExecuteKw(executionContext, compileOdooCollectionRead(this.binding, query)), "the Odoo 'search_read' result array");
         }
-        const spec = this.restOperationSpec(member === 'search' ? 'search' : 'list');
+        const spec = await this.restOperationSpec(member === 'search' ? 'search' : 'list');
         const compiled = compileRestJsonCollectionRead(this.binding, spec, query);
         const body = await this.readClient.restJson(executionContext, compiled);
         return this.expectRowArray(resolveHttpApiResultPath(body, compiled.resultPath), `the declared resultPath '${compiled.resultPath ?? '(body)'}'`);
@@ -438,7 +476,7 @@ export class HttpApiResourceRepositoryBackendService {
         // a paginated envelope needs a total, and an undeclared count operation must refuse before
         // any remote list call is spent.
         if (this.binding.dialect === HttpApiTransportDialect.REST_JSON) {
-            this.restOperationSpec('count');
+            await this.restOperationSpec('count');
         }
         const rows = await this.executeCollectionRead(executionContext, query, operation, searchMember ? 'search' : 'list');
         const total = await this.executeCountRead(executionContext, { ...query, pagination: undefined, sort: [] }, operation);
@@ -461,7 +499,7 @@ export class HttpApiResourceRepositoryBackendService {
             }
             return result;
         }
-        const spec = this.restOperationSpec('count');
+        const spec = await this.restOperationSpec('count');
         const compiled = compileRestJsonCollectionRead(this.binding, spec, { ...query, pagination: undefined });
         const body = await this.readClient.restJson(executionContext, compiled);
         const payload = resolveHttpApiResultPath(body, compiled.resultPath);
@@ -480,6 +518,14 @@ export class HttpApiResourceRepositoryBackendService {
      * never fail the read it observes. Emitted ONLY after a remote round-trip actually happened —
      * match-nothing short-circuits touch no external system and record nothing.
      *
+     * Every emission goes through {@link emitAuditObservation}, so a lost one lands on
+     * `audit_observation_dropped_total` instead of nowhere. The feature detection therefore decides an
+     * ARGUMENT rather than an early return: handing the seam `undefined` is how this site reports
+     * `SERVICE_UNAVAILABLE`, the loss shape that reaches no `_createAuditLog` and used to leave nothing
+     * behind at all. An early return would restore that silence — and the silence is expensive here,
+     * because ATTRIBUTION is the whole point of the row: without it the third party's own logs show
+     * one shared service principal and nothing anywhere resolves it back to a person.
+     *
      * Emission lives at the ADAPTER, deliberately inverting the services-tier precedent
      * (`recordPlatformDirectoryAccess`'s "the repository exists once per adapter" argument):
      * HTTP_API has exactly ONE adapter, and it is the only tier that witnesses EVERY remote access
@@ -491,27 +537,45 @@ export class HttpApiResourceRepositoryBackendService {
      * real initiating user carried through the shared service principal.
      */
     recordReadThroughAccess(executionContext, operationIdentifier, extras = {}) {
+        let emit;
         try {
             const auditLogsService = this.auditLogsResolver?.();
-            if (typeof auditLogsService?.logHttpApiReadThroughAccess !== 'function')
-                return;
-            const initiatorIds = executionContext.initiatorIds;
-            void auditLogsService.logHttpApiReadThroughAccess({
-                resourceType: String(this.resourceConfiguration.resourceIdentifier),
-                operationIdentifier: String(operationIdentifier),
-                providerRef: this.binding.providerRef,
-                remoteEntityRef: this.binding.entityRef,
-                dialect: this.binding.dialect,
-                initiatorUserId: initiatorIds?.userId,
-                executionType: executionContext.executionType,
-                organizationId: initiatorIds?.organizationId
-                    ?? executionContext.getContextResourceId?.('organizationId'),
-                ...extras,
-            }, executionContext)?.catch?.(() => undefined);
+            if (typeof auditLogsService?.logHttpApiReadThroughAccess === 'function') {
+                const initiatorIds = executionContext.initiatorIds;
+                const data = {
+                    resourceType: String(this.resourceConfiguration.resourceIdentifier),
+                    operationIdentifier: String(operationIdentifier),
+                    providerRef: this.binding.providerRef,
+                    remoteEntityRef: this.binding.entityRef,
+                    dialect: this.binding.dialect,
+                    initiatorUserId: initiatorIds?.userId,
+                    executionType: executionContext.executionType,
+                    organizationId: initiatorIds?.organizationId
+                        ?? executionContext.getContextResourceId?.('organizationId'),
+                    ...extras,
+                };
+                emit = () => auditLogsService.logHttpApiReadThroughAccess(data, executionContext);
+            }
         }
         catch {
-            // Observation only — never the reason a read fails.
+            // A thunk or a context accessor that throws leaves `emit` undefined, so the observation is
+            // reported as UNAVAILABLE rather than swallowed. The one thing this method may never do is
+            // fail the read it observes.
         }
+        emitAuditObservation({
+            observation: AuditObservationKind.HTTP_API_READ_THROUGH_ACCESS,
+            emit,
+            metricsResolver: this.metricsResolver,
+            logger: this.logger,
+            // Enough to name WHICH read went unrecorded — the resource, the operation and the remote
+            // entity are what a reviewer would reconstruct the missing attribution row from.
+            context: {
+                observedResourceType: String(this.resourceConfiguration.resourceIdentifier),
+                observedOperationIdentifier: String(operationIdentifier),
+                observedProviderRef: this.binding.providerRef,
+                observedRemoteEntityRef: this.binding.entityRef,
+            },
+        });
     }
     // ── D6 stance 6b: the declared external-erasure door ─────────────────────────
     /**
@@ -523,9 +587,16 @@ export class HttpApiResourceRepositoryBackendService {
      *
      * ## Identity-less by design
      *
-     * The internal context below is inert on this path, verified per consumer: translation runs
-     * `excludeContextualFilter` (an erasure must reach the subject's rows in EVERY tenant — the FK
-     * equality is the confinement), and `resolveAccess` ignores the context for SERVICE_PRINCIPAL.
+     * The internal context below is inert on this path for translation, verified per consumer:
+     * translation runs `excludeContextualFilter` (an erasure must reach the subject's rows in EVERY
+     * tenant — the FK equality is the confinement).
+     *
+     * It is NOT inert for access. This said `resolveAccess` "ignores the context for
+     * SERVICE_PRINCIPAL", and since #333 the context is what NAMES the owner whose account a
+     * tenant-owned or user-owned binding spends. An erasure sweep runs on an internal context, so a
+     * binding that declares anything but an application-owned connection refuses here rather than
+     * erasing under the wrong account — which is the fail-closed direction, and is why the refusal is
+     * worth meeting as an explicit error rather than a silent fallback.
      * Attribution lives in the `HTTP_API_EXTERNAL_ERASURE` audit row the calling effect emits;
      * discovery reads here deliberately do NOT emit read-through events (the read exists only to
      * address the deletion the event already records — double-recording would be noise with no
@@ -731,6 +802,7 @@ export class HttpApiResourceRepositoryBackendService {
     async atomicConditionalSet() { throw this.readOnlyRefusal('atomicConditionalSet'); }
     async atomicGuardedMutation() { throw this.readOnlyRefusal('atomicGuardedMutation'); }
     async updateManyByRawFilter() { throw this.readOnlyRefusal('updateManyByRawFilter'); }
+    async deleteManyByRawFilter() { throw this.readOnlyRefusal('deleteManyByRawFilter'); }
     async insertRawDocument() { throw this.readOnlyRefusal('insertRawDocument'); }
     async findManyByRawFilter() { throw this.readOnlyRefusal('findManyByRawFilter (raw filters are refused — T-set only, paper B R1)'); }
     async countByRawFilter() { throw this.readOnlyRefusal('countByRawFilter (raw filters are refused — T-set only, paper B R1)'); }