@wildo-ai/saas-models 1.1.4 → 1.1.6

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

@@ -0,0 +1,141 @@
+/**
+ * WHICH provider operations a signed-in person's browser may trigger — the application's decision (#367).
+ *
+ * ## The question this answers, and why nothing else did
+ *
+ * A provider operation runs on the backend, through `ProviderOperationExecutorBackendService`, because
+ * the credential it spends must never travel to a browser. A custom backend service reaches it through
+ * a generated typed client. A custom FRONTEND component had no way to reach it at all, and the door
+ * that gives it one has to answer a question no existing engine surface answers: *which operations may
+ * a browser trigger, for whom, and on whose account*.
+ *
+ * The answer is a DECLARATION, authored in the application's SaaS config beside `providers.connections`
+ * and with the same standing: both are the application's decisions about providers, as opposed to what
+ * a vendor's catalogue says it can support.
+ *
+ * ## Fail closed, by construction
+ *
+ * An operation absent from this map is NOT reachable from a browser. There is no default, no
+ * "READ operations are fine" shortcut — classification is not sufficient: a READ still spends a tenant's
+ * credential, can page a vendor's whole account, and returns whatever the vendor holds. The map is the
+ * only thing that opens the door, one operation at a time.
+ *
+ * ## Rejected: a flag on the operation in the provider catalogue
+ *
+ * The catalogue is generated from third-party sources and overwritten on every regeneration, and it
+ * describes the VENDOR. Letting it decide what a browser may trigger would let a scraped listing grant
+ * access in every application that installs the provider — and a regeneration could grant or revoke it
+ * without anyone opening the application.
+ */
+import { ExternalProvider_Connection_OwnerScope, ExternalProvider_ConnectionShapeSchema, } from '@wildo-ai/external-connectors-models';
+import { z } from 'zod';
+import { RateLimitConfigurationSchema } from '../requests/rate-limits.shared.schemas.js';
+/** @wildo_source:part:start saas.models.providers.browser-operation-policy facet:layer:shared facet:family:config facet:audience:app-developer */
+/**
+ * One browser-reachable operation.
+ *
+ * ## `connections` — whose account a browser-triggered call may spend
+ *
+ * Owner-scope × delegation pairs, in the vocabulary the catalogue, `providers.connections`, the connect
+ * leg and the resolver already share. NARROWING ONLY: a call must satisfy this list AND the provider's
+ * admissible connections as `providers.connections` narrows them. Naming a shape the provider does not
+ * admit grants nothing.
+ *
+ * Every call still passes the target-authorization port before anything is spent — a person may name
+ * only an organization they belong to organization-wide, and only their own user account. This list
+ * narrows further; it can never widen what that port allows.
+ *
+ * ## `allowedRoles` — who may trigger it
+ *
+ * Role keys, resolved through the LIVE role hierarchy (a custom role inheriting from a listed one
+ * qualifies), and read in the scope of the ACCOUNT BEING SPENT:
+ *
+ * | target | roles are read from |
+ * |---|---|
+ * | `organization` | the caller's organization-WIDE roles in THAT organization — a unit-scoped grant never counts |
+ * | `application` | the caller's application roles |
+ * | `user` | not applicable — a person acting on their own account holds no role over it, so declaring roles on a policy that admits `user` refuses those calls |
+ *
+ * Absent means any signed-in caller the target-authorization port admits. That is a legitimate choice
+ * for a person's own account or a member acting for their own tenant, and it is REFUSED at parse time
+ * when the policy admits an `application`-owned connection: without roles, every signed-in person could
+ * spend the application's own vendor account.
+ *
+ * ## `callerRateLimit` — how often ONE person may trigger it (#561)
+ *
+ * Counted per signed-in person, per provider operation. Before it, the door's only limits were a
+ * per-provider window (off unless a provider declared one) and the IP-keyed perimeter limiter, so one
+ * person's typing into an address lookup could spend a vendor allowance the whole application shares.
+ *
+ * Absent does NOT mean unlimited: the framework applies
+ * {@link DEFAULT_PROVIDER_BROWSER_OPERATION_CALLER_RATE_LIMIT}, generous enough for a person typing into a
+ * lookup. The two differ in one way that matters, and it is the same split the rest of the engine draws
+ * between an authored and a default limit: a DECLARED limit fails CLOSED when the limiter's store is
+ * unavailable (the application stated it, so an outage must not quietly lift it), while the framework
+ * default fails OPEN (nobody declared it, so it must never be why a door stops working).
+ */
+export const ProviderBrowserOperationPolicySchema = z.strictObject({
+    connections: z.array(ExternalProvider_ConnectionShapeSchema).min(1),
+    allowedRoles: z.array(z.string().trim().min(1)).min(1).optional(),
+    callerRateLimit: RateLimitConfigurationSchema.optional(),
+}).superRefine((policy, ctx) => {
+    const admitsApplicationAccount = policy.connections.some((shape) => shape.ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION);
+    // A declared limit with no window counts nothing, yet reads as DECLARED — the framework default is then not applied
+    // either. A control that looks enforced and enforces nothing is refused where it is written (#561).
+    const limit = policy.callerRateLimit;
+    if (limit !== undefined
+        && limit.requestsPerMinute === undefined
+        && limit.requestsPerHour === undefined
+        && limit.requestsPerDay === undefined
+        && (limit.customWindows === undefined || limit.customWindows.length === 0)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['callerRateLimit'],
+            message: '`callerRateLimit` declares no window, so it would count nothing and replace the framework default. '
+                + 'Declare at least one of requestsPerMinute, requestsPerHour, requestsPerDay or customWindows, or omit it.',
+        });
+    }
+    if (admitsApplicationAccount && policy.allowedRoles === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['allowedRoles'],
+            message: 'A browser-reachable operation that may spend the APPLICATION-owned connection must declare `allowedRoles`. '
+                + 'Without it every signed-in person could spend the application\'s own vendor account.',
+        });
+    }
+});
+/**
+ * The per-person limit a browser-reachable operation gets when its policy declares none (#561).
+ *
+ * Sized for the most frequent legitimate caller, a person typing into an address lookup: suggestions start at
+ * three characters and are debounced, so one address is a handful of calls, and sixty a minute is a person
+ * typing without pause. The hourly window is what stops a script holding a session from draining a vendor
+ * allowance at a steady sixty a minute.
+ */
+export const DEFAULT_PROVIDER_BROWSER_OPERATION_CALLER_RATE_LIMIT = Object.freeze({
+    requestsPerMinute: 60,
+    requestsPerHour: 1000,
+});
+/** Where the limit a browser-triggered call is counted against came from — and so how an outage of the limiter is treated. */
+export var ProviderBrowserOperationCallerRateLimitSource;
+(function (ProviderBrowserOperationCallerRateLimitSource) {
+    /** Declared on the policy: fails CLOSED on a limiter outage. */
+    ProviderBrowserOperationCallerRateLimitSource["DECLARED"] = "DECLARED";
+    /** The framework default: fails OPEN on a limiter outage. */
+    ProviderBrowserOperationCallerRateLimitSource["FRAMEWORK_DEFAULT"] = "FRAMEWORK_DEFAULT";
+})(ProviderBrowserOperationCallerRateLimitSource || (ProviderBrowserOperationCallerRateLimitSource = {}));
+/** The one reading of a policy's per-person limit: its own, or the framework default, and which. */
+export function resolveProviderBrowserOperationCallerRateLimit(policy) {
+    return policy.callerRateLimit === undefined
+        ? { limit: DEFAULT_PROVIDER_BROWSER_OPERATION_CALLER_RATE_LIMIT, source: ProviderBrowserOperationCallerRateLimitSource.FRAMEWORK_DEFAULT }
+        : { limit: policy.callerRateLimit, source: ProviderBrowserOperationCallerRateLimitSource.DECLARED };
+}
+/**
+ * `providerRef` → `operationId` → policy. The operation id is the catalogue's own, exactly as a typed
+ * client or an ETL binding reference names it.
+ *
+ * Absent is an EMPTY map — nothing is browser-reachable — never "everything".
+ */
+export const ProviderBrowserOperationPoliciesSchema = z.record(z.string().min(1), z.record(z.string().min(1), ProviderBrowserOperationPolicySchema)).default(() => ({}));
+/** @wildo_source:part:end saas.models.providers.browser-operation-policy */
+//# sourceMappingURL=provider-browser-operations.shared.schemas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider-browser-operations.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-browser-operations.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * WHICH provider operations a signed-in person's browser may trigger — the application's decision (#367).\n *\n * ## The question this answers, and why nothing else did\n *\n * A provider operation runs on the backend, through `ProviderOperationExecutorBackendService`, because\n * the credential it spends must never travel to a browser. A custom backend service reaches it through\n * a generated typed client. A custom FRONTEND component had no way to reach it at all, and the door\n * that gives it one has to answer a question no existing engine surface answers: *which operations may\n * a browser trigger, for whom, and on whose account*.\n *\n * The answer is a DECLARATION, authored in the application's SaaS config beside `providers.connections`\n * and with the same standing: both are the application's decisions about providers, as opposed to what\n * a vendor's catalogue says it can support.\n *\n * ## Fail closed, by construction\n *\n * An operation absent from this map is NOT reachable from a browser. There is no default, no\n * \"READ operations are fine\" shortcut — classification is not sufficient: a READ still spends a tenant's\n * credential, can page a vendor's whole account, and returns whatever the vendor holds. The map is the\n * only thing that opens the door, one operation at a time.\n *\n * ## Rejected: a flag on the operation in the provider catalogue\n *\n * The catalogue is generated from third-party sources and overwritten on every regeneration, and it\n * describes the VENDOR. Letting it decide what a browser may trigger would let a scraped listing grant\n * access in every application that installs the provider — and a regeneration could grant or revoke it\n * without anyone opening the application.\n */\n\nimport {\n  ExternalProvider_Connection_OwnerScope,\n  ExternalProvider_ConnectionShapeSchema,\n} from '@wildo-ai/external-connectors-models';\nimport { z } from 'zod';\nimport { RateLimitConfigurationSchema, type RateLimitConfiguration } from '../requests/rate-limits.shared.schemas';\n\n/** @wildo_source:part:start saas.models.providers.browser-operation-policy facet:layer:shared facet:family:config facet:audience:app-developer */\n/**\n * One browser-reachable operation.\n *\n * ## `connections` — whose account a browser-triggered call may spend\n *\n * Owner-scope × delegation pairs, in the vocabulary the catalogue, `providers.connections`, the connect\n * leg and the resolver already share. NARROWING ONLY: a call must satisfy this list AND the provider's\n * admissible connections as `providers.connections` narrows them. Naming a shape the provider does not\n * admit grants nothing.\n *\n * Every call still passes the target-authorization port before anything is spent — a person may name\n * only an organization they belong to organization-wide, and only their own user account. This list\n * narrows further; it can never widen what that port allows.\n *\n * ## `allowedRoles` — who may trigger it\n *\n * Role keys, resolved through the LIVE role hierarchy (a custom role inheriting from a listed one\n * qualifies), and read in the scope of the ACCOUNT BEING SPENT:\n *\n * | target | roles are read from |\n * |---|---|\n * | `organization` | the caller's organization-WIDE roles in THAT organization — a unit-scoped grant never counts |\n * | `application` | the caller's application roles |\n * | `user` | not applicable — a person acting on their own account holds no role over it, so declaring roles on a policy that admits `user` refuses those calls |\n *\n * Absent means any signed-in caller the target-authorization port admits. That is a legitimate choice\n * for a person's own account or a member acting for their own tenant, and it is REFUSED at parse time\n * when the policy admits an `application`-owned connection: without roles, every signed-in person could\n * spend the application's own vendor account.\n *\n * ## `callerRateLimit` — how often ONE person may trigger it (#561)\n *\n * Counted per signed-in person, per provider operation. Before it, the door's only limits were a\n * per-provider window (off unless a provider declared one) and the IP-keyed perimeter limiter, so one\n * person's typing into an address lookup could spend a vendor allowance the whole application shares.\n *\n * Absent does NOT mean unlimited: the framework applies\n * {@link DEFAULT_PROVIDER_BROWSER_OPERATION_CALLER_RATE_LIMIT}, generous enough for a person typing into a\n * lookup. The two differ in one way that matters, and it is the same split the rest of the engine draws\n * between an authored and a default limit: a DECLARED limit fails CLOSED when the limiter's store is\n * unavailable (the application stated it, so an outage must not quietly lift it), while the framework\n * default fails OPEN (nobody declared it, so it must never be why a door stops working).\n */\nexport const ProviderBrowserOperationPolicySchema = z.strictObject({\n  connections: z.array(ExternalProvider_ConnectionShapeSchema).min(1),\n  allowedRoles: z.array(z.string().trim().min(1)).min(1).optional(),\n  callerRateLimit: RateLimitConfigurationSchema.optional(),\n}).superRefine((policy, ctx) => {\n  const admitsApplicationAccount = policy.connections.some(\n    (shape) => shape.ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION,\n  );\n  // A declared limit with no window counts nothing, yet reads as DECLARED — the framework default is then not applied\n  // either. A control that looks enforced and enforces nothing is refused where it is written (#561).\n  const limit = policy.callerRateLimit;\n  if (limit !== undefined\n    && limit.requestsPerMinute === undefined\n    && limit.requestsPerHour === undefined\n    && limit.requestsPerDay === undefined\n    && (limit.customWindows === undefined || limit.customWindows.length === 0)) {\n    ctx.addIssue({\n      code: 'custom',\n      path: ['callerRateLimit'],\n      message:\n        '`callerRateLimit` declares no window, so it would count nothing and replace the framework default. '\n        + 'Declare at least one of requestsPerMinute, requestsPerHour, requestsPerDay or customWindows, or omit it.',\n    });\n  }\n  if (admitsApplicationAccount && policy.allowedRoles === undefined) {\n    ctx.addIssue({\n      code: 'custom',\n      path: ['allowedRoles'],\n      message:\n        'A browser-reachable operation that may spend the APPLICATION-owned connection must declare `allowedRoles`. '\n        + 'Without it every signed-in person could spend the application\\'s own vendor account.',\n    });\n  }\n});\nexport type ProviderBrowserOperationPolicy = z.infer<typeof ProviderBrowserOperationPolicySchema>;\n\n/**\n * The per-person limit a browser-reachable operation gets when its policy declares none (#561).\n *\n * Sized for the most frequent legitimate caller, a person typing into an address lookup: suggestions start at\n * three characters and are debounced, so one address is a handful of calls, and sixty a minute is a person\n * typing without pause. The hourly window is what stops a script holding a session from draining a vendor\n * allowance at a steady sixty a minute.\n */\nexport const DEFAULT_PROVIDER_BROWSER_OPERATION_CALLER_RATE_LIMIT: RateLimitConfiguration = Object.freeze({\n  requestsPerMinute: 60,\n  requestsPerHour: 1000,\n});\n\n/** Where the limit a browser-triggered call is counted against came from — and so how an outage of the limiter is treated. */\nexport enum ProviderBrowserOperationCallerRateLimitSource {\n  /** Declared on the policy: fails CLOSED on a limiter outage. */\n  DECLARED = 'DECLARED',\n  /** The framework default: fails OPEN on a limiter outage. */\n  FRAMEWORK_DEFAULT = 'FRAMEWORK_DEFAULT',\n}\n\n/** The one reading of a policy's per-person limit: its own, or the framework default, and which. */\nexport function resolveProviderBrowserOperationCallerRateLimit(policy: Pick<ProviderBrowserOperationPolicy, 'callerRateLimit'>): {\n  readonly limit: RateLimitConfiguration;\n  readonly source: ProviderBrowserOperationCallerRateLimitSource;\n} {\n  return policy.callerRateLimit === undefined\n    ? { limit: DEFAULT_PROVIDER_BROWSER_OPERATION_CALLER_RATE_LIMIT, source: ProviderBrowserOperationCallerRateLimitSource.FRAMEWORK_DEFAULT }\n    : { limit: policy.callerRateLimit, source: ProviderBrowserOperationCallerRateLimitSource.DECLARED };\n}\n\n/**\n * `providerRef` → `operationId` → policy. The operation id is the catalogue's own, exactly as a typed\n * client or an ETL binding reference names it.\n *\n * Absent is an EMPTY map — nothing is browser-reachable — never \"everything\".\n */\nexport const ProviderBrowserOperationPoliciesSchema = z.record(\n  z.string().min(1),\n  z.record(z.string().min(1), ProviderBrowserOperationPolicySchema),\n).default(() => ({}));\nexport type ProviderBrowserOperationPolicies = z.infer<typeof ProviderBrowserOperationPoliciesSchema>;\n/** @wildo_source:part:end saas.models.providers.browser-operation-policy */\n"]}

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

