@wildo-ai/saas-models 1.0.1 → 1.1.0

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

@@ -0,0 +1,102 @@
+/**
+ * `ProviderCapability` — open, app-extensible enum of standardized
+ * behaviors that providers implement.
+ *
+ * Distinct from `EngineCapability` (closed, engine-defined slots that
+ * may require fulfillment). See the analysis glossary in
+ * `.cursor/plans/provider-registration-refactor-draft-analysis.md` §14
+ * for the full naming rationale; this file is the canonical Phase-0
+ * authoring surface called out in §Phase 0.2 of the implementation
+ * plan.
+ *
+ * Built-in values use SCREAMING_SNAKE_CASE; app-augmented values SHOULD
+ * use kebab-case + domain prefix (e.g. `'live-chat-handoff'`,
+ * `'search-index'`). The two namespaces never collide by construction.
+ */
+/** @wildo_source:part:start saas.models.provider-capabilities facet:kind:api facet:audience:app-developer
+ *
+ * Built-in provider capabilities shipped by the framework.
+ *
+ * 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.
+ */
+export const BUILTIN_PROVIDER_CAPABILITY = {
+    EMAIL_TRANSACTIONAL: 'EMAIL_TRANSACTIONAL',
+    EMAIL_MARKETING: 'EMAIL_MARKETING',
+    SMS: 'SMS',
+    /**
+     * Single billing-engagement capability covering everything from
+     * Checkout-style hosted flows to first-party PaymentIntent flows.
+     * Webhook delivery is NOT a separate capability — it is modelled at
+     * the protocol layer (e.g. Stripe declares both a `BILLING_PROVIDER`
+     * and a `WEBHOOK_ORIGINATOR` protocol but a single `BILLING`
+     * capability). This 1:1 matches the billing slot from the older
+     * external connector transformer vocabulary.
+     */
+    BILLING: 'BILLING',
+    SSO_OAUTH2: 'SSO_OAUTH2',
+    /** Reserved for future SAML-based SSO providers (none ship today). */
+    SSO_SAML: 'SSO_SAML',
+    LLM_CHAT: 'LLM_CHAT',
+    LLM_EMBEDDINGS: 'LLM_EMBEDDINGS',
+    /**
+     * Provider turns DOCUMENT BYTES into text — OCR over scans and photographs of pages, not merely
+     * a read of a PDF's existing text layer. Maps to `EngineCapability.AI_DOCUMENT_EXTRACTION`.
+     *
+     * A NEW token was genuinely required rather than convenient: `IMAGE_GENERATION` is an OUTPUT
+     * capability (text → image), and `EngineCapability.DOCUMENT_GENERATION` is PDF *generation*,
+     * which is this capability's exact opposite. Nothing in the existing vocabulary claimed the
+     * document-INPUT slot.
+     *
+     * Distinct from `LLM_CHAT` even where a vendor serves both from one API key: the work is
+     * different (a page-layout model, billed per page, with no sampling parameters), and fusing
+     * them would make the OCR provider unselectable independently of the chat provider — the exact
+     * defect that splitting `AI_EMBEDDINGS` out of `AI_LLM` existed to fix.
+     */
+    DOCUMENT_TEXT_EXTRACTION: 'DOCUMENT_TEXT_EXTRACTION',
+    /**
+     * Provider ships an autonomous CODING AGENT: a process that reads and writes
+     * a workspace, runs commands, and requests authorisation, reachable over the
+     * Agent Client Protocol.
+     *
+     * Distinct from `LLM_CHAT` because the WORK is
+     * different, not merely its transport. A chat model returns text for a caller
+     * to act on; a coding agent acts, and the resulting obligations — permission
+     * decisions, mutation scope, change attribution, verification — have no
+     * counterpart in a completion call.
+     */
+    CODING_AGENT: 'CODING_AGENT',
+    IMAGE_GENERATION: 'IMAGE_GENERATION',
+    FRONTEND_ERROR_MONITORING: 'FRONTEND_ERROR_MONITORING',
+    FRONTEND_PRODUCT_ANALYTICS: 'FRONTEND_PRODUCT_ANALYTICS',
+    FRONTEND_SEARCH: 'FRONTEND_SEARCH',
+    FRONTEND_FILE_PICKER: 'FRONTEND_FILE_PICKER',
+    FRONTEND_CAPTCHA: 'FRONTEND_CAPTCHA',
+    /**
+     * Backend LLM-call observability — a provider that ingests per-`invokeAgent`
+     * generation traces (model / tokens / cost / latency), e.g. PostHog
+     * `$ai_generation`. Maps to `EngineCapability.LLM_OBSERVABILITY`. The engine
+     * consumes it via the `AgentCallTraceSink` (not a request/response transformer).
+     */
+    LLM_OBSERVABILITY: 'LLM_OBSERVABILITY',
+    /**
+     * Operational-telemetry sink — a provider that ingests OpenTelemetry traces,
+     * metrics, and logs over OTLP (e.g. BetterStack). Maps to
+     * `EngineCapability.OBSERVABILITY_TELEMETRY`. Consumed by the OTel SDK preload
+     * (env-var-driven), NOT a request/response transformer or a DI sink.
+     */
+    OBSERVABILITY_TELEMETRY: 'OBSERVABILITY_TELEMETRY',
+    /**
+     * Audit-log sink — a provider that stores or forwards compliance audit
+     * events (who-did-what-when), e.g. immudb (tamper-evident) or a SIEM
+     * webhook. Maps to `EngineCapability.COMPLIANCE_AUDIT_TRAIL`, a FAN_OUT
+     * capability: every declared audit provider receives every event (see
+     * `getEngineCapabilityResolutionMode`). The engine consumes it via the
+     * `AuditLogSink` DI fan-out, layered on the always-on database audit store.
+     */
+    COMPLIANCE_AUDIT_TRAIL: 'COMPLIANCE_AUDIT_TRAIL',
+};
+//# sourceMappingURL=provider-capability.shared.schemas.js.map

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

