@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/external-providers/services/backend-provider-registry.backend.service.js

@@ -5,74 +5,61 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { injectable } from 'inversify';
-import { EngineBackendProviderRegistry, composeBackendProviders, } from '@wildo-ai/external-connectors-private/backend';
-import { ExternalProvider_ExchangeProtocol_Kind } from '@wildo-ai/external-connectors-models';
-const BACKEND_PROTOCOL_TO_EXTERNAL_KIND = {
-    REST_API: ExternalProvider_ExchangeProtocol_Kind.REST_API,
-    WEBHOOK_ORIGINATOR: ExternalProvider_ExchangeProtocol_Kind.WEBHOOK_ORIGINATOR,
-    LLM_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER,
-    EMAIL_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.EMAIL_PROVIDER,
-    SSO_OAUTH2: ExternalProvider_ExchangeProtocol_Kind.SSO_OAUTH2,
-    BILLING_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.BILLING_PROVIDER,
-    SMS_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER,
-    // Multimodal generation (artifact-modality axis). IMAGE_PROVIDER is wired;
-    // AUDIO/VIDEO are reserved (protocol resolvable, but no runtime-contract arm
-    // and no provider serves them yet).
-    IMAGE_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.IMAGE_PROVIDER,
-    AUDIO_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.AUDIO_PROVIDER,
-    VIDEO_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.VIDEO_PROVIDER,
-    // Text → vector embeddings (RAG plan DL2) — its own protocol kind, wired like IMAGE_PROVIDER.
-    EMBEDDINGS_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.EMBEDDINGS_PROVIDER,
-    // Document bytes → text (OCR) — its own protocol kind, wired like EMBEDDINGS_PROVIDER. Without
-    // this row `getRuntimeContract(ref, DOCUMENT_EXTRACTION_PROVIDER)` is structurally `undefined`,
-    // so a provider could declare the transport and the engine could never resolve it.
-    DOCUMENT_EXTRACTION_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.DOCUMENT_EXTRACTION_PROVIDER,
-    // Coding agents over the Agent Client Protocol — a session transport, not a
-    // request/response one, and its own engine capability slot.
-    AGENT_CLIENT_PROTOCOL: ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL,
-};
-const EXTERNAL_KIND_TO_BACKEND_PROTOCOL = new Map(Object.entries(BACKEND_PROTOCOL_TO_EXTERNAL_KIND).map(([protocol, kind]) => [kind, protocol]));
+import { composeBackendProviders, } from '@wildo-ai/external-connectors-private/backend-runtime';
+// The protocol→kind hand map that stood here (`BACKEND_PROTOCOL_TO_EXTERNAL_KIND`, a THIRD enumeration
+// of the protocol population) was retired 2026-09-05 (#327): a runtime contract's `kind` IS the exchange
+// kind now, and `composeBackendProviders` refuses a binding whose authoring key disagrees with it.
+/**
+ * The registry a host serves before `initialize` runs: EMPTY, and composed rather than hand-built so
+ * it is the same shape every consumer expects.
+ *
+ * It used to be the engine's eagerly composed catalogue, and that single default field initialiser is
+ * what put twenty-two provider modules — six of them pulling an `@ai-sdk/*` client at module top
+ * level — into every backend, minion and worker boot graph before any filtering could happen (audit
+ * finding BE-1). Providers now arrive through `resolveBackendProviderRegistry`, which imports only
+ * the refs the process declared, so nothing about this module evaluates a provider.
+ */
+const EMPTY_BACKEND_PROVIDER_REGISTRY = composeBackendProviders({ modules: new Map() });
 let BackendProviderRegistryBackendService = class BackendProviderRegistryBackendService {
-    registry = EngineBackendProviderRegistry;
+    registry = EMPTY_BACKEND_PROVIDER_REGISTRY;
     /** @wildo_source:part:start saas.external-providers.backend-provider-registry.runtime-filter facet:layer:backend facet:family:provider-registry */
     /**
-     * Initialize the backend provider registry that all downstream services
-     * (auth, billing, notifications, …) will resolve through.
+     * Adopt the registry a host RESOLVED, and re-check it against what that host declared.
      *
-     * This is the seam that decides which providers a backend host can actually
-     * reach at runtime. A provider authored only in a NON-backend scope (e.g.
-     * `providers.scopes.frontendServices.<app>`) never enters this registry, so
-     * any backend feature keyed on it (billing, transactional email, server-side
-     * LLM calls) resolves nothing and fails at startup. Author the provider under
-     * `providers.scopes.backend` in `./wildo.saas.config.ts` AND declare a
-     * matching backend contribution (`runtimeTargets: [{ kind: 'backend' }]`) so
-     * `wildo config sync` lists its ref in the generated provider-runtime
-     * artifact — otherwise it is filtered out here.
+     * This is the seam that decides which providers a backend host can actually reach at runtime. A
+     * provider authored only in a NON-backend scope (e.g. `providers.scopes.frontendServices.<app>`)
+     * never enters this registry, so any backend feature keyed on it (billing, transactional email,
+     * server-side LLM calls) resolves nothing and fails at startup. Author the provider under
+     * `providers.scopes.backend` in `./wildo.saas.config.ts` so `wildo config sync` lists its ref in
+     * the generated provider-runtime artifact — otherwise it is filtered out here.
      *
      * Composition model:
      *
-     * 1. The **catalog** is the union of engine-shipped providers
-     *    (`EngineBackendProviderRegistry`) and any application-contributed
-     *    providers (passed in via `registry`). This is what is *available*.
-     * 2. The **runtime artifact** (`providerRuntime`, generated by
-     *    `wildo config sync` and imported by the application bootstrap)
-     *    declares which providers this specific backend process is *allowed*
-     *    to expose, scoped by the authored `providers.scopes.backend`.
-     * 3. The active registry is the catalog filtered to the artifact's
-     *    `providerRefs`. Any ref claimed by the artifact but missing from the
-     *    catalog is a deployment-time error and fails startup loudly — there
-     *    is no silent fallback to the unfiltered catalog.
+     * 1. The **runtime artifact** (`providerRuntime`, generated by `wildo config sync` and imported by
+     *    the application bootstrap) declares which providers this specific process may expose.
+     * 2. `resolveBackendProviderRegistry` LOADS exactly those refs — an application-supplied module
+     *    first, then the engine's on-demand map, then a dynamic import of the package the artifact
+     *    names — and hands the composed result here. Nothing a process did not declare is imported,
+     *    which is the whole point: a worker that declares one email provider evaluates one provider.
+     * 3. This method re-filters that registry to the artifact's `providerRefs` and REFUSES if any ref
+     *    is still missing. That is not redundant with the loader: the loader deliberately does not
+     *    throw, so this stays the one place a deployment gap is reported, and it reports ALL of them at
+     *    once rather than the first import that failed.
+     *
+     * When `providerRuntime` is `undefined` no filtering is applied — the host declared no topology, so
+     * there is nothing to filter against, and the loader will have handed over the whole engine
+     * catalogue (platform applications that initialize their config later).
      *
-     * When `providerRuntime` is `undefined`, no filtering is applied and the
-     * full catalog is exposed (legacy / pre-materialization callers, and
-     * platform applications that initialize their config later).
+     * `unresolvedReasons` carries the loader's per-ref explanation into the refusal below, so an
+     * operator is told WHY a ref did not resolve (no package declares it / the import threw / the
+     * package exports no fragment) instead of only that it was absent.
      */
-    initialize(registry = EngineBackendProviderRegistry, providerRuntime) {
+    initialize(registry, providerRuntime, unresolvedReasons) {
         if (!providerRuntime) {
             this.registry = registry;
             return;
         }
-        this.registry = filterRegistryByProviderRuntime(registry, providerRuntime);
+        this.registry = filterRegistryByProviderRuntime(registry, providerRuntime, unresolvedReasons);
     }
     /** @wildo_source:part:end saas.external-providers.backend-provider-registry.runtime-filter */
     getRegistry() {
@@ -88,18 +75,13 @@ let BackendProviderRegistryBackendService = class BackendProviderRegistryBackend
         return [...this.registry.modules.values()].filter((provider) => (this.getProtocolBinding(provider.metadata.ref, protocolKind) !== undefined));
     }
     getProtocolBinding(providerRef, protocolKind) {
-        const backendProtocol = EXTERNAL_KIND_TO_BACKEND_PROTOCOL.get(protocolKind);
-        if (!backendProtocol)
-            return undefined;
-        return this.getProvider(providerRef)?.protocols.find((protocol) => protocol.protocol === backendProtocol);
+        return this.getProvider(providerRef)?.protocols.find((binding) => binding.runtimeContract.kind === protocolKind);
     }
     getRuntimeContract(providerRef, protocolKind) {
         return this.getProtocolBinding(providerRef, protocolKind)?.runtimeContract;
     }
     getProtocolKinds(providerRef) {
-        return (this.getProvider(providerRef)?.protocols ?? [])
-            .map((protocol) => BACKEND_PROTOCOL_TO_EXTERNAL_KIND[protocol.protocol])
-            .filter((kind) => Boolean(kind));
+        return (this.getProvider(providerRef)?.protocols ?? []).map((binding) => binding.runtimeContract.kind);
     }
 };
 BackendProviderRegistryBackendService = __decorate([
@@ -136,7 +118,7 @@ export { BackendProviderRegistryBackendService };
  * from this runtime, which is exactly what Step 1 of the provider
  * migration is supposed to make impossible to ignore.
  */
-function filterRegistryByProviderRuntime(registry, providerRuntime) {
+function filterRegistryByProviderRuntime(registry, providerRuntime, unresolvedReasons) {
     const authoredRefs = providerRuntime.providerRefs && providerRuntime.providerRefs.length > 0
         ? providerRuntime.providerRefs
         : Object.keys(providerRuntime.scope?.providers ?? {});
@@ -153,8 +135,12 @@ function filterRegistryByProviderRuntime(registry, providerRuntime) {
         filteredModules.set(brandedRef, module);
     }
     if (missingRefs.length > 0) {
+        const explained = missingRefs.sort().map((ref) => {
+            const reason = unresolvedReasons?.get(ref);
+            return reason ? `${ref} — ${reason}` : ref;
+        });
         throw new Error(`[BackendProviderRegistry] generated provider runtime claims providers `
-            + `not present in the composed backend catalog: [${missingRefs.sort().join(', ')}]. `
+            + `not present in the composed backend catalog:\n  - ${explained.join('\n  - ')}\n`
             + `This is a discovery gap — verify that each provider's contributing package `
             + `is reachable from the backend runtime owner and re-run \`wildo config sync\`.`);
     }

package/dist/esm/external-providers/services/backend-provider-registry.backend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend-provider-registry.backend.service.js","sourceRoot":"","sources":["../../../../../src/external-providers/services/backend-provider-registry.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable } from 'inversify';\nimport {\n  EngineBackendProviderRegistry,\n  composeBackendProviders,\n  type BackendProviderModule,\n  type BackendProviderRegistry,\n  type BackendProtocolBinding,\n  type ProviderProtocolRuntimeContract,\n} from '@wildo-ai/external-connectors-private/backend';\nimport { ExternalProvider_ExchangeProtocol_Kind } from '@wildo-ai/external-connectors-models';\nimport type { ProviderRuntimeArtifact } from '~wildo-backend-lib/config/models/provider-runtime-artifact.backend.schemas';\n\nconst BACKEND_PROTOCOL_TO_EXTERNAL_KIND: Record<string, ExternalProvider_ExchangeProtocol_Kind> = {\n  REST_API: ExternalProvider_ExchangeProtocol_Kind.REST_API,\n  WEBHOOK_ORIGINATOR: ExternalProvider_ExchangeProtocol_Kind.WEBHOOK_ORIGINATOR,\n  LLM_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER,\n  EMAIL_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.EMAIL_PROVIDER,\n  SSO_OAUTH2: ExternalProvider_ExchangeProtocol_Kind.SSO_OAUTH2,\n  BILLING_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.BILLING_PROVIDER,\n  SMS_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER,\n  // Multimodal generation (artifact-modality axis). IMAGE_PROVIDER is wired;\n  // AUDIO/VIDEO are reserved (protocol resolvable, but no runtime-contract arm\n  // and no provider serves them yet).\n  IMAGE_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.IMAGE_PROVIDER,\n  AUDIO_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.AUDIO_PROVIDER,\n  VIDEO_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.VIDEO_PROVIDER,\n  // Text → vector embeddings (RAG plan DL2) — its own protocol kind, wired like IMAGE_PROVIDER.\n  EMBEDDINGS_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.EMBEDDINGS_PROVIDER,\n  // Document bytes → text (OCR) — its own protocol kind, wired like EMBEDDINGS_PROVIDER. Without\n  // this row `getRuntimeContract(ref, DOCUMENT_EXTRACTION_PROVIDER)` is structurally `undefined`,\n  // so a provider could declare the transport and the engine could never resolve it.\n  DOCUMENT_EXTRACTION_PROVIDER: ExternalProvider_ExchangeProtocol_Kind.DOCUMENT_EXTRACTION_PROVIDER,\n  // Coding agents over the Agent Client Protocol — a session transport, not a\n  // request/response one, and its own engine capability slot.\n  AGENT_CLIENT_PROTOCOL: ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL,\n};\n\nconst EXTERNAL_KIND_TO_BACKEND_PROTOCOL = new Map(\n  Object.entries(BACKEND_PROTOCOL_TO_EXTERNAL_KIND).map(([protocol, kind]) => [kind, protocol]),\n);\n\n@injectable()\nexport class BackendProviderRegistryBackendService {\n  private registry: BackendProviderRegistry = EngineBackendProviderRegistry;\n\n  /** @wildo_source:part:start saas.external-providers.backend-provider-registry.runtime-filter facet:layer:backend facet:family:provider-registry */\n  /**\n   * Initialize the backend provider registry that all downstream services\n   * (auth, billing, notifications, …) will resolve through.\n   *\n   * This is the seam that decides which providers a backend host can actually\n   * reach at runtime. A provider authored only in a NON-backend scope (e.g.\n   * `providers.scopes.frontendServices.<app>`) never enters this registry, so\n   * any backend feature keyed on it (billing, transactional email, server-side\n   * LLM calls) resolves nothing and fails at startup. Author the provider under\n   * `providers.scopes.backend` in `./wildo.saas.config.ts` AND declare a\n   * matching backend contribution (`runtimeTargets: [{ kind: 'backend' }]`) so\n   * `wildo config sync` lists its ref in the generated provider-runtime\n   * artifact — otherwise it is filtered out here.\n   *\n   * Composition model:\n   *\n   * 1. The **catalog** is the union of engine-shipped providers\n   *    (`EngineBackendProviderRegistry`) and any application-contributed\n   *    providers (passed in via `registry`). This is what is *available*.\n   * 2. The **runtime artifact** (`providerRuntime`, generated by\n   *    `wildo config sync` and imported by the application bootstrap)\n   *    declares which providers this specific backend process is *allowed*\n   *    to expose, scoped by the authored `providers.scopes.backend`.\n   * 3. The active registry is the catalog filtered to the artifact's\n   *    `providerRefs`. Any ref claimed by the artifact but missing from the\n   *    catalog is a deployment-time error and fails startup loudly — there\n   *    is no silent fallback to the unfiltered catalog.\n   *\n   * When `providerRuntime` is `undefined`, no filtering is applied and the\n   * full catalog is exposed (legacy / pre-materialization callers, and\n   * platform applications that initialize their config later).\n   */\n  initialize(\n    registry: BackendProviderRegistry = EngineBackendProviderRegistry,\n    providerRuntime?: ProviderRuntimeArtifact,\n  ): void {\n    if (!providerRuntime) {\n      this.registry = registry;\n      return;\n    }\n\n    this.registry = filterRegistryByProviderRuntime(registry, providerRuntime);\n  }\n  /** @wildo_source:part:end saas.external-providers.backend-provider-registry.runtime-filter */\n\n  getRegistry(): BackendProviderRegistry {\n    return this.registry;\n  }\n\n  getProvider(providerRef: string): BackendProviderModule | undefined {\n    return this.registry.getProviderByRef(providerRef as never);\n  }\n\n  hasProvider(providerRef: string): boolean {\n    return Boolean(this.getProvider(providerRef));\n  }\n\n  getProvidersWithProtocol(protocolKind: ExternalProvider_ExchangeProtocol_Kind): BackendProviderModule[] {\n    return [...this.registry.modules.values()].filter((provider) => (\n      this.getProtocolBinding(provider.metadata.ref, protocolKind) !== undefined\n    ));\n  }\n\n  getProtocolBinding(\n    providerRef: string,\n    protocolKind: ExternalProvider_ExchangeProtocol_Kind,\n  ): BackendProtocolBinding | undefined {\n    const backendProtocol = EXTERNAL_KIND_TO_BACKEND_PROTOCOL.get(protocolKind);\n    if (!backendProtocol) return undefined;\n    return this.getProvider(providerRef)?.protocols.find((protocol) => protocol.protocol === backendProtocol);\n  }\n\n  getRuntimeContract(\n    providerRef: string,\n    protocolKind: ExternalProvider_ExchangeProtocol_Kind,\n  ): ProviderProtocolRuntimeContract | undefined {\n    return this.getProtocolBinding(providerRef, protocolKind)?.runtimeContract;\n  }\n\n  getProtocolKinds(providerRef: string): ExternalProvider_ExchangeProtocol_Kind[] {\n    return (this.getProvider(providerRef)?.protocols ?? [])\n      .map((protocol) => BACKEND_PROTOCOL_TO_EXTERNAL_KIND[protocol.protocol])\n      .filter((kind): kind is ExternalProvider_ExchangeProtocol_Kind => Boolean(kind));\n  }\n}\n\n/**\n * Build a restricted registry containing only the providers authored for\n * this backend process by the materialized `providerRuntime` artifact.\n *\n * The authored ref set comes from the artifact in this priority order:\n *\n *   1. `providerRuntime.providerRefs` — the canonical projection emitted by\n *      `materializeSaasProviderRuntimeArtifacts`.\n *   2. Keys of `providerRuntime.scope.providers` — fallback for older\n *      artifacts written before `providerRefs` was added.\n *\n * Post-2026-05-10 invariant: after the Option-B fix landed in\n * `selectScopedProviderRuntimeArtifact` (canonical) and the per-host\n * projection sites in minion / Node-worker startup (`selectMinionProviderRuntimeScope`,\n * `selectWorkerProviderRuntimeScope`), the canonical path ALWAYS\n * populates `providerRefs` from the per-host projected scope. The\n * fallback branch is unreachable for any artifact produced by the\n * current CLI sync; it only fires for legacy generated modules\n * predating that projection fix. Kept as defense-in-depth — the\n * schema marks `providerRefs` optional and would let a hand-crafted\n * artifact omit the field.\n *\n * If a ref is claimed by the artifact but missing from the composed\n * catalog, startup fails with a single error naming every missing ref.\n * This is deployment-correctness, not defensive coding: the artifact is\n * generated from `wildo.saas.config.ts` after companion-export discovery,\n * so any miss means the contributing package is not actually reachable\n * from this runtime, which is exactly what Step 1 of the provider\n * migration is supposed to make impossible to ignore.\n */\nfunction filterRegistryByProviderRuntime(\n  registry: BackendProviderRegistry,\n  providerRuntime: ProviderRuntimeArtifact,\n): BackendProviderRegistry {\n  const authoredRefs = providerRuntime.providerRefs && providerRuntime.providerRefs.length > 0\n    ? providerRuntime.providerRefs\n    : Object.keys(providerRuntime.scope?.providers ?? {});\n\n  const authoredRefSet = new Set(authoredRefs);\n\n  type BrandedRef = Parameters<typeof registry.getProviderByRef>[0];\n  const filteredModules = new Map<BrandedRef, BackendProviderModule>();\n  const missingRefs: string[] = [];\n\n  for (const ref of authoredRefSet) {\n    const brandedRef = ref as BrandedRef;\n    const module = registry.getProviderByRef(brandedRef);\n    if (!module) {\n      missingRefs.push(ref);\n      continue;\n    }\n    filteredModules.set(brandedRef, module);\n  }\n\n  if (missingRefs.length > 0) {\n    throw new Error(\n      `[BackendProviderRegistry] generated provider runtime claims providers `\n      + `not present in the composed backend catalog: [${missingRefs.sort().join(', ')}]. `\n      + `This is a discovery gap — verify that each provider's contributing package `\n      + `is reachable from the backend runtime owner and re-run \\`wildo config sync\\`.`,\n    );\n  }\n\n  return composeBackendProviders({ modules: filteredModules });\n}\n"]}
+{"version":3,"file":"backend-provider-registry.backend.service.js","sourceRoot":"","sources":["../../../../src/external-providers/services/backend-provider-registry.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable } from 'inversify';\nimport {\n  composeBackendProviders,\n  type BackendProviderModule,\n  type BackendProviderRegistry,\n  type BackendProtocolBinding,\n  type ProviderProtocolRuntimeContract,\n} from '@wildo-ai/external-connectors-private/backend-runtime';\nimport { ExternalProvider_ExchangeProtocol_Kind } from '@wildo-ai/external-connectors-models';\nimport type { ProviderRuntimeArtifact } from '~wildo-backend-lib/config/models/provider-runtime-artifact.backend.schemas';\n\n// The protocol→kind hand map that stood here (`BACKEND_PROTOCOL_TO_EXTERNAL_KIND`, a THIRD enumeration\n// of the protocol population) was retired 2026-09-05 (#327): a runtime contract's `kind` IS the exchange\n// kind now, and `composeBackendProviders` refuses a binding whose authoring key disagrees with it.\n\n/**\n * The registry a host serves before `initialize` runs: EMPTY, and composed rather than hand-built so\n * it is the same shape every consumer expects.\n *\n * It used to be the engine's eagerly composed catalogue, and that single default field initialiser is\n * what put twenty-two provider modules — six of them pulling an `@ai-sdk/*` client at module top\n * level — into every backend, minion and worker boot graph before any filtering could happen (audit\n * finding BE-1). Providers now arrive through `resolveBackendProviderRegistry`, which imports only\n * the refs the process declared, so nothing about this module evaluates a provider.\n */\nconst EMPTY_BACKEND_PROVIDER_REGISTRY: BackendProviderRegistry = composeBackendProviders({ modules: new Map() });\n\n@injectable()\nexport class BackendProviderRegistryBackendService {\n  private registry: BackendProviderRegistry = EMPTY_BACKEND_PROVIDER_REGISTRY;\n\n  /** @wildo_source:part:start saas.external-providers.backend-provider-registry.runtime-filter facet:layer:backend facet:family:provider-registry */\n  /**\n   * Adopt the registry a host RESOLVED, and re-check it against what that host declared.\n   *\n   * This is the seam that decides which providers a backend host can actually reach at runtime. A\n   * provider authored only in a NON-backend scope (e.g. `providers.scopes.frontendServices.<app>`)\n   * never enters this registry, so any backend feature keyed on it (billing, transactional email,\n   * server-side LLM calls) resolves nothing and fails at startup. Author the provider under\n   * `providers.scopes.backend` in `./wildo.saas.config.ts` so `wildo config sync` lists its ref in\n   * the generated provider-runtime artifact — otherwise it is filtered out here.\n   *\n   * Composition model:\n   *\n   * 1. The **runtime artifact** (`providerRuntime`, generated by `wildo config sync` and imported by\n   *    the application bootstrap) declares which providers this specific process may expose.\n   * 2. `resolveBackendProviderRegistry` LOADS exactly those refs — an application-supplied module\n   *    first, then the engine's on-demand map, then a dynamic import of the package the artifact\n   *    names — and hands the composed result here. Nothing a process did not declare is imported,\n   *    which is the whole point: a worker that declares one email provider evaluates one provider.\n   * 3. This method re-filters that registry to the artifact's `providerRefs` and REFUSES if any ref\n   *    is still missing. That is not redundant with the loader: the loader deliberately does not\n   *    throw, so this stays the one place a deployment gap is reported, and it reports ALL of them at\n   *    once rather than the first import that failed.\n   *\n   * When `providerRuntime` is `undefined` no filtering is applied — the host declared no topology, so\n   * there is nothing to filter against, and the loader will have handed over the whole engine\n   * catalogue (platform applications that initialize their config later).\n   *\n   * `unresolvedReasons` carries the loader's per-ref explanation into the refusal below, so an\n   * operator is told WHY a ref did not resolve (no package declares it / the import threw / the\n   * package exports no fragment) instead of only that it was absent.\n   */\n  initialize(\n    registry: BackendProviderRegistry,\n    providerRuntime?: ProviderRuntimeArtifact,\n    unresolvedReasons?: ReadonlyMap<string, string>,\n  ): void {\n    if (!providerRuntime) {\n      this.registry = registry;\n      return;\n    }\n\n    this.registry = filterRegistryByProviderRuntime(registry, providerRuntime, unresolvedReasons);\n  }\n  /** @wildo_source:part:end saas.external-providers.backend-provider-registry.runtime-filter */\n\n  getRegistry(): BackendProviderRegistry {\n    return this.registry;\n  }\n\n  getProvider(providerRef: string): BackendProviderModule | undefined {\n    return this.registry.getProviderByRef(providerRef as never);\n  }\n\n  hasProvider(providerRef: string): boolean {\n    return Boolean(this.getProvider(providerRef));\n  }\n\n  getProvidersWithProtocol(protocolKind: ExternalProvider_ExchangeProtocol_Kind): BackendProviderModule[] {\n    return [...this.registry.modules.values()].filter((provider) => (\n      this.getProtocolBinding(provider.metadata.ref, protocolKind) !== undefined\n    ));\n  }\n\n  getProtocolBinding(\n    providerRef: string,\n    protocolKind: ExternalProvider_ExchangeProtocol_Kind,\n  ): BackendProtocolBinding | undefined {\n    return this.getProvider(providerRef)?.protocols.find((binding) => binding.runtimeContract.kind === protocolKind);\n  }\n\n  getRuntimeContract(\n    providerRef: string,\n    protocolKind: ExternalProvider_ExchangeProtocol_Kind,\n  ): ProviderProtocolRuntimeContract | undefined {\n    return this.getProtocolBinding(providerRef, protocolKind)?.runtimeContract;\n  }\n\n  getProtocolKinds(providerRef: string): ExternalProvider_ExchangeProtocol_Kind[] {\n    return (this.getProvider(providerRef)?.protocols ?? []).map((binding) => binding.runtimeContract.kind);\n  }\n}\n\n/**\n * Build a restricted registry containing only the providers authored for\n * this backend process by the materialized `providerRuntime` artifact.\n *\n * The authored ref set comes from the artifact in this priority order:\n *\n *   1. `providerRuntime.providerRefs` — the canonical projection emitted by\n *      `materializeSaasProviderRuntimeArtifacts`.\n *   2. Keys of `providerRuntime.scope.providers` — fallback for older\n *      artifacts written before `providerRefs` was added.\n *\n * Post-2026-05-10 invariant: after the Option-B fix landed in\n * `selectScopedProviderRuntimeArtifact` (canonical) and the per-host\n * projection sites in minion / Node-worker startup (`selectMinionProviderRuntimeScope`,\n * `selectWorkerProviderRuntimeScope`), the canonical path ALWAYS\n * populates `providerRefs` from the per-host projected scope. The\n * fallback branch is unreachable for any artifact produced by the\n * current CLI sync; it only fires for legacy generated modules\n * predating that projection fix. Kept as defense-in-depth — the\n * schema marks `providerRefs` optional and would let a hand-crafted\n * artifact omit the field.\n *\n * If a ref is claimed by the artifact but missing from the composed\n * catalog, startup fails with a single error naming every missing ref.\n * This is deployment-correctness, not defensive coding: the artifact is\n * generated from `wildo.saas.config.ts` after companion-export discovery,\n * so any miss means the contributing package is not actually reachable\n * from this runtime, which is exactly what Step 1 of the provider\n * migration is supposed to make impossible to ignore.\n */\nfunction filterRegistryByProviderRuntime(\n  registry: BackendProviderRegistry,\n  providerRuntime: ProviderRuntimeArtifact,\n  unresolvedReasons?: ReadonlyMap<string, string>,\n): BackendProviderRegistry {\n  const authoredRefs = providerRuntime.providerRefs && providerRuntime.providerRefs.length > 0\n    ? providerRuntime.providerRefs\n    : Object.keys(providerRuntime.scope?.providers ?? {});\n\n  const authoredRefSet = new Set(authoredRefs);\n\n  type BrandedRef = Parameters<typeof registry.getProviderByRef>[0];\n  const filteredModules = new Map<BrandedRef, BackendProviderModule>();\n  const missingRefs: string[] = [];\n\n  for (const ref of authoredRefSet) {\n    const brandedRef = ref as BrandedRef;\n    const module = registry.getProviderByRef(brandedRef);\n    if (!module) {\n      missingRefs.push(ref);\n      continue;\n    }\n    filteredModules.set(brandedRef, module);\n  }\n\n  if (missingRefs.length > 0) {\n    const explained = missingRefs.sort().map((ref) => {\n      const reason = unresolvedReasons?.get(ref);\n      return reason ? `${ref} — ${reason}` : ref;\n    });\n    throw new Error(\n      `[BackendProviderRegistry] generated provider runtime claims providers `\n      + `not present in the composed backend catalog:\\n  - ${explained.join('\\n  - ')}\\n`\n      + `This is a discovery gap — verify that each provider's contributing package `\n      + `is reachable from the backend runtime owner and re-run \\`wildo config sync\\`.`,\n    );\n  }\n\n  return composeBackendProviders({ modules: filteredModules });\n}\n"]}

package/dist/esm/external-providers/services/document-extraction.backend.service.d.ts

@@ -20,11 +20,41 @@
  * Every sibling provider seam in this package hands an API key to an `@ai-sdk/*` client factory.
  * This one cannot: **`@ai-sdk/mistral@4.0.12` has ZERO OCR support** — the package exports no
  * `ocr` symbol and no client method reaching `POST /v1/ocr`, because the AI SDK models language,
- * embedding and image models and document extraction is none of them. So the request is built
- * here from the provider's declared `baseUrl`, `endpointPath` and `apiKey` header shape.
+ * embedding and image models and document extraction is none of them. So this service is the
+ * transport, issuing the request itself.
  *
- * That is a cost, and it is worth naming what it buys back: the contract declares the route and
- * the auth header, so a second provider in this family is a module edit rather than a change here.
+ * ## The line between engine and provider
+ *
+ * Until 2026-09-09 being the transport had quietly become being the CLIENT. This service composed
+ * MISTRAL's `/v1/ocr` request — `document: { type: 'document_url', document_url }` as an inline
+ * data URI, `include_image_base64: false` — and read MISTRAL's response — `pages[].markdown`,
+ * `usage_info.pages_processed` — while the arm it narrowed to (`kind: DOCUMENT_EXTRACTION`) is a
+ * PROTOCOL any provider may declare, and the vendor was named nowhere. A second provider selected
+ * for `AI_DOCUMENT_EXTRACTION` would have been sent through Mistral's API carrying its own key,
+ * and nothing would have refused it or logged it.
+ *
+ * It now mirrors `EmailBackendService` and `SMSBackendService`, the two arms that already have a
+ * solved shape for this: the provider declares PURE FUNCTIONS on its contract, and the engine owns
+ * transport.
+ *
+ *   ENGINE (here)  — resolve the provider, the model and the secret; compose the URL from the
+ *                    declared `baseUrl` + `endpointPath` and the API-key header from the declared
+ *                    `apiKey`; apply the engine's own byte ceiling and timeout; issue the request;
+ *                    validate what the provider's parser returns; retry per the failure class.
+ *   PROVIDER       — the request body and its `content-type`, how the bytes travel, and the
+ *                    projection of the vendor's response onto the framework's extraction or onto
+ *                    a {@link DocumentExtraction_FailureClass}.
+ *
+ * There is deliberately no consumer-side adapter registry of the kind billing uses. That shape
+ * exists only because a billing adapter is a CLASS in this package, which the provider package
+ * cannot reach without a reverse dependency edge; a document-extraction provider owes two
+ * functions over `@wildo-ai/external-connectors-models` types, which it supplies directly.
+ *
+ * Three floors stay HERE and a provider cannot lower them, because each one's failure mode is
+ * corpus deletion rather than a bad log line: a transport failure or timeout never reaches the
+ * parser and is `PROVIDER_UNAVAILABLE`; a parser that THROWS is `PROVIDER_UNAVAILABLE` rather
+ * than an unclassified crash; and a parser result that violates the standard output schema is
+ * `PROVIDER_UNAVAILABLE`, never "this document has no text".
  *
  * ## Failure posture — THREE outcomes, not two, and the third is the whole point
  *
@@ -32,7 +62,7 @@
  * not ask". Collapsing them is not a tidiness issue: `RagIngestionBackendService` deletes a
  * field's entire chunk set when an ingestion pass yields no text, so reporting a provider OUTAGE
  * as an unreadable document would silently destroy a live, already-embedded corpus and report
- * success. {@link DocumentExtractionFailureClass} carries that distinction, and
+ * success. {@link DocumentExtraction_FailureClass} carries that distinction, and
  * `FileTextExtractionBackendService` branches on it.
  *
  * ## Observability
@@ -45,7 +75,8 @@
  * context, and never included in a diagnostic dump of the request.
  */
 import { type AgentCallTraceSink, type AgentTraceabilityPolicy } from '@wildo-ai/saas-models';
-import { DocumentExtraction_Applicability, type DocumentExtractionProvider_ExtractDocumentTextOutput } from '@wildo-ai/external-connectors-models';
+import { DocumentExtraction_Applicability, DocumentExtraction_FailureClass, type DocumentExtraction_ProviderExtraction, type DocumentExtractionProvider_ExtractDocumentTextOutput } from '@wildo-ai/external-connectors-models';
+import type { DocumentExtractionProviderRequest, DocumentExtractionProviderRequestInput, DocumentExtractionProviderResponseInput } from '@wildo-ai/external-connectors-private/backend';
 import type { LoggerService } from '../../monitoring/logger/services/logger.service';
 import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service';
 import type { ExternalProvidersRegistryBackendService } from '../../external-providers/services/external-providers-registry.backend.service';
@@ -82,31 +113,20 @@ export declare const DOCUMENT_EXTRACTION_REQUEST_TIMEOUT_MS = 120000;
  */
 export declare const DOCUMENT_EXTRACTION_TRACE_AGENT_REF = "engine:document-extraction";
 /**
- * WHY an extraction failed, in the only two senses a caller can act on differently.
+ * A failed extraction, classified.
  *
- * This is the service's most load-bearing output after the text itself. See the file header: the
- * consequence of confusing the two is corpus deletion, not a misleading log line.
+ * The CLASS lives in `@wildo-ai/external-connectors-models` rather than here, and the move is what
+ * made the provider seam possible: a vocabulary a provider module cannot reach is one a provider
+ * cannot answer in, so before 2026-09-09 the classification had to be performed by whoever could
+ * reach it — this service — which is precisely how one vendor's status semantics became the
+ * framework's. The ERROR stays here because it is an engine construct: `FileTextExtractionBackendService`
+ * catches it, and a provider never throws.
  */
-export declare enum DocumentExtractionFailureClass {
-    /**
-     * The provider read the request and judged the DOCUMENT unprocessable — corrupt bytes, an
-     * unsupported format, a password-protected file. PERMANENT: re-sending the same bytes cannot
-     * succeed, so a sweep may safely stop retrying and skip the document.
-     */
-    UNREADABLE_DOCUMENT = "unreadable_document",
-    /**
-     * The provider could not be reached, refused the credential, throttled, or failed internally —
-     * a network error, a 401/403, a 429, any 5xx, or a timeout. TRANSIENT and, decisively, says
-     * NOTHING about the document. A caller must not conclude anything about the bytes from this.
-     */
-    PROVIDER_UNAVAILABLE = "provider_unavailable"
-}
-/** A failed extraction, classified. Thrown as {@link DocumentExtractionError}. */
 export declare class DocumentExtractionError extends Error {
-    readonly failureClass: DocumentExtractionFailureClass;
+    readonly failureClass: DocumentExtraction_FailureClass;
     /** Provider HTTP status, when the failure came from a response rather than from the transport. */
     readonly httpStatus?: number;
-    constructor(failureClass: DocumentExtractionFailureClass, message: string, 
+    constructor(failureClass: DocumentExtraction_FailureClass, message: string, 
     /** Provider HTTP status, when the failure came from a response rather than from the transport. */
     httpStatus?: number);
 }
@@ -126,6 +146,14 @@ export interface DocumentExtractionResolvedBinding {
     endpointPath: string;
     apiKeyHeaderName: string;
     apiKeyPrefix: string;
+    /**
+     * The provider's own request projection. Carried on the binding rather than re-read at the call
+     * site so that `resolveBinding` is the ONE place a contract without an executable wire shape is
+     * refused — see the refusal there for why a type is not enough.
+     */
+    buildExtractRequest: (input: DocumentExtractionProviderRequestInput) => DocumentExtractionProviderRequest;
+    /** The provider's own response projection and failure classification. */
+    parseExtractResponse: (response: DocumentExtractionProviderResponseInput) => DocumentExtraction_ProviderExtraction;
 }
 /** Discriminated "is provider extraction possible here?" answer. */
 export type DocumentExtractionBindingResolution = {
@@ -186,32 +214,51 @@ export declare class DocumentExtractionBackendService {
      * physical call emits an agent-call trace (provider, model, pages, outcome) through the standard
      * sink chain, so a reviewer can enumerate what was sent and when.
      * assurance-control: WILDO.PRIVACY.DATA_MINIMIZATION — only the document bytes reach the
-     * provider: no filename, no row context, no identifiers, no organization or user id. The
-     * document is sent as an inline data URI rather than uploaded to the provider's file store,
-     * which means the provider retains no object of ours to delete (its Files API states a 30-day
-     * retention that an inline request never enters). Observability surfaces receive SUMMARIES only
-     * — the bytes and the extracted text never enter a trace, a log, or an error context.
+     * provider: no filename, no row context, no identifiers, no organization or user id. Since
+     * 2026-09-09 that is STRUCTURAL rather than a property of a body this service composes: the
+     * provider's `buildExtractRequest` receives `DocumentExtractionProviderRequestInput`, which
+     * carries the bytes, the MIME type and the resolved model and nothing else, so no provider can
+     * include an identifier it was never given. What FORM the bytes take on the wire is now the
+     * provider's decision and is recorded and pinned in its own module — the wired one inlines them
+     * as a `data:` URI precisely so no object of ours enters the vendor's file-store retention
+     * window. Observability surfaces receive SUMMARIES only — the bytes and the extracted text never
+     * enter a trace, a log, or an error context.
      * assurance-control: WILDO.PRIVACY.THIRD_PARTY_PROCESSING — routing documents here makes the
      * provider a PROCESSOR of application content. It is opt-in by construction: no bytes leave
      * unless an application selects a provider for `AI_DOCUMENT_EXTRACTION`, and with no selection
      * the local library serves every extraction with no egress at all.
      *
-     * Throws {@link DocumentExtractionError} with a {@link DocumentExtractionFailureClass}. See the
+     * Throws {@link DocumentExtractionError} with a {@link DocumentExtraction_FailureClass}. See the
      * file header for why the caller MUST branch on that class rather than treating any failure as
      * an unreadable document.
      */
     extractDocumentText(request: ExtractDocumentTextRequest): Promise<DocumentExtractionProvider_ExtractDocumentTextOutput>;
     /**
      * Attempt the call up to `binding.maxAttempts` times, retrying ONLY
-     * {@link DocumentExtractionFailureClass.PROVIDER_UNAVAILABLE}.
+     * {@link DocumentExtraction_FailureClass.PROVIDER_UNAVAILABLE}.
      *
      * An `UNREADABLE_DOCUMENT` is never retried, and that asymmetry is the point: the same bytes
      * will be judged the same way, so a retry spends a page of billed quota to receive the identical
      * refusal. The classification is what makes the retry policy expressible at all.
      */
     private invokeWithRetries;
-    /** One physical HTTPS request against the provider's declared route. */
+    /**
+     * One physical HTTPS request against the provider's declared route, with the provider's own body
+     * and the provider's own reading of the answer.
+     *
+     * Everything vendor-shaped comes off the contract. The engine contributes the URL, the API-key
+     * header and the timeout — note the header is applied AFTER the provider's transport headers, so
+     * a provider cannot take authentication over by naming that header.
+     */
     private invokeOnce;
+    /** Lower-cased header projection, so a provider's parser can index headers by a stable name. */
+    private responseHeadersToRecord;
+    /**
+     * Decode a response body without assuming it is JSON. A vendor error page is frequently HTML or
+     * plain text, and handing the raw string to the provider's parser is more useful than throwing
+     * before it gets a chance to classify — the parser is the half that knows what its vendor emits.
+     */
+    private bestEffortParseResponseBody;
     /**
      * One trace per physical extraction call — summaries only (file header: the bytes and the
      * extracted text never enter the trace). Best-effort: a sink failure never turns a successful

package/dist/esm/external-providers/services/document-extraction.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-extraction.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/external-providers/services/document-extraction.backend.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"document-extraction.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/services/document-extraction.backend.service.ts"],"names":[],"mappings":"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"}