@@ -1,17 +1,17 @@
 /**
- * `ProviderCapability` — open, app-extensible enum of standardized
- * behaviors that providers implement.
+ * `ProviderCapability` — the closed vocabulary of standardized behaviors
+ * a provider claims to 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.
+ * may require fulfillment): a provider CLAIMS a `ProviderCapability`, and
+ * `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` projects the claims that fill
+ * an engine slot.
  *
- * 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.
+ * This header described the vocabulary as "open, app-extensible", with a
+ * kebab-case convention for app-augmented values, until 2026-09-12. The
+ * augmentation point was removed by #502 (see below), so no second namespace
+ * exists; the `.cursor/plans/` citation it carried named a directory that no
+ * longer exists.
  */
 /** @wildo_source:part:start saas.models.provider-capabilities facet:kind:api facet:audience:app-developer
  *
@@ -28,6 +28,18 @@
 export declare const BUILTIN_PROVIDER_CAPABILITY: {
     readonly EMAIL_TRANSACTIONAL: "EMAIL_TRANSACTIONAL";
     readonly EMAIL_MARKETING: "EMAIL_MARKETING";
+    /**
+     * Provider RECEIVES email for the application: it hosts the MX for a receiving domain, notifies the
+     * application of each message through a signed webhook, and serves the message (bodies,
+     * authentication results, attachments) on request. Maps to `EngineCapability.EMAIL_INBOUND`.
+     *
+     * A token of its own rather than a reading of `EMAIL_TRANSACTIONAL`, because sending and receiving
+     * are separate procurement decisions: one vendor may send and another receive, and threading only
+     * needs standard headers, so the two never have to agree (#1630). Delivery of the notification is
+     * NOT this capability — like billing's, it rides the `WEBHOOK_ORIGINATOR` protocol through an
+     * endpoint whose `capability` names this token.
+     */
+    readonly EMAIL_INBOUND: "EMAIL_INBOUND";
     readonly SMS: "SMS";
     /**
      * Single billing-engagement capability covering everything from
@@ -75,9 +87,31 @@ export declare const BUILTIN_PROVIDER_CAPABILITY: {
     readonly IMAGE_GENERATION: "IMAGE_GENERATION";
     readonly FRONTEND_ERROR_MONITORING: "FRONTEND_ERROR_MONITORING";
     readonly FRONTEND_PRODUCT_ANALYTICS: "FRONTEND_PRODUCT_ANALYTICS";
+    /**
+     * A hosted search a browser module brings to a surface. The engine ships no provider for it since #1737
+     * (Algolia DocSearch loaded nothing; the documentation site searches its own generated index). Kept
+     * because an application or package module may still declare one, and the consent classification and the
+     * privacy disclosure map both answer for it.
+     */
     readonly FRONTEND_SEARCH: "FRONTEND_SEARCH";
     readonly FRONTEND_FILE_PICKER: "FRONTEND_FILE_PICKER";
     readonly FRONTEND_CAPTCHA: "FRONTEND_CAPTCHA";
