@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/external-data.exports.js

@@ -0,0 +1,30 @@
+/**
+ * `@wildo-ai/saas-models/external-data` — the AUTHORING contract for data that lives in another
+ * system: the read-through VIRTUAL binding (`httpApiBinding`) and the copy-in PIPELINE
+ * (`externalDataPipeline`).
+ *
+ * ## Why this is a subpath rather than root, and why it is not in `saas-backend-lib`
+ *
+ * Both questions were measured on 2026-08-29 rather than argued.
+ *
+ * It is NOT backend-lib, even though only the backend has a runtime for it, because an application
+ * author writes these declarations in `*.resources-config.ts` — which lives in the app's
+ * `shared-lib`, a package that depends on `@wildo-ai/saas-models` and deliberately NOT on
+ * `@wildo-ai/saas-backend-lib` (the frontend imports `shared-lib`, so a backend dependency there
+ * would drag the backend graph browser-ward). Nothing in these modules is runtime: every symbol —
+ * dialects, tenancy, erasure, key fields, population, orphan policy, coercions — is typed by a
+ * human in a schema file. The runtime that consumes them (read client, extraction source,
+ * transform, run service, batch) is already backend-only.
+ *
+ * It IS a subpath rather than the root barrel because only two audiences need it — the app author
+ * declaring a resource, and the backend executing it — while the root is imported by every
+ * consumer of the resource model, including packages that will never speak to a remote system.
+ * Keeping it out of the root shrinks what they see without moving where it lives.
+ *
+ * ROW IDENTITY deliberately stays in the ROOT (`http-api-binding-id.shared.utils`): a synthesized
+ * id appears in URLs and frontend routing, and `ResourcesConfigUtils.isHttpApiSynthesizedId` reads
+ * it from shared code. Identity is not an integration concern.
+ */
+export * from './http-api-binding/http-api-binding.shared.schemas.js';
+export * from './external-data/external-data-pipeline.shared.schemas.js';
+//# sourceMappingURL=external-data.exports.js.map

package/dist/esm/external-data.exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-data.exports.js","sourceRoot":"","sources":["../../../src/external-data.exports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,cAAc,oDAAoD,CAAC;AACnE,cAAc,uDAAuD,CAAC","sourcesContent":["/**\n * `@wildo-ai/saas-models/external-data` — the AUTHORING contract for data that lives in another\n * system: the read-through VIRTUAL binding (`httpApiBinding`) and the copy-in PIPELINE\n * (`externalDataPipeline`).\n *\n * ## Why this is a subpath rather than root, and why it is not in `saas-backend-lib`\n *\n * Both questions were measured on 2026-08-29 rather than argued.\n *\n * It is NOT backend-lib, even though only the backend has a runtime for it, because an application\n * author writes these declarations in `*.resources-config.ts` — which lives in the app's\n * `shared-lib`, a package that depends on `@wildo-ai/saas-models` and deliberately NOT on\n * `@wildo-ai/saas-backend-lib` (the frontend imports `shared-lib`, so a backend dependency there\n * would drag the backend graph browser-ward). Nothing in these modules is runtime: every symbol —\n * dialects, tenancy, erasure, key fields, population, orphan policy, coercions — is typed by a\n * human in a schema file. The runtime that consumes them (read client, extraction source,\n * transform, run service, batch) is already backend-only.\n *\n * It IS a subpath rather than the root barrel because only two audiences need it — the app author\n * declaring a resource, and the backend executing it — while the root is imported by every\n * consumer of the resource model, including packages that will never speak to a remote system.\n * Keeping it out of the root shrinks what they see without moving where it lives.\n *\n * ROW IDENTITY deliberately stays in the ROOT (`http-api-binding-id.shared.utils`): a synthesized\n * id appears in URLs and frontend routing, and `ResourcesConfigUtils.isHttpApiSynthesizedId` reads\n * it from shared code. Identity is not an integration concern.\n */\nexport * from './http-api-binding/http-api-binding.shared.schemas';\nexport * from './external-data/external-data-pipeline.shared.schemas';\n"]}

