@wildo-ai/saas-models 1.1.2 → 1.1.4

package/dist/esm/external-providers/frontend-provider-public-config.shared.js

@@ -0,0 +1,207 @@
+/**
+ * How an APPLICATION supplies a frontend provider's public configuration — the
+ * keys a picker needs that only the application can know (a Drive `appId`, a
+ * OneDrive `clientId`) — and the two guards that keep that channel from
+ * carrying anything else.
+ *
+ * ## The gap this closes
+ *
+ * A frontend provider's `publicConfig` was HARD-CODED on the engine's provider
+ * module and projected verbatim onto the wire. The only way to set a picker's
+ * `appId` was to edit engine code. The backend never had that problem: an
+ * application authors `providerConfigurations[providerRef][protocolKind]` in
+ * `wildo.saas.config.ts`, and SSO's public OAuth client id already travels that
+ * way, keyed by the protocol (`sso_oauth2`).
+ *
+ * This file gives the frontend the same channel, keyed by the same vocabulary:
+ * `providerConfigurations[providerRef][frontend_sdk]`. One authority for
+ * "what an application configured for this provider", read by both sides.
+ *
+ * ## Two guards, because `publicConfig` is served to every browser
+ *
+ * 1. **Only DECLARED keys cross.** A provider module declares the keys it reads
+ *    (`publicConfigSchema` — see `defineFrontendPublicConfigSchema` below, which
+ *    is what makes those keys READABLE without running the schema). A key the
+ *    module never declared is refused with the provider and key named, at the
+ *    two places the overlay runs: `wildo config sync` and the backend's
+ *    fallback projection. A misspelled `apiId` therefore fails where it was
+ *    typed, instead of silently contributing nothing and leaving a picker that
+ *    reports "no appId" at the moment a user opens it.
+ *
+ * 2. **A secret never crosses.** A frontend provider owns no secrets by
+ *    construction (`secretsContractShape: []`), so the only way one reaches a
+ *    browser is an author typing the BACKEND module's secret into the frontend
+ *    bag. The overlay refuses any key whose name matches a slug or an
+ *    environment-variable name from the same vendor's backend secrets
+ *    contract — `GOOGLE_OAUTH2_CLIENT_SECRET` cannot be typed into the bag that
+ *    every visitor downloads.
+ *
+ * Both guards are decisions about NAMES, so they run wherever the names are
+ * known and need no schema execution. Value VALIDATION (is `appId` a string?)
+ * is the schema's job and runs where the schema is: at hydration (FE-8) and, on
+ * the backend fallback, before serving.
+ *
+ * ## Why the overlay is a pure function in this package
+ *
+ * It has THREE call sites that must agree — the companion walk in
+ * `platform-config-lib`, the backend fallback in `saas-backend-lib`, and any
+ * future producer of a `FrontendProviderEntry` — and #380 already paid once for
+ * a projection that landed on one site and not another. A function both import
+ * cannot be applied differently by each.
+ */
+import { ExternalProvider_ExchangeProtocol_Kind } from '@wildo-ai/external-connectors-models';
+/**
+ * The key under `providerConfigurations[providerRef]` an application uses to
+ * supply a frontend provider's public configuration.
+ *
+ * The protocol kind, exactly as SSO's channel is keyed by ITS protocol kind
+ * (`sso_oauth2`): the bag is per-provider, per-protocol, and a frontend module
+ * speaks `FRONTEND_SDK`. Not a new literal — the enum member is the one source.
+ */
+export const FRONTEND_PROVIDER_PUBLIC_CONFIG_KEY = ExternalProvider_ExchangeProtocol_Kind.FRONTEND_SDK;
+/** Why an application-supplied public-config bag was refused. */
+export var FrontendProviderPublicConfigRefusal;
+(function (FrontendProviderPublicConfigRefusal) {
+    /** A key the provider module does not declare — almost always a misspelling. */
+    FrontendProviderPublicConfigRefusal["UNDECLARED_KEY"] = "UNDECLARED_KEY";
+    /** A key naming a secret from the same vendor's backend contract. Never negotiable. */
+    FrontendProviderPublicConfigRefusal["SECRET_KEY"] = "SECRET_KEY";
+    /** The supplied bag is not a plain object — a string, an array, `null`. */
+    FrontendProviderPublicConfigRefusal["NOT_AN_OBJECT"] = "NOT_AN_OBJECT";
+})(FrontendProviderPublicConfigRefusal || (FrontendProviderPublicConfigRefusal = {}));
+export class FrontendProviderPublicConfigError extends Error {
+    providerRef;
+    refusal;
+    keys;
+    constructor(providerRef, refusal, keys, message) {
+        super(message);
+        this.providerRef = providerRef;
+        this.refusal = refusal;
+        this.keys = keys;
+        this.name = 'FrontendProviderPublicConfigError';
+    }
+}
+/**
+ * Merges what the application supplied over what the module authored, refusing
+ * the two classes of key that must never reach a browser.
+ *
+ * Supplied values WIN over authored ones for the same key: the module's value is
+ * a default, and an application that names a key means it. Absent `supplied`
+ * returns the authored bag untouched — an application that configured nothing
+ * is the ordinary case, not a refusal.
+ */
+export function overlayFrontendProviderPublicConfig(input) {
+    const { providerRef, authored, supplied, declaredKeys, forbiddenKeys } = input;
+    if (supplied === undefined)
+        return authored;
+    if (typeof supplied !== 'object' || supplied === null || Array.isArray(supplied)) {
+        throw new FrontendProviderPublicConfigError(providerRef, FrontendProviderPublicConfigRefusal.NOT_AN_OBJECT, [], `providerConfigurations.${providerRef}.${FRONTEND_PROVIDER_PUBLIC_CONFIG_KEY} must be an object of public `
+            + `keys, got ${Array.isArray(supplied) ? 'an array' : typeof supplied}.`);
+    }
+    const suppliedKeys = Object.keys(supplied);
+    // Guard 2 runs FIRST and unconditionally: a secret is refused even when the
+    // module has no introspectable schema, because that is not the module's call.
+    const secretKeys = suppliedKeys.filter((key) => forbiddenKeys.has(key));
+    if (secretKeys.length > 0) {
+        throw new FrontendProviderPublicConfigError(providerRef, FrontendProviderPublicConfigRefusal.SECRET_KEY, secretKeys, `providerConfigurations.${providerRef}.${FRONTEND_PROVIDER_PUBLIC_CONFIG_KEY} names ${secretKeys.map((key) => `"${key}"`).join(', ')}, `
+            + `which is a SECRET of the "${providerRef}" backend provider. A frontend provider's public configuration is `
+            + 'served to every browser; a secret belongs in the deployment environment under its `envVarName`, and '
+            + 'nowhere else.');
+    }
+    if (declaredKeys !== undefined) {
+        const declared = new Set(declaredKeys);
+        const undeclared = suppliedKeys.filter((key) => !declared.has(key));
+        if (undeclared.length > 0) {
+            throw new FrontendProviderPublicConfigError(providerRef, FrontendProviderPublicConfigRefusal.UNDECLARED_KEY, undeclared, `providerConfigurations.${providerRef}.${FRONTEND_PROVIDER_PUBLIC_CONFIG_KEY} names ${undeclared.map((key) => `"${key}"`).join(', ')}, `
+                + `which the "${providerRef}" frontend provider does not declare. It declares: `
+                + `${declaredKeys.length > 0 ? declaredKeys.map((key) => `"${key}"`).join(', ') : '(nothing)'}. `
+                + 'A key the provider never reads would be served to every browser and used by nothing.');
+        }
+    }
+    return { ...(authored ?? {}), ...supplied };
+}
+/**
+ * The value kinds a public-config key may declare. Scalars only, on purpose: a
+ * public key is an identifier or a flag, and a structured value here is a
+ * design smell — a provider that needs one has a capability-level shape
+ * (`FrontendFilePickerPublicConfigSchema`) to declare it in.
+ */
+export var FrontendPublicConfigValueKind;
+(function (FrontendPublicConfigValueKind) {
+    FrontendPublicConfigValueKind["STRING"] = "string";
+    FrontendPublicConfigValueKind["NUMBER"] = "number";
+    FrontendPublicConfigValueKind["BOOLEAN"] = "boolean";
+})(FrontendPublicConfigValueKind || (FrontendPublicConfigValueKind = {}));
+/**
+ * Declares a frontend provider's public-config keys ONCE and gets both halves:
+ * a strict Standard Schema v1 validator (the CODE half hydration runs) and the
+ * key list (the DATA half the companion walk reads).
+ *
+ * Dependency-free by design. It lives here because the engine's provider modules
+ * live in `@wildo-ai/external-connectors-public`, whose bare-specifier allow-list
+ * holds exactly one entry — this package's `/public-runtime` — so those modules
+ * can declare a schema without that package growing a validation library. An
+ * application module may still use Zod (a Zod object satisfies Standard Schema
+ * and its `shape` keys are read the same way).
+ *
+ * Strict: an unknown key is an issue, never ignored. Silently ignoring is the
+ * defect FE-8 closed — a renamed key yielding `undefined` and a picker that
+ * accepts more than it should with no error anywhere.
+ */
+export function defineFrontendPublicConfigSchema(keys) {
+    const declaredKeys = Object.freeze(Object.keys(keys));
+    return {
+        declaredKeys,
+        '~standard': {
+            version: 1,
+            vendor: 'wildo',
+            validate(value) {
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    return { issues: [{ message: 'public configuration must be an object' }] };
+                }
+                const record = value;
+                const issues = [];
+                for (const key of Object.keys(record)) {
+                    if (!(key in keys))
+                        issues.push({ message: 'unknown key', path: [key] });
+                }
+                for (const [key, spec] of Object.entries(keys)) {
+                    const present = record[key];
+                    if (present === undefined) {
+                        if (spec.required === true)
+                            issues.push({ message: 'required', path: [key] });
+                        continue;
+                    }
+                    if (typeof present !== spec.kind) {
+                        issues.push({ message: `expected a ${spec.kind}, got ${typeof present}`, path: [key] });
+                    }
+                }
+                return issues.length > 0 ? { issues } : { value: record };
+            },
+        },
+    };
+}
+/**
+ * Reads the declared keys off a provider's `publicConfigSchema`, whatever
+ * library produced it.
+ *
+ * Two shapes are recognised, and the order matters: a schema built by
+ * `defineFrontendPublicConfigSchema` states its keys outright; a Zod object
+ * exposes them as `shape`. Anything else — a hand-written Standard Schema, a
+ * library without introspection — yields `undefined`, which the overlay reads
+ * as "cannot enforce here" rather than as "declares nothing". That distinction
+ * is load-bearing: an empty list refuses EVERY supplied key.
+ */
+export function readDeclaredPublicConfigKeys(schema) {
+    if (typeof schema !== 'object' || schema === null)
+        return undefined;
+    const candidate = schema;
+    if (Array.isArray(candidate.declaredKeys) && candidate.declaredKeys.every((key) => typeof key === 'string')) {
+        return candidate.declaredKeys;
+    }
+    if (typeof candidate.shape === 'object' && candidate.shape !== null) {
+        return Object.keys(candidate.shape);
+    }
+    return undefined;
+}
+//# sourceMappingURL=frontend-provider-public-config.shared.js.map