+    /**
+     * A browser component that turns what a person types into a STRUCTURED postal address — the
+     * `z_address()` value — optionally with the vendor's own identifier for the place it matched (#1702,
+     * consumed by the address field of #561).
+     *
+     * The component's contract is `ProviderAddressLookupProps` (`@wildo-ai/saas-models`): it hands back a
+     * `ProviderAddressLookupSelection`. Whether the vendor's place id comes back at all is a static
+     * declaration on the component (`placeIdRetention`), refused at the framework boundary when a selection
+     * contradicts it — the #383 pattern — and the id is never stored (#561 D3). The component reaches its
+     * vendor through the application backend's provider-operation door, never from the page (#561 D2).
+     *
+     * Fills no engine slot: nothing in the engine requires an address lookup to exist, and a field that
+     * finds none is typed by hand. Needs no consent at the capability floor (the person asked for the
+     * lookup); a vendor whose terms make it more than that adds purposes on its own module.
+     */
+    readonly FRONTEND_ADDRESS_LOOKUP: "FRONTEND_ADDRESS_LOOKUP";
     /**
      * Backend LLM-call observability — a provider that ingests per-`invokeAgent`
      * generation traces (model / tokens / cost / latency), e.g. PostHog
@@ -105,9 +139,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];
 /**
- * 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.
+ * Every provider capability — exactly the closed built-in set. There is no
+ * app-side augmentation (removed by #502, see above), so this is a name for
+ * `BuiltinProviderCapability` that consumers (the provider registries, the
+ * provider component registry, lock-file digests) accept.
  */
 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;;;;;;;;;;;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"}