@@ -0,0 +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;;;;;;;;;;;;;OAaG;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 `EngineCapability.DOCUMENT_GENERATION` is PDF *generation*,\n   * which is this capability's exact opposite. Nothing in the existing vocabulary claimed the\n   * document-INPUT slot.\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"]}

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

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+/**
+ * WHO RUNS the software a provider module drives.
+ *
+ * This is the axis that decides whether a provider is a third-party RECIPIENT of personal data at
+ * all, and until 2026-08-30 it did not exist anywhere in the provider model. immudb is described in
+ * `BUILTIN_PROVIDER_CAPABILITY` as an audit-trail provider with nothing separating the container an
+ * operator runs themselves from a hosted service — so the first privacy notice to ENUMERATE
+ * recipients would have named a self-hosted audit ledger as a third party. That is false, and false
+ * in the direction that alarms a reader rather than the direction they can check.
+ *
+ * ⚠️ NOT a hosting-topology field and not an infrastructure concern. It answers one compliance
+ * question — does personal data leave the operator's control by reaching this provider — and a
+ * consumer must not read it as "where is it deployed".
+ */
+export declare enum ProviderDeploymentModel {
+    /**
+     * The vendor runs it. Data reaching this provider reaches a third party, so it is a processor
+     * under Art. 28 and belongs in the subprocessor register.
+     */
+    VENDOR_HOSTED = "VENDOR_HOSTED",
+    /**
+     * The operator runs it — their own container, their own infrastructure. No third party receives
+     * anything, so it is NOT a recipient. A notice states it as processing under the operator's own
+     * control, which is a different sentence and a stronger one.
+     */
+    SELF_HOSTED = "SELF_HOSTED"
+}
+/**
+ * The compliance-relevant facts a PROVIDER MODULE knows about itself.
+ *
+ * ## Why these live on the provider and not on the application
+ *
+ * The processor register shipped by issue #88 was fully application-authored, and that made every
+ * application restate facts the framework already holds. What a provider IS — who runs it, which
+ * regions its vendor offers, what legal entity stands behind it — does not vary per application, and
+ * an application asked to restate it will eventually get it wrong. What DOES vary is the operator's
+ * CHOICE among those possibilities, and that is configuration.
+ *
+ * So the split is: possibilities here, choice in `wildo.saas.config.ts`, and the register entry
+ * derived from both (issue #130).
+ *
+ * ## What is deliberately NOT here
+ *
+ * **A transfer mechanism.** Adequacy decisions move by court ruling rather than by release cycle, so
+ * a list baked into the engine goes stale silently and emits a false compliance statement — the worst
+ * failure mode in this lane. The mechanism is a legal determination with a shelf life, recorded per
+ * subprocessor entry by a human, never derived here (issue #126).
+ *
+ * **What the provider RECEIVES.** That is already implied by the capability it serves —
+ * `BUILTIN_PROVIDER_CAPABILITY` describes the data flow per member. Restating it here would be a
+ * second authority for one fact.
+ */
+export declare const ProviderComplianceProfileSchema: z.ZodObject<{
+    /**
+     * The deployment models this provider SUPPORTS — one, or both where the provider genuinely offers
+     * a choice (immudb: a hosted service and a container you run).
+     *
+     * A single entry means the answer is not the operator's to make and no configuration should offer
+     * it. Two means the application must choose, and a register entry cannot be derived until it has.
+     */
+    deploymentModels: z.ZodArray<z.ZodEnum<typeof ProviderDeploymentModel>>;
+    /**
+     * The regions this vendor can process in — POSSIBILITIES the operator chooses from, never a
+     * choice already made.
+     *
+     * Open strings, deliberately, because these are the VENDOR's own labels (`eu-west-1`,
+     * `us-east-1`, `EU`) and a closed enum here would be this repository inventing a vocabulary it
+     * does not own. The compliance question a transfer statement asks is about JURISDICTION rather
+     * than datacentre, and mapping one to the other is part of the legal determination that is
+     * deliberately not modelled (see above).
+     *
+     * EMPTY is meaningful and is the honest answer for a provider that is only ever self-hosted: the
+     * region is wherever the operator runs it, which the framework cannot know. A configuration
+     * choosing `SELF_HOSTED` therefore needs no region from this list.
+     */
+    processingRegions: z.ZodArray<z.ZodString>;
+    /**
+     * The vendor's legal entity, where the provider module's author can state it.
+     *
+     * OPTIONAL, and the reason is that this is the field most likely to go stale: vendors reorganise,
+     * and a stale legal entity published as a current one is worse than an absent one. Absent means
+     * the application must declare it on the register entry, which is where an operator's own contract
+     * makes it checkable.
+     */
+    vendorLegalEntityName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ProviderComplianceProfile = z.infer<typeof ProviderComplianceProfileSchema>;
+/** True when this provider can only ever be run by the operator, so it is never a third-party recipient. */
+export declare function providerIsAlwaysSelfHosted(profile: ProviderComplianceProfile): boolean;
+/**
+ * True when the operator must CHOOSE, because the provider supports both.
+ *
+ * A register entry for such a provider cannot be derived from the provider module alone — the
+ * application's configuration decides whether it is a recipient at all.
+ */
+export declare function providerDeploymentModelIsAnOperatorChoice(profile: ProviderComplianceProfile): boolean;
+/**
+ * The application's CHOICE among what a provider offers — one entry per configured provider.
+ *
+ * The provider declares possibilities ({@link ProviderComplianceProfileSchema}); this is where an
+ * operator says which of them applies to their deployment. Keeping the two apart is the whole point
+ * of the layering: a vendor's regions change when it opens a data centre, an operator's choice
+ * changes when they migrate, and collapsing them would make one edit look like the other.
+ *
+ * Not carried inside `providerConfigurations`, which is an opaque `Record<string, unknown>` bag for a
+ * provider's own runtime profile. A compliance answer must not live somewhere nothing can read it
+ * without knowing the provider.
+ */
+export declare const ApplicationProviderComplianceChoiceSchema: z.ZodObject<{
+    /**
+     * Who runs this provider in THIS deployment.
+     *
+     * Required even when the provider supports only one model. The redundancy is deliberate: whether
+     * personal data leaves the operator's control is the single most consequential fact a notice states
+     * about a provider, and reading it out of a framework default rather than an operator's declaration
+     * is how a wrong one goes unnoticed.
+     */
+    deploymentModel: z.ZodEnum<typeof ProviderDeploymentModel>;
+    /**
+     * 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).
+     */
+    processingRegion: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ApplicationProviderComplianceChoice = z.infer<typeof ApplicationProviderComplianceChoiceSchema>;
+/** Per configured provider ref, the operator's compliance choice. */
+export declare const ApplicationProviderComplianceChoicesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    /**
+     * Who runs this provider in THIS deployment.
+     *
+     * Required even when the provider supports only one model. The redundancy is deliberate: whether
+     * personal data leaves the operator's control is the single most consequential fact a notice states
+     * about a provider, and reading it out of a framework default rather than an operator's declaration
+     * is how a wrong one goes unnoticed.
+     */
+    deploymentModel: z.ZodEnum<typeof ProviderDeploymentModel>;
+    /**
+     * 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).
+     */
+    processingRegion: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export type ApplicationProviderComplianceChoices = z.infer<typeof ApplicationProviderComplianceChoicesSchema>;
+/**
+ * Regions an application asserts that the provider does not declare.
+ *
+ * Reported, never refused — a vendor opening a data centre must not become a build failure, and an
+ * operator who genuinely knows better than a stale framework list should be able to say so. What the
+ * framework owes is that the divergence is VISIBLE, which is the same trade the personal-data
+ * declaration report makes.
+ */
+export declare function appAssertedProcessingRegions(params: {
+    readonly choices: ApplicationProviderComplianceChoices;
+    readonly profilesByProviderRef: Readonly<Record<string, ProviderComplianceProfile>>;
+}): ReadonlyArray<{
+    readonly providerRef: string;
+    readonly region: string;
+}>;
+/**
+ * The configured providers that are THIRD-PARTY RECIPIENTS — vendor-hosted, and therefore processors.
+ *
+ * A self-hosted provider is excluded by construction rather than by a filter a caller must remember:
+ * no data leaves the operator, so it is not a recipient and must never be enumerated as one.
+ */
+export declare function vendorHostedProviderRefs(choices: ApplicationProviderComplianceChoices): readonly string[];
+//# sourceMappingURL=provider-compliance-profile.shared.schemas.d.ts.map

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

@@ -0,0 +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"}

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

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

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,37 @@
+/**
+ * `ProviderMetadata` — shared, frontend-safe header carried by every
+ * provider module across every facet (backend, frontend-app, techdoc,
+ * website).
+ *
+ * Intentionally **frontend-safe**: holds no secrets, no protocol
+ * contracts, no backend behavior. The fields are exactly what a UI needs
+ * to render a provider entry (translation-ready display-name key, optional
+ * legacy fallback label, optional icon ref) plus the stable `ref` used as
+ * the join key between facet modules.
+ *
+ * Phase 0 of the provider-registration refactor introduces this type as
+ * the single source of truth for provider header information so that the
+ * cross-facet seam (`FrontendBootstrapBackendService`) can project a
+ * `BackendProviderModule` into a `FrontendProviderEntry` without ever
+ * leaking backend-only fields.
+ *
+ * See `.cursor/plans/provider-registration-refactor-implementation-plan.md`
+ * §Phase 0.1 for the full rationale.
+ */
+import { z } from 'zod';
+/**
+ * Translation key builder for provider display names.
+ *
+ * Provider modules stay locale-neutral by exporting this stable label key;
+ * consuming frontend surfaces resolve it via the app i18n service at render
+ * time instead of freezing human copy into generated/runtime artifacts.
+ */
+export declare function buildProviderDisplayNameLabelKey(providerRef: string): string;
+export declare const ProviderMetadataSchema: z.ZodObject<{
+    ref: z.ZodString;
+    displayNameLabelKey: z.ZodOptional<z.ZodString>;
+    displayName: z.ZodOptional<z.ZodString>;
+    iconRef: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ProviderMetadata = z.infer<typeof ProviderMetadataSchema>;
+//# sourceMappingURL=provider-metadata.shared.schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider-metadata.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-metadata.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,eAAO,MAAM,sBAAsB;;;;;iBAyBjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

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

@@ -0,0 +1,58 @@
+/**
+ * `ProviderMetadata` — shared, frontend-safe header carried by every
+ * provider module across every facet (backend, frontend-app, techdoc,
+ * website).
+ *
+ * Intentionally **frontend-safe**: holds no secrets, no protocol
+ * contracts, no backend behavior. The fields are exactly what a UI needs
+ * to render a provider entry (translation-ready display-name key, optional
+ * legacy fallback label, optional icon ref) plus the stable `ref` used as
+ * the join key between facet modules.
+ *
+ * Phase 0 of the provider-registration refactor introduces this type as
+ * the single source of truth for provider header information so that the
+ * cross-facet seam (`FrontendBootstrapBackendService`) can project a
+ * `BackendProviderModule` into a `FrontendProviderEntry` without ever
+ * leaking backend-only fields.
+ *
+ * See `.cursor/plans/provider-registration-refactor-implementation-plan.md`
+ * §Phase 0.1 for the full rationale.
+ */
+import { z } from 'zod';
+/**
+ * Translation key builder for provider display names.
+ *
+ * Provider modules stay locale-neutral by exporting this stable label key;
+ * consuming frontend surfaces resolve it via the app i18n service at render
+ * time instead of freezing human copy into generated/runtime artifacts.
+ */
+export function buildProviderDisplayNameLabelKey(providerRef) {
+    return `providers.${providerRef}.displayName`;
+}
+export const ProviderMetadataSchema = z.object({
+    /**
+     * Stable identifier for the provider, e.g. `'resend'`, `'stripe'`,
+     * `'openai'`. Used as the join key across facet modules and as the
+     * map key inside `BackendProviderRegistry.modules`.
+     */
+    ref: z.string(),
+    /**
+     * Translation-ready key for the provider display name.
+     *
+     * Frontend/public surfaces should prefer this field over embedding
+     * locale-bound copy in provider modules or runtime artifacts.
+     */
+    displayNameLabelKey: z.string().optional(),
+    /**
+     * Legacy human-readable fallback label for non-i18n-aware consumers.
+     * When absent, consumers fall back to the `ref`.
+     */
+    displayName: z.string().optional(),
+    /**
+     * Optional icon reference resolved through the frontend icon registry.
+     * Stays a string (not a URL or component reference) to keep this type
+     * frontend-safe AND portable to non-React surfaces.
+     */
+    iconRef: z.string().optional(),
+});
+//# sourceMappingURL=provider-metadata.shared.schemas.js.map