package/dist/esm/external-providers/compose-provider-registry.shared.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `composeProviderRegistry` — facet-agnostic registry composition core.
+ *
+ * Each facet (backend, frontend-app, frontend-techdoc, frontend-website)
+ * exposes its own `compose<Facet>Providers` wrapper that delegates here
+ * so the conflict-detection diagnostic, the index-building algorithm,
+ * and the freeze semantics stay identical across the codebase.
+ *
+ * The helper is generic over the facet-brand `TRef` (each facet uses a
+ * branded string for its `ref` to keep cross-facet leakage compile-blocked)
+ * and over the facet module shape `TModule` (constrained to anything with
+ * a `providerCapabilities: ReadonlyArray<ProviderCapability>` field, which
+ * is the one cross-facet invariant — every provider declares what it can
+ * do regardless of facet).
+ *
+ * Conflict policy (locked in analysis §6 / §10 Q4): same `ref` declared in
+ * two or more fragments → THROW with a precise diagnostic listing every
+ * fragment index that contributed the conflicting ref. NO silent override.
+ *
+ * Returned shape: a frozen `ComposedProviderRegistry<TRef, TModule>` with:
+ *   - `modules`                              — direct ref→module map
+ *   - `getProviderByRef(ref)`                — direct lookup
+ *   - `getProvidersByProviderCapability(c)`  — capability fan-out (ordered
+ *                                              by fragment index, then by
+ *                                              insertion order within each
+ *                                              fragment's `modules` Map)
+ *   - `findProviderByProviderCapability(c)`  — first match (single-fulfiller)
+ *
+ * The returned object surface is `Object.freeze`d; the underlying `Map`
+ * and array references are NOT defensively cloned on every read — the
+ * `Readonly` typing at consumer sites is the contract, and the builder is
+ * the sole writer.
+ *
+ * See `.cursor/plans/provider-registration-refactor-implementation-plan.md`
+ * §Phase 1.e for the canonical contract.
+ */
+import type { ProviderCapability } from './provider-capability.shared.schemas';
+export interface ProviderRegistryFragment<TRef extends string, TModule extends {
+    readonly providerCapabilities: ReadonlyArray<ProviderCapability>;
+}> {
+    readonly modules: ReadonlyMap<TRef, TModule>;
+}
+export interface ComposedProviderRegistry<TRef extends string, TModule extends {
+    readonly providerCapabilities: ReadonlyArray<ProviderCapability>;
+}> {
+    readonly modules: ReadonlyMap<TRef, TModule>;
+    getProviderByRef(ref: TRef): TModule | undefined;
+    getProvidersByProviderCapability(providerCapability: ProviderCapability): ReadonlyArray<TModule>;
+    findProviderByProviderCapability(providerCapability: ProviderCapability): TModule | undefined;
+}
+export interface ProviderCompositionConflict<TRef extends string> {
+    ref: TRef;
+    fragmentIndexes: ReadonlyArray<number>;
+}
+export declare class ProviderCompositionConflictError<TRef extends string> extends Error {
+    readonly facet: string;
+    readonly conflicts: ReadonlyArray<ProviderCompositionConflict<TRef>>;
+    constructor(facet: string, conflicts: ReadonlyArray<ProviderCompositionConflict<TRef>>);
+}
+export declare function composeProviderRegistry<TRef extends string, TModule extends {
+    readonly providerCapabilities: ReadonlyArray<ProviderCapability>;
+}>(facet: string, fragments: ReadonlyArray<ProviderRegistryFragment<TRef, TModule>>): ComposedProviderRegistry<TRef, TModule>;
+//# sourceMappingURL=compose-provider-registry.shared.d.ts.map

package/dist/esm/external-providers/compose-provider-registry.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-provider-registry.shared.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/compose-provider-registry.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE/E,MAAM,WAAW,wBAAwB,CACvC,IAAI,SAAS,MAAM,EACnB,OAAO,SAAS;IAAE,QAAQ,CAAC,oBAAoB,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;CAAE;IAEpF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,wBAAwB,CACvC,IAAI,SAAS,MAAM,EACnB,OAAO,SAAS;IAAE,QAAQ,CAAC,oBAAoB,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;CAAE;IAEpF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7C,gBAAgB,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACjD,gCAAgC,CAC9B,kBAAkB,EAAE,kBAAkB,GACrC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1B,gCAAgC,CAC9B,kBAAkB,EAAE,kBAAkB,GACrC,OAAO,GAAG,SAAS,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B,CAAC,IAAI,SAAS,MAAM;IAC9D,GAAG,EAAE,IAAI,CAAC;IACV,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,qBAAa,gCAAgC,CAAC,IAAI,SAAS,MAAM,CAAE,SAAQ,KAAK;IAC9E,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,SAAS,EAAE,aAAa,CAAC,2BAA2B,CAAC,IAAI,CAAC,CAAC,CAAC;gBAG1E,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,aAAa,CAAC,2BAA2B,CAAC,IAAI,CAAC,CAAC;CAc9D;AAED,wBAAgB,uBAAuB,CACrC,IAAI,SAAS,MAAM,EACnB,OAAO,SAAS;IAAE,QAAQ,CAAC,oBAAoB,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;CAAE,EAEpF,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,aAAa,CAAC,wBAAwB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,GAChE,wBAAwB,CAAC,IAAI,EAAE,OAAO,CAAC,CAsDzC"}

package/dist/esm/external-providers/compose-provider-registry.shared.js

@@ -0,0 +1,102 @@
+/**
+ * `composeProviderRegistry` — facet-agnostic registry composition core.
+ *
+ * Each facet (backend, frontend-app, frontend-techdoc, frontend-website)
+ * exposes its own `compose<Facet>Providers` wrapper that delegates here
+ * so the conflict-detection diagnostic, the index-building algorithm,
+ * and the freeze semantics stay identical across the codebase.
+ *
+ * The helper is generic over the facet-brand `TRef` (each facet uses a
+ * branded string for its `ref` to keep cross-facet leakage compile-blocked)
+ * and over the facet module shape `TModule` (constrained to anything with
+ * a `providerCapabilities: ReadonlyArray<ProviderCapability>` field, which
+ * is the one cross-facet invariant — every provider declares what it can
+ * do regardless of facet).
+ *
+ * Conflict policy (locked in analysis §6 / §10 Q4): same `ref` declared in
+ * two or more fragments → THROW with a precise diagnostic listing every
+ * fragment index that contributed the conflicting ref. NO silent override.
+ *
+ * Returned shape: a frozen `ComposedProviderRegistry<TRef, TModule>` with:
+ *   - `modules`                              — direct ref→module map
+ *   - `getProviderByRef(ref)`                — direct lookup
+ *   - `getProvidersByProviderCapability(c)`  — capability fan-out (ordered
+ *                                              by fragment index, then by
+ *                                              insertion order within each
+ *                                              fragment's `modules` Map)
+ *   - `findProviderByProviderCapability(c)`  — first match (single-fulfiller)
+ *
+ * The returned object surface is `Object.freeze`d; the underlying `Map`
+ * and array references are NOT defensively cloned on every read — the
+ * `Readonly` typing at consumer sites is the contract, and the builder is
+ * the sole writer.
+ *
+ * See `.cursor/plans/provider-registration-refactor-implementation-plan.md`
+ * §Phase 1.e for the canonical contract.
+ */
+export class ProviderCompositionConflictError extends Error {
+    facet;
+    conflicts;
+    constructor(facet, conflicts) {
+        const lines = conflicts.map(({ ref, fragmentIndexes }) => `  - ref "${ref}" declared by fragments [${fragmentIndexes.join(', ')}]`);
+        super(`[compose${facet}Providers] conflicting provider refs across fragments:\n${lines.join('\n')}\n` +
+            'Resolution: pick a different ref OR drop the conflicting fragment from the composition call.');
+        this.name = 'ProviderCompositionConflictError';
+        this.facet = facet;
+        this.conflicts = conflicts;
+    }
+}
+export function composeProviderRegistry(facet, fragments) {
+    const refOwners = new Map();
+    for (let index = 0; index < fragments.length; index += 1) {
+        for (const ref of fragments[index].modules.keys()) {
+            const existing = refOwners.get(ref);
+            if (existing) {
+                existing.push(index);
+            }
+            else {
+                refOwners.set(ref, [index]);
+            }
+        }
+    }
+    const conflicts = [];
+    for (const [ref, indexes] of refOwners) {
+        if (indexes.length > 1) {
+            conflicts.push({ ref, fragmentIndexes: indexes });
+        }
+    }
+    if (conflicts.length > 0) {
+        throw new ProviderCompositionConflictError(facet, conflicts);
+    }
+    const byRef = new Map();
+    const byProviderCapability = new Map();
+    for (const fragment of fragments) {
+        for (const [ref, module] of fragment.modules) {
+            byRef.set(ref, module);
+            for (const capability of module.providerCapabilities) {
+                const bucket = byProviderCapability.get(capability);
+                if (bucket) {
+                    bucket.push(module);
+                }
+                else {
+                    byProviderCapability.set(capability, [module]);
+                }
+            }
+        }
+    }
+    const registry = {
+        modules: byRef,
+        getProviderByRef(ref) {
+            return byRef.get(ref);
+        },
+        getProvidersByProviderCapability(providerCapability) {
+            return byProviderCapability.get(providerCapability) ?? [];
+        },
+        findProviderByProviderCapability(providerCapability) {
+            const bucket = byProviderCapability.get(providerCapability);
+            return bucket && bucket.length > 0 ? bucket[0] : undefined;
+        },
+    };
+    return Object.freeze(registry);
+}
+//# sourceMappingURL=compose-provider-registry.shared.js.map

package/dist/esm/external-providers/compose-provider-registry.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-provider-registry.shared.js","sourceRoot":"","sources":["../../../../src/external-providers/compose-provider-registry.shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `composeProviderRegistry` — facet-agnostic registry composition core.\n *\n * Each facet (backend, frontend-app, frontend-techdoc, frontend-website)\n * exposes its own `compose<Facet>Providers` wrapper that delegates here\n * so the conflict-detection diagnostic, the index-building algorithm,\n * and the freeze semantics stay identical across the codebase.\n *\n * The helper is generic over the facet-brand `TRef` (each facet uses a\n * branded string for its `ref` to keep cross-facet leakage compile-blocked)\n * and over the facet module shape `TModule` (constrained to anything with\n * a `providerCapabilities: ReadonlyArray<ProviderCapability>` field, which\n * is the one cross-facet invariant — every provider declares what it can\n * do regardless of facet).\n *\n * Conflict policy (locked in analysis §6 / §10 Q4): same `ref` declared in\n * two or more fragments → THROW with a precise diagnostic listing every\n * fragment index that contributed the conflicting ref. NO silent override.\n *\n * Returned shape: a frozen `ComposedProviderRegistry<TRef, TModule>` with:\n *   - `modules`                              — direct ref→module map\n *   - `getProviderByRef(ref)`                — direct lookup\n *   - `getProvidersByProviderCapability(c)`  — capability fan-out (ordered\n *                                              by fragment index, then by\n *                                              insertion order within each\n *                                              fragment's `modules` Map)\n *   - `findProviderByProviderCapability(c)`  — first match (single-fulfiller)\n *\n * The returned object surface is `Object.freeze`d; the underlying `Map`\n * and array references are NOT defensively cloned on every read — the\n * `Readonly` typing at consumer sites is the contract, and the builder is\n * the sole writer.\n *\n * See `.cursor/plans/provider-registration-refactor-implementation-plan.md`\n * §Phase 1.e for the canonical contract.\n */\n\nimport type { ProviderCapability } from './provider-capability.shared.schemas';\n\nexport interface ProviderRegistryFragment<\n  TRef extends string,\n  TModule extends { readonly providerCapabilities: ReadonlyArray<ProviderCapability> },\n> {\n  readonly modules: ReadonlyMap<TRef, TModule>;\n}\n\nexport interface ComposedProviderRegistry<\n  TRef extends string,\n  TModule extends { readonly providerCapabilities: ReadonlyArray<ProviderCapability> },\n> {\n  readonly modules: ReadonlyMap<TRef, TModule>;\n  getProviderByRef(ref: TRef): TModule | undefined;\n  getProvidersByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): ReadonlyArray<TModule>;\n  findProviderByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): TModule | undefined;\n}\n\nexport interface ProviderCompositionConflict<TRef extends string> {\n  ref: TRef;\n  fragmentIndexes: ReadonlyArray<number>;\n}\n\nexport class ProviderCompositionConflictError<TRef extends string> extends Error {\n  public readonly facet: string;\n  public readonly conflicts: ReadonlyArray<ProviderCompositionConflict<TRef>>;\n\n  constructor(\n    facet: string,\n    conflicts: ReadonlyArray<ProviderCompositionConflict<TRef>>,\n  ) {\n    const lines = conflicts.map(\n      ({ ref, fragmentIndexes }) =>\n        `  - ref \"${ref}\" declared by fragments [${fragmentIndexes.join(', ')}]`,\n    );\n    super(\n      `[compose${facet}Providers] conflicting provider refs across fragments:\\n${lines.join('\\n')}\\n` +\n        'Resolution: pick a different ref OR drop the conflicting fragment from the composition call.',\n    );\n    this.name = 'ProviderCompositionConflictError';\n    this.facet = facet;\n    this.conflicts = conflicts;\n  }\n}\n\nexport function composeProviderRegistry<\n  TRef extends string,\n  TModule extends { readonly providerCapabilities: ReadonlyArray<ProviderCapability> },\n>(\n  facet: string,\n  fragments: ReadonlyArray<ProviderRegistryFragment<TRef, TModule>>,\n): ComposedProviderRegistry<TRef, TModule> {\n  const refOwners = new Map<TRef, number[]>();\n  for (let index = 0; index < fragments.length; index += 1) {\n    for (const ref of fragments[index].modules.keys()) {\n      const existing = refOwners.get(ref);\n      if (existing) {\n        existing.push(index);\n      } else {\n        refOwners.set(ref, [index]);\n      }\n    }\n  }\n\n  const conflicts: ProviderCompositionConflict<TRef>[] = [];\n  for (const [ref, indexes] of refOwners) {\n    if (indexes.length > 1) {\n      conflicts.push({ ref, fragmentIndexes: indexes });\n    }\n  }\n  if (conflicts.length > 0) {\n    throw new ProviderCompositionConflictError<TRef>(facet, conflicts);\n  }\n\n  const byRef = new Map<TRef, TModule>();\n  const byProviderCapability = new Map<ProviderCapability, TModule[]>();\n  for (const fragment of fragments) {\n    for (const [ref, module] of fragment.modules) {\n      byRef.set(ref, module);\n      for (const capability of module.providerCapabilities) {\n        const bucket = byProviderCapability.get(capability);\n        if (bucket) {\n          bucket.push(module);\n        } else {\n          byProviderCapability.set(capability, [module]);\n        }\n      }\n    }\n  }\n\n  const registry: ComposedProviderRegistry<TRef, TModule> = {\n    modules: byRef,\n    getProviderByRef(ref) {\n      return byRef.get(ref);\n    },\n    getProvidersByProviderCapability(providerCapability) {\n      return byProviderCapability.get(providerCapability) ?? [];\n    },\n    findProviderByProviderCapability(providerCapability) {\n      const bucket = byProviderCapability.get(providerCapability);\n      return bucket && bucket.length > 0 ? bucket[0] : undefined;\n    },\n  };\n\n  return Object.freeze(registry);\n}\n"]}

package/dist/esm/external-providers/engine-capabilities.shared.schemas.d.ts

@@ -0,0 +1,164 @@
+import { type BuiltinProviderCapability } from './provider-capability.shared.schemas';
+/** @wildo_source:part:start saas.models.engine-capabilities facet:kind:api facet:audience:app-developer
+ *
+ * Closed application capability vocabulary used to declare what the
+ * application needs from its configured providers.
+ *
+ * `EngineCapability` no longer means "feature gate id" and no longer
+ * carries provider routing by itself. Provider-backed fulfillment is selected
+ * by the application's provider configuration; entitlement/billing features
+ * remain application feature decisions. Import this enum from
+ * `@wildo-ai/saas-models` and declare only capabilities the application
+ * actually intends to configure and operate.
+ */
+export declare enum EngineCapability {
+    ORGANIZATIONS = "ORGANIZATIONS",
+    BILLING = "BILLING",
+    BILLING_PAYMENTS = "BILLING_PAYMENTS",
+    MULTI_LANGUAGE = "MULTI_LANGUAGE",
+    COMPLIANCE_AUDIT_TRAIL = "COMPLIANCE_AUDIT_TRAIL",
+    EMAIL_TRANSACTIONAL = "EMAIL_TRANSACTIONAL",
+    EMAIL_MARKETING = "EMAIL_MARKETING",
+    SMS = "SMS",
+    AI_LLM = "AI_LLM",
+    AI_IMAGE_GENERATION = "AI_IMAGE_GENERATION",
+    /**
+     * Text → vector embeddings (the RAG derived-data tier: `.ragSource()` corpus embedding by the
+     * `rag:embedding-drain` worker, and query-time embedding in retrieval). A slot of its OWN,
+     * deliberately separate from `AI_LLM` (RAG plan DL2/H4): while `LLM_EMBEDDINGS` mapped into the
+     * `AI_LLM` slot, an application structurally could not pick Anthropic for chat and a different
+     * provider for embeddings — one `selection[AI_LLM].primary` decided both. Embeddings resolve
+     * through `EMBEDDINGS_PROVIDER` protocol bindings and are selected by applicability class
+     * (`Embeddings_Applicability`), never by a concrete model id at a call site.
+     */
+    AI_EMBEDDINGS = "AI_EMBEDDINGS",
+    /**
+     * Document bytes → text: provider-backed extraction (OCR) for uploaded documents, serving
+     * `FileTextExtractionBackendService` and, through it, `.ragSource()` corpus ingestion.
+     *
+     * ## Why a slot of its own
+     *
+     * Three unrelated procurement decisions were otherwise fused. A deployment may well want one
+     * vendor for chat, another for embeddings, and a third for OCR — vendors are not equally good
+     * at all three, and their pricing models do not even share a unit (tokens vs. pages). Mapping
+     * extraction into `AI_LLM` would have made one `selection[AI_LLM].primary` decide all three,
+     * which is exactly the defect that split `AI_EMBEDDINGS` out of `AI_LLM`.
+     *
+     * ## Not to be confused with `DOCUMENT_GENERATION`
+     *
+     * `DOCUMENT_GENERATION` is PDF *generation* — templates and data become bytes. This is the
+     * opposite direction: bytes become text. The names are adjacent and the capabilities are
+     * unrelated; nothing routes between them.
+     *
+     * ## Absence is benign, and that is load-bearing
+     *
+     * With no provider selected, extraction falls back to the local `pdfjs-dist` text-layer read.
+     * That is a real answer for a born-digital PDF and returns nothing for a SCAN — so this
+     * capability is what makes scanned documents answerable, never what makes extraction work at
+     * all. An application that ingests only born-digital documents may leave it unset deliberately.
+     */
+    AI_DOCUMENT_EXTRACTION = "AI_DOCUMENT_EXTRACTION",
+    /**
+     * An autonomous coding agent that mutates the application workspace.
+     *
+     * Its own slot rather than `AI_LLM`, for exactly the reason `AI_EMBEDDINGS`
+     * was split out of it: one `selection[AI_LLM].primary` decides every provider
+     * mapped into that slot. While the coding transport mapped to `AI_LLM`, an
+     * application structurally could NOT choose one vendor's coding agent and a
+     * different vendor for chat — picking a chat provider silently picked the
+     * agent that would be allowed to edit its source.
+     *
+     * The stakes differ too, which is why fusing them was wrong beyond the
+     * ergonomics: selecting a chat model is a quality and cost decision, while
+     * selecting the agent that writes your code is those things AND an
+     * authorisation decision. They deserve separate, deliberate answers.
+     */
+    AI_CODING_AGENT = "AI_CODING_AGENT",
+    DOCUMENT_GENERATION = "DOCUMENT_GENERATION",
+    ANTIVIRUS_SCANNING = "ANTIVIRUS_SCANNING",
+    FRONTEND_ERROR_MONITORING = "FRONTEND_ERROR_MONITORING",
+    FRONTEND_PRODUCT_ANALYTICS = "FRONTEND_PRODUCT_ANALYTICS",
+    /**
+     * Backend LLM-call observability (model/tokens/cost/latency per `invokeAgent`),
+     * platform-scoped. This enables model-call observability when the selected
+     * provider configuration supplies that capability; it does not itself
+     * configure a provider or make telemetry operational.
+     */
+    LLM_OBSERVABILITY = "LLM_OBSERVABILITY",
+    /**
+     * Operational telemetry (traces/metrics/logs) shipped via the OpenTelemetry
+     * SDK over OTLP to a provider (for example, BetterStack). Unlike
+     * `LLM_OBSERVABILITY`, the connection is preloaded from
+     * `OTEL_*` env vars (the CLI translates the saas-config selection + per-env
+     * infra config into them) BEFORE app config — not resolved through the runtime
+     * registry. Author the corresponding infrastructure/provider settings in
+     * the application environment before relying on telemetry.
+     */
+    OBSERVABILITY_TELEMETRY = "OBSERVABILITY_TELEMETRY"
+}
+/** @wildo_source:part:end saas.models.engine-capabilities */
+/**
+ * Canonical, single-source-of-truth mapping from the open
+ * `ProviderCapability` vocabulary (the built-in subset) to the closed
+ * `EngineCapability` slots the engine actually fulfills.
+ *
+ * A provider declares which `providerCapabilities` it satisfies (e.g.
+ * Stripe → `BILLING`, Resend → `EMAIL_TRANSACTIONAL`, Anthropic →
+ * `LLM_CHAT`/`CODING_AGENT`). This map projects each built-in
+ * capability onto the engine slot it fills, so a provider's
+ * `engineCapabilities` set can be derived mechanically. Multiple
+ * provider capabilities may share one engine slot (every `LLM_*`
+ * capability maps to `AI_LLM`); de-duplicate after projecting.
+ *
+ * **Why this lives here (one map, three consumers).** The projection
+ * used to be hand-copied in three places that silently drifted:
+ *   1. The runtime registry projection in `saas-backend-lib`
+ *      (`ExternalProvidersRegistryBackendService.buildRuntimeRegistryFromProviderModules`),
+ *      which decides which provider answers `getProvidersForEngineCapability`.
+ *   2. The backend companion-discovery export in
+ *      `@wildo-ai/external-connectors-private` (feeds the generated
+ *      `provider-catalog.types.ts` autocomplete via `wildo config sync`).
+ *   3. The frontend companion-discovery export in
+ *      `@wildo-ai/external-connectors-public` (same, for browser-bound
+ *      provider modules).
+ * A missing/wrong entry in any copy silently breaks a different surface
+ * (a registry resolution, or the catalog autocomplete). It is co-located
+ * with the `EngineCapability` enum it projects onto, and every consumer
+ * imports it from the `@wildo-ai/saas-models` package root barrel.
+ *
+ * **Bundle boundary — why here and not beside `BUILTIN_PROVIDER_CAPABILITY`.**
+ * This map references `EngineCapability`, which is deliberately kept off
+ * the browser-safe `@wildo-ai/saas-models/public-runtime` seam. So it must
+ * live in a full-only module. `engine-capabilities.shared.schemas.ts` is
+ * exactly that (exported from the root barrel, never from
+ * `public-runtime/index.ts`), whereas `provider-capability.shared.schemas.ts`
+ * — the other natural home — IS on the public seam and would drag
+ * `EngineCapability` into the browser bundle. The frontend discovery
+ * consumer (#3) imports this map through its Node-only `./companion`
+ * subpath, which already pulls the full root barrel; the browser-shipped
+ * `./app`/`./techdoc`/`./website` subpaths never reach it.
+ *
+ * **BILLING → BILLING (not BILLING_PAYMENTS).** A billing provider
+ * (Stripe) declares `BUILTIN_PROVIDER_CAPABILITY.BILLING` and fills the
+ * `EngineCapability.BILLING` slot — the SAME slot apps enable in
+ * `defineSaaSProviders`/`engineCapabilities` activation config and that
+ * `getProvidersForEngineCapability` gates resolution on. Mapping it to
+ * the distinct `EngineCapability.BILLING_PAYMENTS` slot (as the runtime
+ * copy historically did) registered Stripe under a slot no activation
+ * config enables and no consumer queries, making it unreachable through
+ * the registry. `BILLING_PAYMENTS` currently has no producer or consumer
+ * other than that former bug; it is left in the enum as a reserved slot.
+ *
+ * **Intentionally unmapped.** `SSO_OAUTH2`, `SSO_SAML`, `FRONTEND_SEARCH`,
+ * `FRONTEND_FILE_PICKER`, and `FRONTEND_CAPTCHA` have no closed engine
+ * slot today — they are fulfilled by provider protocols / app wiring, not
+ * by an `EngineCapability`. Their absence here is by construction, not an
+ * oversight: a `Partial<Record<…>>` lookup returns `undefined` and the
+ * capability contributes nothing to a provider's `engineCapabilities`.
+ *
+ * App-extended (kebab-case) provider capabilities never appear here:
+ * they live in the open `AppCustomProviderCapabilities` namespace and
+ * have no engine slot by definition.
+ */
+export declare const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY: Partial<Record<BuiltinProviderCapability, EngineCapability>>;
+//# sourceMappingURL=engine-capabilities.shared.schemas.d.ts.map

package/dist/esm/external-providers/engine-capabilities.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-capabilities.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/engine-capabilities.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAEnH;;;;;;;;;;;GAWG;AACH,oBAAY,gBAAgB;IAC1B,aAAa,kBAAkB;IAC/B,OAAO,YAAY;IACnB,gBAAgB,qBAAqB;IACrC,cAAc,mBAAmB;IACjC,sBAAsB,2BAA2B;IAEjD,mBAAmB,wBAAwB;IAC3C,eAAe,oBAAoB;IACnC,GAAG,QAAQ;IAEX,MAAM,WAAW;IACjB,mBAAmB,wBAAwB;IAC3C;;;;;;;;OAQG;IACH,aAAa,kBAAkB;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,sBAAsB,2BAA2B;IACjD;;;;;;;;;;;;;;OAcG;IACH,eAAe,oBAAoB;IAEnC,mBAAmB,wBAAwB;IAC3C,kBAAkB,uBAAuB;IAEzC,yBAAyB,8BAA8B;IACvD,0BAA0B,+BAA+B;IAEzD;;;;;OAKG;IACH,iBAAiB,sBAAsB;IAEvC;;;;;;;;OAQG;IACH,uBAAuB,4BAA4B;CACpD;AACD,6DAA6D;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,eAAO,MAAM,wCAAwC,EAAE,OAAO,CAC5D,MAAM,CAAC,yBAAyB,EAAE,gBAAgB,CAAC,CA8BpD,CAAC"}

package/dist/esm/external-providers/engine-capabilities.shared.schemas.js

@@ -0,0 +1,194 @@
+import { BUILTIN_PROVIDER_CAPABILITY } from './provider-capability.shared.schemas.js';
+/** @wildo_source:part:start saas.models.engine-capabilities facet:kind:api facet:audience:app-developer
+ *
+ * Closed application capability vocabulary used to declare what the
+ * application needs from its configured providers.
+ *
+ * `EngineCapability` no longer means "feature gate id" and no longer
+ * carries provider routing by itself. Provider-backed fulfillment is selected
+ * by the application's provider configuration; entitlement/billing features
+ * remain application feature decisions. Import this enum from
+ * `@wildo-ai/saas-models` and declare only capabilities the application
+ * actually intends to configure and operate.
+ */
+export var EngineCapability;
+(function (EngineCapability) {
+    EngineCapability["ORGANIZATIONS"] = "ORGANIZATIONS";
+    EngineCapability["BILLING"] = "BILLING";
+    EngineCapability["BILLING_PAYMENTS"] = "BILLING_PAYMENTS";
+    EngineCapability["MULTI_LANGUAGE"] = "MULTI_LANGUAGE";
+    EngineCapability["COMPLIANCE_AUDIT_TRAIL"] = "COMPLIANCE_AUDIT_TRAIL";
+    EngineCapability["EMAIL_TRANSACTIONAL"] = "EMAIL_TRANSACTIONAL";
+    EngineCapability["EMAIL_MARKETING"] = "EMAIL_MARKETING";
+    EngineCapability["SMS"] = "SMS";
+    EngineCapability["AI_LLM"] = "AI_LLM";
+    EngineCapability["AI_IMAGE_GENERATION"] = "AI_IMAGE_GENERATION";
+    /**
+     * Text → vector embeddings (the RAG derived-data tier: `.ragSource()` corpus embedding by the
+     * `rag:embedding-drain` worker, and query-time embedding in retrieval). A slot of its OWN,
+     * deliberately separate from `AI_LLM` (RAG plan DL2/H4): while `LLM_EMBEDDINGS` mapped into the
+     * `AI_LLM` slot, an application structurally could not pick Anthropic for chat and a different
+     * provider for embeddings — one `selection[AI_LLM].primary` decided both. Embeddings resolve
+     * through `EMBEDDINGS_PROVIDER` protocol bindings and are selected by applicability class
+     * (`Embeddings_Applicability`), never by a concrete model id at a call site.
+     */
+    EngineCapability["AI_EMBEDDINGS"] = "AI_EMBEDDINGS";
+    /**
+     * Document bytes → text: provider-backed extraction (OCR) for uploaded documents, serving
+     * `FileTextExtractionBackendService` and, through it, `.ragSource()` corpus ingestion.
+     *
+     * ## Why a slot of its own
+     *
+     * Three unrelated procurement decisions were otherwise fused. A deployment may well want one
+     * vendor for chat, another for embeddings, and a third for OCR — vendors are not equally good
+     * at all three, and their pricing models do not even share a unit (tokens vs. pages). Mapping
+     * extraction into `AI_LLM` would have made one `selection[AI_LLM].primary` decide all three,
+     * which is exactly the defect that split `AI_EMBEDDINGS` out of `AI_LLM`.
+     *
+     * ## Not to be confused with `DOCUMENT_GENERATION`
+     *
+     * `DOCUMENT_GENERATION` is PDF *generation* — templates and data become bytes. This is the
+     * opposite direction: bytes become text. The names are adjacent and the capabilities are
+     * unrelated; nothing routes between them.
+     *
+     * ## Absence is benign, and that is load-bearing
+     *
+     * With no provider selected, extraction falls back to the local `pdfjs-dist` text-layer read.
+     * That is a real answer for a born-digital PDF and returns nothing for a SCAN — so this
+     * capability is what makes scanned documents answerable, never what makes extraction work at
+     * all. An application that ingests only born-digital documents may leave it unset deliberately.
+     */
+    EngineCapability["AI_DOCUMENT_EXTRACTION"] = "AI_DOCUMENT_EXTRACTION";
+    /**
+     * An autonomous coding agent that mutates the application workspace.
+     *
+     * Its own slot rather than `AI_LLM`, for exactly the reason `AI_EMBEDDINGS`
+     * was split out of it: one `selection[AI_LLM].primary` decides every provider
+     * mapped into that slot. While the coding transport mapped to `AI_LLM`, an
+     * application structurally could NOT choose one vendor's coding agent and a
+     * different vendor for chat — picking a chat provider silently picked the
+     * agent that would be allowed to edit its source.
+     *
+     * The stakes differ too, which is why fusing them was wrong beyond the
+     * ergonomics: selecting a chat model is a quality and cost decision, while
+     * selecting the agent that writes your code is those things AND an
+     * authorisation decision. They deserve separate, deliberate answers.
+     */
+    EngineCapability["AI_CODING_AGENT"] = "AI_CODING_AGENT";
+    EngineCapability["DOCUMENT_GENERATION"] = "DOCUMENT_GENERATION";
+    EngineCapability["ANTIVIRUS_SCANNING"] = "ANTIVIRUS_SCANNING";
+    EngineCapability["FRONTEND_ERROR_MONITORING"] = "FRONTEND_ERROR_MONITORING";
+    EngineCapability["FRONTEND_PRODUCT_ANALYTICS"] = "FRONTEND_PRODUCT_ANALYTICS";
+    /**
+     * Backend LLM-call observability (model/tokens/cost/latency per `invokeAgent`),
+     * platform-scoped. This enables model-call observability when the selected
+     * provider configuration supplies that capability; it does not itself
+     * configure a provider or make telemetry operational.
+     */
+    EngineCapability["LLM_OBSERVABILITY"] = "LLM_OBSERVABILITY";
+    /**
+     * Operational telemetry (traces/metrics/logs) shipped via the OpenTelemetry
+     * SDK over OTLP to a provider (for example, BetterStack). Unlike
+     * `LLM_OBSERVABILITY`, the connection is preloaded from
+     * `OTEL_*` env vars (the CLI translates the saas-config selection + per-env
+     * infra config into them) BEFORE app config — not resolved through the runtime
+     * registry. Author the corresponding infrastructure/provider settings in
+     * the application environment before relying on telemetry.
+     */
+    EngineCapability["OBSERVABILITY_TELEMETRY"] = "OBSERVABILITY_TELEMETRY";
+})(EngineCapability || (EngineCapability = {}));
+/** @wildo_source:part:end saas.models.engine-capabilities */
+/**
+ * Canonical, single-source-of-truth mapping from the open
+ * `ProviderCapability` vocabulary (the built-in subset) to the closed
+ * `EngineCapability` slots the engine actually fulfills.
+ *
+ * A provider declares which `providerCapabilities` it satisfies (e.g.
+ * Stripe → `BILLING`, Resend → `EMAIL_TRANSACTIONAL`, Anthropic →
+ * `LLM_CHAT`/`CODING_AGENT`). This map projects each built-in
+ * capability onto the engine slot it fills, so a provider's
+ * `engineCapabilities` set can be derived mechanically. Multiple
+ * provider capabilities may share one engine slot (every `LLM_*`
+ * capability maps to `AI_LLM`); de-duplicate after projecting.
+ *
+ * **Why this lives here (one map, three consumers).** The projection
+ * used to be hand-copied in three places that silently drifted:
+ *   1. The runtime registry projection in `saas-backend-lib`
+ *      (`ExternalProvidersRegistryBackendService.buildRuntimeRegistryFromProviderModules`),
+ *      which decides which provider answers `getProvidersForEngineCapability`.
+ *   2. The backend companion-discovery export in
+ *      `@wildo-ai/external-connectors-private` (feeds the generated
+ *      `provider-catalog.types.ts` autocomplete via `wildo config sync`).
+ *   3. The frontend companion-discovery export in
+ *      `@wildo-ai/external-connectors-public` (same, for browser-bound
+ *      provider modules).
+ * A missing/wrong entry in any copy silently breaks a different surface
+ * (a registry resolution, or the catalog autocomplete). It is co-located
+ * with the `EngineCapability` enum it projects onto, and every consumer
+ * imports it from the `@wildo-ai/saas-models` package root barrel.
+ *
+ * **Bundle boundary — why here and not beside `BUILTIN_PROVIDER_CAPABILITY`.**
+ * This map references `EngineCapability`, which is deliberately kept off
+ * the browser-safe `@wildo-ai/saas-models/public-runtime` seam. So it must
+ * live in a full-only module. `engine-capabilities.shared.schemas.ts` is
+ * exactly that (exported from the root barrel, never from
+ * `public-runtime/index.ts`), whereas `provider-capability.shared.schemas.ts`
+ * — the other natural home — IS on the public seam and would drag
+ * `EngineCapability` into the browser bundle. The frontend discovery
+ * consumer (#3) imports this map through its Node-only `./companion`
+ * subpath, which already pulls the full root barrel; the browser-shipped
+ * `./app`/`./techdoc`/`./website` subpaths never reach it.
+ *
+ * **BILLING → BILLING (not BILLING_PAYMENTS).** A billing provider
+ * (Stripe) declares `BUILTIN_PROVIDER_CAPABILITY.BILLING` and fills the
+ * `EngineCapability.BILLING` slot — the SAME slot apps enable in
+ * `defineSaaSProviders`/`engineCapabilities` activation config and that
+ * `getProvidersForEngineCapability` gates resolution on. Mapping it to
+ * the distinct `EngineCapability.BILLING_PAYMENTS` slot (as the runtime
+ * copy historically did) registered Stripe under a slot no activation
+ * config enables and no consumer queries, making it unreachable through
+ * the registry. `BILLING_PAYMENTS` currently has no producer or consumer
+ * other than that former bug; it is left in the enum as a reserved slot.
+ *
+ * **Intentionally unmapped.** `SSO_OAUTH2`, `SSO_SAML`, `FRONTEND_SEARCH`,
+ * `FRONTEND_FILE_PICKER`, and `FRONTEND_CAPTCHA` have no closed engine
+ * slot today — they are fulfilled by provider protocols / app wiring, not
+ * by an `EngineCapability`. Their absence here is by construction, not an
+ * oversight: a `Partial<Record<…>>` lookup returns `undefined` and the
+ * capability contributes nothing to a provider's `engineCapabilities`.
+ *
+ * App-extended (kebab-case) provider capabilities never appear here:
+ * they live in the open `AppCustomProviderCapabilities` namespace and
+ * have no engine slot by definition.
+ */
+export const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY = {
+    [BUILTIN_PROVIDER_CAPABILITY.EMAIL_TRANSACTIONAL]: EngineCapability.EMAIL_TRANSACTIONAL,
+    [BUILTIN_PROVIDER_CAPABILITY.EMAIL_MARKETING]: EngineCapability.EMAIL_MARKETING,
+    [BUILTIN_PROVIDER_CAPABILITY.SMS]: EngineCapability.SMS,
+    [BUILTIN_PROVIDER_CAPABILITY.BILLING]: EngineCapability.BILLING,
+    [BUILTIN_PROVIDER_CAPABILITY.LLM_CHAT]: EngineCapability.AI_LLM,
+    /**
+     * REPOINTED 2026-08-27 (RAG plan DL2/H4): `LLM_EMBEDDINGS` used to map into `AI_LLM`, which
+     * fused the chat and embeddings provider selections into one slot. The TOKEN keeps its name —
+     * it correctly says "this provider can produce embeddings", and it sits inside the anchored
+     * `saas.models.provider-capabilities` block compiled into shipped skills — only the slot it
+     * fills changed. Exactly one token claims the embeddings slot.
+     */
+    [BUILTIN_PROVIDER_CAPABILITY.LLM_EMBEDDINGS]: EngineCapability.AI_EMBEDDINGS,
+    /**
+     * EXACTLY ONE token claims the document-extraction slot, and it is a new one. Checked rather
+     * than assumed before adding it: `IMAGE_GENERATION` maps to `AI_IMAGE_GENERATION` (output),
+     * `LLM_CHAT` to `AI_LLM`, `LLM_EMBEDDINGS` to `AI_EMBEDDINGS`, and no built-in token mapped
+     * anywhere near document INPUT. Repointing an existing token — the move that kept
+     * `LLM_EMBEDDINGS` alive — was not available here because none of them meant this.
+     */
+    [BUILTIN_PROVIDER_CAPABILITY.DOCUMENT_TEXT_EXTRACTION]: EngineCapability.AI_DOCUMENT_EXTRACTION,
+    [BUILTIN_PROVIDER_CAPABILITY.CODING_AGENT]: EngineCapability.AI_CODING_AGENT,
+    [BUILTIN_PROVIDER_CAPABILITY.IMAGE_GENERATION]: EngineCapability.AI_IMAGE_GENERATION,
+    [BUILTIN_PROVIDER_CAPABILITY.FRONTEND_ERROR_MONITORING]: EngineCapability.FRONTEND_ERROR_MONITORING,
+    [BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS]: EngineCapability.FRONTEND_PRODUCT_ANALYTICS,
+    [BUILTIN_PROVIDER_CAPABILITY.LLM_OBSERVABILITY]: EngineCapability.LLM_OBSERVABILITY,
+    [BUILTIN_PROVIDER_CAPABILITY.OBSERVABILITY_TELEMETRY]: EngineCapability.OBSERVABILITY_TELEMETRY,
+    [BUILTIN_PROVIDER_CAPABILITY.COMPLIANCE_AUDIT_TRAIL]: EngineCapability.COMPLIANCE_AUDIT_TRAIL,
+};
+//# sourceMappingURL=engine-capabilities.shared.schemas.js.map

package/dist/esm/external-providers/engine-capabilities.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-capabilities.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/engine-capabilities.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAkC,MAAM,sCAAsC,CAAC;AAEnH;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,gBA0FX;AA1FD,WAAY,gBAAgB;IAC1B,mDAA+B,CAAA;IAC/B,uCAAmB,CAAA;IACnB,yDAAqC,CAAA;IACrC,qDAAiC,CAAA;IACjC,qEAAiD,CAAA;IAEjD,+DAA2C,CAAA;IAC3C,uDAAmC,CAAA;IACnC,+BAAW,CAAA;IAEX,qCAAiB,CAAA;IACjB,+DAA2C,CAAA;IAC3C;;;;;;;;OAQG;IACH,mDAA+B,CAAA;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,qEAAiD,CAAA;IACjD;;;;;;;;;;;;;;OAcG;IACH,uDAAmC,CAAA;IAEnC,+DAA2C,CAAA;IAC3C,6DAAyC,CAAA;IAEzC,2EAAuD,CAAA;IACvD,6EAAyD,CAAA;IAEzD;;;;;OAKG;IACH,2DAAuC,CAAA;IAEvC;;;;;;;;OAQG;IACH,uEAAmD,CAAA;AACrD,CAAC,EA1FW,gBAAgB,KAAhB,gBAAgB,QA0F3B;AACD,6DAA6D;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAEjD;IACF,CAAC,2BAA2B,CAAC,mBAAmB,CAAC,EAAE,gBAAgB,CAAC,mBAAmB;IACvF,CAAC,2BAA2B,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC,eAAe;IAC/E,CAAC,2BAA2B,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAC,GAAG;IACvD,CAAC,2BAA2B,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO;IAC/D,CAAC,2BAA2B,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC,MAAM;IAC/D;;;;;;OAMG;IACH,CAAC,2BAA2B,CAAC,cAAc,CAAC,EAAE,gBAAgB,CAAC,aAAa;IAC5E;;;;;;OAMG;IACH,CAAC,2BAA2B,CAAC,wBAAwB,CAAC,EAAE,gBAAgB,CAAC,sBAAsB;IAC/F,CAAC,2BAA2B,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC,eAAe;IAC5E,CAAC,2BAA2B,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC,mBAAmB;IACpF,CAAC,2BAA2B,CAAC,yBAAyB,CAAC,EAAE,gBAAgB,CAAC,yBAAyB;IACnG,CAAC,2BAA2B,CAAC,0BAA0B,CAAC,EAAE,gBAAgB,CAAC,0BAA0B;IACrG,CAAC,2BAA2B,CAAC,iBAAiB,CAAC,EAAE,gBAAgB,CAAC,iBAAiB;IACnF,CAAC,2BAA2B,CAAC,uBAAuB,CAAC,EAAE,gBAAgB,CAAC,uBAAuB;IAC/F,CAAC,2BAA2B,CAAC,sBAAsB,CAAC,EAAE,gBAAgB,CAAC,sBAAsB;CAC9F,CAAC","sourcesContent":["import { BUILTIN_PROVIDER_CAPABILITY, type BuiltinProviderCapability } from './provider-capability.shared.schemas';\n\n/** @wildo_source:part:start saas.models.engine-capabilities facet:kind:api facet:audience:app-developer\n *\n * Closed application capability vocabulary used to declare what the\n * application needs from its configured providers.\n *\n * `EngineCapability` no longer means \"feature gate id\" and no longer\n * carries provider routing by itself. Provider-backed fulfillment is selected\n * by the application's provider configuration; entitlement/billing features\n * remain application feature decisions. Import this enum from\n * `@wildo-ai/saas-models` and declare only capabilities the application\n * actually intends to configure and operate.\n */\nexport enum EngineCapability {\n  ORGANIZATIONS = 'ORGANIZATIONS',\n  BILLING = 'BILLING',\n  BILLING_PAYMENTS = 'BILLING_PAYMENTS',\n  MULTI_LANGUAGE = 'MULTI_LANGUAGE',\n  COMPLIANCE_AUDIT_TRAIL = 'COMPLIANCE_AUDIT_TRAIL',\n\n  EMAIL_TRANSACTIONAL = 'EMAIL_TRANSACTIONAL',\n  EMAIL_MARKETING = 'EMAIL_MARKETING',\n  SMS = 'SMS',\n\n  AI_LLM = 'AI_LLM',\n  AI_IMAGE_GENERATION = 'AI_IMAGE_GENERATION',\n  /**\n   * Text → vector embeddings (the RAG derived-data tier: `.ragSource()` corpus embedding by the\n   * `rag:embedding-drain` worker, and query-time embedding in retrieval). A slot of its OWN,\n   * deliberately separate from `AI_LLM` (RAG plan DL2/H4): while `LLM_EMBEDDINGS` mapped into the\n   * `AI_LLM` slot, an application structurally could not pick Anthropic for chat and a different\n   * provider for embeddings — one `selection[AI_LLM].primary` decided both. Embeddings resolve\n   * through `EMBEDDINGS_PROVIDER` protocol bindings and are selected by applicability class\n   * (`Embeddings_Applicability`), never by a concrete model id at a call site.\n   */\n  AI_EMBEDDINGS = 'AI_EMBEDDINGS',\n  /**\n   * Document bytes → text: provider-backed extraction (OCR) for uploaded documents, serving\n   * `FileTextExtractionBackendService` and, through it, `.ragSource()` corpus ingestion.\n   *\n   * ## Why a slot of its own\n   *\n   * Three unrelated procurement decisions were otherwise fused. A deployment may well want one\n   * vendor for chat, another for embeddings, and a third for OCR — vendors are not equally good\n   * at all three, and their pricing models do not even share a unit (tokens vs. pages). Mapping\n   * extraction into `AI_LLM` would have made one `selection[AI_LLM].primary` decide all three,\n   * which is exactly the defect that split `AI_EMBEDDINGS` out of `AI_LLM`.\n   *\n   * ## Not to be confused with `DOCUMENT_GENERATION`\n   *\n   * `DOCUMENT_GENERATION` is PDF *generation* — templates and data become bytes. This is the\n   * opposite direction: bytes become text. The names are adjacent and the capabilities are\n   * unrelated; nothing routes between them.\n   *\n   * ## Absence is benign, and that is load-bearing\n   *\n   * With no provider selected, extraction falls back to the local `pdfjs-dist` text-layer read.\n   * That is a real answer for a born-digital PDF and returns nothing for a SCAN — so this\n   * capability is what makes scanned documents answerable, never what makes extraction work at\n   * all. An application that ingests only born-digital documents may leave it unset deliberately.\n   */\n  AI_DOCUMENT_EXTRACTION = 'AI_DOCUMENT_EXTRACTION',\n  /**\n   * An autonomous coding agent that mutates the application workspace.\n   *\n   * Its own slot rather than `AI_LLM`, for exactly the reason `AI_EMBEDDINGS`\n   * was split out of it: one `selection[AI_LLM].primary` decides every provider\n   * mapped into that slot. While the coding transport mapped to `AI_LLM`, an\n   * application structurally could NOT choose one vendor's coding agent and a\n   * different vendor for chat — picking a chat provider silently picked the\n   * agent that would be allowed to edit its source.\n   *\n   * The stakes differ too, which is why fusing them was wrong beyond the\n   * ergonomics: selecting a chat model is a quality and cost decision, while\n   * selecting the agent that writes your code is those things AND an\n   * authorisation decision. They deserve separate, deliberate answers.\n   */\n  AI_CODING_AGENT = 'AI_CODING_AGENT',\n\n  DOCUMENT_GENERATION = 'DOCUMENT_GENERATION',\n  ANTIVIRUS_SCANNING = 'ANTIVIRUS_SCANNING',\n\n  FRONTEND_ERROR_MONITORING = 'FRONTEND_ERROR_MONITORING',\n  FRONTEND_PRODUCT_ANALYTICS = 'FRONTEND_PRODUCT_ANALYTICS',\n\n  /**\n   * Backend LLM-call observability (model/tokens/cost/latency per `invokeAgent`),\n   * platform-scoped. This enables model-call observability when the selected\n   * provider configuration supplies that capability; it does not itself\n   * configure a provider or make telemetry operational.\n   */\n  LLM_OBSERVABILITY = 'LLM_OBSERVABILITY',\n\n  /**\n   * Operational telemetry (traces/metrics/logs) shipped via the OpenTelemetry\n   * SDK over OTLP to a provider (for example, BetterStack). Unlike\n   * `LLM_OBSERVABILITY`, the connection is preloaded from\n   * `OTEL_*` env vars (the CLI translates the saas-config selection + per-env\n   * infra config into them) BEFORE app config — not resolved through the runtime\n   * registry. Author the corresponding infrastructure/provider settings in\n   * the application environment before relying on telemetry.\n   */\n  OBSERVABILITY_TELEMETRY = 'OBSERVABILITY_TELEMETRY',\n}\n/** @wildo_source:part:end saas.models.engine-capabilities */\n\n/**\n * Canonical, single-source-of-truth mapping from the open\n * `ProviderCapability` vocabulary (the built-in subset) to the closed\n * `EngineCapability` slots the engine actually fulfills.\n *\n * A provider declares which `providerCapabilities` it satisfies (e.g.\n * Stripe → `BILLING`, Resend → `EMAIL_TRANSACTIONAL`, Anthropic →\n * `LLM_CHAT`/`CODING_AGENT`). This map projects each built-in\n * capability onto the engine slot it fills, so a provider's\n * `engineCapabilities` set can be derived mechanically. Multiple\n * provider capabilities may share one engine slot (every `LLM_*`\n * capability maps to `AI_LLM`); de-duplicate after projecting.\n *\n * **Why this lives here (one map, three consumers).** The projection\n * used to be hand-copied in three places that silently drifted:\n *   1. The runtime registry projection in `saas-backend-lib`\n *      (`ExternalProvidersRegistryBackendService.buildRuntimeRegistryFromProviderModules`),\n *      which decides which provider answers `getProvidersForEngineCapability`.\n *   2. The backend companion-discovery export in\n *      `@wildo-ai/external-connectors-private` (feeds the generated\n *      `provider-catalog.types.ts` autocomplete via `wildo config sync`).\n *   3. The frontend companion-discovery export in\n *      `@wildo-ai/external-connectors-public` (same, for browser-bound\n *      provider modules).\n * A missing/wrong entry in any copy silently breaks a different surface\n * (a registry resolution, or the catalog autocomplete). It is co-located\n * with the `EngineCapability` enum it projects onto, and every consumer\n * imports it from the `@wildo-ai/saas-models` package root barrel.\n *\n * **Bundle boundary — why here and not beside `BUILTIN_PROVIDER_CAPABILITY`.**\n * This map references `EngineCapability`, which is deliberately kept off\n * the browser-safe `@wildo-ai/saas-models/public-runtime` seam. So it must\n * live in a full-only module. `engine-capabilities.shared.schemas.ts` is\n * exactly that (exported from the root barrel, never from\n * `public-runtime/index.ts`), whereas `provider-capability.shared.schemas.ts`\n * — the other natural home — IS on the public seam and would drag\n * `EngineCapability` into the browser bundle. The frontend discovery\n * consumer (#3) imports this map through its Node-only `./companion`\n * subpath, which already pulls the full root barrel; the browser-shipped\n * `./app`/`./techdoc`/`./website` subpaths never reach it.\n *\n * **BILLING → BILLING (not BILLING_PAYMENTS).** A billing provider\n * (Stripe) declares `BUILTIN_PROVIDER_CAPABILITY.BILLING` and fills the\n * `EngineCapability.BILLING` slot — the SAME slot apps enable in\n * `defineSaaSProviders`/`engineCapabilities` activation config and that\n * `getProvidersForEngineCapability` gates resolution on. Mapping it to\n * the distinct `EngineCapability.BILLING_PAYMENTS` slot (as the runtime\n * copy historically did) registered Stripe under a slot no activation\n * config enables and no consumer queries, making it unreachable through\n * the registry. `BILLING_PAYMENTS` currently has no producer or consumer\n * other than that former bug; it is left in the enum as a reserved slot.\n *\n * **Intentionally unmapped.** `SSO_OAUTH2`, `SSO_SAML`, `FRONTEND_SEARCH`,\n * `FRONTEND_FILE_PICKER`, and `FRONTEND_CAPTCHA` have no closed engine\n * slot today — they are fulfilled by provider protocols / app wiring, not\n * by an `EngineCapability`. Their absence here is by construction, not an\n * oversight: a `Partial<Record<…>>` lookup returns `undefined` and the\n * capability contributes nothing to a provider's `engineCapabilities`.\n *\n * App-extended (kebab-case) provider capabilities never appear here:\n * they live in the open `AppCustomProviderCapabilities` namespace and\n * have no engine slot by definition.\n */\nexport const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY: Partial<\n  Record<BuiltinProviderCapability, EngineCapability>\n> = {\n  [BUILTIN_PROVIDER_CAPABILITY.EMAIL_TRANSACTIONAL]: EngineCapability.EMAIL_TRANSACTIONAL,\n  [BUILTIN_PROVIDER_CAPABILITY.EMAIL_MARKETING]: EngineCapability.EMAIL_MARKETING,\n  [BUILTIN_PROVIDER_CAPABILITY.SMS]: EngineCapability.SMS,\n  [BUILTIN_PROVIDER_CAPABILITY.BILLING]: EngineCapability.BILLING,\n  [BUILTIN_PROVIDER_CAPABILITY.LLM_CHAT]: EngineCapability.AI_LLM,\n  /**\n   * REPOINTED 2026-08-27 (RAG plan DL2/H4): `LLM_EMBEDDINGS` used to map into `AI_LLM`, which\n   * fused the chat and embeddings provider selections into one slot. The TOKEN keeps its name —\n   * it correctly says \"this provider can produce embeddings\", and it sits inside the anchored\n   * `saas.models.provider-capabilities` block compiled into shipped skills — only the slot it\n   * fills changed. Exactly one token claims the embeddings slot.\n   */\n  [BUILTIN_PROVIDER_CAPABILITY.LLM_EMBEDDINGS]: EngineCapability.AI_EMBEDDINGS,\n  /**\n   * EXACTLY ONE token claims the document-extraction slot, and it is a new one. Checked rather\n   * than assumed before adding it: `IMAGE_GENERATION` maps to `AI_IMAGE_GENERATION` (output),\n   * `LLM_CHAT` to `AI_LLM`, `LLM_EMBEDDINGS` to `AI_EMBEDDINGS`, and no built-in token mapped\n   * anywhere near document INPUT. Repointing an existing token — the move that kept\n   * `LLM_EMBEDDINGS` alive — was not available here because none of them meant this.\n   */\n  [BUILTIN_PROVIDER_CAPABILITY.DOCUMENT_TEXT_EXTRACTION]: EngineCapability.AI_DOCUMENT_EXTRACTION,\n  [BUILTIN_PROVIDER_CAPABILITY.CODING_AGENT]: EngineCapability.AI_CODING_AGENT,\n  [BUILTIN_PROVIDER_CAPABILITY.IMAGE_GENERATION]: EngineCapability.AI_IMAGE_GENERATION,\n  [BUILTIN_PROVIDER_CAPABILITY.FRONTEND_ERROR_MONITORING]: EngineCapability.FRONTEND_ERROR_MONITORING,\n  [BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS]: EngineCapability.FRONTEND_PRODUCT_ANALYTICS,\n  [BUILTIN_PROVIDER_CAPABILITY.LLM_OBSERVABILITY]: EngineCapability.LLM_OBSERVABILITY,\n  [BUILTIN_PROVIDER_CAPABILITY.OBSERVABILITY_TELEMETRY]: EngineCapability.OBSERVABILITY_TELEMETRY,\n  [BUILTIN_PROVIDER_CAPABILITY.COMPLIANCE_AUDIT_TRAIL]: EngineCapability.COMPLIANCE_AUDIT_TRAIL,\n};\n"]}