+{"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;;;IAGtC;;;;;;;;;;OAUG;;;IAGH;;;;;;;;OAQG;;;IAGH,sEAAsE;;;;IAItE;;;;;;;;;;;;;;OAcG;;IAEH;;;;;;;;;;OAUG;;;;;IAKH;;;;;OAKG;;;;IAIH;;;;;;;;;;;;;;OAcG;;IAEH;;;;;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;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,CAAC"}

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

@@ -1,17 +1,17 @@
 /**
- * `ProviderCapability` — open, app-extensible enum of standardized
- * behaviors that providers implement.
+ * `ProviderCapability` — the closed vocabulary of standardized behaviors
+ * a provider claims to 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.
+ * may require fulfillment): a provider CLAIMS a `ProviderCapability`, and
+ * `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` projects the claims that fill
+ * an engine slot.
  *
- * 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.
+ * This header described the vocabulary as "open, app-extensible", with a
+ * kebab-case convention for app-augmented values, until 2026-09-12. The
+ * augmentation point was removed by #502 (see below), so no second namespace
+ * exists; the `.cursor/plans/` citation it carried named a directory that no
+ * longer exists.
  */
 /** @wildo_source:part:start saas.models.provider-capabilities facet:kind:api facet:audience:app-developer
  *
@@ -28,6 +28,18 @@
 export const BUILTIN_PROVIDER_CAPABILITY = {
     EMAIL_TRANSACTIONAL: 'EMAIL_TRANSACTIONAL',
     EMAIL_MARKETING: 'EMAIL_MARKETING',
+    /**
+     * Provider RECEIVES email for the application: it hosts the MX for a receiving domain, notifies the
+     * application of each message through a signed webhook, and serves the message (bodies,
+     * authentication results, attachments) on request. Maps to `EngineCapability.EMAIL_INBOUND`.
+     *
+     * A token of its own rather than a reading of `EMAIL_TRANSACTIONAL`, because sending and receiving
+     * are separate procurement decisions: one vendor may send and another receive, and threading only
+     * needs standard headers, so the two never have to agree (#1630). Delivery of the notification is
+     * NOT this capability — like billing's, it rides the `WEBHOOK_ORIGINATOR` protocol through an
+     * endpoint whose `capability` names this token.
+     */
+    EMAIL_INBOUND: 'EMAIL_INBOUND',
     SMS: 'SMS',
     /**
      * Single billing-engagement capability covering everything from
@@ -75,9 +87,31 @@ export const BUILTIN_PROVIDER_CAPABILITY = {
     IMAGE_GENERATION: 'IMAGE_GENERATION',
     FRONTEND_ERROR_MONITORING: 'FRONTEND_ERROR_MONITORING',
     FRONTEND_PRODUCT_ANALYTICS: 'FRONTEND_PRODUCT_ANALYTICS',
+    /**
+     * A hosted search a browser module brings to a surface. The engine ships no provider for it since #1737
+     * (Algolia DocSearch loaded nothing; the documentation site searches its own generated index). Kept
+     * because an application or package module may still declare one, and the consent classification and the
+     * privacy disclosure map both answer for it.
+     */
     FRONTEND_SEARCH: 'FRONTEND_SEARCH',
     FRONTEND_FILE_PICKER: 'FRONTEND_FILE_PICKER',
     FRONTEND_CAPTCHA: 'FRONTEND_CAPTCHA',
