@wildo-ai/saas-models 1.1.2 → 1.1.4

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

@@ -14,8 +14,33 @@ import { type BuiltinProviderCapability } from './provider-capability.shared.sch
 export declare enum EngineCapability {
     ORGANIZATIONS = "ORGANIZATIONS",
     BILLING = "BILLING",
-    BILLING_PAYMENTS = "BILLING_PAYMENTS",
     MULTI_LANGUAGE = "MULTI_LANGUAGE",
+    /**
+     * Durable, provider-backed audit trail — and the capability with the widest reach into what the
+     * application is able to CLAIM about itself.
+     *
+     * Leaving it out is a legitimate choice, but it is not a small one, and the cost is invisible
+     * until much later. The assurance surface attests roughly half its control objectives through the
+     * audit trail: with this capability absent, about a third of them cannot be claimed AT ALL — every
+     * objective whose only attesting capability is the audit trail — and several more resolve to
+     * "undetermined", meaning the application may genuinely operate the control while being unable to
+     * evidence it. Enabling it typically moves an application from partial to complete coverage in one
+     * step.
+     *
+     * Two things this does NOT mean, because both are easy to assume:
+     *
+     * - It is not what makes security events happen. Authentication, authorization, privilege and
+     *   credential events are recorded in the application's own database regardless. What this
+     *   capability adds is the provider-backed fan-out — the durable, external, tamper-evident
+     *   destination an assurance reader can be pointed at.
+     * - It is not retroactive. Turning it on later starts a trail from that moment; it does not
+     *   furnish evidence for the period it was off, and a control's evidence cannot begin before its
+     *   evidence store does.
+     *
+     * So decide it with the compliance posture rather than as an infrastructure detail: if the
+     * application intends to claim access, audit, identity or privacy control objectives to anyone
+     * outside itself, this is the capability those claims rest on.
+     */
     COMPLIANCE_AUDIT_TRAIL = "COMPLIANCE_AUDIT_TRAIL",
     EMAIL_TRANSACTIONAL = "EMAIL_TRANSACTIONAL",
     EMAIL_MARKETING = "EMAIL_MARKETING",
@@ -96,69 +121,96 @@ export declare enum EngineCapability {
      */
     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.
+ * The projection every consumer uses, with the WIDE type it has always had.
+ *
+ * **Why the literal above and the widened alias here are two declarations.** Consumers index this
+ * map with a `BuiltinProviderCapability` VARIABLE — `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY[cap]`
+ * in the runtime registry, in both companion-discovery exports, in `defineSaaSProviders` and in the
+ * tier rule — and that only type-checks against `Partial<Record<…>>`, which admits every token in
+ * the vocabulary and answers `undefined` for the five that map nowhere. Annotating the literal that
+ * way is what USED to be written here, and it is also what erased the information the totality
+ * check below needs: an annotation discards the per-property literal types, so
+ * `(typeof MAP)[keyof typeof MAP]` collapsed to `EngineCapability | undefined` and could not say
+ * WHICH slots are filled.
+ *
+ * `as const satisfies` on the literal keeps both: the compiler still rejects a wrong key or a
+ * non-`EngineCapability` value at the site where it is written, and the exact filled set survives
+ * into the type system. The widening then happens once, here, so no consumer changes and nobody has
+ * to know the literal exists.
+ */
+export declare const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY: Partial<Record<BuiltinProviderCapability, EngineCapability>>;
+/**
+ * Engine capabilities that DELIBERATELY have no provider capability pointing at them, each named
+ * with the reason it is an empty slot rather than a hole.
+ *
+ * This exists so the two states can never be confused. Before it, an `EngineCapability` member with
+ * no entry in the map above looked exactly like one whose entry someone forgot — the absence WAS the
+ * record — and that indistinguishability is the whole mechanism behind three separate slots shipping
+ * unfillable: `DOCUMENT_GENERATION` and `ANTIVIRUS_SCANNING` (withdrawn 2026-09-03) and
+ * `BILLING_PAYMENTS` (withdrawn 2026-09-09, and left standing for six days precisely because
+ * "reserved" reads like a decision). A capability listed here has been looked at; one that is
+ * neither listed here nor mapped above does not compile.
  *
- * 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.
+ * **Both members are ACTIVATION capabilities, and that is the criterion.** Each is a real, live,
+ * enabled-or-not decision an application makes in `wildo.saas.config.ts` (`ORGANIZATIONS` is
+ * enabled by both dogfood applications, `MULTI_LANGUAGE` is written by the scaffold and by the
+ * application-creation composition step), and each is implemented BY THE ENGINE — multi-tenancy is
+ * the engine's own organization model and scoping, translation is the engine's own i18n pipeline.
+ * There is no external party to select, so there is nothing for a provider capability to say. That
+ * is categorically different from a withdrawn slot, which named work an external party WOULD do and
+ * had no external party able to do it.
  *
- * **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.
+ * **Adding a member here is a decision that must be argued, not a way to make a compile error go
+ * away.** The test beside this file pins the set to exactly these two, so a third one cannot arrive
+ * as a silent edit — see `__tests__/engine-capability-provider-coverage.shared.test.ts`.
+ */
+export declare const ENGINE_CAPABILITIES_WITH_NO_PROVIDER_CAPABILITY: readonly [EngineCapability.ORGANIZATIONS, EngineCapability.MULTI_LANGUAGE];
+/** @wildo_source:part:start saas.models.engine-capabilities.required-provider-floor facet:layer:shared facet:audience:app-developer */
+/**
+ * Engine capabilities that REQUIRE a resolved provider the moment an
+ * application ENABLES them — the engine-level MAIN floor (#328).
  *
- * **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.
+ * The asymmetry is the thing to carry away: **enabling a capability with nothing serving it fails at
+ * BOOT for these three and at the point of USE for every other slot.** So an author who tries one
+ * unserved slot, sees the application come up, and concludes that an unserved capability degrades
+ * gracefully has learned the wrong rule from the larger half of the vocabulary.
  *
- * **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.
+ * `EngineCapabilityActivation.required` is the application's decision;
+ * this set is the ENGINE's: for each member, an enabled capability with no
+ * provider is not a degraded mode but a boot-time misconfiguration, because
+ * an engine flow the application already relies on fails at first use:
  *
- * **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`.
+ * - `EMAIL_TRANSACTIONAL` — invitations, address verification and password
+ *   reset are engine flows that send mail; with no provider they fail
+ *   silently at the moment a user needs them.
+ * - `BILLING` — `initializeBillingServices` already fails loud with no
+ *   provider; the floor names it in the same place as the others.
+ * - `SMS` — phone verification and MFA-by-SMS are engine flows.
  *
- * App-extended (kebab-case) provider capabilities never appear here:
- * they live in the open `AppCustomProviderCapabilities` namespace and
- * have no engine slot by definition.
+ * DELIBERATELY ABSENT, with the reason each would need to overturn:
+ * - the `AI_*` slots — consumed per feature (an agent, the logo generator)
+ *   and legitimately served on a DIFFERENT host (the companion reaches image
+ *   generation; the backend need not), so "enabled with no backend provider"
+ *   is a normal topology, not a fault. A feature that needs one refuses at
+ *   its own site.
+ * - the sinks (`COMPLIANCE_AUDIT_TRAIL`, `LLM_OBSERVABILITY`,
+ *   `OBSERVABILITY_TELEMETRY`) — fail-OPEN by design (the G4 reconcile
+ *   warns), because Layer-1 persistence is unaffected.
+ * - `EMAIL_MARKETING` — a campaign feature, not an engine flow.
+ * - the `FRONTEND_*` slots — resolved by the frontend facet, invisible to
+ *   the backend registry that evaluates this floor.
+ * - `ORGANIZATIONS` and `MULTI_LANGUAGE` — no provider token maps to them,
+ *   deliberately and by declaration; see
+ *   `ENGINE_CAPABILITIES_WITH_NO_PROVIDER_CAPABILITY`. A floor requiring a
+ *   resolved provider for a slot nothing can fill would refuse every boot that
+ *   enabled them. (`BILLING_PAYMENTS` was named here too until it was withdrawn
+ *   from the enum on 2026-09-09.)
+ *
+ * The floor runs only on a host expected to SERVE these slots (see
+ * `ApplicationRuntimeProfileBootAssertions.assertsEngineCapabilityProviderFloor`);
+ * a minion's scope-filtered registry legitimately resolves none of them.
  */
-export declare const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY: Partial<Record<BuiltinProviderCapability, EngineCapability>>;
+export declare const ENGINE_CAPABILITIES_REQUIRING_A_PROVIDER_WHEN_ENABLED: ReadonlySet<EngineCapability>;
+/** @wildo_source:part:end saas.models.engine-capabilities.required-provider-floor */
 //# sourceMappingURL=engine-capabilities.shared.schemas.d.ts.map

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

@@ -1 +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;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,sBAAsB,2BAA2B;IACjD;;;;;;;;;;;;;;OAcG;IACH,eAAe,oBAAoB;IAuBnC,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"}
+{"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,cAAc,mBAAmB;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,sBAAsB,2BAA2B;IAEjD,mBAAmB,wBAAwB;IAC3C,eAAe,oBAAoB;IACnC,GAAG,QAAQ;IAEX,MAAM,WAAW;IACjB,mBAAmB,wBAAwB;IAC3C;;;;;;;;OAQG;IACH,aAAa,kBAAkB;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,sBAAsB,2BAA2B;IACjD;;;;;;;;;;;;;;OAcG;IACH,eAAe,oBAAoB;IAyDnC,yBAAyB,8BAA8B;IACvD,0BAA0B,+BAA+B;IAEzD;;;;;OAKG;IACH,iBAAiB,sBAAsB;IAEvC;;;;;;;;OAQG;IACH,uBAAuB,4BAA4B;CACpD;AAkGD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wCAAwC,EAAE,OAAO,CAC5D,MAAM,CAAC,yBAAyB,EAAE,gBAAgB,CAAC,CACD,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,+CAA+C,4EAYZ,CAAC;AA8CjD,uIAAuI;AACvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,qDAAqD,EAAE,WAAW,CAAC,gBAAgB,CAI9F,CAAC;AACH,qFAAqF"}

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

@@ -15,8 +15,33 @@ export var EngineCapability;
 (function (EngineCapability) {
     EngineCapability["ORGANIZATIONS"] = "ORGANIZATIONS";
     EngineCapability["BILLING"] = "BILLING";
-    EngineCapability["BILLING_PAYMENTS"] = "BILLING_PAYMENTS";
     EngineCapability["MULTI_LANGUAGE"] = "MULTI_LANGUAGE";
+    /**
+     * Durable, provider-backed audit trail — and the capability with the widest reach into what the
+     * application is able to CLAIM about itself.
+     *
+     * Leaving it out is a legitimate choice, but it is not a small one, and the cost is invisible
+     * until much later. The assurance surface attests roughly half its control objectives through the
+     * audit trail: with this capability absent, about a third of them cannot be claimed AT ALL — every
+     * objective whose only attesting capability is the audit trail — and several more resolve to
+     * "undetermined", meaning the application may genuinely operate the control while being unable to
+     * evidence it. Enabling it typically moves an application from partial to complete coverage in one
+     * step.
+     *
+     * Two things this does NOT mean, because both are easy to assume:
+     *
+     * - It is not what makes security events happen. Authentication, authorization, privilege and
+     *   credential events are recorded in the application's own database regardless. What this
+     *   capability adds is the provider-backed fan-out — the durable, external, tamper-evident
+     *   destination an assurance reader can be pointed at.
+     * - It is not retroactive. Turning it on later starts a trail from that moment; it does not
+     *   furnish evidence for the period it was off, and a control's evidence cannot begin before its
+     *   evidence store does.
+     *
+     * So decide it with the compliance posture rather than as an infrastructure detail: if the
+     * application intends to claim access, audit, identity or privacy control objectives to anyone
+     * outside itself, this is the capability those claims rest on.
+     */
     EngineCapability["COMPLIANCE_AUDIT_TRAIL"] = "COMPLIANCE_AUDIT_TRAIL";
     EngineCapability["EMAIL_TRANSACTIONAL"] = "EMAIL_TRANSACTIONAL";
     EngineCapability["EMAIL_MARKETING"] = "EMAIL_MARKETING";
@@ -87,8 +112,15 @@ export var EngineCapability;
      * Both capabilities are real and both are delivered elsewhere, which is why withdrawing the slots
      * costs nothing: antivirus scanning is `InfraCapability.ANTIVIRUS_SCANNING`, fulfilled by ClamAV
      * and consumed by `FileScanningBackendService`; PDF generation is the in-process `pdfTemplates`
-     * surface, with `InfraCapability.DOCUMENT_RENDERING` (Gotenberg) provisioned beside it. Neither
-     * has an external provider, and neither is planned to.
+     * surface, rendered by `@react-pdf/renderer` inside the backend. Neither has an external
+     * provider, and neither is planned to.
+     *
+     * `InfraCapability.DOCUMENT_RENDERING` (Gotenberg) was provisioned beside the PDF surface and
+     * consumed by nothing; it was withdrawn on 2026-09-08 (#477) because in-process rendering had
+     * superseded it. Note the two are not interchangeable if it is ever reconsidered:
+     * `@react-pdf/renderer` composes a document from React primitives, while Gotenberg converts
+     * EXISTING HTML and Office documents — that is a different capability, not a second
+     * implementation of this one.
      *
      * Removing `ANTIVIRUS_SCANNING` also removes a collision: the identical spelling named an engine
      * slot nothing could fill AND a live infra capability, in two packages, so a reader grepping the
@@ -96,6 +128,33 @@ export var EngineCapability;
      *
      * If a hosted AV or document-rendering vendor is ever adopted, the member comes back WITH its
      * `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` entry and its own JSDoc in the same change.
+     *
+     * WITHDRAWN 2026-09-09: `BILLING_PAYMENTS`, the third member of exactly that shape, and the one
+     * this paragraph's own closing rule should have caught. It was never withdrawn with the other two
+     * because it had been left behind DELIBERATELY — as a "reserved slot" — which reads as a decision
+     * and is why nobody re-examined it. Measured before removing, across the whole repository outside
+     * `node_modules` / `dist`: it appeared in live source at exactly THREE sites, and none of them was
+     * a use — the enum declaration itself, its row in the compile-forced
+     * `ENGINE_CAPABILITY_RESOLUTION_MODE` record, and a comment in a test naming it as a slot the
+     * billing provider must NOT be registered under. Zero applications enabled it, zero scaffolds
+     * wrote it, zero consumers queried it, and no provider capability token mapped to it.
+     *
+     * The capability it names is real and is already delivered: a billing provider (Stripe) declares
+     * `BUILTIN_PROVIDER_CAPABILITY.BILLING` and fills `EngineCapability.BILLING`, which is the slot
+     * applications enable and `getProvidersForEngineCapability` gates on. Payment EXECUTION is served
+     * through that same provider's `BILLING_PROVIDER` protocol; splitting it into a second engine slot
+     * was a plan-era intention (`provider-registry-materialization-workflow.md`) that the shipped
+     * model settled the other way. So the withdrawal removes a name, not a capability.
+     *
+     * The reason a reserved slot is worse than no slot is `EngineCapabilityResolutionMode`: every
+     * member must be classified, `BILLING_PAYMENTS` was classified `SELECT_ONE`, and `SELECT_ONE`
+     * asserts that exactly one provider is selected from the candidates. There were zero candidates
+     * and there could never be one. A vocabulary member that no configuration can satisfy is not a
+     * reservation, it is a false statement the compiler is forced to carry.
+     *
+     * If a payments vendor is ever selected independently of the billing vendor, the member comes back
+     * with its provider-capability token and its map entry in the same change — the same rule as
+     * above, now with three instances behind it.
      */
     EngineCapability["FRONTEND_ERROR_MONITORING"] = "FRONTEND_ERROR_MONITORING";
     EngineCapability["FRONTEND_PRODUCT_ANALYTICS"] = "FRONTEND_PRODUCT_ANALYTICS";
@@ -159,16 +218,17 @@ export var EngineCapability;
  * 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
+ * **BILLING → BILLING.** 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.
+ * `getProvidersForEngineCapability` gates resolution on. The runtime copy
+ * of this projection historically mapped it onto a distinct
+ * `EngineCapability.BILLING_PAYMENTS` slot instead, registering Stripe
+ * under something no activation config enables and no consumer queries,
+ * which made it unreachable through the registry. That second slot was
+ * withdrawn from the enum on 2026-09-09 (see the WITHDRAWN block beside
+ * the enum) — it had no producer and no consumer other than the bug.
  *
  * **Intentionally unmapped.** `SSO_OAUTH2`, `SSO_SAML`, `FRONTEND_SEARCH`,
  * `FRONTEND_FILE_PICKER`, and `FRONTEND_CAPTCHA` have no closed engine
@@ -177,11 +237,11 @@ export var EngineCapability;
  * 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.
+ * There are no app-extended provider capabilities: the augmentation point was
+ * removed as an extension point with no resolver (#502), so this map covers the
+ * whole vocabulary rather than the built-in half of it.
  */
-export const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY = {
+const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY_ENTRIES = {
     [BUILTIN_PROVIDER_CAPABILITY.EMAIL_TRANSACTIONAL]: EngineCapability.EMAIL_TRANSACTIONAL,
     [BUILTIN_PROVIDER_CAPABILITY.EMAIL_MARKETING]: EngineCapability.EMAIL_MARKETING,
     [BUILTIN_PROVIDER_CAPABILITY.SMS]: EngineCapability.SMS,
@@ -211,4 +271,112 @@ export const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY = {
     [BUILTIN_PROVIDER_CAPABILITY.OBSERVABILITY_TELEMETRY]: EngineCapability.OBSERVABILITY_TELEMETRY,
     [BUILTIN_PROVIDER_CAPABILITY.COMPLIANCE_AUDIT_TRAIL]: EngineCapability.COMPLIANCE_AUDIT_TRAIL,
 };
+/**
+ * The projection every consumer uses, with the WIDE type it has always had.
+ *
+ * **Why the literal above and the widened alias here are two declarations.** Consumers index this
+ * map with a `BuiltinProviderCapability` VARIABLE — `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY[cap]`
+ * in the runtime registry, in both companion-discovery exports, in `defineSaaSProviders` and in the
+ * tier rule — and that only type-checks against `Partial<Record<…>>`, which admits every token in
+ * the vocabulary and answers `undefined` for the five that map nowhere. Annotating the literal that
+ * way is what USED to be written here, and it is also what erased the information the totality
+ * check below needs: an annotation discards the per-property literal types, so
+ * `(typeof MAP)[keyof typeof MAP]` collapsed to `EngineCapability | undefined` and could not say
+ * WHICH slots are filled.
+ *
+ * `as const satisfies` on the literal keeps both: the compiler still rejects a wrong key or a
+ * non-`EngineCapability` value at the site where it is written, and the exact filled set survives
+ * into the type system. The widening then happens once, here, so no consumer changes and nobody has
+ * to know the literal exists.
+ */
+export const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY = PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY_ENTRIES;
+/**
+ * Engine capabilities that DELIBERATELY have no provider capability pointing at them, each named
+ * with the reason it is an empty slot rather than a hole.
+ *
+ * This exists so the two states can never be confused. Before it, an `EngineCapability` member with
+ * no entry in the map above looked exactly like one whose entry someone forgot — the absence WAS the
+ * record — and that indistinguishability is the whole mechanism behind three separate slots shipping
+ * unfillable: `DOCUMENT_GENERATION` and `ANTIVIRUS_SCANNING` (withdrawn 2026-09-03) and
+ * `BILLING_PAYMENTS` (withdrawn 2026-09-09, and left standing for six days precisely because
+ * "reserved" reads like a decision). A capability listed here has been looked at; one that is
+ * neither listed here nor mapped above does not compile.
+ *
+ * **Both members are ACTIVATION capabilities, and that is the criterion.** Each is a real, live,
+ * enabled-or-not decision an application makes in `wildo.saas.config.ts` (`ORGANIZATIONS` is
+ * enabled by both dogfood applications, `MULTI_LANGUAGE` is written by the scaffold and by the
+ * application-creation composition step), and each is implemented BY THE ENGINE — multi-tenancy is
+ * the engine's own organization model and scoping, translation is the engine's own i18n pipeline.
+ * There is no external party to select, so there is nothing for a provider capability to say. That
+ * is categorically different from a withdrawn slot, which named work an external party WOULD do and
+ * had no external party able to do it.
+ *
+ * **Adding a member here is a decision that must be argued, not a way to make a compile error go
+ * away.** The test beside this file pins the set to exactly these two, so a third one cannot arrive
+ * as a silent edit — see `__tests__/engine-capability-provider-coverage.shared.test.ts`.
+ */
+export const ENGINE_CAPABILITIES_WITH_NO_PROVIDER_CAPABILITY = [
+    /**
+     * Multi-tenancy: organizations, memberships, roles and organization scoping are engine resources
+     * and engine authorization. Nothing about them is procured.
+     */
+    EngineCapability.ORGANIZATIONS,
+    /**
+     * Application-wide i18n: the label tree, the locale negotiation and the translation pipeline are
+     * the engine's. Where translation is MODEL-backed it reaches a provider through `AI_LLM`, which is
+     * its own slot with its own selection — so even that path is not this capability's producer.
+     */
+    EngineCapability.MULTI_LANGUAGE,
+];
+/** @wildo_source:part:start saas.models.engine-capabilities.required-provider-floor facet:layer:shared facet:audience:app-developer */
+/**
+ * Engine capabilities that REQUIRE a resolved provider the moment an
+ * application ENABLES them — the engine-level MAIN floor (#328).
+ *
+ * The asymmetry is the thing to carry away: **enabling a capability with nothing serving it fails at
+ * BOOT for these three and at the point of USE for every other slot.** So an author who tries one
+ * unserved slot, sees the application come up, and concludes that an unserved capability degrades
+ * gracefully has learned the wrong rule from the larger half of the vocabulary.
+ *
+ * `EngineCapabilityActivation.required` is the application's decision;
+ * this set is the ENGINE's: for each member, an enabled capability with no
+ * provider is not a degraded mode but a boot-time misconfiguration, because
+ * an engine flow the application already relies on fails at first use:
+ *
+ * - `EMAIL_TRANSACTIONAL` — invitations, address verification and password
+ *   reset are engine flows that send mail; with no provider they fail
+ *   silently at the moment a user needs them.
+ * - `BILLING` — `initializeBillingServices` already fails loud with no
+ *   provider; the floor names it in the same place as the others.
+ * - `SMS` — phone verification and MFA-by-SMS are engine flows.
+ *
+ * DELIBERATELY ABSENT, with the reason each would need to overturn:
+ * - the `AI_*` slots — consumed per feature (an agent, the logo generator)
+ *   and legitimately served on a DIFFERENT host (the companion reaches image
+ *   generation; the backend need not), so "enabled with no backend provider"
+ *   is a normal topology, not a fault. A feature that needs one refuses at
+ *   its own site.
+ * - the sinks (`COMPLIANCE_AUDIT_TRAIL`, `LLM_OBSERVABILITY`,
+ *   `OBSERVABILITY_TELEMETRY`) — fail-OPEN by design (the G4 reconcile
+ *   warns), because Layer-1 persistence is unaffected.
+ * - `EMAIL_MARKETING` — a campaign feature, not an engine flow.
+ * - the `FRONTEND_*` slots — resolved by the frontend facet, invisible to
+ *   the backend registry that evaluates this floor.
+ * - `ORGANIZATIONS` and `MULTI_LANGUAGE` — no provider token maps to them,
+ *   deliberately and by declaration; see
+ *   `ENGINE_CAPABILITIES_WITH_NO_PROVIDER_CAPABILITY`. A floor requiring a
+ *   resolved provider for a slot nothing can fill would refuse every boot that
+ *   enabled them. (`BILLING_PAYMENTS` was named here too until it was withdrawn
+ *   from the enum on 2026-09-09.)
+ *
+ * The floor runs only on a host expected to SERVE these slots (see
+ * `ApplicationRuntimeProfileBootAssertions.assertsEngineCapabilityProviderFloor`);
+ * a minion's scope-filtered registry legitimately resolves none of them.
+ */
+export const ENGINE_CAPABILITIES_REQUIRING_A_PROVIDER_WHEN_ENABLED = new Set([
+    EngineCapability.EMAIL_TRANSACTIONAL,
+    EngineCapability.BILLING,
+    EngineCapability.SMS,
+]);
+/** @wildo_source:part:end saas.models.engine-capabilities.required-provider-floor */
 //# sourceMappingURL=engine-capabilities.shared.schemas.js.map

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

@@ -1 +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,gBA8GX;AA9GD,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;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,qEAAiD,CAAA;IACjD;;;;;;;;;;;;;;OAcG;IACH,uDAAmC,CAAA;IAEnC;;;;;;;;;;;;;;;;;;;OAmBG;IAEH,2EAAuD,CAAA;IACvD,6EAAyD,CAAA;IAEzD;;;;;OAKG;IACH,2DAAuC,CAAA;IAEvC;;;;;;;;OAQG;IACH,uEAAmD,CAAA;AACrD,CAAC,EA9GW,gBAAgB,KAAhB,gBAAgB,QA8G3B;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 PDF GENERATION\n   *\n   * PDF generation — templates and data become bytes — is the `pdfTemplates` surface, done\n   * in-process and with no provider slot of its own. This is the opposite direction: bytes become\n   * text. The two are unrelated and nothing routes between them. (There WAS an\n   * `EngineCapability.DOCUMENT_GENERATION` that this paragraph used to name; it was withdrawn\n   * because no provider capability could ever fill it.)\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  /*\n   * WITHDRAWN 2026-09-03: `DOCUMENT_GENERATION` and `ANTIVIRUS_SCANNING` were members here and are\n   * not any more. Neither could ever be filled — `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` had no\n   * entry pointing at either, so no provider capability token could claim the slot — while both were\n   * classified `SELECT_ONE`, which asserts that exactly one provider must be selected. Selecting one\n   * of zero candidates is not a resolution mode.\n   *\n   * Both capabilities are real and both are delivered elsewhere, which is why withdrawing the slots\n   * costs nothing: antivirus scanning is `InfraCapability.ANTIVIRUS_SCANNING`, fulfilled by ClamAV\n   * and consumed by `FileScanningBackendService`; PDF generation is the in-process `pdfTemplates`\n   * surface, with `InfraCapability.DOCUMENT_RENDERING` (Gotenberg) provisioned beside it. Neither\n   * has an external provider, and neither is planned to.\n   *\n   * Removing `ANTIVIRUS_SCANNING` also removes a collision: the identical spelling named an engine\n   * slot nothing could fill AND a live infra capability, in two packages, so a reader grepping the\n   * word landed in whichever they searched first.\n   *\n   * If a hosted AV or document-rendering vendor is ever adopted, the member comes back WITH its\n   * `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` entry and its own JSDoc in the same change.\n   */\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"]}
+{"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,gBAyKX;AAzKD,WAAY,gBAAgB;IAC1B,mDAA+B,CAAA;IAC/B,uCAAmB,CAAA;IACnB,qDAAiC,CAAA;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,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;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,qEAAiD,CAAA;IACjD;;;;;;;;;;;;;;OAcG;IACH,uDAAmC,CAAA;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IAEH,2EAAuD,CAAA;IACvD,6EAAyD,CAAA;IAEzD;;;;;OAKG;IACH,2DAAuC,CAAA;IAEvC;;;;;;;;OAQG;IACH,uEAAmD,CAAA;AACrD,CAAC,EAzKW,gBAAgB,KAAhB,gBAAgB,QAyK3B;AACD,6DAA6D;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,gDAAgD,GAAG;IACvD,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;CACd,CAAC;AAElF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAEjD,gDAAgD,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,+CAA+C,GAAG;IAC7D;;;OAGG;IACH,gBAAgB,CAAC,aAAa;IAC9B;;;;OAIG;IACH,gBAAgB,CAAC,cAAc;CACe,CAAC;AA8CjD,uIAAuI;AACvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,CAAC,MAAM,qDAAqD,GAAkC,IAAI,GAAG,CAAC;IAC1G,gBAAgB,CAAC,mBAAmB;IACpC,gBAAgB,CAAC,OAAO;IACxB,gBAAgB,CAAC,GAAG;CACrB,CAAC,CAAC;AACH,qFAAqF","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  MULTI_LANGUAGE = 'MULTI_LANGUAGE',\n  /**\n   * Durable, provider-backed audit trail — and the capability with the widest reach into what the\n   * application is able to CLAIM about itself.\n   *\n   * Leaving it out is a legitimate choice, but it is not a small one, and the cost is invisible\n   * until much later. The assurance surface attests roughly half its control objectives through the\n   * audit trail: with this capability absent, about a third of them cannot be claimed AT ALL — every\n   * objective whose only attesting capability is the audit trail — and several more resolve to\n   * \"undetermined\", meaning the application may genuinely operate the control while being unable to\n   * evidence it. Enabling it typically moves an application from partial to complete coverage in one\n   * step.\n   *\n   * Two things this does NOT mean, because both are easy to assume:\n   *\n   * - It is not what makes security events happen. Authentication, authorization, privilege and\n   *   credential events are recorded in the application's own database regardless. What this\n   *   capability adds is the provider-backed fan-out — the durable, external, tamper-evident\n   *   destination an assurance reader can be pointed at.\n   * - It is not retroactive. Turning it on later starts a trail from that moment; it does not\n   *   furnish evidence for the period it was off, and a control's evidence cannot begin before its\n   *   evidence store does.\n   *\n   * So decide it with the compliance posture rather than as an infrastructure detail: if the\n   * application intends to claim access, audit, identity or privacy control objectives to anyone\n   * outside itself, this is the capability those claims rest on.\n   */\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 PDF GENERATION\n   *\n   * PDF generation — templates and data become bytes — is the `pdfTemplates` surface, done\n   * in-process and with no provider slot of its own. This is the opposite direction: bytes become\n   * text. The two are unrelated and nothing routes between them. (There WAS an\n   * `EngineCapability.DOCUMENT_GENERATION` that this paragraph used to name; it was withdrawn\n   * because no provider capability could ever fill it.)\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  /*\n   * WITHDRAWN 2026-09-03: `DOCUMENT_GENERATION` and `ANTIVIRUS_SCANNING` were members here and are\n   * not any more. Neither could ever be filled — `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` had no\n   * entry pointing at either, so no provider capability token could claim the slot — while both were\n   * classified `SELECT_ONE`, which asserts that exactly one provider must be selected. Selecting one\n   * of zero candidates is not a resolution mode.\n   *\n   * Both capabilities are real and both are delivered elsewhere, which is why withdrawing the slots\n   * costs nothing: antivirus scanning is `InfraCapability.ANTIVIRUS_SCANNING`, fulfilled by ClamAV\n   * and consumed by `FileScanningBackendService`; PDF generation is the in-process `pdfTemplates`\n   * surface, rendered by `@react-pdf/renderer` inside the backend. Neither has an external\n   * provider, and neither is planned to.\n   *\n   * `InfraCapability.DOCUMENT_RENDERING` (Gotenberg) was provisioned beside the PDF surface and\n   * consumed by nothing; it was withdrawn on 2026-09-08 (#477) because in-process rendering had\n   * superseded it. Note the two are not interchangeable if it is ever reconsidered:\n   * `@react-pdf/renderer` composes a document from React primitives, while Gotenberg converts\n   * EXISTING HTML and Office documents — that is a different capability, not a second\n   * implementation of this one.\n   *\n   * Removing `ANTIVIRUS_SCANNING` also removes a collision: the identical spelling named an engine\n   * slot nothing could fill AND a live infra capability, in two packages, so a reader grepping the\n   * word landed in whichever they searched first.\n   *\n   * If a hosted AV or document-rendering vendor is ever adopted, the member comes back WITH its\n   * `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` entry and its own JSDoc in the same change.\n   *\n   * WITHDRAWN 2026-09-09: `BILLING_PAYMENTS`, the third member of exactly that shape, and the one\n   * this paragraph's own closing rule should have caught. It was never withdrawn with the other two\n   * because it had been left behind DELIBERATELY — as a \"reserved slot\" — which reads as a decision\n   * and is why nobody re-examined it. Measured before removing, across the whole repository outside\n   * `node_modules` / `dist`: it appeared in live source at exactly THREE sites, and none of them was\n   * a use — the enum declaration itself, its row in the compile-forced\n   * `ENGINE_CAPABILITY_RESOLUTION_MODE` record, and a comment in a test naming it as a slot the\n   * billing provider must NOT be registered under. Zero applications enabled it, zero scaffolds\n   * wrote it, zero consumers queried it, and no provider capability token mapped to it.\n   *\n   * The capability it names is real and is already delivered: a billing provider (Stripe) declares\n   * `BUILTIN_PROVIDER_CAPABILITY.BILLING` and fills `EngineCapability.BILLING`, which is the slot\n   * applications enable and `getProvidersForEngineCapability` gates on. Payment EXECUTION is served\n   * through that same provider's `BILLING_PROVIDER` protocol; splitting it into a second engine slot\n   * was a plan-era intention (`provider-registry-materialization-workflow.md`) that the shipped\n   * model settled the other way. So the withdrawal removes a name, not a capability.\n   *\n   * The reason a reserved slot is worse than no slot is `EngineCapabilityResolutionMode`: every\n   * member must be classified, `BILLING_PAYMENTS` was classified `SELECT_ONE`, and `SELECT_ONE`\n   * asserts that exactly one provider is selected from the candidates. There were zero candidates\n   * and there could never be one. A vocabulary member that no configuration can satisfy is not a\n   * reservation, it is a false statement the compiler is forced to carry.\n   *\n   * If a payments vendor is ever selected independently of the billing vendor, the member comes back\n   * with its provider-capability token and its map entry in the same change — the same rule as\n   * above, now with three instances behind it.\n   */\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.** A billing provider (Stripe) declares\n * `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. The runtime copy\n * of this projection historically mapped it onto a distinct\n * `EngineCapability.BILLING_PAYMENTS` slot instead, registering Stripe\n * under something no activation config enables and no consumer queries,\n * which made it unreachable through the registry. That second slot was\n * withdrawn from the enum on 2026-09-09 (see the WITHDRAWN block beside\n * the enum) — it had no producer and no consumer other than the bug.\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 * There are no app-extended provider capabilities: the augmentation point was\n * removed as an extension point with no resolver (#502), so this map covers the\n * whole vocabulary rather than the built-in half of it.\n */\nconst PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY_ENTRIES = {\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} as const satisfies Partial<Record<BuiltinProviderCapability, EngineCapability>>;\n\n/**\n * The projection every consumer uses, with the WIDE type it has always had.\n *\n * **Why the literal above and the widened alias here are two declarations.** Consumers index this\n * map with a `BuiltinProviderCapability` VARIABLE — `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY[cap]`\n * in the runtime registry, in both companion-discovery exports, in `defineSaaSProviders` and in the\n * tier rule — and that only type-checks against `Partial<Record<…>>`, which admits every token in\n * the vocabulary and answers `undefined` for the five that map nowhere. Annotating the literal that\n * way is what USED to be written here, and it is also what erased the information the totality\n * check below needs: an annotation discards the per-property literal types, so\n * `(typeof MAP)[keyof typeof MAP]` collapsed to `EngineCapability | undefined` and could not say\n * WHICH slots are filled.\n *\n * `as const satisfies` on the literal keeps both: the compiler still rejects a wrong key or a\n * non-`EngineCapability` value at the site where it is written, and the exact filled set survives\n * into the type system. The widening then happens once, here, so no consumer changes and nobody has\n * to know the literal exists.\n */\nexport const PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY: Partial<\n  Record<BuiltinProviderCapability, EngineCapability>\n> = PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY_ENTRIES;\n\n/**\n * Engine capabilities that DELIBERATELY have no provider capability pointing at them, each named\n * with the reason it is an empty slot rather than a hole.\n *\n * This exists so the two states can never be confused. Before it, an `EngineCapability` member with\n * no entry in the map above looked exactly like one whose entry someone forgot — the absence WAS the\n * record — and that indistinguishability is the whole mechanism behind three separate slots shipping\n * unfillable: `DOCUMENT_GENERATION` and `ANTIVIRUS_SCANNING` (withdrawn 2026-09-03) and\n * `BILLING_PAYMENTS` (withdrawn 2026-09-09, and left standing for six days precisely because\n * \"reserved\" reads like a decision). A capability listed here has been looked at; one that is\n * neither listed here nor mapped above does not compile.\n *\n * **Both members are ACTIVATION capabilities, and that is the criterion.** Each is a real, live,\n * enabled-or-not decision an application makes in `wildo.saas.config.ts` (`ORGANIZATIONS` is\n * enabled by both dogfood applications, `MULTI_LANGUAGE` is written by the scaffold and by the\n * application-creation composition step), and each is implemented BY THE ENGINE — multi-tenancy is\n * the engine's own organization model and scoping, translation is the engine's own i18n pipeline.\n * There is no external party to select, so there is nothing for a provider capability to say. That\n * is categorically different from a withdrawn slot, which named work an external party WOULD do and\n * had no external party able to do it.\n *\n * **Adding a member here is a decision that must be argued, not a way to make a compile error go\n * away.** The test beside this file pins the set to exactly these two, so a third one cannot arrive\n * as a silent edit — see `__tests__/engine-capability-provider-coverage.shared.test.ts`.\n */\nexport const ENGINE_CAPABILITIES_WITH_NO_PROVIDER_CAPABILITY = [\n  /**\n   * Multi-tenancy: organizations, memberships, roles and organization scoping are engine resources\n   * and engine authorization. Nothing about them is procured.\n   */\n  EngineCapability.ORGANIZATIONS,\n  /**\n   * Application-wide i18n: the label tree, the locale negotiation and the translation pipeline are\n   * the engine's. Where translation is MODEL-backed it reaches a provider through `AI_LLM`, which is\n   * its own slot with its own selection — so even that path is not this capability's producer.\n   */\n  EngineCapability.MULTI_LANGUAGE,\n] as const satisfies readonly EngineCapability[];\n\n/**\n * COMPILE-TIME TOTALITY: every `EngineCapability` is either filled by a provider capability or\n * declared an empty slot above. Adding a member to the enum without doing one of the two is a\n * TypeScript error at this line, not a test failure and not a runtime surprise.\n *\n * A compile error is the right instrument here because both inputs are static literals in this one\n * file — there is no runtime state to consult, so nothing is gained by deferring the question to\n * execution, and a great deal is lost: a test only fails for someone who runs it, while this fails\n * for whoever adds the member, in the editor, before the commit.\n *\n * The error a violation produces is `TS2344` on `EngineCapabilityAccountedFor`, reading\n * `Type 'EngineCapability.X' does not satisfy the constraint 'never'` — X being the exact member\n * that is neither mapped nor declared. Measured rather than asserted: deleting the\n * `BUILTIN_PROVIDER_CAPABILITY.SMS` row from the literal above produced exactly that diagnostic,\n * naming `EngineCapability.SMS`, and the row was restored.\n *\n * The two declarations below are unused by design — the assertion IS the declaration, and it is\n * evaluated the moment the file is type-checked. `noUnusedLocals` is off in this package's\n * tsconfig, so nothing objects; do not \"clean them up\".\n */\ntype EngineCapabilityFilledByAProviderCapability =\n  (typeof PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY_ENTRIES)[keyof typeof PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY_ENTRIES];\n\ntype EngineCapabilityDeclaredEmpty = (typeof ENGINE_CAPABILITIES_WITH_NO_PROVIDER_CAPABILITY)[number];\n\n/** Resolves to `never` when the two sets above cover the enum, and to the offending member(s) when they do not. */\ntype EngineCapabilityAccountedFor<Unaccounted extends never> = Unaccounted;\n\ntype _EveryEngineCapabilityIsMappedOrDeclaredEmpty = EngineCapabilityAccountedFor<\n  Exclude<EngineCapability, EngineCapabilityFilledByAProviderCapability | EngineCapabilityDeclaredEmpty>\n>;\n\n/**\n * The mirror assertion: a capability may not be BOTH mapped and declared empty.\n *\n * Without it the totality check is satisfiable by lying in the easier direction — list a mapped\n * capability as an empty slot and the union still covers the enum, so a genuinely missing mapping\n * elsewhere could be hidden by a bogus declaration here. `TS2344` again, naming the member that\n * appears on both sides.\n */\ntype _NoEngineCapabilityIsBothMappedAndDeclaredEmpty = EngineCapabilityAccountedFor<\n  Extract<EngineCapabilityDeclaredEmpty, EngineCapabilityFilledByAProviderCapability>\n>;\n\n/** @wildo_source:part:start saas.models.engine-capabilities.required-provider-floor facet:layer:shared facet:audience:app-developer */\n/**\n * Engine capabilities that REQUIRE a resolved provider the moment an\n * application ENABLES them — the engine-level MAIN floor (#328).\n *\n * The asymmetry is the thing to carry away: **enabling a capability with nothing serving it fails at\n * BOOT for these three and at the point of USE for every other slot.** So an author who tries one\n * unserved slot, sees the application come up, and concludes that an unserved capability degrades\n * gracefully has learned the wrong rule from the larger half of the vocabulary.\n *\n * `EngineCapabilityActivation.required` is the application's decision;\n * this set is the ENGINE's: for each member, an enabled capability with no\n * provider is not a degraded mode but a boot-time misconfiguration, because\n * an engine flow the application already relies on fails at first use:\n *\n * - `EMAIL_TRANSACTIONAL` — invitations, address verification and password\n *   reset are engine flows that send mail; with no provider they fail\n *   silently at the moment a user needs them.\n * - `BILLING` — `initializeBillingServices` already fails loud with no\n *   provider; the floor names it in the same place as the others.\n * - `SMS` — phone verification and MFA-by-SMS are engine flows.\n *\n * DELIBERATELY ABSENT, with the reason each would need to overturn:\n * - the `AI_*` slots — consumed per feature (an agent, the logo generator)\n *   and legitimately served on a DIFFERENT host (the companion reaches image\n *   generation; the backend need not), so \"enabled with no backend provider\"\n *   is a normal topology, not a fault. A feature that needs one refuses at\n *   its own site.\n * - the sinks (`COMPLIANCE_AUDIT_TRAIL`, `LLM_OBSERVABILITY`,\n *   `OBSERVABILITY_TELEMETRY`) — fail-OPEN by design (the G4 reconcile\n *   warns), because Layer-1 persistence is unaffected.\n * - `EMAIL_MARKETING` — a campaign feature, not an engine flow.\n * - the `FRONTEND_*` slots — resolved by the frontend facet, invisible to\n *   the backend registry that evaluates this floor.\n * - `ORGANIZATIONS` and `MULTI_LANGUAGE` — no provider token maps to them,\n *   deliberately and by declaration; see\n *   `ENGINE_CAPABILITIES_WITH_NO_PROVIDER_CAPABILITY`. A floor requiring a\n *   resolved provider for a slot nothing can fill would refuse every boot that\n *   enabled them. (`BILLING_PAYMENTS` was named here too until it was withdrawn\n *   from the enum on 2026-09-09.)\n *\n * The floor runs only on a host expected to SERVE these slots (see\n * `ApplicationRuntimeProfileBootAssertions.assertsEngineCapabilityProviderFloor`);\n * a minion's scope-filtered registry legitimately resolves none of them.\n */\nexport const ENGINE_CAPABILITIES_REQUIRING_A_PROVIDER_WHEN_ENABLED: ReadonlySet<EngineCapability> = new Set([\n  EngineCapability.EMAIL_TRANSACTIONAL,\n  EngineCapability.BILLING,\n  EngineCapability.SMS,\n]);\n/** @wildo_source:part:end saas.models.engine-capabilities.required-provider-floor */\n"]}

package/dist/esm/external-providers/engine-capability-resolution-mode.shared.d.ts

@@ -1,5 +1,7 @@
 import { EngineCapability } from './engine-capabilities.shared.schemas';
 /**
+ * @wildo_source:part:start saas.models.providers.capability-resolution-mode facet:layer:shared facet:audience:app-developer
+ *
  * How the engine resolves the provider(s) fulfilling an `EngineCapability`
  * when more than one is declared for the same scope.
  *
@@ -12,9 +14,19 @@ import { EngineCapability } from './engine-capabilities.shared.schemas';
  */
 export declare enum EngineCapabilityResolutionMode {
     /**
-     * Exactly one active provider — `selection.<capability>.primary`, with
-     * `fallbacks` tried only on failure. The default for every capability
-     * (billing, email, observability, …): a request is served by one provider.
+     * Exactly one active provider: `selection.<capability>.primary`. The default for every capability
+     * (billing, email, observability, …), and a request is served by that one provider.
+     *
+     * ⚠️ `whenUnavailable` is NOT a failover list, and the field was renamed from `fallbacks` on
+     * 2026-09-08 precisely because that name promised one. It names ORDERED SUBSTITUTES for a
+     * primary that is not AVAILABLE at resolution time — undeclared in the scope, disabled, or
+     * unconfigured — and it decides which provider ends up first in the resolved list. Nothing
+     * retries a second provider when a call to the first one FAILS: the send raises the primary's
+     * error and stops.
+     *
+     * So do not read a declared `whenUnavailable` entry as redundancy, and do not size an
+     * availability argument on it. An application that wants call-time failover builds it at its own
+     * call site, per capability — a deliberate framework boundary, not an omission.
      */
     SELECT_ONE = "SELECT_ONE",
     /**

package/dist/esm/external-providers/engine-capability-resolution-mode.shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-capability-resolution-mode.shared.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/engine-capability-resolution-mode.shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAExE;;;;;;;;;;GAUG;AACH,oBAAY,8BAA8B;IACxC;;;;OAIG;IACH,UAAU,eAAe;IACzB;;;;;OAKG;IACH,OAAO,YAAY;CACpB;AA6CD;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,gBAAgB,GAC3B,8BAA8B,CAEhC"}
+{"version":3,"file":"engine-capability-resolution-mode.shared.d.ts","sourceRoot":"","sources":["../../../src/external-providers/engine-capability-resolution-mode.shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,oBAAY,8BAA8B;IACxC;;;;;;;;;;;;;;OAcG;IACH,UAAU,eAAe;IACzB;;;;;OAKG;IACH,OAAO,YAAY;CACpB;AA4DD;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,gBAAgB,GAC3B,8BAA8B,CAEhC"}