package/dist/esm/external-providers/frontend-provider-public-config.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-provider-public-config.shared.js","sourceRoot":"","sources":["../../../src/external-providers/frontend-provider-public-config.shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How an APPLICATION supplies a frontend provider's public configuration — the\n * keys a picker needs that only the application can know (a Drive `appId`, a\n * OneDrive `clientId`) — and the two guards that keep that channel from\n * carrying anything else.\n *\n * ## The gap this closes\n *\n * A frontend provider's `publicConfig` was HARD-CODED on the engine's provider\n * module and projected verbatim onto the wire. The only way to set a picker's\n * `appId` was to edit engine code. The backend never had that problem: an\n * application authors `providerConfigurations[providerRef][protocolKind]` in\n * `wildo.saas.config.ts`, and SSO's public OAuth client id already travels that\n * way, keyed by the protocol (`sso_oauth2`).\n *\n * This file gives the frontend the same channel, keyed by the same vocabulary:\n * `providerConfigurations[providerRef][frontend_sdk]`. One authority for\n * \"what an application configured for this provider\", read by both sides.\n *\n * ## Two guards, because `publicConfig` is served to every browser\n *\n * 1. **Only DECLARED keys cross.** A provider module declares the keys it reads\n *    (`publicConfigSchema` — see `defineFrontendPublicConfigSchema` below, which\n *    is what makes those keys READABLE without running the schema). A key the\n *    module never declared is refused with the provider and key named, at the\n *    two places the overlay runs: `wildo config sync` and the backend's\n *    fallback projection. A misspelled `apiId` therefore fails where it was\n *    typed, instead of silently contributing nothing and leaving a picker that\n *    reports \"no appId\" at the moment a user opens it.\n *\n * 2. **A secret never crosses.** A frontend provider owns no secrets by\n *    construction (`secretsContractShape: []`), so the only way one reaches a\n *    browser is an author typing the BACKEND module's secret into the frontend\n *    bag. The overlay refuses any key whose name matches a slug or an\n *    environment-variable name from the same vendor's backend secrets\n *    contract — `GOOGLE_OAUTH2_CLIENT_SECRET` cannot be typed into the bag that\n *    every visitor downloads.\n *\n * Both guards are decisions about NAMES, so they run wherever the names are\n * known and need no schema execution. Value VALIDATION (is `appId` a string?)\n * is the schema's job and runs where the schema is: at hydration (FE-8) and, on\n * the backend fallback, before serving.\n *\n * ## Why the overlay is a pure function in this package\n *\n * It has THREE call sites that must agree — the companion walk in\n * `platform-config-lib`, the backend fallback in `saas-backend-lib`, and any\n * future producer of a `FrontendProviderEntry` — and #380 already paid once for\n * a projection that landed on one site and not another. A function both import\n * cannot be applied differently by each.\n */\n\nimport { ExternalProvider_ExchangeProtocol_Kind } from '@wildo-ai/external-connectors-models';\n\n/**\n * The key under `providerConfigurations[providerRef]` an application uses to\n * supply a frontend provider's public configuration.\n *\n * The protocol kind, exactly as SSO's channel is keyed by ITS protocol kind\n * (`sso_oauth2`): the bag is per-provider, per-protocol, and a frontend module\n * speaks `FRONTEND_SDK`. Not a new literal — the enum member is the one source.\n */\nexport const FRONTEND_PROVIDER_PUBLIC_CONFIG_KEY: string = ExternalProvider_ExchangeProtocol_Kind.FRONTEND_SDK;\n\n/** Why an application-supplied public-config bag was refused. */\nexport enum FrontendProviderPublicConfigRefusal {\n  /** A key the provider module does not declare — almost always a misspelling. */\n  UNDECLARED_KEY = 'UNDECLARED_KEY',\n  /** A key naming a secret from the same vendor's backend contract. Never negotiable. */\n  SECRET_KEY = 'SECRET_KEY',\n  /** The supplied bag is not a plain object — a string, an array, `null`. */\n  NOT_AN_OBJECT = 'NOT_AN_OBJECT',\n}\n\nexport class FrontendProviderPublicConfigError extends Error {\n  constructor(\n    readonly providerRef: string,\n    readonly refusal: FrontendProviderPublicConfigRefusal,\n    readonly keys: readonly string[],\n    message: string,\n  ) {\n    super(message);\n    this.name = 'FrontendProviderPublicConfigError';\n  }\n}\n\nexport interface OverlayFrontendProviderPublicConfigInput {\n  readonly providerRef: string;\n  /** What the provider module authored — its own defaults, e.g. `{ authProviderRef: 'google' }`. */\n  readonly authored: Readonly<Record<string, unknown>> | undefined;\n  /** What the application supplied under `providerConfigurations[providerRef][frontend_sdk]`. */\n  readonly supplied: unknown;\n  /**\n   * The keys the provider module declares it reads. `undefined` means the\n   * module declared no introspectable schema, so guard 1 cannot run HERE and\n   * hydration's validation is the gate; an empty array means the module\n   * declares it reads NOTHING, so every supplied key is refused.\n   */\n  readonly declaredKeys: readonly string[] | undefined;\n  /** Slugs and environment-variable names of the same vendor's backend secrets. */\n  readonly forbiddenKeys: ReadonlySet<string>;\n}\n\n/**\n * Merges what the application supplied over what the module authored, refusing\n * the two classes of key that must never reach a browser.\n *\n * Supplied values WIN over authored ones for the same key: the module's value is\n * a default, and an application that names a key means it. Absent `supplied`\n * returns the authored bag untouched — an application that configured nothing\n * is the ordinary case, not a refusal.\n */\nexport function overlayFrontendProviderPublicConfig(\n  input: OverlayFrontendProviderPublicConfigInput,\n): Readonly<Record<string, unknown>> | undefined {\n  const { providerRef, authored, supplied, declaredKeys, forbiddenKeys } = input;\n\n  if (supplied === undefined) return authored;\n\n  if (typeof supplied !== 'object' || supplied === null || Array.isArray(supplied)) {\n    throw new FrontendProviderPublicConfigError(\n      providerRef,\n      FrontendProviderPublicConfigRefusal.NOT_AN_OBJECT,\n      [],\n      `providerConfigurations.${providerRef}.${FRONTEND_PROVIDER_PUBLIC_CONFIG_KEY} must be an object of public `\n      + `keys, got ${Array.isArray(supplied) ? 'an array' : typeof supplied}.`,\n    );\n  }\n\n  const suppliedKeys = Object.keys(supplied);\n\n  // Guard 2 runs FIRST and unconditionally: a secret is refused even when the\n  // module has no introspectable schema, because that is not the module's call.\n  const secretKeys = suppliedKeys.filter((key) => forbiddenKeys.has(key));\n  if (secretKeys.length > 0) {\n    throw new FrontendProviderPublicConfigError(\n      providerRef,\n      FrontendProviderPublicConfigRefusal.SECRET_KEY,\n      secretKeys,\n      `providerConfigurations.${providerRef}.${FRONTEND_PROVIDER_PUBLIC_CONFIG_KEY} names ${secretKeys.map((key) => `\"${key}\"`).join(', ')}, `\n      + `which is a SECRET of the \"${providerRef}\" backend provider. A frontend provider's public configuration is `\n      + 'served to every browser; a secret belongs in the deployment environment under its `envVarName`, and '\n      + 'nowhere else.',\n    );\n  }\n\n  if (declaredKeys !== undefined) {\n    const declared = new Set(declaredKeys);\n    const undeclared = suppliedKeys.filter((key) => !declared.has(key));\n    if (undeclared.length > 0) {\n      throw new FrontendProviderPublicConfigError(\n        providerRef,\n        FrontendProviderPublicConfigRefusal.UNDECLARED_KEY,\n        undeclared,\n        `providerConfigurations.${providerRef}.${FRONTEND_PROVIDER_PUBLIC_CONFIG_KEY} names ${undeclared.map((key) => `\"${key}\"`).join(', ')}, `\n        + `which the \"${providerRef}\" frontend provider does not declare. It declares: `\n        + `${declaredKeys.length > 0 ? declaredKeys.map((key) => `\"${key}\"`).join(', ') : '(nothing)'}. `\n        + 'A key the provider never reads would be served to every browser and used by nothing.',\n      );\n    }\n  }\n\n  return { ...(authored ?? {}), ...(supplied as Record<string, unknown>) };\n}\n\n/**\n * The value kinds a public-config key may declare. Scalars only, on purpose: a\n * public key is an identifier or a flag, and a structured value here is a\n * design smell — a provider that needs one has a capability-level shape\n * (`FrontendFilePickerPublicConfigSchema`) to declare it in.\n */\nexport enum FrontendPublicConfigValueKind {\n  STRING = 'string',\n  NUMBER = 'number',\n  BOOLEAN = 'boolean',\n}\n\nexport interface FrontendPublicConfigKeySpec {\n  readonly kind: FrontendPublicConfigValueKind;\n  /** Absent = optional. Picker keys are usually optional: a missing one is reported when the picker opens, not by dropping the provider. */\n  readonly required?: boolean;\n  /** For the person writing `wildo.saas.config.ts`. Not validated; surfaced in refusals. */\n  readonly description?: string;\n}\n\n/** A Standard Schema v1 validator that ALSO says which keys it declares. */\nexport interface FrontendPublicConfigSchema<TOutput = Readonly<Record<string, unknown>>> {\n  readonly '~standard': {\n    readonly version: 1;\n    readonly vendor: 'wildo';\n    validate(value: unknown):\n      | { readonly value: TOutput }\n      | { readonly issues: ReadonlyArray<{ readonly message: string; readonly path?: ReadonlyArray<PropertyKey> }> };\n  };\n  /**\n   * The keys this schema admits, readable without running it.\n   *\n   * This is the DATA half of the declaration, and it is why this helper exists\n   * rather than \"use Zod\": Standard Schema v1 exposes `validate` and nothing\n   * else, so a schema alone cannot tell the companion walk which keys an\n   * application may supply — and the walk runs in Node, from a projected\n   * contribution, without the module. `projectFrontendProviderContribution`\n   * mirrors this list onto the entry as `publicConfigKeys`.\n   */\n  readonly declaredKeys: readonly string[];\n}\n\n/**\n * Declares a frontend provider's public-config keys ONCE and gets both halves:\n * a strict Standard Schema v1 validator (the CODE half hydration runs) and the\n * key list (the DATA half the companion walk reads).\n *\n * Dependency-free by design. It lives here because the engine's provider modules\n * live in `@wildo-ai/external-connectors-public`, whose bare-specifier allow-list\n * holds exactly one entry — this package's `/public-runtime` — so those modules\n * can declare a schema without that package growing a validation library. An\n * application module may still use Zod (a Zod object satisfies Standard Schema\n * and its `shape` keys are read the same way).\n *\n * Strict: an unknown key is an issue, never ignored. Silently ignoring is the\n * defect FE-8 closed — a renamed key yielding `undefined` and a picker that\n * accepts more than it should with no error anywhere.\n */\nexport function defineFrontendPublicConfigSchema(\n  keys: Readonly<Record<string, FrontendPublicConfigKeySpec>>,\n): FrontendPublicConfigSchema {\n  const declaredKeys = Object.freeze(Object.keys(keys));\n\n  return {\n    declaredKeys,\n    '~standard': {\n      version: 1,\n      vendor: 'wildo',\n      validate(value: unknown) {\n        if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n          return { issues: [{ message: 'public configuration must be an object' }] };\n        }\n        const record = value as Record<string, unknown>;\n        const issues: Array<{ message: string; path?: PropertyKey[] }> = [];\n\n        for (const key of Object.keys(record)) {\n          if (!(key in keys)) issues.push({ message: 'unknown key', path: [key] });\n        }\n        for (const [key, spec] of Object.entries(keys)) {\n          const present = record[key];\n          if (present === undefined) {\n            if (spec.required === true) issues.push({ message: 'required', path: [key] });\n            continue;\n          }\n          if (typeof present !== spec.kind) {\n            issues.push({ message: `expected a ${spec.kind}, got ${typeof present}`, path: [key] });\n          }\n        }\n\n        return issues.length > 0 ? { issues } : { value: record };\n      },\n    },\n  };\n}\n\n/**\n * Reads the declared keys off a provider's `publicConfigSchema`, whatever\n * library produced it.\n *\n * Two shapes are recognised, and the order matters: a schema built by\n * `defineFrontendPublicConfigSchema` states its keys outright; a Zod object\n * exposes them as `shape`. Anything else — a hand-written Standard Schema, a\n * library without introspection — yields `undefined`, which the overlay reads\n * as \"cannot enforce here\" rather than as \"declares nothing\". That distinction\n * is load-bearing: an empty list refuses EVERY supplied key.\n */\nexport function readDeclaredPublicConfigKeys(schema: unknown): readonly string[] | undefined {\n  if (typeof schema !== 'object' || schema === null) return undefined;\n  const candidate = schema as { declaredKeys?: unknown; shape?: unknown };\n  if (Array.isArray(candidate.declaredKeys) && candidate.declaredKeys.every((key) => typeof key === 'string')) {\n    return candidate.declaredKeys as readonly string[];\n  }\n  if (typeof candidate.shape === 'object' && candidate.shape !== null) {\n    return Object.keys(candidate.shape as Record<string, unknown>);\n  }\n  return undefined;\n}\n"]}