+    /**
+     * A browser component that turns what a person types into a STRUCTURED postal address — the
+     * `z_address()` value — optionally with the vendor's own identifier for the place it matched (#1702,
+     * consumed by the address field of #561).
+     *
+     * The component's contract is `ProviderAddressLookupProps` (`@wildo-ai/saas-models`): it hands back a
+     * `ProviderAddressLookupSelection`. Whether the vendor's place id comes back at all is a static
+     * declaration on the component (`placeIdRetention`), refused at the framework boundary when a selection
+     * contradicts it — the #383 pattern — and the id is never stored (#561 D3). The component reaches its
+     * vendor through the application backend's provider-operation door, never from the page (#561 D2).
+     *
+     * Fills no engine slot: nothing in the engine requires an address lookup to exist, and a field that
+     * finds none is typed by hand. Needs no consent at the capability floor (the person asked for the
+     * lookup); a vendor whose terms make it more than that adds purposes on its own module.
+     */
+    FRONTEND_ADDRESS_LOOKUP: 'FRONTEND_ADDRESS_LOOKUP',
     /**
      * Backend LLM-call observability — a provider that ingests per-`invokeAgent`
      * generation traces (model / tokens / cost / latency), e.g. PostHog

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;;;;;;;;;;;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"]}
+{"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;;;;;;;;;;OAUG;IACH,aAAa,EAAE,eAAe;IAC9B,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;;;;;OAKG;IACH,eAAe,EAAE,iBAAiB;IAClC,oBAAoB,EAAE,sBAAsB;IAC5C,gBAAgB,EAAE,kBAAkB;IACpC;;;;;;;;;;;;;;OAcG;IACH,uBAAuB,EAAE,yBAAyB;IAClD;;;;;OAKG;IACH,iBAAiB,EAAE,mBAAmB;IACtC;;;;;OAKG;IACH,uBAAuB,EAAE,yBAAyB;IAClD;;;;;;;OAOG;IACH,sBAAsB,EAAE,wBAAwB;CACxC,CAAC","sourcesContent":["/**\n * `ProviderCapability` — the closed vocabulary of standardized behaviors\n * a provider claims to implement.\n *\n * Distinct from `EngineCapability` (closed, engine-defined slots that\n * may require fulfillment): a provider CLAIMS a `ProviderCapability`, and\n * `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` projects the claims that fill\n * an engine slot.\n *\n * This header described the vocabulary as \"open, app-extensible\", with a\n * kebab-case convention for app-augmented values, until 2026-09-12. The\n * augmentation point was removed by #502 (see below), so no second namespace\n * exists; the `.cursor/plans/` citation it carried named a directory that no\n * longer exists.\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  /**\n   * Provider RECEIVES email for the application: it hosts the MX for a receiving domain, notifies the\n   * application of each message through a signed webhook, and serves the message (bodies,\n   * authentication results, attachments) on request. Maps to `EngineCapability.EMAIL_INBOUND`.\n   *\n   * A token of its own rather than a reading of `EMAIL_TRANSACTIONAL`, because sending and receiving\n   * are separate procurement decisions: one vendor may send and another receive, and threading only\n   * needs standard headers, so the two never have to agree (#1630). Delivery of the notification is\n   * NOT this capability — like billing's, it rides the `WEBHOOK_ORIGINATOR` protocol through an\n   * endpoint whose `capability` names this token.\n   */\n  EMAIL_INBOUND: 'EMAIL_INBOUND',\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  /**\n   * A hosted search a browser module brings to a surface. The engine ships no provider for it since #1737\n   * (Algolia DocSearch loaded nothing; the documentation site searches its own generated index). Kept\n   * because an application or package module may still declare one, and the consent classification and the\n   * privacy disclosure map both answer for it.\n   */\n  FRONTEND_SEARCH: 'FRONTEND_SEARCH',\n  FRONTEND_FILE_PICKER: 'FRONTEND_FILE_PICKER',\n  FRONTEND_CAPTCHA: 'FRONTEND_CAPTCHA',\n  /**\n   * A browser component that turns what a person types into a STRUCTURED postal address — the\n   * `z_address()` value — optionally with the vendor's own identifier for the place it matched (#1702,\n   * consumed by the address field of #561).\n   *\n   * The component's contract is `ProviderAddressLookupProps` (`@wildo-ai/saas-models`): it hands back a\n   * `ProviderAddressLookupSelection`. Whether the vendor's place id comes back at all is a static\n   * declaration on the component (`placeIdRetention`), refused at the framework boundary when a selection\n   * contradicts it — the #383 pattern — and the id is never stored (#561 D3). The component reaches its\n   * vendor through the application backend's provider-operation door, never from the page (#561 D2).\n   *\n   * Fills no engine slot: nothing in the engine requires an address lookup to exist, and a field that\n   * finds none is typed by hand. Needs no consent at the capability floor (the person asked for the\n   * lookup); a vendor whose terms make it more than that adds purposes on its own module.\n   */\n  FRONTEND_ADDRESS_LOOKUP: 'FRONTEND_ADDRESS_LOOKUP',\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 * Every provider capability — exactly the closed built-in set. There is no\n * app-side augmentation (removed by #502, see above), so this is a name for\n * `BuiltinProviderCapability` that consumers (the provider registries, the\n * provider component registry, lock-file digests) accept.\n */\nexport type ProviderCapability = BuiltinProviderCapability;\n"]}