@wildo-ai/saas-models 1.1.5 → 1.1.7

package/dist/esm/external-providers/provider-address-lookup-contract.shared.types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The contract between a `FRONTEND_ADDRESS_LOOKUP` component and the address field that mounts it
+ * (#1702, consumed by #561).
+ *
+ * ## Why it lives here, and why NOT on `public-runtime`
+ *
+ * It sits beside the file-picker contract (`provider-frontend-component-contract.shared.types.ts`) for
+ * the reason that file gives: a component ships in its own React-bearing package, which must be able to
+ * type itself without importing the connectors package that resolves it.
+ *
+ * Unlike that file it is exported from the package ROOT only. The value it hands back is the framework's
+ * address value, `AddressValue` from `@wildo-ai/zod-decorators`, and the `public-runtime` closure may not
+ * import that package at all — not even for a type (K-3, measured by `public-runtime.boundary.test.ts`).
+ * Restating the address shape here to stay inside that closure was the rejected alternative: it would be
+ * a second source for the one address vocabulary #1730 exists to make single. A type-only import is
+ * erased from every bundle, so a component package importing these types from the root pays nothing.
+ *
+ * The DATA half — whether a component returns a vendor place id (never stored, #561 D3) — is
+ * `ProviderAddressLookupPlaceIdRetention` on the component descriptor, which IS on `public-runtime`.
+ */
+import type { AddressValue } from '@wildo-ai/zod-decorators';
+/** @wildo_source:part:start saas.models.provider-address-lookup-contract facet:kind:api facet:audience:app-developer */
+/**
+ * What an address lookup hands back for ONE chosen place.
+ *
+ * `address` is the application's own value: the person chose it, and it is stored exactly as a typed
+ * address would be. `placeId` is the VENDOR's key for the place, present only when the component's
+ * declared `placeIdRetention` allows one; the framework refuses a selection that carries a place id its
+ * component declared it never returns, and never stores one (#561 D3).
+ */
+export interface ProviderAddressLookupSelection {
+    readonly address: AddressValue;
+    /** The vendor's identifier for the matched place. Opaque, usable for this interaction only, and never stored. */
+    readonly placeId?: string;
+}
+/**
+ * The props every `FRONTEND_ADDRESS_LOOKUP` component receives.
+ *
+ * Deliberately narrow. The component suggests and resolves; the FIELD owns the value, its validation
+ * (`z_address()` with its `countriesAllowed`) and its persistence. That split is what lets an address
+ * field work with no lookup at all, which is why the capability fills no engine slot.
+ *
+ * ## The vendor is reached through `suggest` and `retrieve`, never directly (#561 D2)
+ *
+ * The framework's host binds both to the operations the component's descriptor declares
+ * (`addressLookup.suggestOperationId` / `retrieveOperationId`) and runs them through the application
+ * backend's provider-operation door. The host also writes the vendor session token into each input when the
+ * descriptor names `sessionTokenInput` (#561 D4) — a component never generates, holds or rotates one. Each
+ * resolves to the operation's parsed output, and rejects with the door's error (a refusal, a throttle, a
+ * vendor timeout); a component reports that through `onError` and the field stays usable by hand.
+ */
+export interface ProviderAddressLookupProps {
+    /** The provider's own `ref`. */
+    readonly providerRef: string;
+    /** The provider's public configuration, already validated against its `publicConfigSchema` when it declares one. */
+    readonly publicConfig: Readonly<Record<string, unknown>>;
+    /**
+     * ISO 3166-1 alpha-2 codes the field accepts (`z_address({ countriesAllowed })`). A component should
+     * restrict its suggestions to them; the field still validates whatever comes back.
+     */
+    readonly countriesAllowed?: readonly string[];
+    /** The field's default country, a hint for ranking suggestions. */
+    readonly defaultCountry?: string;
+    /** The person's language (BCP 47), so suggestions and the retrieved address are spelled in it where the vendor can. */
+    readonly languageCode: string;
+    /** True while the field is disabled or read-only: the component offers no search then. */
+    readonly disabled: boolean;
+    /**
+     * The search control's form NAME. The host renders the control's visible label (from the application's
+     * labels) for the element whose id is `field-<name>` — the id every engine form control takes — so the
+     * component puts that id on its focusable control and invents no label text of its own.
+     */
+    readonly name: string;
+    /**
+     * The vendor's required attribution (#561 D4), from the descriptor's `attributionMark`, or absent when the vendor
+     * requires none. `mark` is the vendor's text, verbatim; `accessibleLabel` is a sentence from the application's
+     * labels naming it, for assistive technology.
+     *
+     * The component shows it INSIDE the container that shows its suggestions, whenever suggestions are shown — the
+     * placement Google requires ("within the same visual container" as the content). Render it with
+     * `ProviderAddressLookupAttribution` (`@wildo-ai/saas-frontend-lib`), which applies the vendor's text rules
+     * (untranslated, on one line, in a permitted colour); the framework's own lookup combobox does.
+     * spec-cite: https://developers.google.com/maps/documentation/places/web-service/policies — text attribution rules,
+     * fetched 2026-09-29.
+     */
+    readonly attribution?: ProviderAddressLookupAttributionText;
+    /** Run the declared SUGGEST operation with this input. */
+    suggest(input: Readonly<Record<string, unknown>>): Promise<unknown>;
+    /** Run the declared RETRIEVE operation with this input. Ends the vendor session, whatever it answers. */
+    retrieve(input: Readonly<Record<string, unknown>>): Promise<unknown>;
+    /** The person chose a place. Called at most once per interaction. */
+    onSelect(selection: ProviderAddressLookupSelection): void;
+    /** The person dismissed the lookup without choosing. Ends the vendor session. */
+    onCancel(): void;
+    /**
+     * The lookup could not run — the door refused it, the vendor timed out or answered a shape the adapter
+     * cannot read. Reported rather than thrown, for the reason the file-picker contract gives: a throw inside
+     * a component's own event handler reaches no React error boundary.
+     */
+    onError(error: Error): void;
+}
+/** A vendor's required attribution, as the host hands it to a lookup component. */
+export interface ProviderAddressLookupAttributionText {
+    /** The vendor's own attribution text, never translated or restyled ("Google Maps"). */
+    readonly mark: string;
+    /** A sentence from the application's labels that names the mark, for assistive technology. */
+    readonly accessibleLabel: string;
+}
+/** One suggestion, as a person reads it. Vendor text, never derived by the framework. */
+export interface ProviderAddressLookupSuggestion {
+    /** The vendor's handle for the suggestion, passed back to `buildRetrieveInput`. Opaque; never stored. */
+    readonly id: string;
+    /** The line a person recognises the place by (the street address). */
+    readonly primaryText: string;
+    /** The line that disambiguates it (town, region, country), when the vendor gives one. */
+    readonly secondaryText?: string;
+}
+/**
+ * Everything VENDOR-SPECIFIC about an address lookup, as four pure functions: how a query becomes the
+ * suggest operation's input, how its answer becomes suggestions, how a chosen suggestion becomes the retrieve
+ * operation's input, and how that answer becomes the framework's `AddressValue`.
+ *
+ * With it, the framework's own combobox (`ProviderAddressLookupCombobox` in `@wildo-ai/saas-frontend-lib`)
+ * is a complete lookup component: the keyboard pattern, the debounce, the minimum query length, stale-answer
+ * handling and the manual-entry fallback are written once rather than once per vendor. A provider whose
+ * lookup needs its own UI implements `ProviderAddressLookupProps` directly instead.
+ *
+ * `readAddress` returns TEXT parts only: a vendor geocode is never taken (#561 D3). A stored coordinate has no
+ * expiry, while a lookup's geocode is at best storable for a limited time (Google: 30 days) or not at all (Mapbox
+ * Search Box) — #561's 2026-09-14 reading of both vendors' terms — and nothing runs the vendor's clock. The
+ * field drops coordinates anyway.
+ */
+export interface ProviderAddressLookupAdapter {
+    buildSuggestInput(request: {
+        readonly query: string;
+        readonly countriesAllowed?: readonly string[];
+        readonly defaultCountry?: string;
+        readonly languageCode: string;
+    }): Record<string, unknown>;
+    /** Never throws on a well-formed but empty answer; returns `[]`. Throws only on an answer it cannot read. */
+    readSuggestions(output: unknown): readonly ProviderAddressLookupSuggestion[];
+    buildRetrieveInput(request: {
+        readonly suggestion: ProviderAddressLookupSuggestion;
+        readonly languageCode: string;
+    }): Record<string, unknown>;
+    /** `undefined` when the vendor answered with no postal address for the place (a place with no street address). */
+    readAddress(output: unknown): AddressValue | undefined;
+}
+/** @wildo_source:part:end saas.models.provider-address-lookup-contract */
+//# sourceMappingURL=provider-address-lookup-contract.shared.types.d.ts.map

package/dist/esm/external-providers/provider-address-lookup-contract.shared.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-address-lookup-contract.shared.types.d.ts","sourceRoot":"","sources":["../../../src/external-providers/provider-address-lookup-contract.shared.types.ts"],"names":[],"mappings":"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"}

package/dist/esm/external-providers/provider-address-lookup-contract.shared.types.js

@@ -0,0 +1,22 @@
+/**
+ * The contract between a `FRONTEND_ADDRESS_LOOKUP` component and the address field that mounts it
+ * (#1702, consumed by #561).
+ *
+ * ## Why it lives here, and why NOT on `public-runtime`
+ *
+ * It sits beside the file-picker contract (`provider-frontend-component-contract.shared.types.ts`) for
+ * the reason that file gives: a component ships in its own React-bearing package, which must be able to
+ * type itself without importing the connectors package that resolves it.
+ *
+ * Unlike that file it is exported from the package ROOT only. The value it hands back is the framework's
+ * address value, `AddressValue` from `@wildo-ai/zod-decorators`, and the `public-runtime` closure may not
+ * import that package at all — not even for a type (K-3, measured by `public-runtime.boundary.test.ts`).
+ * Restating the address shape here to stay inside that closure was the rejected alternative: it would be
+ * a second source for the one address vocabulary #1730 exists to make single. A type-only import is
+ * erased from every bundle, so a component package importing these types from the root pays nothing.
+ *
+ * The DATA half — whether a component returns a vendor place id (never stored, #561 D3) — is
+ * `ProviderAddressLookupPlaceIdRetention` on the component descriptor, which IS on `public-runtime`.
+ */
+/** @wildo_source:part:end saas.models.provider-address-lookup-contract */
+//# sourceMappingURL=provider-address-lookup-contract.shared.types.js.map

package/dist/esm/external-providers/provider-address-lookup-contract.shared.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-address-lookup-contract.shared.types.js","sourceRoot":"","sources":["../../../src/external-providers/provider-address-lookup-contract.shared.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAqIH,0EAA0E","sourcesContent":["/**\n * The contract between a `FRONTEND_ADDRESS_LOOKUP` component and the address field that mounts it\n * (#1702, consumed by #561).\n *\n * ## Why it lives here, and why NOT on `public-runtime`\n *\n * It sits beside the file-picker contract (`provider-frontend-component-contract.shared.types.ts`) for\n * the reason that file gives: a component ships in its own React-bearing package, which must be able to\n * type itself without importing the connectors package that resolves it.\n *\n * Unlike that file it is exported from the package ROOT only. The value it hands back is the framework's\n * address value, `AddressValue` from `@wildo-ai/zod-decorators`, and the `public-runtime` closure may not\n * import that package at all — not even for a type (K-3, measured by `public-runtime.boundary.test.ts`).\n * Restating the address shape here to stay inside that closure was the rejected alternative: it would be\n * a second source for the one address vocabulary #1730 exists to make single. A type-only import is\n * erased from every bundle, so a component package importing these types from the root pays nothing.\n *\n * The DATA half — whether a component returns a vendor place id (never stored, #561 D3) — is\n * `ProviderAddressLookupPlaceIdRetention` on the component descriptor, which IS on `public-runtime`.\n */\n\nimport type { AddressValue } from '@wildo-ai/zod-decorators';\n\n/** @wildo_source:part:start saas.models.provider-address-lookup-contract facet:kind:api facet:audience:app-developer */\n\n/**\n * What an address lookup hands back for ONE chosen place.\n *\n * `address` is the application's own value: the person chose it, and it is stored exactly as a typed\n * address would be. `placeId` is the VENDOR's key for the place, present only when the component's\n * declared `placeIdRetention` allows one; the framework refuses a selection that carries a place id its\n * component declared it never returns, and never stores one (#561 D3).\n */\nexport interface ProviderAddressLookupSelection {\n  readonly address: AddressValue;\n  /** The vendor's identifier for the matched place. Opaque, usable for this interaction only, and never stored. */\n  readonly placeId?: string;\n}\n\n/**\n * The props every `FRONTEND_ADDRESS_LOOKUP` component receives.\n *\n * Deliberately narrow. The component suggests and resolves; the FIELD owns the value, its validation\n * (`z_address()` with its `countriesAllowed`) and its persistence. That split is what lets an address\n * field work with no lookup at all, which is why the capability fills no engine slot.\n *\n * ## The vendor is reached through `suggest` and `retrieve`, never directly (#561 D2)\n *\n * The framework's host binds both to the operations the component's descriptor declares\n * (`addressLookup.suggestOperationId` / `retrieveOperationId`) and runs them through the application\n * backend's provider-operation door. The host also writes the vendor session token into each input when the\n * descriptor names `sessionTokenInput` (#561 D4) — a component never generates, holds or rotates one. Each\n * resolves to the operation's parsed output, and rejects with the door's error (a refusal, a throttle, a\n * vendor timeout); a component reports that through `onError` and the field stays usable by hand.\n */\nexport interface ProviderAddressLookupProps {\n  /** The provider's own `ref`. */\n  readonly providerRef: string;\n  /** The provider's public configuration, already validated against its `publicConfigSchema` when it declares one. */\n  readonly publicConfig: Readonly<Record<string, unknown>>;\n  /**\n   * ISO 3166-1 alpha-2 codes the field accepts (`z_address({ countriesAllowed })`). A component should\n   * restrict its suggestions to them; the field still validates whatever comes back.\n   */\n  readonly countriesAllowed?: readonly string[];\n  /** The field's default country, a hint for ranking suggestions. */\n  readonly defaultCountry?: string;\n  /** The person's language (BCP 47), so suggestions and the retrieved address are spelled in it where the vendor can. */\n  readonly languageCode: string;\n  /** True while the field is disabled or read-only: the component offers no search then. */\n  readonly disabled: boolean;\n  /**\n   * The search control's form NAME. The host renders the control's visible label (from the application's\n   * labels) for the element whose id is `field-<name>` — the id every engine form control takes — so the\n   * component puts that id on its focusable control and invents no label text of its own.\n   */\n  readonly name: string;\n  /**\n   * The vendor's required attribution (#561 D4), from the descriptor's `attributionMark`, or absent when the vendor\n   * requires none. `mark` is the vendor's text, verbatim; `accessibleLabel` is a sentence from the application's\n   * labels naming it, for assistive technology.\n   *\n   * The component shows it INSIDE the container that shows its suggestions, whenever suggestions are shown — the\n   * placement Google requires (\"within the same visual container\" as the content). Render it with\n   * `ProviderAddressLookupAttribution` (`@wildo-ai/saas-frontend-lib`), which applies the vendor's text rules\n   * (untranslated, on one line, in a permitted colour); the framework's own lookup combobox does.\n   * spec-cite: https://developers.google.com/maps/documentation/places/web-service/policies — text attribution rules,\n   * fetched 2026-09-29.\n   */\n  readonly attribution?: ProviderAddressLookupAttributionText;\n  /** Run the declared SUGGEST operation with this input. */\n  suggest(input: Readonly<Record<string, unknown>>): Promise<unknown>;\n  /** Run the declared RETRIEVE operation with this input. Ends the vendor session, whatever it answers. */\n  retrieve(input: Readonly<Record<string, unknown>>): Promise<unknown>;\n  /** The person chose a place. Called at most once per interaction. */\n  onSelect(selection: ProviderAddressLookupSelection): void;\n  /** The person dismissed the lookup without choosing. Ends the vendor session. */\n  onCancel(): void;\n  /**\n   * The lookup could not run — the door refused it, the vendor timed out or answered a shape the adapter\n   * cannot read. Reported rather than thrown, for the reason the file-picker contract gives: a throw inside\n   * a component's own event handler reaches no React error boundary.\n   */\n  onError(error: Error): void;\n}\n\n/** A vendor's required attribution, as the host hands it to a lookup component. */\nexport interface ProviderAddressLookupAttributionText {\n  /** The vendor's own attribution text, never translated or restyled (\"Google Maps\"). */\n  readonly mark: string;\n  /** A sentence from the application's labels that names the mark, for assistive technology. */\n  readonly accessibleLabel: string;\n}\n\n/** One suggestion, as a person reads it. Vendor text, never derived by the framework. */\nexport interface ProviderAddressLookupSuggestion {\n  /** The vendor's handle for the suggestion, passed back to `buildRetrieveInput`. Opaque; never stored. */\n  readonly id: string;\n  /** The line a person recognises the place by (the street address). */\n  readonly primaryText: string;\n  /** The line that disambiguates it (town, region, country), when the vendor gives one. */\n  readonly secondaryText?: string;\n}\n\n/**\n * Everything VENDOR-SPECIFIC about an address lookup, as four pure functions: how a query becomes the\n * suggest operation's input, how its answer becomes suggestions, how a chosen suggestion becomes the retrieve\n * operation's input, and how that answer becomes the framework's `AddressValue`.\n *\n * With it, the framework's own combobox (`ProviderAddressLookupCombobox` in `@wildo-ai/saas-frontend-lib`)\n * is a complete lookup component: the keyboard pattern, the debounce, the minimum query length, stale-answer\n * handling and the manual-entry fallback are written once rather than once per vendor. A provider whose\n * lookup needs its own UI implements `ProviderAddressLookupProps` directly instead.\n *\n * `readAddress` returns TEXT parts only: a vendor geocode is never taken (#561 D3). A stored coordinate has no\n * expiry, while a lookup's geocode is at best storable for a limited time (Google: 30 days) or not at all (Mapbox\n * Search Box) — #561's 2026-09-14 reading of both vendors' terms — and nothing runs the vendor's clock. The\n * field drops coordinates anyway.\n */\nexport interface ProviderAddressLookupAdapter {\n  buildSuggestInput(request: {\n    readonly query: string;\n    readonly countriesAllowed?: readonly string[];\n    readonly defaultCountry?: string;\n    readonly languageCode: string;\n  }): Record<string, unknown>;\n  /** Never throws on a well-formed but empty answer; returns `[]`. Throws only on an answer it cannot read. */\n  readSuggestions(output: unknown): readonly ProviderAddressLookupSuggestion[];\n  buildRetrieveInput(request: { readonly suggestion: ProviderAddressLookupSuggestion; readonly languageCode: string }): Record<string, unknown>;\n  /** `undefined` when the vendor answered with no postal address for the place (a place with no street address). */\n  readAddress(output: unknown): AddressValue | undefined;\n}\n/** @wildo_source:part:end saas.models.provider-address-lookup-contract */\n"]}

package/dist/esm/external-providers/provider-augmentation-opt-ins.shared.schemas.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/** @wildo_source:part:start saas.config.providers.augmentations facet:layer:shared facet:family:provider-config facet:audience:app-developer */
+/**
+ * Which provider AUGMENTATIONS this application admits (#1672): `baseRef` → the packages allowed to add
+ * operations to that provider.
+ *
+ * ```ts
+ * providers: {
+ *   scopes: { backend: { providers: { 'acme-crm': { protocols: ['REST_API'] } } } },
+ *   augmentations: { 'acme-crm': ['@acme/provider-crm-chat'] },
+ * }
+ * ```
+ *
+ * The base provider must declare a `REST_API` binding, and the package must be one discovery walks: a
+ * framework provider package, a provider package in the application's own scope
+ * (`<application-scope>/provider-*`), or a package listed in `providers.packages`.
+ *
+ * ## Why an augmentation needs an opt-in at all
+ *
+ * An augmentation adds operations to a provider it does not own, and those operations run with the BASE
+ * provider's credential — for a delegated connection, a person's own grant. Admitting one is therefore a
+ * trust decision about third-party code spending a grant, of the same kind as `connections`, and it is the
+ * application's to make. Installing a package decides nothing: a package that is a dependency and is not
+ * named here contributes no operation. That is also what keeps a provider package that augments many
+ * engine-owned refs (`stripe`, `openai`…) inert until an application asks for one of them.
+ *
+ * ## Why application-level rather than per runtime scope
+ *
+ * An augmented provider has ONE operation catalogue per grant, whichever runtime spends it. Opting a package
+ * in for the backend and not for a minion would give one grant two operation sets, and an operation id
+ * would mean a request in one process and nothing in another. The augmentation applies wherever the base
+ * provider is scoped.
+ *
+ * `wildo config sync` refuses a package it did not discover, a package that does not augment this ref, a
+ * ref no scope declares, a base with no REST binding, and two opted-in packages sharing an operation id.
+ *
+ * Absent means none — never "every installed augmentation".
+ */
+export declare const ProviderAugmentationOptInsSchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+export type ProviderAugmentationOptIns = z.infer<typeof ProviderAugmentationOptInsSchema>;
+/** @wildo_source:part:end saas.config.providers.augmentations */
+//# sourceMappingURL=provider-augmentation-opt-ins.shared.schemas.d.ts.map

package/dist/esm/external-providers/provider-augmentation-opt-ins.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-augmentation-opt-ins.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/external-providers/provider-augmentation-opt-ins.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gJAAgJ;AAChJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,gCAAgC,mDAW5C,CAAC;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAC1F,iEAAiE"}

package/dist/esm/external-providers/provider-augmentation-opt-ins.shared.schemas.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/** @wildo_source:part:start saas.config.providers.augmentations facet:layer:shared facet:family:provider-config facet:audience:app-developer */
+/**
+ * Which provider AUGMENTATIONS this application admits (#1672): `baseRef` → the packages allowed to add
+ * operations to that provider.
+ *
+ * ```ts
+ * providers: {
+ *   scopes: { backend: { providers: { 'acme-crm': { protocols: ['REST_API'] } } } },
+ *   augmentations: { 'acme-crm': ['@acme/provider-crm-chat'] },
+ * }
+ * ```
+ *
+ * The base provider must declare a `REST_API` binding, and the package must be one discovery walks: a
+ * framework provider package, a provider package in the application's own scope
+ * (`<application-scope>/provider-*`), or a package listed in `providers.packages`.
+ *
+ * ## Why an augmentation needs an opt-in at all
+ *
+ * An augmentation adds operations to a provider it does not own, and those operations run with the BASE
+ * provider's credential — for a delegated connection, a person's own grant. Admitting one is therefore a
+ * trust decision about third-party code spending a grant, of the same kind as `connections`, and it is the
+ * application's to make. Installing a package decides nothing: a package that is a dependency and is not
+ * named here contributes no operation. That is also what keeps a provider package that augments many
+ * engine-owned refs (`stripe`, `openai`…) inert until an application asks for one of them.
+ *
+ * ## Why application-level rather than per runtime scope
+ *
+ * An augmented provider has ONE operation catalogue per grant, whichever runtime spends it. Opting a package
+ * in for the backend and not for a minion would give one grant two operation sets, and an operation id
+ * would mean a request in one process and nothing in another. The augmentation applies wherever the base
+ * provider is scoped.
+ *
+ * `wildo config sync` refuses a package it did not discover, a package that does not augment this ref, a
+ * ref no scope declares, a base with no REST binding, and two opted-in packages sharing an operation id.
+ *
+ * Absent means none — never "every installed augmentation".
+ */
+export const ProviderAugmentationOptInsSchema = z.record(z.string().min(1), z.array(z.string().min(1)).min(1).superRefine((packageNames, ctx) => {
+    const seen = new Set();
+    for (const [index, packageName] of packageNames.entries()) {
+        if (seen.has(packageName)) {
+            ctx.addIssue({ code: 'custom', path: [index], message: `"${packageName}" is opted in twice for one provider.` });
+        }
+        seen.add(packageName);
+    }
+}));
+/** @wildo_source:part:end saas.config.providers.augmentations */
+//# sourceMappingURL=provider-augmentation-opt-ins.shared.schemas.js.map

package/dist/esm/external-providers/provider-augmentation-opt-ins.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-augmentation-opt-ins.shared.schemas.js","sourceRoot":"","sources":["../../../src/external-providers/provider-augmentation-opt-ins.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gJAAgJ;AAChJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CACtD,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EACjB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,YAAY,EAAE,GAAG,EAAE,EAAE;IAClE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1D,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1B,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,WAAW,uCAAuC,EAAE,CAAC,CAAC;QACnH,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACxB,CAAC;AACH,CAAC,CAAC,CACH,CAAC;AAEF,iEAAiE","sourcesContent":["import { z } from 'zod';\n\n/** @wildo_source:part:start saas.config.providers.augmentations facet:layer:shared facet:family:provider-config facet:audience:app-developer */\n/**\n * Which provider AUGMENTATIONS this application admits (#1672): `baseRef` → the packages allowed to add\n * operations to that provider.\n *\n * ```ts\n * providers: {\n *   scopes: { backend: { providers: { 'acme-crm': { protocols: ['REST_API'] } } } },\n *   augmentations: { 'acme-crm': ['@acme/provider-crm-chat'] },\n * }\n * ```\n *\n * The base provider must declare a `REST_API` binding, and the package must be one discovery walks: a\n * framework provider package, a provider package in the application's own scope\n * (`<application-scope>/provider-*`), or a package listed in `providers.packages`.\n *\n * ## Why an augmentation needs an opt-in at all\n *\n * An augmentation adds operations to a provider it does not own, and those operations run with the BASE\n * provider's credential — for a delegated connection, a person's own grant. Admitting one is therefore a\n * trust decision about third-party code spending a grant, of the same kind as `connections`, and it is the\n * application's to make. Installing a package decides nothing: a package that is a dependency and is not\n * named here contributes no operation. That is also what keeps a provider package that augments many\n * engine-owned refs (`stripe`, `openai`…) inert until an application asks for one of them.\n *\n * ## Why application-level rather than per runtime scope\n *\n * An augmented provider has ONE operation catalogue per grant, whichever runtime spends it. Opting a package\n * in for the backend and not for a minion would give one grant two operation sets, and an operation id\n * would mean a request in one process and nothing in another. The augmentation applies wherever the base\n * provider is scoped.\n *\n * `wildo config sync` refuses a package it did not discover, a package that does not augment this ref, a\n * ref no scope declares, a base with no REST binding, and two opted-in packages sharing an operation id.\n *\n * Absent means none — never \"every installed augmentation\".\n */\nexport const ProviderAugmentationOptInsSchema = z.record(\n  z.string().min(1),\n  z.array(z.string().min(1)).min(1).superRefine((packageNames, ctx) => {\n    const seen = new Set<string>();\n    for (const [index, packageName] of packageNames.entries()) {\n      if (seen.has(packageName)) {\n        ctx.addIssue({ code: 'custom', path: [index], message: `\"${packageName}\" is opted in twice for one provider.` });\n      }\n      seen.add(packageName);\n    }\n  }),\n);\nexport type ProviderAugmentationOptIns = z.infer<typeof ProviderAugmentationOptInsSchema>;\n/** @wildo_source:part:end saas.config.providers.augmentations */\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"provider-authentication-assurance.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-authentication-assurance.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yFAAyF;AACzF,oBAAY,4BAA4B;IACtC,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,mGAAmG;AACnG,oBAAY,yBAAyB;IACnC,YAAY,iBAAiB;IAC7B,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AACD,oBAAY,uBAAuB;IACjC,mBAAmB,wBAAwB;IAC3C,qBAAqB,0BAA0B;IAC/C,WAAW,gBAAgB;IAC3B,gBAAgB,qBAAqB;IACrC,qBAAqB,0BAA0B;IAC/C,2BAA2B,gCAAgC;CAC5D;AAED,oFAAoF;AACpF,eAAO,MAAM,iCAAiC;;;;iBAI5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC"}
+{"version":3,"file":"provider-authentication-assurance.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/external-providers/provider-authentication-assurance.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yFAAyF;AACzF,oBAAY,4BAA4B;IACtC,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,mGAAmG;AACnG,oBAAY,yBAAyB;IACnC,YAAY,iBAAiB;IAC7B,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AACD,oBAAY,uBAAuB;IACjC,mBAAmB,wBAAwB;IAC3C,qBAAqB,0BAA0B;IAC/C,WAAW,gBAAgB;IAC3B,gBAAgB,qBAAqB;IACrC,qBAAqB,0BAA0B;IAC/C,2BAA2B,gCAAgC;CAC5D;AAED,oFAAoF;AACpF,eAAO,MAAM,iCAAiC;;;;iBAI5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"provider-authentication-assurance.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-authentication-assurance.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yFAAyF;AACzF,MAAM,CAAN,IAAY,4BAGX;AAHD,WAAY,4BAA4B;IACtC,6CAAa,CAAA;IACb,iDAAiB,CAAA;AACnB,CAAC,EAHW,4BAA4B,KAA5B,4BAA4B,QAGvC;AAED,mGAAmG;AACnG,MAAM,CAAN,IAAY,yBAMX;AAND,WAAY,yBAAyB;IACnC,0DAA6B,CAAA;IAC7B,oDAAuB,CAAA;IACvB,0DAA6B,CAAA;IAC7B,8CAAiB,CAAA;IACjB,gDAAmB,CAAA;AACrB,CAAC,EANW,yBAAyB,KAAzB,yBAAyB,QAMpC;AACD,MAAM,CAAN,IAAY,uBAOX;AAPD,WAAY,uBAAuB;IACjC,sEAA2C,CAAA;IAC3C,0EAA+C,CAAA;IAC/C,sDAA2B,CAAA;IAC3B,gEAAqC,CAAA;IACrC,0EAA+C,CAAA;IAC/C,sFAA2D,CAAA;AAC7D,CAAC,EAPW,uBAAuB,KAAvB,uBAAuB,QAOlC;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC;IACxD,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC;IAC3C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC;IACvC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,4BAA4B,CAAC;CAClD,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\n\n/** Policy for an otherwise valid external login that cannot demonstrate required MFA. */\nexport enum ExternalAssuranceEnforcement {\n  WARN = 'warn',\n  STRICT = 'strict',\n}\n\n/** Do not collapse contractual delegation, measured MFA and warning admission into one boolean. */\nexport enum ExternalAssuranceDecision {\n  NOT_REQUIRED = 'not_required',\n  DELEGATED = 'delegated',\n  VERIFIED_MFA = 'verified_mfa',\n  WARNED = 'warned',\n  REFUSED = 'refused',\n}\nexport enum ExternalAssuranceReason {\n  POLICY_NOT_REQUIRED = 'policy_not_required',\n  ENTERPRISE_DELEGATION = 'enterprise_delegation',\n  SESSION_MFA = 'session_mfa',\n  EVIDENCE_MISSING = 'evidence_missing',\n  EVIDENCE_INSUFFICIENT = 'evidence_insufficient',\n  METHOD_REQUIREMENT_UNPROVEN = 'method_requirement_unproven',\n}\n\n/** Safe decision summary: no upstream token, raw claims, nonce, or user profile. */\nexport const ExternalAssuranceAssessmentSchema = z.object({\n  decision: z.enum(ExternalAssuranceDecision),\n  reason: z.enum(ExternalAssuranceReason),\n  enforcement: z.enum(ExternalAssuranceEnforcement),\n});\nexport type ExternalAssuranceAssessment = z.infer<typeof ExternalAssuranceAssessmentSchema>;\n"]}
+{"version":3,"file":"provider-authentication-assurance.shared.schemas.js","sourceRoot":"","sources":["../../../src/external-providers/provider-authentication-assurance.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yFAAyF;AACzF,MAAM,CAAN,IAAY,4BAGX;AAHD,WAAY,4BAA4B;IACtC,6CAAa,CAAA;IACb,iDAAiB,CAAA;AACnB,CAAC,EAHW,4BAA4B,KAA5B,4BAA4B,QAGvC;AAED,mGAAmG;AACnG,MAAM,CAAN,IAAY,yBAMX;AAND,WAAY,yBAAyB;IACnC,0DAA6B,CAAA;IAC7B,oDAAuB,CAAA;IACvB,0DAA6B,CAAA;IAC7B,8CAAiB,CAAA;IACjB,gDAAmB,CAAA;AACrB,CAAC,EANW,yBAAyB,KAAzB,yBAAyB,QAMpC;AACD,MAAM,CAAN,IAAY,uBAOX;AAPD,WAAY,uBAAuB;IACjC,sEAA2C,CAAA;IAC3C,0EAA+C,CAAA;IAC/C,sDAA2B,CAAA;IAC3B,gEAAqC,CAAA;IACrC,0EAA+C,CAAA;IAC/C,sFAA2D,CAAA;AAC7D,CAAC,EAPW,uBAAuB,KAAvB,uBAAuB,QAOlC;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC;IACxD,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC;IAC3C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC;IACvC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,4BAA4B,CAAC;CAClD,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\n\n/** Policy for an otherwise valid external login that cannot demonstrate required MFA. */\nexport enum ExternalAssuranceEnforcement {\n  WARN = 'warn',\n  STRICT = 'strict',\n}\n\n/** Do not collapse contractual delegation, measured MFA and warning admission into one boolean. */\nexport enum ExternalAssuranceDecision {\n  NOT_REQUIRED = 'not_required',\n  DELEGATED = 'delegated',\n  VERIFIED_MFA = 'verified_mfa',\n  WARNED = 'warned',\n  REFUSED = 'refused',\n}\nexport enum ExternalAssuranceReason {\n  POLICY_NOT_REQUIRED = 'policy_not_required',\n  ENTERPRISE_DELEGATION = 'enterprise_delegation',\n  SESSION_MFA = 'session_mfa',\n  EVIDENCE_MISSING = 'evidence_missing',\n  EVIDENCE_INSUFFICIENT = 'evidence_insufficient',\n  METHOD_REQUIREMENT_UNPROVEN = 'method_requirement_unproven',\n}\n\n/** Safe decision summary: no upstream token, raw claims, nonce, or user profile. */\nexport const ExternalAssuranceAssessmentSchema = z.object({\n  decision: z.enum(ExternalAssuranceDecision),\n  reason: z.enum(ExternalAssuranceReason),\n  enforcement: z.enum(ExternalAssuranceEnforcement),\n});\nexport type ExternalAssuranceAssessment = z.infer<typeof ExternalAssuranceAssessmentSchema>;\n"]}

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

@@ -29,6 +29,7 @@
  */
 import { ExternalProvider_Connection_OwnerScope } from '@wildo-ai/external-connectors-models';
 import { z } from 'zod';
+import { type RateLimitConfiguration } from '../requests/rate-limits.shared.schemas';
 /** @wildo_source:part:start saas.models.providers.browser-operation-policy facet:layer:shared facet:family:config facet:audience:app-developer */
 /**
  * One browser-reachable operation.
@@ -59,6 +60,19 @@ import { z } from 'zod';
  * 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 declare const ProviderBrowserOperationPolicySchema: z.ZodObject<{
     connections: z.ZodArray<z.ZodObject<{
@@ -66,8 +80,38 @@ export declare const ProviderBrowserOperationPolicySchema: z.ZodObject<{
         delegation: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ExternalProvider_Connection_DelegationMode>>;
     }, z.core.$strip>>;
     allowedRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    callerRateLimit: z.ZodOptional<z.ZodObject<{
+        requestsPerMinute: z.ZodOptional<z.ZodNumber>;
+        requestsPerHour: z.ZodOptional<z.ZodNumber>;
+        requestsPerDay: z.ZodOptional<z.ZodNumber>;
+        customWindows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            requestsPerWindow: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strict>;
 export type ProviderBrowserOperationPolicy = z.infer<typeof ProviderBrowserOperationPolicySchema>;
+/**
+ * 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 declare const DEFAULT_PROVIDER_BROWSER_OPERATION_CALLER_RATE_LIMIT: RateLimitConfiguration;
+/** Where the limit a browser-triggered call is counted against came from — and so how an outage of the limiter is treated. */
+export declare enum ProviderBrowserOperationCallerRateLimitSource {
+    /** Declared on the policy: fails CLOSED on a limiter outage. */
+    DECLARED = "DECLARED",
+    /** The framework default: fails OPEN on a limiter outage. */
+    FRAMEWORK_DEFAULT = "FRAMEWORK_DEFAULT"
+}
+/** The one reading of a policy's per-person limit: its own, or the framework default, and which. */
+export declare function resolveProviderBrowserOperationCallerRateLimit(policy: Pick<ProviderBrowserOperationPolicy, 'callerRateLimit'>): {
+    readonly limit: RateLimitConfiguration;
+    readonly source: ProviderBrowserOperationCallerRateLimitSource;
+};
 /**
  * `providerRef` → `operationId` → policy. The operation id is the catalogue's own, exactly as a typed
  * client or an ETL binding reference names it.
@@ -80,6 +124,15 @@ export declare const ProviderBrowserOperationPoliciesSchema: z.ZodDefault<z.ZodR
         delegation: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ExternalProvider_Connection_DelegationMode>>;
     }, z.core.$strip>>;
     allowedRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    callerRateLimit: z.ZodOptional<z.ZodObject<{
+        requestsPerMinute: z.ZodOptional<z.ZodNumber>;
+        requestsPerHour: z.ZodOptional<z.ZodNumber>;
+        requestsPerDay: z.ZodOptional<z.ZodNumber>;
+        customWindows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            requestsPerWindow: z.ZodNumber;
+            windowSeconds: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strict>>>>;
 export type ProviderBrowserOperationPolicies = z.infer<typeof ProviderBrowserOperationPoliciesSchema>;
 /** @wildo_source:part:end saas.models.providers.browser-operation-policy */

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

@@ -1 +1 @@
-{"version":3,"file":"provider-browser-operations.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-browser-operations.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACL,sCAAsC,EAEvC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,kJAAkJ;AAClJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,oCAAoC;;;;;;kBAgB/C,CAAC;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAElG;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC;;;;;;qBAG9B,CAAC;AACtB,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sCAAsC,CAAC,CAAC;AACtG,4EAA4E"}
+{"version":3,"file":"provider-browser-operations.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/external-providers/provider-browser-operations.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACL,sCAAsC,EAEvC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAgC,KAAK,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAEnH,kJAAkJ;AAClJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;kBAiC/C,CAAC;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAElG;;;;;;;GAOG;AACH,eAAO,MAAM,oDAAoD,EAAE,sBAGjE,CAAC;AAEH,8HAA8H;AAC9H,oBAAY,6CAA6C;IACvD,gEAAgE;IAChE,QAAQ,aAAa;IACrB,6DAA6D;IAC7D,iBAAiB,sBAAsB;CACxC;AAED,oGAAoG;AACpG,wBAAgB,8CAA8C,CAAC,MAAM,EAAE,IAAI,CAAC,8BAA8B,EAAE,iBAAiB,CAAC,GAAG;IAC/H,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,6CAA6C,CAAC;CAChE,CAIA;AAED;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;qBAG9B,CAAC;AACtB,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sCAAsC,CAAC,CAAC;AACtG,4EAA4E"}

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

@@ -29,6 +29,7 @@
  */
 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.
@@ -59,12 +60,41 @@ import { z } from 'zod';
  * 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',
@@ -74,6 +104,32 @@ export const ProviderBrowserOperationPolicySchema = z.strictObject({
         });
     }
 });
+/**
+ * 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.

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

@@ -1 +1 @@
-{"version":3,"file":"provider-browser-operations.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-browser-operations.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACL,sCAAsC,EACtC,sCAAsC,GACvC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,kJAAkJ;AAClJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC,YAAY,CAAC;IACjE,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACnE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAClE,CAAC,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;IAC7B,MAAM,wBAAwB,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CACtD,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,KAAK,sCAAsC,CAAC,WAAW,CACnF,CAAC;IACF,IAAI,wBAAwB,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAClE,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,cAAc,CAAC;YACtB,OAAO,EACL,6GAA6G;kBAC3G,sFAAsF;SAC3F,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAGH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,CAAC,CAAC,MAAM,CAC5D,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EACjB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,oCAAoC,CAAC,CAClE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEtB,4EAA4E","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';\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 */\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}).superRefine((policy, ctx) => {\n  const admitsApplicationAccount = policy.connections.some(\n    (shape) => shape.ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION,\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 * `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"]}
+{"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

@@ -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

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;;;;;GAKG;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"}