package/dist/esm/external-providers/provider-capability.shared.schemas.d.ts

@@ -20,8 +20,10 @@
  * Authoring rule: keep this list narrow and stable. Adding a new
  * built-in capability is a framework-level decision (it implies the
  * engine knows how to consume the capability via a transformer or a
- * platform binding); apps that need a one-off capability MUST extend
- * via `AppCustomProviderCapabilities` instead.
+ * platform binding). There is no app-side extension point: an application
+ * needing a capability this vocabulary does not name is a decision to widen
+ * the vocabulary, taken with the resolution path that would make it mean
+ * something (#502).
  */
 export declare const BUILTIN_PROVIDER_CAPABILITY: {
     readonly EMAIL_TRANSACTIONAL: "EMAIL_TRANSACTIONAL";
@@ -102,35 +104,10 @@ export declare const BUILTIN_PROVIDER_CAPABILITY: {
 };
 /** @wildo_source:part:end saas.models.provider-capabilities */
 export type BuiltinProviderCapability = (typeof BUILTIN_PROVIDER_CAPABILITY)[keyof typeof BUILTIN_PROVIDER_CAPABILITY];
-/**
- * Open extension point — apps augment via TypeScript module augmentation
- * inside their `wildo.saas.config.ts`. See analysis §10 Q2 for the
- * design decision (no `app.d.ts` file; declaration merging happens
- * inline in the saas config so the surface is co-located with the
- * authored configuration).
- *
- * Example app-side augmentation:
- *
- * ```ts
- * declare module '@wildo-ai/saas-models' {
- *   interface AppCustomProviderCapabilities {
- *     'live-chat-handoff': true;
- *     'search-index': true;
- *   }
- * }
- * ```
- *
- * Phase 3.d (per the implementation plan) wires this augmentation point
- * into `BackendProviderRegistry.getProvidersByProviderCapability()` so
- * apps can register and resolve custom capabilities in a fully
- * type-checked way. In Phase 0 the interface is intentionally empty.
- */
-export interface AppCustomProviderCapabilities {
-}
 /**
  * Union of every possible provider capability — the closed built-in set
  * plus any app-side augmentations. Consumers (registries, transformers,
  * lock-file digests) accept this union.
  */
-export type ProviderCapability = BuiltinProviderCapability | keyof AppCustomProviderCapabilities;
+export type ProviderCapability = BuiltinProviderCapability;
 //# sourceMappingURL=provider-capability.shared.schemas.d.ts.map

package/dist/esm/external-providers/provider-capability.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-capability.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-capability.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B;;;;IAItC;;;;;;;;OAQG;;;IAGH,sEAAsE;;;;IAItE;;;;;;;;;;;;;;OAcG;;IAEH;;;;;;;;;;OAUG;;;;;;;;IAQH;;;;;OAKG;;IAEH;;;;;OAKG;;IAEH;;;;;;;OAOG;;CAEK,CAAC;AACX,+DAA+D;AAE/D,MAAM,MAAM,yBAAyB,GACnC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,6BAA6B;CAAG;AAEjD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B,yBAAyB,GACzB,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"provider-capability.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/external-providers/provider-capability.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B;;;;IAItC;;;;;;;;OAQG;;;IAGH,sEAAsE;;;;IAItE;;;;;;;;;;;;;;OAcG;;IAEH;;;;;;;;;;OAUG;;;;;;;;IAQH;;;;;OAKG;;IAEH;;;;;OAKG;;IAEH;;;;;;;OAOG;;CAEK,CAAC;AACX,+DAA+D;AAE/D,MAAM,MAAM,yBAAyB,GACnC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAC;AAiBjF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,CAAC"}

package/dist/esm/external-providers/provider-capability.shared.schemas.js

@@ -20,8 +20,10 @@
  * Authoring rule: keep this list narrow and stable. Adding a new
  * built-in capability is a framework-level decision (it implies the
  * engine knows how to consume the capability via a transformer or a
- * platform binding); apps that need a one-off capability MUST extend
- * via `AppCustomProviderCapabilities` instead.
+ * platform binding). There is no app-side extension point: an application
+ * needing a capability this vocabulary does not name is a decision to widen
+ * the vocabulary, taken with the resolution path that would make it mean
+ * something (#502).
  */
 export const BUILTIN_PROVIDER_CAPABILITY = {
     EMAIL_TRANSACTIONAL: 'EMAIL_TRANSACTIONAL',

package/dist/esm/external-providers/provider-capability.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-capability.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-capability.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,mBAAmB,EAAE,qBAAqB;IAC1C,eAAe,EAAE,iBAAiB;IAClC,GAAG,EAAE,KAAK;IACV;;;;;;;;OAQG;IACH,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,YAAY;IACxB,sEAAsE;IACtE,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,cAAc,EAAE,gBAAgB;IAChC;;;;;;;;;;;;;;OAcG;IACH,wBAAwB,EAAE,0BAA0B;IACpD;;;;;;;;;;OAUG;IACH,YAAY,EAAE,cAAc;IAC5B,gBAAgB,EAAE,kBAAkB;IACpC,yBAAyB,EAAE,2BAA2B;IACtD,0BAA0B,EAAE,4BAA4B;IACxD,eAAe,EAAE,iBAAiB;IAClC,oBAAoB,EAAE,sBAAsB;IAC5C,gBAAgB,EAAE,kBAAkB;IACpC;;;;;OAKG;IACH,iBAAiB,EAAE,mBAAmB;IACtC;;;;;OAKG;IACH,uBAAuB,EAAE,yBAAyB;IAClD;;;;;;;OAOG;IACH,sBAAsB,EAAE,wBAAwB;CACxC,CAAC","sourcesContent":["/**\n * `ProviderCapability` — open, app-extensible enum of standardized\n * behaviors that providers implement.\n *\n * Distinct from `EngineCapability` (closed, engine-defined slots that\n * may require fulfillment). See the analysis glossary in\n * `.cursor/plans/provider-registration-refactor-draft-analysis.md` §14\n * for the full naming rationale; this file is the canonical Phase-0\n * authoring surface called out in §Phase 0.2 of the implementation\n * plan.\n *\n * Built-in values use SCREAMING_SNAKE_CASE; app-augmented values SHOULD\n * use kebab-case + domain prefix (e.g. `'live-chat-handoff'`,\n * `'search-index'`). The two namespaces never collide by construction.\n */\n\n/** @wildo_source:part:start saas.models.provider-capabilities facet:kind:api facet:audience:app-developer\n *\n * Built-in provider capabilities shipped by the framework.\n *\n * Authoring rule: keep this list narrow and stable. Adding a new\n * built-in capability is a framework-level decision (it implies the\n * engine knows how to consume the capability via a transformer or a\n * platform binding); apps that need a one-off capability MUST extend\n * via `AppCustomProviderCapabilities` instead.\n */\nexport const BUILTIN_PROVIDER_CAPABILITY = {\n  EMAIL_TRANSACTIONAL: 'EMAIL_TRANSACTIONAL',\n  EMAIL_MARKETING: 'EMAIL_MARKETING',\n  SMS: 'SMS',\n  /**\n   * Single billing-engagement capability covering everything from\n   * Checkout-style hosted flows to first-party PaymentIntent flows.\n   * Webhook delivery is NOT a separate capability — it is modelled at\n   * the protocol layer (e.g. Stripe declares both a `BILLING_PROVIDER`\n   * and a `WEBHOOK_ORIGINATOR` protocol but a single `BILLING`\n   * capability). This 1:1 matches the billing slot from the older\n   * external connector transformer vocabulary.\n   */\n  BILLING: 'BILLING',\n  SSO_OAUTH2: 'SSO_OAUTH2',\n  /** Reserved for future SAML-based SSO providers (none ship today). */\n  SSO_SAML: 'SSO_SAML',\n  LLM_CHAT: 'LLM_CHAT',\n  LLM_EMBEDDINGS: 'LLM_EMBEDDINGS',\n  /**\n   * Provider turns DOCUMENT BYTES into text — OCR over scans and photographs of pages, not merely\n   * a read of a PDF's existing text layer. Maps to `EngineCapability.AI_DOCUMENT_EXTRACTION`.\n   *\n   * A NEW token was genuinely required rather than convenient: `IMAGE_GENERATION` is an OUTPUT\n   * capability (text → image), and PDF *generation* — the `pdfTemplates` surface — is this\n   * capability's exact opposite. Nothing in the existing vocabulary claimed the document-INPUT\n   * slot. (This paragraph used to name `EngineCapability.DOCUMENT_GENERATION`; that member was\n   * withdrawn because no provider capability could fill it.)\n   *\n   * Distinct from `LLM_CHAT` even where a vendor serves both from one API key: the work is\n   * different (a page-layout model, billed per page, with no sampling parameters), and fusing\n   * them would make the OCR provider unselectable independently of the chat provider — the exact\n   * defect that splitting `AI_EMBEDDINGS` out of `AI_LLM` existed to fix.\n   */\n  DOCUMENT_TEXT_EXTRACTION: 'DOCUMENT_TEXT_EXTRACTION',\n  /**\n   * Provider ships an autonomous CODING AGENT: a process that reads and writes\n   * a workspace, runs commands, and requests authorisation, reachable over the\n   * Agent Client Protocol.\n   *\n   * Distinct from `LLM_CHAT` because the WORK is\n   * different, not merely its transport. A chat model returns text for a caller\n   * to act on; a coding agent acts, and the resulting obligations — permission\n   * decisions, mutation scope, change attribution, verification — have no\n   * counterpart in a completion call.\n   */\n  CODING_AGENT: 'CODING_AGENT',\n  IMAGE_GENERATION: 'IMAGE_GENERATION',\n  FRONTEND_ERROR_MONITORING: 'FRONTEND_ERROR_MONITORING',\n  FRONTEND_PRODUCT_ANALYTICS: 'FRONTEND_PRODUCT_ANALYTICS',\n  FRONTEND_SEARCH: 'FRONTEND_SEARCH',\n  FRONTEND_FILE_PICKER: 'FRONTEND_FILE_PICKER',\n  FRONTEND_CAPTCHA: 'FRONTEND_CAPTCHA',\n  /**\n   * Backend LLM-call observability — a provider that ingests per-`invokeAgent`\n   * generation traces (model / tokens / cost / latency), e.g. PostHog\n   * `$ai_generation`. Maps to `EngineCapability.LLM_OBSERVABILITY`. The engine\n   * consumes it via the `AgentCallTraceSink` (not a request/response transformer).\n   */\n  LLM_OBSERVABILITY: 'LLM_OBSERVABILITY',\n  /**\n   * Operational-telemetry sink — a provider that ingests OpenTelemetry traces,\n   * metrics, and logs over OTLP (e.g. BetterStack). Maps to\n   * `EngineCapability.OBSERVABILITY_TELEMETRY`. Consumed by the OTel SDK preload\n   * (env-var-driven), NOT a request/response transformer or a DI sink.\n   */\n  OBSERVABILITY_TELEMETRY: 'OBSERVABILITY_TELEMETRY',\n  /**\n   * Audit-log sink — a provider that stores or forwards compliance audit\n   * events (who-did-what-when), e.g. immudb (tamper-evident) or a SIEM\n   * webhook. Maps to `EngineCapability.COMPLIANCE_AUDIT_TRAIL`, a FAN_OUT\n   * capability: every declared audit provider receives every event (see\n   * `getEngineCapabilityResolutionMode`). The engine consumes it via the\n   * `AuditLogSink` DI fan-out, layered on the always-on database audit store.\n   */\n  COMPLIANCE_AUDIT_TRAIL: 'COMPLIANCE_AUDIT_TRAIL',\n} as const;\n/** @wildo_source:part:end saas.models.provider-capabilities */\n\nexport type BuiltinProviderCapability =\n  (typeof BUILTIN_PROVIDER_CAPABILITY)[keyof typeof BUILTIN_PROVIDER_CAPABILITY];\n\n/**\n * Open extension point — apps augment via TypeScript module augmentation\n * inside their `wildo.saas.config.ts`. See analysis §10 Q2 for the\n * design decision (no `app.d.ts` file; declaration merging happens\n * inline in the saas config so the surface is co-located with the\n * authored configuration).\n *\n * Example app-side augmentation:\n *\n * ```ts\n * declare module '@wildo-ai/saas-models' {\n *   interface AppCustomProviderCapabilities {\n *     'live-chat-handoff': true;\n *     'search-index': true;\n *   }\n * }\n * ```\n *\n * Phase 3.d (per the implementation plan) wires this augmentation point\n * into `BackendProviderRegistry.getProvidersByProviderCapability()` so\n * apps can register and resolve custom capabilities in a fully\n * type-checked way. In Phase 0 the interface is intentionally empty.\n */\nexport interface AppCustomProviderCapabilities {}\n\n/**\n * Union of every possible provider capability — the closed built-in set\n * plus any app-side augmentations. Consumers (registries, transformers,\n * lock-file digests) accept this union.\n */\nexport type ProviderCapability =\n  | BuiltinProviderCapability\n  | keyof AppCustomProviderCapabilities;\n"]}
+{"version":3,"file":"provider-capability.shared.schemas.js","sourceRoot":"","sources":["../../../src/external-providers/provider-capability.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,mBAAmB,EAAE,qBAAqB;IAC1C,eAAe,EAAE,iBAAiB;IAClC,GAAG,EAAE,KAAK;IACV;;;;;;;;OAQG;IACH,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,YAAY;IACxB,sEAAsE;IACtE,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,cAAc,EAAE,gBAAgB;IAChC;;;;;;;;;;;;;;OAcG;IACH,wBAAwB,EAAE,0BAA0B;IACpD;;;;;;;;;;OAUG;IACH,YAAY,EAAE,cAAc;IAC5B,gBAAgB,EAAE,kBAAkB;IACpC,yBAAyB,EAAE,2BAA2B;IACtD,0BAA0B,EAAE,4BAA4B;IACxD,eAAe,EAAE,iBAAiB;IAClC,oBAAoB,EAAE,sBAAsB;IAC5C,gBAAgB,EAAE,kBAAkB;IACpC;;;;;OAKG;IACH,iBAAiB,EAAE,mBAAmB;IACtC;;;;;OAKG;IACH,uBAAuB,EAAE,yBAAyB;IAClD;;;;;;;OAOG;IACH,sBAAsB,EAAE,wBAAwB;CACxC,CAAC","sourcesContent":["/**\n * `ProviderCapability` — open, app-extensible enum of standardized\n * behaviors that providers implement.\n *\n * Distinct from `EngineCapability` (closed, engine-defined slots that\n * may require fulfillment). See the analysis glossary in\n * `.cursor/plans/provider-registration-refactor-draft-analysis.md` §14\n * for the full naming rationale; this file is the canonical Phase-0\n * authoring surface called out in §Phase 0.2 of the implementation\n * plan.\n *\n * Built-in values use SCREAMING_SNAKE_CASE; app-augmented values SHOULD\n * use kebab-case + domain prefix (e.g. `'live-chat-handoff'`,\n * `'search-index'`). The two namespaces never collide by construction.\n */\n\n/** @wildo_source:part:start saas.models.provider-capabilities facet:kind:api facet:audience:app-developer\n *\n * Built-in provider capabilities shipped by the framework.\n *\n * Authoring rule: keep this list narrow and stable. Adding a new\n * built-in capability is a framework-level decision (it implies the\n * engine knows how to consume the capability via a transformer or a\n * platform binding). There is no app-side extension point: an application\n * needing a capability this vocabulary does not name is a decision to widen\n * the vocabulary, taken with the resolution path that would make it mean\n * something (#502).\n */\nexport const BUILTIN_PROVIDER_CAPABILITY = {\n  EMAIL_TRANSACTIONAL: 'EMAIL_TRANSACTIONAL',\n  EMAIL_MARKETING: 'EMAIL_MARKETING',\n  SMS: 'SMS',\n  /**\n   * Single billing-engagement capability covering everything from\n   * Checkout-style hosted flows to first-party PaymentIntent flows.\n   * Webhook delivery is NOT a separate capability — it is modelled at\n   * the protocol layer (e.g. Stripe declares both a `BILLING_PROVIDER`\n   * and a `WEBHOOK_ORIGINATOR` protocol but a single `BILLING`\n   * capability). This 1:1 matches the billing slot from the older\n   * external connector transformer vocabulary.\n   */\n  BILLING: 'BILLING',\n  SSO_OAUTH2: 'SSO_OAUTH2',\n  /** Reserved for future SAML-based SSO providers (none ship today). */\n  SSO_SAML: 'SSO_SAML',\n  LLM_CHAT: 'LLM_CHAT',\n  LLM_EMBEDDINGS: 'LLM_EMBEDDINGS',\n  /**\n   * Provider turns DOCUMENT BYTES into text — OCR over scans and photographs of pages, not merely\n   * a read of a PDF's existing text layer. Maps to `EngineCapability.AI_DOCUMENT_EXTRACTION`.\n   *\n   * A NEW token was genuinely required rather than convenient: `IMAGE_GENERATION` is an OUTPUT\n   * capability (text → image), and PDF *generation* — the `pdfTemplates` surface — is this\n   * capability's exact opposite. Nothing in the existing vocabulary claimed the document-INPUT\n   * slot. (This paragraph used to name `EngineCapability.DOCUMENT_GENERATION`; that member was\n   * withdrawn because no provider capability could fill it.)\n   *\n   * Distinct from `LLM_CHAT` even where a vendor serves both from one API key: the work is\n   * different (a page-layout model, billed per page, with no sampling parameters), and fusing\n   * them would make the OCR provider unselectable independently of the chat provider — the exact\n   * defect that splitting `AI_EMBEDDINGS` out of `AI_LLM` existed to fix.\n   */\n  DOCUMENT_TEXT_EXTRACTION: 'DOCUMENT_TEXT_EXTRACTION',\n  /**\n   * Provider ships an autonomous CODING AGENT: a process that reads and writes\n   * a workspace, runs commands, and requests authorisation, reachable over the\n   * Agent Client Protocol.\n   *\n   * Distinct from `LLM_CHAT` because the WORK is\n   * different, not merely its transport. A chat model returns text for a caller\n   * to act on; a coding agent acts, and the resulting obligations — permission\n   * decisions, mutation scope, change attribution, verification — have no\n   * counterpart in a completion call.\n   */\n  CODING_AGENT: 'CODING_AGENT',\n  IMAGE_GENERATION: 'IMAGE_GENERATION',\n  FRONTEND_ERROR_MONITORING: 'FRONTEND_ERROR_MONITORING',\n  FRONTEND_PRODUCT_ANALYTICS: 'FRONTEND_PRODUCT_ANALYTICS',\n  FRONTEND_SEARCH: 'FRONTEND_SEARCH',\n  FRONTEND_FILE_PICKER: 'FRONTEND_FILE_PICKER',\n  FRONTEND_CAPTCHA: 'FRONTEND_CAPTCHA',\n  /**\n   * Backend LLM-call observability — a provider that ingests per-`invokeAgent`\n   * generation traces (model / tokens / cost / latency), e.g. PostHog\n   * `$ai_generation`. Maps to `EngineCapability.LLM_OBSERVABILITY`. The engine\n   * consumes it via the `AgentCallTraceSink` (not a request/response transformer).\n   */\n  LLM_OBSERVABILITY: 'LLM_OBSERVABILITY',\n  /**\n   * Operational-telemetry sink — a provider that ingests OpenTelemetry traces,\n   * metrics, and logs over OTLP (e.g. BetterStack). Maps to\n   * `EngineCapability.OBSERVABILITY_TELEMETRY`. Consumed by the OTel SDK preload\n   * (env-var-driven), NOT a request/response transformer or a DI sink.\n   */\n  OBSERVABILITY_TELEMETRY: 'OBSERVABILITY_TELEMETRY',\n  /**\n   * Audit-log sink — a provider that stores or forwards compliance audit\n   * events (who-did-what-when), e.g. immudb (tamper-evident) or a SIEM\n   * webhook. Maps to `EngineCapability.COMPLIANCE_AUDIT_TRAIL`, a FAN_OUT\n   * capability: every declared audit provider receives every event (see\n   * `getEngineCapabilityResolutionMode`). The engine consumes it via the\n   * `AuditLogSink` DI fan-out, layered on the always-on database audit store.\n   */\n  COMPLIANCE_AUDIT_TRAIL: 'COMPLIANCE_AUDIT_TRAIL',\n} as const;\n/** @wildo_source:part:end saas.models.provider-capabilities */\n\nexport type BuiltinProviderCapability =\n  (typeof BUILTIN_PROVIDER_CAPABILITY)[keyof typeof BUILTIN_PROVIDER_CAPABILITY];\n\n/*\n * The app-side augmentation point was REMOVED here (#502, decided 2026-09-08).\n *\n * `AppCustomProviderCapabilities` was an empty interface, extended by no application in the\n * repository, whose own docstring described wiring it into `getProvidersByProviderCapability()` as a\n * later phase nobody scheduled. It offered a choice that did not exist: `keyof` an empty interface is\n * `never`, so the union below already resolved to `BuiltinProviderCapability` and removing it changes\n * the resolved type for none of its consumers.\n *\n * If an application genuinely needs a capability the built-in vocabulary does not name, that is a\n * decision about widening a CLOSED semantic vocabulary — with a resolution path built at the same\n * time — not an empty interface left open in advance. An extension point with no resolver is not\n * extensibility; it is a promise nothing can keep.\n */\n\n/**\n * Union of every possible provider capability — the closed built-in set\n * plus any app-side augmentations. Consumers (registries, transformers,\n * lock-file digests) accept this union.\n */\nexport type ProviderCapability = BuiltinProviderCapability;\n"]}

package/dist/esm/external-providers/provider-compliance-profile.shared.schemas.d.ts

@@ -95,6 +95,7 @@ export declare function providerIsAlwaysSelfHosted(profile: ProviderCompliancePr
  * application's configuration decides whether it is a recipient at all.
  */
 export declare function providerDeploymentModelIsAnOperatorChoice(profile: ProviderComplianceProfile): boolean;
+/** @wildo_source:part:start saas.models.providers.compliance-choice facet:layer:shared facet:audience:app-developer */
 /**
  * The application's CHOICE among what a provider offers — one entry per configured provider.
  *
@@ -120,10 +121,19 @@ export declare const ApplicationProviderComplianceChoiceSchema: z.ZodObject<{
     /**
      * Which region this provider processes in, chosen from what the provider declares possible.
      *
-     * Validated against the provider's declared list at BOOT rather than here — this schema cannot see
-     * the provider registry, and refusing an unlisted region would make a vendor's new data centre an
-     * application build failure. A region outside the list is APP-ASSERTED and reported, never refused
-     * (the same warn-do-not-block posture as the personal-data declaration report).
+     * NOT validated here, and NOT validated at boot either. This schema cannot see the provider
+     * registry, and refusing an unlisted region would make a vendor's new data centre an application
+     * build failure, so the intended posture is warn-do-not-block: a region outside the provider's
+     * declared list is APP-ASSERTED and reported, never refused.
+     *
+     * WIRED since 2026-09-10 (issue #308). `appAssertedProcessingRegions` below computes exactly that
+     * set, and the companion's compliance-primary-facts section reports it per provider, naming both the
+     * configured value and what the provider declares — because a divergence is either a typo or a stale
+     * provider module, and those are opposite work. It took this long only because of a DATA PATH: the
+     * vendor's region list lives on the backend provider module and the renderer reads provider
+     * SPECIFICATIONS, so the helper could not be called until `complianceProfile` was mirrored onto the
+     * specification contract. Any future report must call this helper rather than re-derive the
+     * comparison.
      */
     processingRegion: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -142,10 +152,19 @@ export declare const ApplicationProviderComplianceChoicesSchema: z.ZodRecord<z.Z
     /**
      * Which region this provider processes in, chosen from what the provider declares possible.
      *
-     * Validated against the provider's declared list at BOOT rather than here — this schema cannot see
-     * the provider registry, and refusing an unlisted region would make a vendor's new data centre an
-     * application build failure. A region outside the list is APP-ASSERTED and reported, never refused
-     * (the same warn-do-not-block posture as the personal-data declaration report).
+     * NOT validated here, and NOT validated at boot either. This schema cannot see the provider
+     * registry, and refusing an unlisted region would make a vendor's new data centre an application
+     * build failure, so the intended posture is warn-do-not-block: a region outside the provider's
+     * declared list is APP-ASSERTED and reported, never refused.
+     *
+     * WIRED since 2026-09-10 (issue #308). `appAssertedProcessingRegions` below computes exactly that
+     * set, and the companion's compliance-primary-facts section reports it per provider, naming both the
+     * configured value and what the provider declares — because a divergence is either a typo or a stale
+     * provider module, and those are opposite work. It took this long only because of a DATA PATH: the
+     * vendor's region list lives on the backend provider module and the renderer reads provider
+     * SPECIFICATIONS, so the helper could not be called until `complianceProfile` was mirrored onto the
+     * specification contract. Any future report must call this helper rather than re-derive the
+     * comparison.
      */
     processingRegion: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>>;
@@ -165,6 +184,7 @@ export declare function appAssertedProcessingRegions(params: {
     readonly providerRef: string;
     readonly region: string;
 }>;
+/** @wildo_source:part:end saas.models.providers.compliance-choice */
 /**
  * The configured providers that are THIRD-PARTY RECIPIENTS — vendor-hosted, and therefore processors.
  *

package/dist/esm/external-providers/provider-compliance-profile.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-compliance-profile.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-compliance-profile.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,oBAAY,uBAAuB;IACjC;;;OAGG;IACH,aAAa,kBAAkB;IAC/B;;;;OAIG;IACH,WAAW,gBAAgB;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,+BAA+B;IAC1C;;;;;;OAMG;;IAEH;;;;;;;;;;;;;OAaG;;IAEH;;;;;;;OAOG;;kBAkBH,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,4GAA4G;AAC5G,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAEtF;AAED;;;;;GAKG;AACH,wBAAgB,yCAAyC,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAErG;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yCAAyC;IACpD;;;;;;;OAOG;;IAEH;;;;;;;OAOG;;kBAyBH,CAAC;AACH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yCAAyC,CAAC,CAAC;AAE5G,qEAAqE;AACrE,eAAO,MAAM,0CAA0C;IA7CrD;;;;;;;OAOG;;IAEH;;;;;;;OAOG;;mBAgCJ,CAAC;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0CAA0C,CAAC,CAAC;AAE9G;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,QAAQ,CAAC,OAAO,EAAE,oCAAoC,CAAC;IACvD,QAAQ,CAAC,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;CACrF,GAAG,aAAa,CAAC;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAc3E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,oCAAoC,GAAG,SAAS,MAAM,EAAE,CAKzG"}
+{"version":3,"file":"provider-compliance-profile.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/external-providers/provider-compliance-profile.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,oBAAY,uBAAuB;IACjC;;;OAGG;IACH,aAAa,kBAAkB;IAC/B;;;;OAIG;IACH,WAAW,gBAAgB;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,+BAA+B;IAC1C;;;;;;OAMG;;IAEH;;;;;;;;;;;;;OAaG;;IAEH;;;;;;;OAOG;;kBAkBH,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,4GAA4G;AAC5G,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAEtF;AAED;;;;;GAKG;AACH,wBAAgB,yCAAyC,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAErG;AAED,uHAAuH;AACvH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yCAAyC;IACpD;;;;;;;OAOG;;IAEH;;;;;;;;;;;;;;;;OAgBG;;kBAyBH,CAAC;AACH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yCAAyC,CAAC,CAAC;AAE5G,qEAAqE;AACrE,eAAO,MAAM,0CAA0C;IAtDrD;;;;;;;OAOG;;IAEH;;;;;;;;;;;;;;;;OAgBG;;mBAgCJ,CAAC;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0CAA0C,CAAC,CAAC;AAE9G;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,QAAQ,CAAC,OAAO,EAAE,oCAAoC,CAAC;IACvD,QAAQ,CAAC,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;CACrF,GAAG,aAAa,CAAC;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAc3E;AACD,qEAAqE;AAErE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,oCAAoC,GAAG,SAAS,MAAM,EAAE,CAKzG"}

package/dist/esm/external-providers/provider-compliance-profile.shared.schemas.js

@@ -115,6 +115,7 @@ export function providerIsAlwaysSelfHosted(profile) {
 export function providerDeploymentModelIsAnOperatorChoice(profile) {
     return profile.deploymentModels.length > 1;
 }
+/** @wildo_source:part:start saas.models.providers.compliance-choice facet:layer:shared facet:audience:app-developer */
 /**
  * The application's CHOICE among what a provider offers — one entry per configured provider.
  *
@@ -140,10 +141,19 @@ export const ApplicationProviderComplianceChoiceSchema = z.strictObject({
     /**
      * Which region this provider processes in, chosen from what the provider declares possible.
      *
-     * Validated against the provider's declared list at BOOT rather than here — this schema cannot see
-     * the provider registry, and refusing an unlisted region would make a vendor's new data centre an
-     * application build failure. A region outside the list is APP-ASSERTED and reported, never refused
-     * (the same warn-do-not-block posture as the personal-data declaration report).
+     * NOT validated here, and NOT validated at boot either. This schema cannot see the provider
+     * registry, and refusing an unlisted region would make a vendor's new data centre an application
+     * build failure, so the intended posture is warn-do-not-block: a region outside the provider's
+     * declared list is APP-ASSERTED and reported, never refused.
+     *
+     * WIRED since 2026-09-10 (issue #308). `appAssertedProcessingRegions` below computes exactly that
+     * set, and the companion's compliance-primary-facts section reports it per provider, naming both the
+     * configured value and what the provider declares — because a divergence is either a typo or a stale
+     * provider module, and those are opposite work. It took this long only because of a DATA PATH: the
+     * vendor's region list lives on the backend provider module and the renderer reads provider
+     * SPECIFICATIONS, so the helper could not be called until `complianceProfile` was mirrored onto the
+     * specification contract. Any future report must call this helper rather than re-derive the
+     * comparison.
      */
     processingRegion: z.string().trim().min(1).optional(),
 }).superRefine((choice, context) => {
@@ -196,6 +206,7 @@ export function appAssertedProcessingRegions(params) {
     }
     return asserted;
 }
+/** @wildo_source:part:end saas.models.providers.compliance-choice */
 /**
  * The configured providers that are THIRD-PARTY RECIPIENTS — vendor-hosted, and therefore processors.
  *

package/dist/esm/external-providers/provider-compliance-profile.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-compliance-profile.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-compliance-profile.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\n/**\n * WHO RUNS the software a provider module drives.\n *\n * This is the axis that decides whether a provider is a third-party RECIPIENT of personal data at\n * all, and until 2026-08-30 it did not exist anywhere in the provider model. immudb is described in\n * `BUILTIN_PROVIDER_CAPABILITY` as an audit-trail provider with nothing separating the container an\n * operator runs themselves from a hosted service — so the first privacy notice to ENUMERATE\n * recipients would have named a self-hosted audit ledger as a third party. That is false, and false\n * in the direction that alarms a reader rather than the direction they can check.\n *\n * ⚠️ NOT a hosting-topology field and not an infrastructure concern. It answers one compliance\n * question — does personal data leave the operator's control by reaching this provider — and a\n * consumer must not read it as \"where is it deployed\".\n */\nexport enum ProviderDeploymentModel {\n  /**\n   * The vendor runs it. Data reaching this provider reaches a third party, so it is a processor\n   * under Art. 28 and belongs in the subprocessor register.\n   */\n  VENDOR_HOSTED = 'VENDOR_HOSTED',\n  /**\n   * The operator runs it — their own container, their own infrastructure. No third party receives\n   * anything, so it is NOT a recipient. A notice states it as processing under the operator's own\n   * control, which is a different sentence and a stronger one.\n   */\n  SELF_HOSTED = 'SELF_HOSTED',\n}\n\n/**\n * The compliance-relevant facts a PROVIDER MODULE knows about itself.\n *\n * ## Why these live on the provider and not on the application\n *\n * The processor register shipped by issue #88 was fully application-authored, and that made every\n * application restate facts the framework already holds. What a provider IS — who runs it, which\n * regions its vendor offers, what legal entity stands behind it — does not vary per application, and\n * an application asked to restate it will eventually get it wrong. What DOES vary is the operator's\n * CHOICE among those possibilities, and that is configuration.\n *\n * So the split is: possibilities here, choice in `wildo.saas.config.ts`, and the register entry\n * derived from both (issue #130).\n *\n * ## What is deliberately NOT here\n *\n * **A transfer mechanism.** Adequacy decisions move by court ruling rather than by release cycle, so\n * a list baked into the engine goes stale silently and emits a false compliance statement — the worst\n * failure mode in this lane. The mechanism is a legal determination with a shelf life, recorded per\n * subprocessor entry by a human, never derived here (issue #126).\n *\n * **What the provider RECEIVES.** That is already implied by the capability it serves —\n * `BUILTIN_PROVIDER_CAPABILITY` describes the data flow per member. Restating it here would be a\n * second authority for one fact.\n */\nexport const ProviderComplianceProfileSchema = z.strictObject({\n  /**\n   * The deployment models this provider SUPPORTS — one, or both where the provider genuinely offers\n   * a choice (immudb: a hosted service and a container you run).\n   *\n   * A single entry means the answer is not the operator's to make and no configuration should offer\n   * it. Two means the application must choose, and a register entry cannot be derived until it has.\n   */\n  deploymentModels: z.array(z.enum(ProviderDeploymentModel)).min(1),\n  /**\n   * The regions this vendor can process in — POSSIBILITIES the operator chooses from, never a\n   * choice already made.\n   *\n   * Open strings, deliberately, because these are the VENDOR's own labels (`eu-west-1`,\n   * `us-east-1`, `EU`) and a closed enum here would be this repository inventing a vocabulary it\n   * does not own. The compliance question a transfer statement asks is about JURISDICTION rather\n   * than datacentre, and mapping one to the other is part of the legal determination that is\n   * deliberately not modelled (see above).\n   *\n   * EMPTY is meaningful and is the honest answer for a provider that is only ever self-hosted: the\n   * region is wherever the operator runs it, which the framework cannot know. A configuration\n   * choosing `SELF_HOSTED` therefore needs no region from this list.\n   */\n  processingRegions: z.array(z.string().trim().min(1)),\n  /**\n   * The vendor's legal entity, where the provider module's author can state it.\n   *\n   * OPTIONAL, and the reason is that this is the field most likely to go stale: vendors reorganise,\n   * and a stale legal entity published as a current one is worse than an absent one. Absent means\n   * the application must declare it on the register entry, which is where an operator's own contract\n   * makes it checkable.\n   */\n  vendorLegalEntityName: z.string().trim().min(1).optional(),\n}).superRefine((profile, context) => {\n  /*\n   * A VENDOR_HOSTED provider that offers no region cannot support a transfer statement, and the\n   * whole point of carrying regions is that a transfer statement becomes derivable. Refused at the\n   * schema so the gap surfaces where the provider module is authored, rather than as an\n   * unexplainable hole in a produced notice months later.\n   *\n   * The SELF_HOSTED-only case is exempt above: its region is wherever the operator runs it.\n   */\n  if (profile.deploymentModels.includes(ProviderDeploymentModel.VENDOR_HOSTED) && profile.processingRegions.length === 0) {\n    context.addIssue({\n      code: 'custom',\n      path: ['processingRegions'],\n      message: 'a VENDOR_HOSTED provider must declare at least one processing region — without one, no transfer statement about it can be derived',\n    });\n  }\n});\nexport type ProviderComplianceProfile = z.infer<typeof ProviderComplianceProfileSchema>;\n\n/** True when this provider can only ever be run by the operator, so it is never a third-party recipient. */\nexport function providerIsAlwaysSelfHosted(profile: ProviderComplianceProfile): boolean {\n  return profile.deploymentModels.every((model) => model === ProviderDeploymentModel.SELF_HOSTED);\n}\n\n/**\n * True when the operator must CHOOSE, because the provider supports both.\n *\n * A register entry for such a provider cannot be derived from the provider module alone — the\n * application's configuration decides whether it is a recipient at all.\n */\nexport function providerDeploymentModelIsAnOperatorChoice(profile: ProviderComplianceProfile): boolean {\n  return profile.deploymentModels.length > 1;\n}\n\n/**\n * The application's CHOICE among what a provider offers — one entry per configured provider.\n *\n * The provider declares possibilities ({@link ProviderComplianceProfileSchema}); this is where an\n * operator says which of them applies to their deployment. Keeping the two apart is the whole point\n * of the layering: a vendor's regions change when it opens a data centre, an operator's choice\n * changes when they migrate, and collapsing them would make one edit look like the other.\n *\n * Not carried inside `providerConfigurations`, which is an opaque `Record<string, unknown>` bag for a\n * provider's own runtime profile. A compliance answer must not live somewhere nothing can read it\n * without knowing the provider.\n */\nexport const ApplicationProviderComplianceChoiceSchema = z.strictObject({\n  /**\n   * Who runs this provider in THIS deployment.\n   *\n   * Required even when the provider supports only one model. The redundancy is deliberate: whether\n   * personal data leaves the operator's control is the single most consequential fact a notice states\n   * about a provider, and reading it out of a framework default rather than an operator's declaration\n   * is how a wrong one goes unnoticed.\n   */\n  deploymentModel: z.enum(ProviderDeploymentModel),\n  /**\n   * Which region this provider processes in, chosen from what the provider declares possible.\n   *\n   * Validated against the provider's declared list at BOOT rather than here — this schema cannot see\n   * the provider registry, and refusing an unlisted region would make a vendor's new data centre an\n   * application build failure. A region outside the list is APP-ASSERTED and reported, never refused\n   * (the same warn-do-not-block posture as the personal-data declaration report).\n   */\n  processingRegion: z.string().trim().min(1).optional(),\n}).superRefine((choice, context) => {\n  /*\n   * The pairing, in both directions.\n   *\n   * A VENDOR_HOSTED choice with no region leaves the notice unable to state where the data goes,\n   * which is the question this whole layer exists to answer. A SELF_HOSTED choice WITH one is the\n   * fiction the provider layer already refuses: the operator runs it, so its region is wherever they\n   * run it, and a value here would be a guess presented as a configuration.\n   */\n  if (choice.deploymentModel === ProviderDeploymentModel.VENDOR_HOSTED && choice.processingRegion === undefined) {\n    context.addIssue({\n      code: 'custom',\n      path: ['processingRegion'],\n      message: 'a VENDOR_HOSTED provider must be configured with the region it processes in — without one, no notice can state where this data goes',\n    });\n  }\n  if (choice.deploymentModel === ProviderDeploymentModel.SELF_HOSTED && choice.processingRegion !== undefined) {\n    context.addIssue({\n      code: 'custom',\n      path: ['processingRegion'],\n      message: 'a SELF_HOSTED provider runs wherever the operator runs it, so a processing region here is a guess presented as configuration — drop it',\n    });\n  }\n});\nexport type ApplicationProviderComplianceChoice = z.infer<typeof ApplicationProviderComplianceChoiceSchema>;\n\n/** Per configured provider ref, the operator's compliance choice. */\nexport const ApplicationProviderComplianceChoicesSchema = z.record(\n  z.string().trim().min(1),\n  ApplicationProviderComplianceChoiceSchema,\n);\nexport type ApplicationProviderComplianceChoices = z.infer<typeof ApplicationProviderComplianceChoicesSchema>;\n\n/**\n * Regions an application asserts that the provider does not declare.\n *\n * Reported, never refused — a vendor opening a data centre must not become a build failure, and an\n * operator who genuinely knows better than a stale framework list should be able to say so. What the\n * framework owes is that the divergence is VISIBLE, which is the same trade the personal-data\n * declaration report makes.\n */\nexport function appAssertedProcessingRegions(params: {\n  readonly choices: ApplicationProviderComplianceChoices;\n  readonly profilesByProviderRef: Readonly<Record<string, ProviderComplianceProfile>>;\n}): ReadonlyArray<{ readonly providerRef: string; readonly region: string }> {\n  const asserted: Array<{ providerRef: string; region: string }> = [];\n\n  for (const [providerRef, choice] of Object.entries(params.choices)) {\n    if (choice.processingRegion === undefined) continue;\n    const profile = params.profilesByProviderRef[providerRef];\n    // No profile is not an assertion about a region — it is a provider that declares no compliance\n    // profile at all, which is a different gap and belongs to whoever reports THAT.\n    if (profile === undefined) continue;\n    if (profile.processingRegions.includes(choice.processingRegion)) continue;\n    asserted.push({ providerRef, region: choice.processingRegion });\n  }\n\n  return asserted;\n}\n\n/**\n * The configured providers that are THIRD-PARTY RECIPIENTS — vendor-hosted, and therefore processors.\n *\n * A self-hosted provider is excluded by construction rather than by a filter a caller must remember:\n * no data leaves the operator, so it is not a recipient and must never be enumerated as one.\n */\nexport function vendorHostedProviderRefs(choices: ApplicationProviderComplianceChoices): readonly string[] {\n  return Object.entries(choices)\n    .filter(([, choice]) => choice.deploymentModel === ProviderDeploymentModel.VENDOR_HOSTED)\n    .map(([providerRef]) => providerRef)\n    .sort();\n}\n"]}
+{"version":3,"file":"provider-compliance-profile.shared.schemas.js","sourceRoot":"","sources":["../../../src/external-providers/provider-compliance-profile.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\n/**\n * WHO RUNS the software a provider module drives.\n *\n * This is the axis that decides whether a provider is a third-party RECIPIENT of personal data at\n * all, and until 2026-08-30 it did not exist anywhere in the provider model. immudb is described in\n * `BUILTIN_PROVIDER_CAPABILITY` as an audit-trail provider with nothing separating the container an\n * operator runs themselves from a hosted service — so the first privacy notice to ENUMERATE\n * recipients would have named a self-hosted audit ledger as a third party. That is false, and false\n * in the direction that alarms a reader rather than the direction they can check.\n *\n * ⚠️ NOT a hosting-topology field and not an infrastructure concern. It answers one compliance\n * question — does personal data leave the operator's control by reaching this provider — and a\n * consumer must not read it as \"where is it deployed\".\n */\nexport enum ProviderDeploymentModel {\n  /**\n   * The vendor runs it. Data reaching this provider reaches a third party, so it is a processor\n   * under Art. 28 and belongs in the subprocessor register.\n   */\n  VENDOR_HOSTED = 'VENDOR_HOSTED',\n  /**\n   * The operator runs it — their own container, their own infrastructure. No third party receives\n   * anything, so it is NOT a recipient. A notice states it as processing under the operator's own\n   * control, which is a different sentence and a stronger one.\n   */\n  SELF_HOSTED = 'SELF_HOSTED',\n}\n\n/**\n * The compliance-relevant facts a PROVIDER MODULE knows about itself.\n *\n * ## Why these live on the provider and not on the application\n *\n * The processor register shipped by issue #88 was fully application-authored, and that made every\n * application restate facts the framework already holds. What a provider IS — who runs it, which\n * regions its vendor offers, what legal entity stands behind it — does not vary per application, and\n * an application asked to restate it will eventually get it wrong. What DOES vary is the operator's\n * CHOICE among those possibilities, and that is configuration.\n *\n * So the split is: possibilities here, choice in `wildo.saas.config.ts`, and the register entry\n * derived from both (issue #130).\n *\n * ## What is deliberately NOT here\n *\n * **A transfer mechanism.** Adequacy decisions move by court ruling rather than by release cycle, so\n * a list baked into the engine goes stale silently and emits a false compliance statement — the worst\n * failure mode in this lane. The mechanism is a legal determination with a shelf life, recorded per\n * subprocessor entry by a human, never derived here (issue #126).\n *\n * **What the provider RECEIVES.** That is already implied by the capability it serves —\n * `BUILTIN_PROVIDER_CAPABILITY` describes the data flow per member. Restating it here would be a\n * second authority for one fact.\n */\nexport const ProviderComplianceProfileSchema = z.strictObject({\n  /**\n   * The deployment models this provider SUPPORTS — one, or both where the provider genuinely offers\n   * a choice (immudb: a hosted service and a container you run).\n   *\n   * A single entry means the answer is not the operator's to make and no configuration should offer\n   * it. Two means the application must choose, and a register entry cannot be derived until it has.\n   */\n  deploymentModels: z.array(z.enum(ProviderDeploymentModel)).min(1),\n  /**\n   * The regions this vendor can process in — POSSIBILITIES the operator chooses from, never a\n   * choice already made.\n   *\n   * Open strings, deliberately, because these are the VENDOR's own labels (`eu-west-1`,\n   * `us-east-1`, `EU`) and a closed enum here would be this repository inventing a vocabulary it\n   * does not own. The compliance question a transfer statement asks is about JURISDICTION rather\n   * than datacentre, and mapping one to the other is part of the legal determination that is\n   * deliberately not modelled (see above).\n   *\n   * EMPTY is meaningful and is the honest answer for a provider that is only ever self-hosted: the\n   * region is wherever the operator runs it, which the framework cannot know. A configuration\n   * choosing `SELF_HOSTED` therefore needs no region from this list.\n   */\n  processingRegions: z.array(z.string().trim().min(1)),\n  /**\n   * The vendor's legal entity, where the provider module's author can state it.\n   *\n   * OPTIONAL, and the reason is that this is the field most likely to go stale: vendors reorganise,\n   * and a stale legal entity published as a current one is worse than an absent one. Absent means\n   * the application must declare it on the register entry, which is where an operator's own contract\n   * makes it checkable.\n   */\n  vendorLegalEntityName: z.string().trim().min(1).optional(),\n}).superRefine((profile, context) => {\n  /*\n   * A VENDOR_HOSTED provider that offers no region cannot support a transfer statement, and the\n   * whole point of carrying regions is that a transfer statement becomes derivable. Refused at the\n   * schema so the gap surfaces where the provider module is authored, rather than as an\n   * unexplainable hole in a produced notice months later.\n   *\n   * The SELF_HOSTED-only case is exempt above: its region is wherever the operator runs it.\n   */\n  if (profile.deploymentModels.includes(ProviderDeploymentModel.VENDOR_HOSTED) && profile.processingRegions.length === 0) {\n    context.addIssue({\n      code: 'custom',\n      path: ['processingRegions'],\n      message: 'a VENDOR_HOSTED provider must declare at least one processing region — without one, no transfer statement about it can be derived',\n    });\n  }\n});\nexport type ProviderComplianceProfile = z.infer<typeof ProviderComplianceProfileSchema>;\n\n/** True when this provider can only ever be run by the operator, so it is never a third-party recipient. */\nexport function providerIsAlwaysSelfHosted(profile: ProviderComplianceProfile): boolean {\n  return profile.deploymentModels.every((model) => model === ProviderDeploymentModel.SELF_HOSTED);\n}\n\n/**\n * True when the operator must CHOOSE, because the provider supports both.\n *\n * A register entry for such a provider cannot be derived from the provider module alone — the\n * application's configuration decides whether it is a recipient at all.\n */\nexport function providerDeploymentModelIsAnOperatorChoice(profile: ProviderComplianceProfile): boolean {\n  return profile.deploymentModels.length > 1;\n}\n\n/** @wildo_source:part:start saas.models.providers.compliance-choice facet:layer:shared facet:audience:app-developer */\n/**\n * The application's CHOICE among what a provider offers — one entry per configured provider.\n *\n * The provider declares possibilities ({@link ProviderComplianceProfileSchema}); this is where an\n * operator says which of them applies to their deployment. Keeping the two apart is the whole point\n * of the layering: a vendor's regions change when it opens a data centre, an operator's choice\n * changes when they migrate, and collapsing them would make one edit look like the other.\n *\n * Not carried inside `providerConfigurations`, which is an opaque `Record<string, unknown>` bag for a\n * provider's own runtime profile. A compliance answer must not live somewhere nothing can read it\n * without knowing the provider.\n */\nexport const ApplicationProviderComplianceChoiceSchema = z.strictObject({\n  /**\n   * Who runs this provider in THIS deployment.\n   *\n   * Required even when the provider supports only one model. The redundancy is deliberate: whether\n   * personal data leaves the operator's control is the single most consequential fact a notice states\n   * about a provider, and reading it out of a framework default rather than an operator's declaration\n   * is how a wrong one goes unnoticed.\n   */\n  deploymentModel: z.enum(ProviderDeploymentModel),\n  /**\n   * Which region this provider processes in, chosen from what the provider declares possible.\n   *\n   * NOT validated here, and NOT validated at boot either. This schema cannot see the provider\n   * registry, and refusing an unlisted region would make a vendor's new data centre an application\n   * build failure, so the intended posture is warn-do-not-block: a region outside the provider's\n   * declared list is APP-ASSERTED and reported, never refused.\n   *\n   * WIRED since 2026-09-10 (issue #308). `appAssertedProcessingRegions` below computes exactly that\n   * set, and the companion's compliance-primary-facts section reports it per provider, naming both the\n   * configured value and what the provider declares — because a divergence is either a typo or a stale\n   * provider module, and those are opposite work. It took this long only because of a DATA PATH: the\n   * vendor's region list lives on the backend provider module and the renderer reads provider\n   * SPECIFICATIONS, so the helper could not be called until `complianceProfile` was mirrored onto the\n   * specification contract. Any future report must call this helper rather than re-derive the\n   * comparison.\n   */\n  processingRegion: z.string().trim().min(1).optional(),\n}).superRefine((choice, context) => {\n  /*\n   * The pairing, in both directions.\n   *\n   * A VENDOR_HOSTED choice with no region leaves the notice unable to state where the data goes,\n   * which is the question this whole layer exists to answer. A SELF_HOSTED choice WITH one is the\n   * fiction the provider layer already refuses: the operator runs it, so its region is wherever they\n   * run it, and a value here would be a guess presented as a configuration.\n   */\n  if (choice.deploymentModel === ProviderDeploymentModel.VENDOR_HOSTED && choice.processingRegion === undefined) {\n    context.addIssue({\n      code: 'custom',\n      path: ['processingRegion'],\n      message: 'a VENDOR_HOSTED provider must be configured with the region it processes in — without one, no notice can state where this data goes',\n    });\n  }\n  if (choice.deploymentModel === ProviderDeploymentModel.SELF_HOSTED && choice.processingRegion !== undefined) {\n    context.addIssue({\n      code: 'custom',\n      path: ['processingRegion'],\n      message: 'a SELF_HOSTED provider runs wherever the operator runs it, so a processing region here is a guess presented as configuration — drop it',\n    });\n  }\n});\nexport type ApplicationProviderComplianceChoice = z.infer<typeof ApplicationProviderComplianceChoiceSchema>;\n\n/** Per configured provider ref, the operator's compliance choice. */\nexport const ApplicationProviderComplianceChoicesSchema = z.record(\n  z.string().trim().min(1),\n  ApplicationProviderComplianceChoiceSchema,\n);\nexport type ApplicationProviderComplianceChoices = z.infer<typeof ApplicationProviderComplianceChoicesSchema>;\n\n/**\n * Regions an application asserts that the provider does not declare.\n *\n * Reported, never refused — a vendor opening a data centre must not become a build failure, and an\n * operator who genuinely knows better than a stale framework list should be able to say so. What the\n * framework owes is that the divergence is VISIBLE, which is the same trade the personal-data\n * declaration report makes.\n */\nexport function appAssertedProcessingRegions(params: {\n  readonly choices: ApplicationProviderComplianceChoices;\n  readonly profilesByProviderRef: Readonly<Record<string, ProviderComplianceProfile>>;\n}): ReadonlyArray<{ readonly providerRef: string; readonly region: string }> {\n  const asserted: Array<{ providerRef: string; region: string }> = [];\n\n  for (const [providerRef, choice] of Object.entries(params.choices)) {\n    if (choice.processingRegion === undefined) continue;\n    const profile = params.profilesByProviderRef[providerRef];\n    // No profile is not an assertion about a region — it is a provider that declares no compliance\n    // profile at all, which is a different gap and belongs to whoever reports THAT.\n    if (profile === undefined) continue;\n    if (profile.processingRegions.includes(choice.processingRegion)) continue;\n    asserted.push({ providerRef, region: choice.processingRegion });\n  }\n\n  return asserted;\n}\n/** @wildo_source:part:end saas.models.providers.compliance-choice */\n\n/**\n * The configured providers that are THIRD-PARTY RECIPIENTS — vendor-hosted, and therefore processors.\n *\n * A self-hosted provider is excluded by construction rather than by a filter a caller must remember:\n * no data leaves the operator, so it is not a recipient and must never be enumerated as one.\n */\nexport function vendorHostedProviderRefs(choices: ApplicationProviderComplianceChoices): readonly string[] {\n  return Object.entries(choices)\n    .filter(([, choice]) => choice.deploymentModel === ProviderDeploymentModel.VENDOR_HOSTED)\n    .map(([providerRef]) => providerRef)\n    .sort();\n}\n"]}