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

package/dist/esm/external-providers/operations/provider-operation-executor.backend.service.js

@@ -0,0 +1,333 @@
+/**
+ * `ProviderOperationExecutorBackendService` — the ONE door through which an application executes a
+ * provider-declared operation (S3a, #331; plan D4).
+ *
+ * A custom backend service names a provider and an operation; everything between that and the wire
+ * lives here: resolving the provider's runtime contract, loading its catalogue on demand and
+ * memoizing it, validating the caller's input against the operation's own schema, compiling the
+ * request, resolving identity through the shared access port, executing under the provider's rate
+ * budget and semantics, and parsing the answer.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * - **It does not resolve secrets.** `HttpApiProviderAccessResolver` does, over the provider
+ *   registry — the same port the ETL lane uses. When #329 makes that registry the COMPOSED one, a
+ *   package-shipped provider's key arrives here with no edit. A second secret path would be a
+ *   second thing to get wrong.
+ * - **It does not decide IDENTITY.** Whose account a call spends, and on whose behalf, is the
+ *   connection target the resolver is handed; a delegated target is served or refused THERE. This
+ *   read "it does not implement `USER_DELEGATED` … the resolver refuses it by name today" until
+ *   #333, which retired that mode for the two-axis `ExternalProvider_ConnectionShape` and lifted
+ *   the refusal — neither change reached this class, which is the point of asking the port.
+ * - **It does not page.** `pagination` on an operation is a hint the caller reads.
+ * - **It does not AUDIT — yet, and this is the one gap worth stating loudly.** The seam is built
+ *   and called on every outbound call (`ProviderOperationAuditResolver`, the lazily-resolved thunk
+ *   this repository uses for the same job in the HTTP-API repository), but the
+ *   `CoreAuditableEventType` member and the audit-logs method behind it belong to S3b, which the
+ *   plan's seam table requires to agree the event NAMES with S5a before either commits. So the
+ *   emission point exists and answers nothing until S3b writes the sink. That is a real hole, not
+ *   a design: an application calling a vendor on a user's behalf must leave a trail, and until
+ *   S3b lands it leaves none.
+ *
+ * ## Bound by FACTORY, not by decoration
+ *
+ * This class carried "Not `@injectable`, on purpose" and deferred registration to the slice that
+ * needed it injected. That slice arrived: an application scopes a provider from the scraped
+ * catalogue and a service of its own calls an operation, which it cannot do while the only door is a
+ * class nothing binds.
+ *
+ * It is still a plain class. `SAAS_SERVICE_TYPES.ProviderOperationExecutorService` is bound with
+ * `toDynamicValue`, so the lane's classes stay constructible with `new` — the repositories registry
+ * builds its own resolver that way — and no injection token has to be invented for
+ * `ConnectionTargetAuthorizationPort`, which nothing binds and whose absence is deliberately
+ * fail-closed.
+ *
+ * Singleton, because this memoizes a catalogue per `(providerRef, domain)` and holds one rate-limit
+ * window per provider. A transient would reload the catalogue per call and give every caller its own
+ * window, which is not a rate limit.
+ */
+import { ExternalProvider_ExchangeProtocol_Kind, ProviderProtocolRuntimeKind } from '@wildo-ai/external-connectors-models';
+import { ExternalProvider_Connection_DelegationMode, ExternalProvider_Connection_OwnerScope, } from '@wildo-ai/external-connectors-models';
+import { resolveHttpApiResultPath } from '../../base-classes/services/repositories/http-api/http-api-row-projection.backend.js';
+import { compileProviderOperationRequest, ProviderOperationRequestError, ProviderOperationRequestFailureKind } from './provider-operation-request.backend.js';
+import { DEFAULT_PROVIDER_REST_CALL_SEMANTICS, ProviderRestCallClient } from './provider-rest-call-client.backend.js';
+/** Why an operation could not be reached at all — each member names a different remedy. */
+export var ProviderOperationLookupFailureKind;
+(function (ProviderOperationLookupFailureKind) {
+    /** The provider declares no `rest` runtime contract; it may not even be a REST provider. */
+    ProviderOperationLookupFailureKind["PROVIDER_NOT_REST"] = "PROVIDER_NOT_REST";
+    /** The provider is REST but declares no operation catalogue — nothing to call. */
+    ProviderOperationLookupFailureKind["PROVIDER_DECLARES_NO_OPERATIONS"] = "PROVIDER_DECLARES_NO_OPERATIONS";
+    /** The catalogue loaded and holds no operation by that id. */
+    ProviderOperationLookupFailureKind["OPERATION_NOT_IN_CATALOGUE"] = "OPERATION_NOT_IN_CATALOGUE";
+    /** The provider's own loader threw. */
+    ProviderOperationLookupFailureKind["CATALOGUE_LOAD_FAILED"] = "CATALOGUE_LOAD_FAILED";
+})(ProviderOperationLookupFailureKind || (ProviderOperationLookupFailureKind = {}));
+export class ProviderOperationLookupError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.detail = detail;
+        this.name = 'ProviderOperationLookupError';
+    }
+}
+export class ProviderOperationExecutorBackendService {
+    externalProvidersRegistry;
+    providerAccessResolver;
+    fetchImpl;
+    auditResolver;
+    warn;
+    credentialUseRecorder;
+    /** Per `(providerRef, domain)`, exactly as the loader's contract promises. */
+    catalogueCache = new Map();
+    /** Per provider, so the rate window survives between calls. */
+    clientCache = new Map();
+    /** Deprecation is logged once per operation, never per call — a log nobody can read is not a warning. */
+    deprecationsWarned = new Set();
+    constructor(externalProvidersRegistry, providerAccessResolver, fetchImpl, auditResolver, warn = () => undefined, 
+    // APPENDED rather than slotted beside its sibling thunk: every parameter here is positional, and
+    // inserting one silently reassigns whatever a caller passed after it. Measured — putting it
+    // before `warn` handed the deprecation test's spy to this slot, so the warning was recorded by
+    // nobody and a pin about vendor deprecation failed for a reason that had nothing to do with it.
+    credentialUseRecorder) {
+        this.externalProvidersRegistry = externalProvidersRegistry;
+        this.providerAccessResolver = providerAccessResolver;
+        this.fetchImpl = fetchImpl;
+        this.auditResolver = auditResolver;
+        this.warn = warn;
+        this.credentialUseRecorder = credentialUseRecorder;
+    }
+    /**
+     * The provider's `rest` runtime contract, refusing by NAME when there is none: every branch here
+     * is an authoring or configuration gap someone must fix, never a transient.
+     */
+    restContractOf(providerRef) {
+        const runtimeContract = this.externalProvidersRegistry.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API);
+        if (!runtimeContract || runtimeContract.kind !== ProviderProtocolRuntimeKind.REST) {
+            throw new ProviderOperationLookupError(`Provider '${providerRef}' declares no REST runtime contract `
+                + `(found: ${runtimeContract ? `kind '${String(runtimeContract.kind)}'` : 'none'}), so it has no operations to execute.`, { kind: ProviderOperationLookupFailureKind.PROVIDER_NOT_REST, providerRef });
+        }
+        return runtimeContract;
+    }
+    /**
+     * Load a catalogue once per `(providerRef, domain)`.
+     *
+     * The PROMISE is cached rather than its value, so two concurrent calls for the same pair share
+     * one load instead of racing two — and a failed load is EVICTED, because caching a rejection
+     * would make one bad moment permanent for the process's whole life.
+     */
+    async loadCatalogue(providerRef, domain) {
+        const cacheKey = `${providerRef}::${domain ?? '*'}`;
+        const cached = this.catalogueCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const contract = this.restContractOf(providerRef);
+        if (!contract.operations) {
+            throw new ProviderOperationLookupError(`Provider '${providerRef}' declares a REST contract but no operation catalogue — `
+                + 'add `operations` to its rest runtime contract, or call it through an ETL httpApiBinding instead.', { kind: ProviderOperationLookupFailureKind.PROVIDER_DECLARES_NO_OPERATIONS, providerRef });
+        }
+        const loadFailure = (cause) => new ProviderOperationLookupError(`Provider '${providerRef}' failed to load its operation catalogue${domain ? ` for domain '${domain}'` : ''}: `
+            + `${cause instanceof Error ? cause.message : String(cause)}`, { kind: ProviderOperationLookupFailureKind.CATALOGUE_LOAD_FAILED, providerRef, cause });
+        let invoked;
+        try {
+            // A loader is the provider PACKAGE's own code, and its whole job is to `import()` or
+            // `require()` an operation module lazily. That throws SYNCHRONOUSLY when the module is
+            // absent or fails to evaluate — a missing dependency, a bad barrel — and a synchronous
+            // throw never reaches `.catch`. Without this the two ways one loader can fail refuse
+            // differently: a rejection is named `CATALOGUE_LOAD_FAILED` and a throw escapes as the raw
+            // `Error`, past the vocabulary that exists so an operator can act on the sentence.
+            // Nothing is cached yet on this path, so there is nothing to evict.
+            invoked = Promise.resolve(contract.operations(domain));
+        }
+        catch (cause) {
+            throw loadFailure(cause);
+        }
+        const loading = invoked.catch((cause) => {
+            this.catalogueCache.delete(cacheKey);
+            throw loadFailure(cause);
+        });
+        this.catalogueCache.set(cacheKey, loading);
+        return loading;
+    }
+    /** One operation, by id. */
+    async resolveOperation(providerRef, operationId, domain) {
+        const catalogue = await this.loadCatalogue(providerRef, domain);
+        const operation = catalogue.operations[operationId];
+        if (!operation) {
+            const known = Object.keys(catalogue.operations);
+            throw new ProviderOperationLookupError(`Provider '${providerRef}' declares no operation '${operationId}'`
+                + `${domain ? ` in domain '${domain}'` : ''}. Declared${known.length > 20 ? ` (first 20 of ${known.length})` : ''}: `
+                + `${known.slice(0, 20).join(', ') || '(none)'}.`, { kind: ProviderOperationLookupFailureKind.OPERATION_NOT_IN_CATALOGUE, providerRef, operationId });
+        }
+        return operation;
+    }
+    clientFor(providerRef) {
+        const cached = this.clientCache.get(providerRef);
+        if (cached)
+            return cached;
+        const contract = this.restContractOf(providerRef);
+        const semantics = contract.remoteCallSemantics ?? DEFAULT_PROVIDER_REST_CALL_SEMANTICS;
+        const client = new ProviderRestCallClient(providerRef, semantics, this.providerAccessResolver, this.fetchImpl);
+        this.clientCache.set(providerRef, client);
+        return client;
+    }
+    /** Execute one declared operation end to end. */
+    /**
+     * Adapt this executor to what a GENERATED TYPED CLIENT takes.
+     *
+     * `createSlackClient(execute)` wants `(providerRef, operationId, input) => Promise<unknown>` — no
+     * execution context and no connection target, because the generated package must carry no runtime
+     * dependency on the engine and cannot name either type. Those two are exactly what a call needs and
+     * what only the caller knows, so they are bound HERE, once, by the service that has them:
+     *
+     * ```ts
+     * const slack = createSlackClient(this.providerOperations.forExecution(executionContext));
+     * await slack.slackPostMessage({ channel: 'C123', text: 'Deal closed' });
+     * ```
+     *
+     * The `connection` default is the floor — the application's own account, acting as itself —
+     * matching {@link execute}. A caller spending a tenant's account passes the target explicitly, and
+     * the context still decides whether the execution may act for that owner.
+     *
+     * Returns `output` rather than the whole envelope, because that is what the typed client's
+     * `Promise<unknown>` promises. A caller who needs the status or the raw body calls {@link execute}
+     * directly — the adapter is ergonomics, never a narrower door.
+     */
+    forExecution(executionContext, defaults) {
+        // The per-CALL connection wins over the client's default, and that precedence is the whole
+        // reason the parameter exists. A default binds one client to one owner, which is right for the
+        // ordinary case and cannot express the one that forced the design: a single user action pushing
+        // to every organization that user belongs to issues N calls through ONE client and names a
+        // different owner each time. Reading only the default would make that unreachable through the
+        // generated surface while the engine underneath supports it.
+        return async (providerRef, operationId, input, connection) => {
+            const result = await this.execute({ providerRef, operationId, input, connection: connection ?? defaults?.connection, domain: defaults?.domain }, executionContext);
+            return result.output;
+        };
+    }
+    async execute(call, executionContext) {
+        const target = call.connection ?? {
+            ownerScope: ExternalProvider_Connection_OwnerScope.APPLICATION,
+            delegation: ExternalProvider_Connection_DelegationMode.SERVICE,
+        };
+        const operation = await this.resolveOperation(call.providerRef, call.operationId, call.domain);
+        if (operation.deprecated && !this.deprecationsWarned.has(`${call.providerRef}::${operation.operationId}`)) {
+            this.deprecationsWarned.add(`${call.providerRef}::${operation.operationId}`);
+            // Warn, never refuse: the vendor decides when a deprecated operation stops answering, and a
+            // framework that refused first would break a working application ahead of the vendor.
+            this.warn(`Provider operation '${call.providerRef}.${operation.operationId}' is deprecated`
+                + `${operation.deprecated.since ? ` since ${operation.deprecated.since}` : ''}: ${operation.deprecated.reason}`
+                + `${operation.deprecated.replacedByOperationId ? ` — use '${operation.deprecated.replacedByOperationId}'.` : '.'}`);
+        }
+        const rawInput = call.input ?? {};
+        let input = rawInput;
+        if (operation.inputSchema) {
+            const parsed = operation.inputSchema.safeParse(rawInput);
+            if (!parsed.success) {
+                throw new ProviderOperationRequestError(`Input rejected for '${call.providerRef}.${operation.operationId}': `
+                    + parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'} ${issue.message}`).join('; '), { kind: ProviderOperationRequestFailureKind.INPUT_REJECTED, operationId: operation.operationId, providerRef: call.providerRef });
+            }
+            input = parsed.data;
+        }
+        const client = this.clientFor(call.providerRef);
+        const access = await client.resolveAccess(target, executionContext);
+        const request = compileProviderOperationRequest({ operation, providerRef: call.providerRef, input, access });
+        try {
+            // `access` is handed on so the client can SIGN, which only it can do last. Resolving it twice
+            // would be a second read of the same secrets and, for a signed provider, a second timestamp.
+            const response = await client.execute(request, operation.remoteCallSemantics, access);
+            this.record(call.providerRef, operation, target, executionContext, { status: response.status });
+            // A 2xx is the provider ACCEPTING the credential. Recording it is what moves a stored row off
+            // UNVALIDATED — which is otherwise where every working credential stays forever, so an operator
+            // reading the settings screen cannot tell a healthy integration from one that has never run.
+            this.recordCredentialOutcome(call.providerRef, target, access, { accepted: response.status < 400 });
+            const payload = operation.resultPath ? resolveHttpApiResultPath(response.json, operation.resultPath) : response.json;
+            if (!operation.outputSchema) {
+                return { status: response.status, output: payload, rawBody: response.json, operation };
+            }
+            const parsed = operation.outputSchema.safeParse(payload);
+            if (!parsed.success) {
+                // A vendor answering a shape the declaration does not describe is a CONTRACT problem, and
+                // the honest place to learn it is here rather than three frames into the caller.
+                throw new ProviderOperationRequestError(`Provider '${call.providerRef}' answered '${operation.operationId}' with a body its declared outputSchema rejects: `
+                    + parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'} ${issue.message}`).join('; '), { kind: ProviderOperationRequestFailureKind.DECLARATION_INCOHERENT, operationId: operation.operationId, providerRef: call.providerRef });
+            }
+            return { status: response.status, output: parsed.data, rawBody: response.json, operation };
+        }
+        catch (error) {
+            const detail = error.detail;
+            this.record(call.providerRef, operation, target, executionContext, {
+                status: detail?.status,
+                failureKind: detail?.kind ?? (error instanceof Error ? error.name : 'UNKNOWN'),
+            });
+            throw error;
+        }
+    }
+    /**
+     * Record one outbound call. Fire-and-forget and feature-detected, per the house pattern: a
+     * partial audit binding or a store failure must never fail the call it observes.
+     *
+     * Called on BOTH the success and the failure path deliberately — a refused or failed outbound
+     * call is exactly what a reviewer wants to see, and a trail that records only what worked is a
+     * trail that hides the attempts.
+     */
+    /**
+     * Stamp the stored credential with what the provider said. Best-effort, and after the call.
+     *
+     * Fire-and-forget for the same reason the audit emit is: the outbound call has already happened, so
+     * failing the caller because a bookkeeping write did not land would turn a successful integration
+     * into an error. Nothing downstream reads the result, and the store logs its own failures with the
+     * row named.
+     *
+     * Only a tenant's OWN credential has a row. An APPLICATION-owned resolution carries no provenance
+     * and is skipped here rather than filtered later, so the deployment environment can never acquire a
+     * row describing a credential the tenant never set.
+     */
+    recordCredentialOutcome(providerRef, target, access, outcome) {
+        const provenance = access.credentialProvenance;
+        if (!provenance || target.ownerId === undefined)
+            return;
+        try {
+            const store = this.credentialUseRecorder?.();
+            if (typeof store?.recordCredentialUse !== 'function')
+                return;
+            void store.recordCredentialUse({
+                organizationId: target.ownerId,
+                providerRef,
+                secretSlug: provenance.secretSlug,
+                source: provenance.source,
+                credentialId: provenance.credentialId,
+                outcome,
+            }).catch(() => undefined);
+        }
+        catch {
+            // A recorder that throws on resolution must not take the call down with it.
+        }
+    }
+    record(providerRef, operation, target, executionContext, outcome) {
+        try {
+            const auditLogsService = this.auditResolver?.();
+            if (typeof auditLogsService?.logProviderOperationCall !== 'function')
+                return;
+            const initiatorIds = executionContext.initiatorIds;
+            void auditLogsService.logProviderOperationCall({
+                providerRef,
+                operationId: operation.operationId,
+                domain: operation.domain,
+                method: operation.method,
+                classification: operation.classification,
+                connectionOwnerScope: target.ownerScope,
+                ...(target.ownerId === undefined ? {} : { connectionOwnerId: target.ownerId }),
+                connectionDelegation: target.delegation,
+                initiatorUserId: initiatorIds?.userId,
+                organizationId: initiatorIds?.organizationId,
+                executionType: executionContext.executionType,
+                ...outcome,
+            }, executionContext)?.catch?.(() => undefined);
+        }
+        catch {
+            // Observation only — never the reason a call fails.
+        }
+    }
+}
+//# sourceMappingURL=provider-operation-executor.backend.service.js.map

package/dist/esm/external-providers/operations/provider-operation-executor.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-operation-executor.backend.service.js","sourceRoot":"","sources":["../../../../../src/external-providers/operations/provider-operation-executor.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `ProviderOperationExecutorBackendService` — the ONE door through which an application executes a\n * provider-declared operation (S3a, #331; plan D4).\n *\n * A custom backend service names a provider and an operation; everything between that and the wire\n * lives here: resolving the provider's runtime contract, loading its catalogue on demand and\n * memoizing it, validating the caller's input against the operation's own schema, compiling the\n * request, resolving identity through the shared access port, executing under the provider's rate\n * budget and semantics, and parsing the answer.\n *\n * ## What it deliberately does NOT do\n *\n * - **It does not resolve secrets.** `HttpApiProviderAccessResolver` does, over the provider\n *   registry — the same port the ETL lane uses. When #329 makes that registry the COMPOSED one, a\n *   package-shipped provider's key arrives here with no edit. A second secret path would be a\n *   second thing to get wrong.\n * - **It does not decide IDENTITY.** Whose account a call spends, and on whose behalf, is the\n *   connection target the resolver is handed; a delegated target is served or refused THERE. This\n *   read \"it does not implement `USER_DELEGATED` … the resolver refuses it by name today\" until\n *   #333, which retired that mode for the two-axis `ExternalProvider_ConnectionShape` and lifted\n *   the refusal — neither change reached this class, which is the point of asking the port.\n * - **It does not page.** `pagination` on an operation is a hint the caller reads.\n * - **It does not AUDIT — yet, and this is the one gap worth stating loudly.** The seam is built\n *   and called on every outbound call (`ProviderOperationAuditResolver`, the lazily-resolved thunk\n *   this repository uses for the same job in the HTTP-API repository), but the\n *   `CoreAuditableEventType` member and the audit-logs method behind it belong to S3b, which the\n *   plan's seam table requires to agree the event NAMES with S5a before either commits. So the\n *   emission point exists and answers nothing until S3b writes the sink. That is a real hole, not\n *   a design: an application calling a vendor on a user's behalf must leave a trail, and until\n *   S3b lands it leaves none.\n *\n * ## Bound by FACTORY, not by decoration\n *\n * This class carried \"Not `@injectable`, on purpose\" and deferred registration to the slice that\n * needed it injected. That slice arrived: an application scopes a provider from the scraped\n * catalogue and a service of its own calls an operation, which it cannot do while the only door is a\n * class nothing binds.\n *\n * It is still a plain class. `SAAS_SERVICE_TYPES.ProviderOperationExecutorService` is bound with\n * `toDynamicValue`, so the lane's classes stay constructible with `new` — the repositories registry\n * builds its own resolver that way — and no injection token has to be invented for\n * `ConnectionTargetAuthorizationPort`, which nothing binds and whose absence is deliberately\n * fail-closed.\n *\n * Singleton, because this memoizes a catalogue per `(providerRef, domain)` and holds one rate-limit\n * window per provider. A transient would reload the catalogue per call and give every caller its own\n * window, which is not a rate limit.\n */\n\nimport { ExternalProvider_ExchangeProtocol_Kind, ProviderProtocolRuntimeKind } from '@wildo-ai/external-connectors-models';\nimport {\n  ExternalProvider_Connection_DelegationMode,\n  ExternalProvider_Connection_OwnerScope,\n} from '@wildo-ai/external-connectors-models';\nimport type { ExternalProvider_ConnectionTarget } from '@wildo-ai/external-connectors-models';\nimport type { ProviderOperationExecute, ProviderRestCallSemantics, ProviderRestOperation, ProviderRestOperationCatalogue } from '@wildo-ai/external-connectors-models';\n\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport type { HttpApiFetchLike } from '~wildo-backend-lib/base-classes/services/repositories/http-api/http-api-transport.backend';\nimport type { HttpApiProviderAccessResolver } from '~wildo-backend-lib/base-classes/services/repositories/http-api/http-api-provider-access.backend';\nimport { resolveHttpApiResultPath } from '~wildo-backend-lib/base-classes/services/repositories/http-api/http-api-row-projection.backend';\nimport type { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';\n\nimport { compileProviderOperationRequest, ProviderOperationRequestError, ProviderOperationRequestFailureKind } from './provider-operation-request.backend';\nimport { DEFAULT_PROVIDER_REST_CALL_SEMANTICS, ProviderRestCallClient } from './provider-rest-call-client.backend';\n\n/** Why an operation could not be reached at all — each member names a different remedy. */\nexport enum ProviderOperationLookupFailureKind {\n  /** The provider declares no `rest` runtime contract; it may not even be a REST provider. */\n  PROVIDER_NOT_REST = 'PROVIDER_NOT_REST',\n  /** The provider is REST but declares no operation catalogue — nothing to call. */\n  PROVIDER_DECLARES_NO_OPERATIONS = 'PROVIDER_DECLARES_NO_OPERATIONS',\n  /** The catalogue loaded and holds no operation by that id. */\n  OPERATION_NOT_IN_CATALOGUE = 'OPERATION_NOT_IN_CATALOGUE',\n  /** The provider's own loader threw. */\n  CATALOGUE_LOAD_FAILED = 'CATALOGUE_LOAD_FAILED',\n}\n\nexport class ProviderOperationLookupError extends Error {\n  constructor(\n    message: string,\n    public readonly detail: {\n      readonly kind: ProviderOperationLookupFailureKind;\n      readonly providerRef: string;\n      readonly operationId?: string;\n      readonly cause?: unknown;\n    },\n  ) {\n    super(message);\n    this.name = 'ProviderOperationLookupError';\n  }\n}\n\n/**\n * The audit seam — structural and lazily resolved, the pattern this repository already uses for\n * the HTTP-API read-through trail. The executor never holds the audit service, only a thunk; an\n * absent binding means no emission, and an emission failure never fails the call it observes.\n *\n * TODO(assurance-control): WILDO.AUDIT.ATTRIBUTION — an outbound provider call made on a user's\n * behalf must be recorded with the real initiating user. The sink behind this thunk is S3b's, and\n * the `CoreAuditableEventType` member it writes must be agreed with S5a first (plan seam table).\n */\n/**\n * The credential store, reached the way the audit sink is — through a thunk, so this class takes no\n * dependency on `security/connected-accounts` and a unit harness needs neither.\n *\n * Optional in both directions: a host that binds no store records nothing, and an APPLICATION-owned\n * call has no row to stamp.\n */\nexport type ProviderCredentialUseRecorder = () => {\n  recordCredentialUse?: (use: {\n    organizationId: string;\n    providerRef: string;\n    secretSlug: string;\n    source: string;\n    credentialId?: string;\n    outcome?: { accepted: boolean; providerMessage?: string };\n  }) => Promise<void>;\n} | undefined;\n\nexport type ProviderOperationAuditResolver = () => {\n  logProviderOperationCall?: (\n    data: ProviderOperationAuditRecord,\n    requestExecutionContext?: ExecutionContext<any>,\n  ) => Promise<void>;\n} | undefined;\n\n/**\n * What one outbound provider call is worth recording. Ids and shape only, never a payload.\n *\n * assurance-control: WILDO.ACCESS.AUTHORIZATION_DECISION_AUDIT — records WHOSE third-party account an\n * outbound call spent, which the initiator's own ids cannot answer once one execution may spend\n * several.\n */\nexport interface ProviderOperationAuditRecord {\n  providerRef: string;\n  operationId: string;\n  domain: string;\n  method: string;\n  /** READ or WRITE, as the operation declares it — the axis a reviewer filters on first. */\n  classification: string;\n  /**\n   * WHOSE ACCOUNT the call spent — the first question of any provider incident, and one the\n   * initiator's own ids cannot answer.\n   *\n   * Distinct from `organizationId` below, which records the tenant the REQUEST was scoped to. Those\n   * are the same tenant in the ordinary case and different ones exactly where it matters: a user\n   * action fanning out to every organization that user belongs to spends N accounts under one\n   * initiating scope. A trail carrying only the initiator's organization would attribute every one\n   * of those calls to the wrong tenant.\n   */\n  connectionOwnerScope: string;\n  connectionOwnerId?: string;\n  connectionDelegation: string;\n  /** HTTP status of the answer; absent when the call never got one. */\n  status?: number;\n  /** Present when the call failed, naming the failure kind rather than the vendor's prose. */\n  failureKind?: string;\n  initiatorUserId?: string;\n  organizationId?: string;\n  executionType?: string;\n}\n\nexport interface ProviderOperationCallInput {\n  providerRef: string;\n  operationId: string;\n  /**\n   * The catalogue DOMAIN the operation belongs to, when the caller knows it. Passing it lets the\n   * provider's loader answer one domain instead of every one — the whole point of the lazy loader\n   * — and is what keeps a vendor with hundreds of operations from evaluating them all to run one.\n   * Absent, the whole catalogue is loaded once and memoized.\n   */\n  domain?: string;\n  input?: Readonly<Record<string, unknown>>;\n  /**\n   * WHOSE ACCOUNT this call spends. Defaults to the floor — the application's own, acting as itself.\n   *\n   * On the CALL rather than on the provider or the execution context, because one execution may\n   * legitimately spend several tenants' accounts: a single user action pushing a message to every\n   * organization that user belongs to issues N calls with N targets and one initiator. The context\n   * still decides whether the execution MAY act for each named owner.\n   */\n  connection?: ExternalProvider_ConnectionTarget;\n}\n\nexport interface ProviderOperationCallResult<TOutput = unknown> {\n  status: number;\n  /** The payload at the operation's `resultPath`, parsed through `outputSchema` when declared. */\n  output: TOutput;\n  /** The whole parsed body, before `resultPath` and before validation. */\n  rawBody: unknown;\n  operation: ProviderRestOperation;\n}\n\nexport class ProviderOperationExecutorBackendService {\n  /** Per `(providerRef, domain)`, exactly as the loader's contract promises. */\n  private readonly catalogueCache = new Map<string, Promise<ProviderRestOperationCatalogue>>();\n  /** Per provider, so the rate window survives between calls. */\n  private readonly clientCache = new Map<string, ProviderRestCallClient>();\n  /** Deprecation is logged once per operation, never per call — a log nobody can read is not a warning. */\n  private readonly deprecationsWarned = new Set<string>();\n\n  constructor(\n    private readonly externalProvidersRegistry: ExternalProvidersRegistryBackendService,\n    private readonly providerAccessResolver: HttpApiProviderAccessResolver,\n    private readonly fetchImpl?: HttpApiFetchLike,\n    private readonly auditResolver?: ProviderOperationAuditResolver,\n    private readonly warn: (message: string) => void = () => undefined,\n    // APPENDED rather than slotted beside its sibling thunk: every parameter here is positional, and\n    // inserting one silently reassigns whatever a caller passed after it. Measured — putting it\n    // before `warn` handed the deprecation test's spy to this slot, so the warning was recorded by\n    // nobody and a pin about vendor deprecation failed for a reason that had nothing to do with it.\n    private readonly credentialUseRecorder?: ProviderCredentialUseRecorder,\n  ) {}\n\n  /**\n   * The provider's `rest` runtime contract, refusing by NAME when there is none: every branch here\n   * is an authoring or configuration gap someone must fix, never a transient.\n   */\n  private restContractOf(providerRef: string) {\n    const runtimeContract = this.externalProvidersRegistry.getProviderRuntimeContract(\n      providerRef,\n      ExternalProvider_ExchangeProtocol_Kind.REST_API,\n    );\n    if (!runtimeContract || runtimeContract.kind !== ProviderProtocolRuntimeKind.REST) {\n      throw new ProviderOperationLookupError(\n        `Provider '${providerRef}' declares no REST runtime contract `\n        + `(found: ${runtimeContract ? `kind '${String(runtimeContract.kind)}'` : 'none'}), so it has no operations to execute.`,\n        { kind: ProviderOperationLookupFailureKind.PROVIDER_NOT_REST, providerRef },\n      );\n    }\n    return runtimeContract;\n  }\n\n  /**\n   * Load a catalogue once per `(providerRef, domain)`.\n   *\n   * The PROMISE is cached rather than its value, so two concurrent calls for the same pair share\n   * one load instead of racing two — and a failed load is EVICTED, because caching a rejection\n   * would make one bad moment permanent for the process's whole life.\n   */\n  public async loadCatalogue(providerRef: string, domain?: string): Promise<ProviderRestOperationCatalogue> {\n    const cacheKey = `${providerRef}::${domain ?? '*'}`;\n    const cached = this.catalogueCache.get(cacheKey);\n    if (cached) return cached;\n\n    const contract = this.restContractOf(providerRef);\n    if (!contract.operations) {\n      throw new ProviderOperationLookupError(\n        `Provider '${providerRef}' declares a REST contract but no operation catalogue — `\n        + 'add `operations` to its rest runtime contract, or call it through an ETL httpApiBinding instead.',\n        { kind: ProviderOperationLookupFailureKind.PROVIDER_DECLARES_NO_OPERATIONS, providerRef },\n      );\n    }\n\n    const loadFailure = (cause: unknown) => new ProviderOperationLookupError(\n      `Provider '${providerRef}' failed to load its operation catalogue${domain ? ` for domain '${domain}'` : ''}: `\n      + `${cause instanceof Error ? cause.message : String(cause)}`,\n      { kind: ProviderOperationLookupFailureKind.CATALOGUE_LOAD_FAILED, providerRef, cause },\n    );\n\n    let invoked: Promise<ProviderRestOperationCatalogue>;\n    try {\n      // A loader is the provider PACKAGE's own code, and its whole job is to `import()` or\n      // `require()` an operation module lazily. That throws SYNCHRONOUSLY when the module is\n      // absent or fails to evaluate — a missing dependency, a bad barrel — and a synchronous\n      // throw never reaches `.catch`. Without this the two ways one loader can fail refuse\n      // differently: a rejection is named `CATALOGUE_LOAD_FAILED` and a throw escapes as the raw\n      // `Error`, past the vocabulary that exists so an operator can act on the sentence.\n      // Nothing is cached yet on this path, so there is nothing to evict.\n      invoked = Promise.resolve(contract.operations(domain));\n    } catch (cause) {\n      throw loadFailure(cause);\n    }\n\n    const loading = invoked.catch((cause: unknown) => {\n      this.catalogueCache.delete(cacheKey);\n      throw loadFailure(cause);\n    });\n    this.catalogueCache.set(cacheKey, loading);\n    return loading;\n  }\n\n  /** One operation, by id. */\n  public async resolveOperation(providerRef: string, operationId: string, domain?: string): Promise<ProviderRestOperation> {\n    const catalogue = await this.loadCatalogue(providerRef, domain);\n    const operation = catalogue.operations[operationId];\n    if (!operation) {\n      const known = Object.keys(catalogue.operations);\n      throw new ProviderOperationLookupError(\n        `Provider '${providerRef}' declares no operation '${operationId}'`\n        + `${domain ? ` in domain '${domain}'` : ''}. Declared${known.length > 20 ? ` (first 20 of ${known.length})` : ''}: `\n        + `${known.slice(0, 20).join(', ') || '(none)'}.`,\n        { kind: ProviderOperationLookupFailureKind.OPERATION_NOT_IN_CATALOGUE, providerRef, operationId },\n      );\n    }\n    return operation;\n  }\n\n  private clientFor(providerRef: string): ProviderRestCallClient {\n    const cached = this.clientCache.get(providerRef);\n    if (cached) return cached;\n    const contract = this.restContractOf(providerRef);\n    const semantics: ProviderRestCallSemantics = contract.remoteCallSemantics ?? DEFAULT_PROVIDER_REST_CALL_SEMANTICS;\n    const client = new ProviderRestCallClient(providerRef, semantics, this.providerAccessResolver, this.fetchImpl);\n    this.clientCache.set(providerRef, client);\n    return client;\n  }\n\n  /** Execute one declared operation end to end. */\n  /**\n   * Adapt this executor to what a GENERATED TYPED CLIENT takes.\n   *\n   * `createSlackClient(execute)` wants `(providerRef, operationId, input) => Promise<unknown>` — no\n   * execution context and no connection target, because the generated package must carry no runtime\n   * dependency on the engine and cannot name either type. Those two are exactly what a call needs and\n   * what only the caller knows, so they are bound HERE, once, by the service that has them:\n   *\n   * ```ts\n   * const slack = createSlackClient(this.providerOperations.forExecution(executionContext));\n   * await slack.slackPostMessage({ channel: 'C123', text: 'Deal closed' });\n   * ```\n   *\n   * The `connection` default is the floor — the application's own account, acting as itself —\n   * matching {@link execute}. A caller spending a tenant's account passes the target explicitly, and\n   * the context still decides whether the execution may act for that owner.\n   *\n   * Returns `output` rather than the whole envelope, because that is what the typed client's\n   * `Promise<unknown>` promises. A caller who needs the status or the raw body calls {@link execute}\n   * directly — the adapter is ergonomics, never a narrower door.\n   */\n  public forExecution(\n    executionContext: ExecutionContext<any>,\n    defaults?: { readonly connection?: ExternalProvider_ConnectionTarget; readonly domain?: string },\n  ): ProviderOperationExecute {\n    // The per-CALL connection wins over the client's default, and that precedence is the whole\n    // reason the parameter exists. A default binds one client to one owner, which is right for the\n    // ordinary case and cannot express the one that forced the design: a single user action pushing\n    // to every organization that user belongs to issues N calls through ONE client and names a\n    // different owner each time. Reading only the default would make that unreachable through the\n    // generated surface while the engine underneath supports it.\n    return async (providerRef, operationId, input, connection) => {\n      const result = await this.execute(\n        { providerRef, operationId, input, connection: connection ?? defaults?.connection, domain: defaults?.domain },\n        executionContext,\n      );\n      return result.output;\n    };\n  }\n\n  public async execute<TOutput = unknown>(\n    call: ProviderOperationCallInput,\n    executionContext: ExecutionContext<any>,\n  ): Promise<ProviderOperationCallResult<TOutput>> {\n    const target: ExternalProvider_ConnectionTarget = call.connection ?? {\n      ownerScope: ExternalProvider_Connection_OwnerScope.APPLICATION,\n      delegation: ExternalProvider_Connection_DelegationMode.SERVICE,\n    };\n    const operation = await this.resolveOperation(call.providerRef, call.operationId, call.domain);\n\n    if (operation.deprecated && !this.deprecationsWarned.has(`${call.providerRef}::${operation.operationId}`)) {\n      this.deprecationsWarned.add(`${call.providerRef}::${operation.operationId}`);\n      // Warn, never refuse: the vendor decides when a deprecated operation stops answering, and a\n      // framework that refused first would break a working application ahead of the vendor.\n      this.warn(\n        `Provider operation '${call.providerRef}.${operation.operationId}' is deprecated`\n        + `${operation.deprecated.since ? ` since ${operation.deprecated.since}` : ''}: ${operation.deprecated.reason}`\n        + `${operation.deprecated.replacedByOperationId ? ` — use '${operation.deprecated.replacedByOperationId}'.` : '.'}`,\n      );\n    }\n\n    const rawInput = call.input ?? {};\n    let input: Readonly<Record<string, unknown>> = rawInput;\n    if (operation.inputSchema) {\n      const parsed = operation.inputSchema.safeParse(rawInput);\n      if (!parsed.success) {\n        throw new ProviderOperationRequestError(\n          `Input rejected for '${call.providerRef}.${operation.operationId}': `\n          + parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'} ${issue.message}`).join('; '),\n          { kind: ProviderOperationRequestFailureKind.INPUT_REJECTED, operationId: operation.operationId, providerRef: call.providerRef },\n        );\n      }\n      input = parsed.data as Record<string, unknown>;\n    }\n\n    const client = this.clientFor(call.providerRef);\n    const access = await client.resolveAccess(target, executionContext);\n    const request = compileProviderOperationRequest({ operation, providerRef: call.providerRef, input, access });\n\n    try {\n      // `access` is handed on so the client can SIGN, which only it can do last. Resolving it twice\n      // would be a second read of the same secrets and, for a signed provider, a second timestamp.\n      const response = await client.execute(request, operation.remoteCallSemantics, access);\n      this.record(call.providerRef, operation, target, executionContext, { status: response.status });\n      // A 2xx is the provider ACCEPTING the credential. Recording it is what moves a stored row off\n      // UNVALIDATED — which is otherwise where every working credential stays forever, so an operator\n      // reading the settings screen cannot tell a healthy integration from one that has never run.\n      this.recordCredentialOutcome(call.providerRef, target, access, { accepted: response.status < 400 });\n\n      const payload = operation.resultPath ? resolveHttpApiResultPath(response.json, operation.resultPath) : response.json;\n      if (!operation.outputSchema) {\n        return { status: response.status, output: payload as TOutput, rawBody: response.json, operation };\n      }\n      const parsed = operation.outputSchema.safeParse(payload);\n      if (!parsed.success) {\n        // A vendor answering a shape the declaration does not describe is a CONTRACT problem, and\n        // the honest place to learn it is here rather than three frames into the caller.\n        throw new ProviderOperationRequestError(\n          `Provider '${call.providerRef}' answered '${operation.operationId}' with a body its declared outputSchema rejects: `\n          + parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'} ${issue.message}`).join('; '),\n          { kind: ProviderOperationRequestFailureKind.DECLARATION_INCOHERENT, operationId: operation.operationId, providerRef: call.providerRef },\n        );\n      }\n      return { status: response.status, output: parsed.data as TOutput, rawBody: response.json, operation };\n    } catch (error) {\n      const detail = (error as { detail?: { status?: number; kind?: string } }).detail;\n      this.record(call.providerRef, operation, target, executionContext, {\n        status: detail?.status,\n        failureKind: detail?.kind ?? (error instanceof Error ? error.name : 'UNKNOWN'),\n      });\n      throw error;\n    }\n  }\n\n  /**\n   * Record one outbound call. Fire-and-forget and feature-detected, per the house pattern: a\n   * partial audit binding or a store failure must never fail the call it observes.\n   *\n   * Called on BOTH the success and the failure path deliberately — a refused or failed outbound\n   * call is exactly what a reviewer wants to see, and a trail that records only what worked is a\n   * trail that hides the attempts.\n   */\n  /**\n   * Stamp the stored credential with what the provider said. Best-effort, and after the call.\n   *\n   * Fire-and-forget for the same reason the audit emit is: the outbound call has already happened, so\n   * failing the caller because a bookkeeping write did not land would turn a successful integration\n   * into an error. Nothing downstream reads the result, and the store logs its own failures with the\n   * row named.\n   *\n   * Only a tenant's OWN credential has a row. An APPLICATION-owned resolution carries no provenance\n   * and is skipped here rather than filtered later, so the deployment environment can never acquire a\n   * row describing a credential the tenant never set.\n   */\n  private recordCredentialOutcome(\n    providerRef: string,\n    target: ExternalProvider_ConnectionTarget,\n    access: { credentialProvenance?: { source: string; credentialId?: string; secretSlug: string } },\n    outcome: { accepted: boolean; providerMessage?: string },\n  ): void {\n    const provenance = access.credentialProvenance;\n    if (!provenance || target.ownerId === undefined) return;\n    try {\n      const store = this.credentialUseRecorder?.();\n      if (typeof store?.recordCredentialUse !== 'function') return;\n      void store.recordCredentialUse({\n        organizationId: target.ownerId,\n        providerRef,\n        secretSlug: provenance.secretSlug,\n        source: provenance.source,\n        credentialId: provenance.credentialId,\n        outcome,\n      }).catch(() => undefined);\n    } catch {\n      // A recorder that throws on resolution must not take the call down with it.\n    }\n  }\n\n  private record(\n    providerRef: string,\n    operation: ProviderRestOperation,\n    target: ExternalProvider_ConnectionTarget,\n    executionContext: ExecutionContext<any>,\n    outcome: { status?: number; failureKind?: string },\n  ): void {\n    try {\n      const auditLogsService = this.auditResolver?.();\n      if (typeof auditLogsService?.logProviderOperationCall !== 'function') return;\n      const initiatorIds = (executionContext as { initiatorIds?: { userId?: string; organizationId?: string } }).initiatorIds;\n      void auditLogsService.logProviderOperationCall({\n        providerRef,\n        operationId: operation.operationId,\n        domain: operation.domain,\n        method: operation.method,\n        classification: operation.classification,\n        connectionOwnerScope: target.ownerScope,\n        ...(target.ownerId === undefined ? {} : { connectionOwnerId: target.ownerId }),\n        connectionDelegation: target.delegation,\n        initiatorUserId: initiatorIds?.userId,\n        organizationId: initiatorIds?.organizationId,\n        executionType: (executionContext as { executionType?: string }).executionType,\n        ...outcome,\n      }, executionContext)?.catch?.(() => undefined);\n    } catch {\n      // Observation only — never the reason a call fails.\n    }\n  }\n}\n"]}

package/dist/esm/external-providers/operations/provider-operation-request.backend.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Compiling a declared provider operation + a caller's input into ONE transport request (S3a,
+ * #331).
+ *
+ * Deliberately a pure function over data, with no registry, no secrets and no I/O: an operation
+ * declaration and an input go in, an {@link HttpApiTransportRequest} comes out. That is what makes
+ * the interesting half — which input field lands in the path, which in the query, which in the
+ * body, and whether the call may be retried — testable without a network, a provider or a
+ * container.
+ *
+ * What this does NOT do, on purpose: it never PAGES. `pagination` on an operation is a hint the
+ * caller reads; an executor that paged on its own would decide a caller's memory budget for it.
+ */
+import { type ProviderRestOperation } from '@wildo-ai/external-connectors-models';
+import { type HttpApiTransportRequest } from '../../base-classes/services/repositories/http-api/http-api-transport.backend';
+/** What went wrong while turning a declaration + an input into a request. */
+export declare enum ProviderOperationRequestFailureKind {
+    /** The caller's input does not satisfy the operation's declared input schema. */
+    INPUT_REJECTED = "INPUT_REJECTED",
+    /** A required value is absent — a path token with nothing to fill it, a required parameter. */
+    INPUT_INCOMPLETE = "INPUT_INCOMPLETE",
+    /** The DECLARATION is inconsistent — a path token no parameter declares, a body with no source. */
+    DECLARATION_INCOHERENT = "DECLARATION_INCOHERENT"
+}
+export declare class ProviderOperationRequestError extends Error {
+    readonly detail: {
+        readonly kind: ProviderOperationRequestFailureKind;
+        readonly operationId: string;
+        readonly providerRef: string;
+    };
+    constructor(message: string, detail: {
+        readonly kind: ProviderOperationRequestFailureKind;
+        readonly operationId: string;
+        readonly providerRef: string;
+    });
+}
+/** Whether re-sending this operation is safe — the value that reaches the transport's retry gate. */
+export declare function providerOperationIsRetrySafe(operation: ProviderRestOperation): boolean;
+export interface CompileProviderOperationInput {
+    operation: ProviderRestOperation;
+    providerRef: string;
+    /** Already validated against `operation.inputSchema` by the executor when one is declared. */
+    input: Readonly<Record<string, unknown>>;
+    /** Base URL and auth/default headers, from the provider access resolver. */
+    access: {
+        baseUrl: string;
+        headers: Record<string, string>;
+    };
+}
+/**
+ * Build the request. Reads in one direction — path, then query, then headers, then body — and
+ * records which input fields were consumed on the way, because the body's default source is
+ * "everything not consumed" and that set can only be known after the parameters are placed.
+ */
+export declare function compileProviderOperationRequest(input: CompileProviderOperationInput): HttpApiTransportRequest;
+//# sourceMappingURL=provider-operation-request.backend.d.ts.map

package/dist/esm/external-providers/operations/provider-operation-request.backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-operation-request.backend.d.ts","sourceRoot":"","sources":["../../../../../src/external-providers/operations/provider-operation-request.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH,OAAO,EAAkE,KAAK,qBAAqB,EAAuC,MAAM,sCAAsC,CAAC;AAEvL,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,2FAA2F,CAAC;AAEnG,6EAA6E;AAC7E,oBAAY,mCAAmC;IAC7C,iFAAiF;IACjF,cAAc,mBAAmB;IACjC,+FAA+F;IAC/F,gBAAgB,qBAAqB;IACrC,mGAAmG;IACnG,sBAAsB,2BAA2B;CAClD;AAED,qBAAa,6BAA8B,SAAQ,KAAK;aAGpC,MAAM,EAAE;QACtB,QAAQ,CAAC,IAAI,EAAE,mCAAmC,CAAC;QACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B;gBALD,OAAO,EAAE,MAAM,EACC,MAAM,EAAE;QACtB,QAAQ,CAAC,IAAI,EAAE,mCAAmC,CAAC;QACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B;CAKJ;AAmBD,qGAAqG;AACrG,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,qBAAqB,GAAG,OAAO,CAEtF;AAaD,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,qBAAqB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,8FAA8F;IAC9F,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzC,4EAA4E;IAC5E,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;CAC9D;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,6BAA6B,GAAG,uBAAuB,CAiK7G"}