@jini-ai/core 0.4.8 → 0.6.10

package/dist/origin-validation.js

@@ -26,18 +26,23 @@ function splitAllowedOriginsEnv(config, env) {
         .map((origin) => origin.trim())
         .filter(Boolean);
 }
-/** Normalizes one entry to a protocol://host origin; invalid or non-HTTP(S) entries are rejected. */
-function parseAllowedOrigin(entry) {
+/** Parses `value` as a URL, or `undefined` when it is unparseable or not HTTP(S). Shared by
+ * allow-list parsing and the Origin check so both agree on what counts as a web origin. */
+function parseHttpUrl(value) {
     let parsed;
     try {
-        parsed = new URL(entry);
+        parsed = new URL(value);
     }
     catch {
         return undefined;
     }
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
         return undefined;
-    return parsed.origin;
+    return parsed;
+}
+/** Normalizes one entry to a protocol://host origin; invalid or non-HTTP(S) entries are rejected. */
+function parseAllowedOrigin(entry) {
+    return parseHttpUrl(entry)?.origin;
 }
 /**
  * Parses {@link OriginValidationEnvConfig.allowedOriginsEnvVar} into normalized origins.
@@ -93,6 +98,8 @@ export function allowedBrowserPorts({ config, port, env }) {
         ports.push(webPort);
     return ports;
 }
+/** The loopback spellings a locally-served page's Host or Origin can carry. */
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '[::1]'];
 function headerValue(value) {
     if (Array.isArray(value)) {
         const first = value[0];
@@ -113,20 +120,28 @@ export function parseHostHeader({ value }) {
         return null;
     }
 }
+/** Parses an exact dotted-quad (four all-digit parts, each 0-255) into octets, else `undefined`.
+ * Shared by the private-range and IP-literal checks so both agree on what an IPv4 literal is.
+ * `/^\d+$/` admits only non-negative integers, so the octet range check needs only an upper bound. */
+function parseDottedQuad(host) {
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return undefined;
+    if (!parts.every((part) => /^\d+$/.test(part)))
+        return undefined;
+    const octets = parts.map(Number);
+    return octets.every((n) => n <= 255) ? octets : undefined;
+}
+/** RFC 1918 (10/8, 172.16/12, 192.168/16) or link-local (169.254/16), from the first two octets. */
+function isPrivateIpv4Prefix([a, b]) {
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+}
 /** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16).
  * Implements the dev-browser LAN allow-list, not SSRF blocking. Use @jini-ai/platform/net
  * for SSRF address classification; private addresses are allowed here for local development. */
 export function isPrivateIpv4({ hostname }) {
-    const parts = String(hostname || '').split('.');
-    if (parts.length !== 4)
-        return false;
-    if (!parts.every((part) => /^\d+$/.test(part)))
-        return false;
-    const octets = parts.map((part) => Number(part));
-    if (!octets.every((n) => Number.isInteger(n) && n >= 0 && n <= 255))
-        return false;
-    const [a, b] = octets;
-    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    const octets = parseDottedQuad(String(hostname || ''));
+    return octets !== undefined && isPrivateIpv4Prefix(octets);
 }
 /** Whether `hostname` is a literal IPv4 address or bracketed IPv6 literal (as opposed to a DNS name). */
 export function isIpLiteralHostname({ hostname }) {
@@ -135,12 +150,7 @@ export function isIpLiteralHostname({ hostname }) {
         return false;
     if (host.startsWith('[') && host.endsWith(']'))
         return true;
-    const parts = host.split('.');
-    if (parts.length !== 4)
-        return false;
-    if (!parts.every((part) => /^\d+$/.test(part)))
-        return false;
-    return parts.map(Number).every((n) => Number.isInteger(n) && n >= 0 && n <= 255);
+    return parseDottedQuad(host) !== undefined;
 }
 /** Whether `hostname` is loopback, unspecified, or a private-LAN address.
  * Implements the dev-browser LAN allow-list, not SSRF blocking (@jini-ai/platform/net). */
@@ -159,9 +169,8 @@ export function isAllowedBrowserHost({ hostHeader, ports, bindHost, extraAllowed
     const requestHost = parseHostHeader({ value: hostHeader });
     if (!requestHost)
         return false;
-    const loopbackHosts = ['127.0.0.1', 'localhost', '[::1]'];
     const explicitHosts = new Set([
-        ...ports.flatMap((p) => [...loopbackHosts.map((h) => `${h}:${p}`), `${bindHost}:${p}`]),
+        ...ports.flatMap((p) => [...LOOPBACK_HOSTS.map((h) => `${h}:${p}`), `${bindHost}:${p}`]),
         ...configuredAllowedHosts({ origins: extraAllowedOrigins }),
     ]);
     if (explicitHosts.has(requestHost.host))
@@ -170,37 +179,51 @@ export function isAllowedBrowserHost({ hostHeader, ports, bindHost, extraAllowed
         return false;
     return isLoopbackOrPrivateLanHost({ hostname: requestHost.hostname });
 }
+/** Every `scheme://host:port` origin a locally-served page can have: loopback spellings and the bind host, over both schemes. */
+function explicitLocalOrigins(ports, bindHost) {
+    const hosts = [...LOOPBACK_HOSTS, bindHost];
+    return new Set(ports.flatMap((p) => ['http', 'https'].flatMap((s) => hosts.map((h) => `${s}://${h}:${p}`))));
+}
+/** The URL's port, or its scheme's default when the URL omits it (only http/https reach here). */
+function effectivePort(url) {
+    return url.port || (url.protocol === 'https:' ? '443' : '80');
+}
 /** Whether an `Origin` header value names a locally-served or explicitly allow-listed origin. */
 export function isAllowedBrowserOrigin({ origin, hostHeader, ports, bindHost, extraAllowedOrigins }) {
-    if (extraAllowedOrigins.includes(String(origin)))
+    const originText = String(origin);
+    if (extraAllowedOrigins.includes(originText))
         return true;
-    let parsedOrigin;
-    try {
-        parsedOrigin = new URL(String(origin));
-    }
-    catch {
-        return false;
-    }
-    if (parsedOrigin.protocol !== 'http:' && parsedOrigin.protocol !== 'https:')
+    const parsedOrigin = parseHttpUrl(originText);
+    if (!parsedOrigin)
         return false;
     const requestHost = parseHostHeader({ value: hostHeader });
     if (!requestHost)
         return false;
-    const schemes = ['http', 'https'];
-    const loopbackHosts = ['127.0.0.1', 'localhost', '[::1]'];
-    const explicitOrigins = new Set(ports.flatMap((p) => [
-        ...schemes.flatMap((s) => loopbackHosts.map((h) => `${s}://${h}:${p}`)),
-        ...schemes.map((s) => `${s}://${bindHost}:${p}`),
-    ]));
-    if (explicitOrigins.has(String(origin)))
+    if (explicitLocalOrigins(ports, bindHost).has(originText))
         return true;
-    const originPort = parsedOrigin.port || (parsedOrigin.protocol === 'https:' ? '443' : '80');
-    if (!ports.map(String).includes(originPort))
+    if (!ports.map(String).includes(effectivePort(parsedOrigin)))
         return false;
     if (parsedOrigin.hostname !== requestHost.hostname)
         return false;
     return isLoopbackOrPrivateLanHost({ hostname: parsedOrigin.hostname });
 }
+/** The decision for a request carrying no `Origin` header (as a same-origin GET subresource does). */
+function isAllowedWithoutOrigin({ req, hostArgs, extraAllowedOrigins }) {
+    const ipOnlyExtraOrigins = extraAllowedOrigins.filter((o) => isIpLiteralHostname({ hostname: new URL(o).hostname }));
+    if (isAllowedBrowserHost({ ...hostArgs, extraAllowedOrigins: ipOnlyExtraOrigins }))
+        return true;
+    // Browsers (Firefox, Chrome) omit Origin on same-origin GET subresource
+    // requests per the Fetch spec, which makes hostname entries in the
+    // allow-list unreachable for legitimate same-origin GETs through a
+    // reverse proxy. Sec-Fetch-Site is set by the user agent and cannot be
+    // modified by JavaScript, so a value of "same-origin" attests that the
+    // request originated from the same origin as the target — a cross-site
+    // `<img>`/`<script>` exploit would carry "cross-site" instead. Only
+    // consult the broader allow-list once that signal is present.
+    if (headerValue(req.headers?.['sec-fetch-site']) !== 'same-origin')
+        return false;
+    return isAllowedBrowserHost({ ...hostArgs, extraAllowedOrigins });
+}
 /**
  * The top-level same-origin gate: is `req` a request the daemon should treat
  * as coming from one of its own locally-served (or explicitly allow-listed)
@@ -212,24 +235,8 @@ export function isLocalSameOrigin({ config, req, port, env }, { logger } = {}) {
     const ports = allowedBrowserPorts({ config, port, env });
     const bindHost = env[config.bindHostEnvVar] || '127.0.0.1';
     const extraAllowedOrigins = configuredAllowedOrigins({ config, env }, { logger });
-    const ipOnlyExtraOrigins = extraAllowedOrigins.filter((o) => isIpLiteralHostname({ hostname: new URL(o).hostname }));
-    const localHostAllowed = isAllowedBrowserHost({ config, hostHeader: host, ports, bindHost, extraAllowedOrigins: ipOnlyExtraOrigins });
     if (origin == null || origin === '') {
-        if (localHostAllowed)
-            return true;
-        // Browsers (Firefox, Chrome) omit Origin on same-origin GET subresource
-        // requests per the Fetch spec, which makes hostname entries in the
-        // allow-list unreachable for legitimate same-origin GETs through a
-        // reverse proxy. Sec-Fetch-Site is set by the user agent and cannot be
-        // modified by JavaScript, so a value of "same-origin" attests that the
-        // request originated from the same origin as the target — a cross-site
-        // `<img>`/`<script>` exploit would carry "cross-site" instead. Only
-        // consult the broader allow-list once that signal is present.
-        const fetchSite = headerValue(req.headers?.['sec-fetch-site']);
-        if (fetchSite === 'same-origin') {
-            return isAllowedBrowserHost({ config, hostHeader: host, ports, bindHost, extraAllowedOrigins });
-        }
-        return false;
+        return isAllowedWithoutOrigin({ req, hostArgs: { config, hostHeader: host, ports, bindHost }, extraAllowedOrigins });
     }
     // Reverse-proxy deployments terminate the browser connection at the proxy
     // and open a fresh upstream connection to the daemon. The Host header the

package/dist/primitives/http.d.ts

@@ -5,8 +5,8 @@ export type HttpRequest = {
     method: "POST" | "GET" | "HEAD" | "PUT" | "PATCH" | "DELETE";
     url: string;
     headers: Readonly<Record<string, string>>;
-    /** Preserve the signed bytes: re-serialization between signing and sending changes the signature. */
-    body?: string;
+    /** Preserve signed text and raw binary uploads without base64 expansion or UTF-8 corruption. */
+    body?: string | Uint8Array;
     /** Whole-operation deadline, including DNS, redirects and body reads. Off by default.
      * Retry/backoff belongs to the caller; its deadline can cover the whole retry operation. */
     totalDeadlineMs?: number;

package/dist/primitives/index.d.ts

@@ -7,4 +7,5 @@ export type { DecodedSseEvent, DecodedSseFrame, SseFramingOptions } from './sse.
 export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';
+export * from './tasks.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/primitives/index.js

@@ -6,4 +6,5 @@ export { decodeSseFrames, decodeSseStream, parseSseRecord } from './sse.js';
 export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';
+export * from './tasks.js';
 //# sourceMappingURL=index.js.map

package/dist/primitives/paths.js

@@ -1,13 +1,11 @@
-/** Pure lexical normalization of an already absolute path; no cwd, filesystem or symlink access. */
-function normalizeAbsolutePath(value, separator) {
-    const path = separator === '\\' ? value.replace(/\\/g, '/') : value;
-    const drive = separator === '\\' ? /^[A-Za-z]:\//.exec(path)?.[0] : undefined;
-    const unc = separator === '\\' ? /^\/\/[^/]+\/[^/]+(?:\/|$)/.exec(path)?.[0] : undefined;
-    const prefix = drive ?? unc ?? (path.startsWith('/') ? '/' : undefined);
-    if (!prefix)
-        throw new RangeError('pathContains requires resolved absolute paths');
+/** Root of an already `/`-separated Windows path: a drive root (`C:/`) or a UNC share root. */
+function windowsRoot(path) {
+    return /^[A-Za-z]:\//.exec(path)?.[0] ?? /^\/\/[^/]+\/[^/]+(?:\/|$)/.exec(path)?.[0];
+}
+/** Lexically resolve `.` and `..` segments; `..` never climbs above the root. */
+function resolveSegments(rest) {
     const segments = [];
-    for (const segment of path.slice(prefix.length).split('/')) {
+    for (const segment of rest.split('/')) {
         if (!segment || segment === '.')
             continue;
         if (segment === '..')
@@ -15,7 +13,16 @@ function normalizeAbsolutePath(value, separator) {
         else
             segments.push(segment);
     }
-    return prefix.replace(/\/+$/, '') + '/' + segments.join('/');
+    return segments;
+}
+/** Pure lexical normalization of an already absolute path; no cwd, filesystem or symlink access. */
+function normalizeAbsolutePath(value, separator) {
+    const windows = separator === '\\';
+    const path = windows ? value.replace(/\\/g, '/') : value;
+    const prefix = (windows ? windowsRoot(path) : undefined) ?? (path.startsWith('/') ? '/' : undefined);
+    if (!prefix)
+        throw new RangeError('pathContains requires resolved absolute paths');
+    return prefix.replace(/\/+$/, '') + '/' + resolveSegments(path.slice(prefix.length)).join('/');
 }
 /**
  * Check lexical containment using whole directory segments, including equality.

package/dist/primitives/tasks.d.ts

@@ -0,0 +1,10 @@
+/** Append work to a fulfilled serial tail and report failures without rejecting the next tail.
+ * The observer owns failure policy and must not throw. Callers retain the returned tail to drain.
+ * @complexity O(1) scheduling time and space per task, excluding task work.
+ */
+export declare function appendSerialTask({ previous, task, onError }: {
+    previous: Promise<void>;
+    task: () => Promise<unknown>;
+    onError: (error: unknown) => void;
+}, _optional?: Record<string, never>): Promise<void>;
+//# sourceMappingURL=tasks.d.ts.map

package/dist/primitives/tasks.js

@@ -0,0 +1,8 @@
+/** Append work to a fulfilled serial tail and report failures without rejecting the next tail.
+ * The observer owns failure policy and must not throw. Callers retain the returned tail to drain.
+ * @complexity O(1) scheduling time and space per task, excluding task work.
+ */
+export function appendSerialTask({ previous, task, onError }, _optional = {}) {
+    return previous.then(task).then(() => undefined, onError);
+}
+//# sourceMappingURL=tasks.js.map

package/dist/provider-catalog.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Neutral catalog contracts consumed by UI and implemented by host adapters.
+ * Vendor identities, aliases and endpoint defaults belong to integrations.
+ */
+/** UI catalog identity policy. Operations are pure, synchronous and must agree on IDs.
+ * Normalization returns a new map, preserves values, and resolves alias collisions
+ * deterministically. The host keeps one policy for the lifetime of a mounted tab.
+ *
+ * @example
+ * MediaProvidersTab({ port, catalog, catalogPolicy: mediaProviderCatalogPolicy });
+ */
+export interface MediaProviderCatalogPolicy {
+    /** Canonicalize catalog entries, pinned IDs, edits and clears; preserve unknown IDs. */
+    canonicalMediaProviderId(input: {
+        id: string;
+    }, options?: Record<string, never>): string;
+    /** Normalize initial state and daemon replies before reconciliation. Canonical entries win aliases. */
+    normalizeMediaProviderMap<T>(input: {
+        providers: Readonly<Record<string, T>>;
+    }, options?: Record<string, never>): Record<string, T>;
+}
+/**
+ * One selectable provider in the host-supplied catalog.
+ */
+export interface MediaProviderOption {
+    id: string;
+    label: string;
+    /** Prefilled when the operator picks this provider and typed nothing. */
+    defaultBaseUrl?: string;
+    /** Model ids this provider advertises. A host that discovers models at
+     *  runtime can leave this empty. */
+    models?: readonly string[];
+}
+/** Whether a preset appears in the protocol or gateway chip row. */
+export type ProviderPresetKind = 'protocol' | 'gateway';
+/** One host-supplied endpoint preset, parameterized by the consumer's wire protocols. */
+export interface ProviderPreset<Protocol extends string = string> {
+    id: string;
+    title: string;
+    protocol: Protocol;
+    baseUrl: string;
+    /** Ranked suggestions shown in the model field. Never authoritative — a
+     *  host with live model discovery should pass `ExecutionPort.listModels`. */
+    preferredModels: readonly string[];
+    kind?: ProviderPresetKind;
+    /** Fixed-origin gateways resolve their base URL themselves, so the Base URL
+     *  field is hidden rather than shown-and-ignored (origin: `isFixedOriginGateway`). */
+    fixedOrigin?: boolean;
+    /** Some local/self-hosted endpoints need no bearer credential. Defaults to
+     *  `true` — i.e. an API key is required unless a preset opts out. */
+    requiresApiKey?: boolean;
+    /** Optional "Get key" deep link rendered beside the API-key field. */
+    apiKeyConsoleUrl?: string;
+    /**
+     * The literal prefix that positively identifies a pasted key as belonging to THIS provider —
+     * `'AIza'` for Google, `'sk-ant-'` for Anthropic. Omit it for a vendor whose keys carry no
+     * distinguishing prefix (Azure OpenAI's are bare hex) rather than inventing one.
+     *
+     * Read in exactly one direction: to recognise a key as SOMEONE ELSE'S. It is deliberately NOT an
+     * allowlist, and no code may ask "does the selected preset's key match this?" as a validity test.
+     * That is the shape this field replaced, and it shipped a false positive within hours of landing:
+     * a real Google Gemini key in a newer shape than `/^AIza/` was reported to its owner as not
+     * looking like a Google key. Vendors add key formats without telling anyone, so a catalog can
+     * prove a string belongs to vendor X, but never that it belongs to nobody. See
+     * `apiKeyFormatWarning`.
+     *
+     * Data rather than an `if (providerId === …)` chain in the rule, so adding a provider stays a row
+     * in the preset catalog — including for a host that supplies its own `presets` and never touches
+     * this package.
+     */
+    apiKeyPrefix?: string;
+    /** The synthetic "Custom" preset. Exactly one may carry this flag; it is
+     *  never treated as configured-by-preset and never hides the Base URL. */
+    custom?: boolean;
+}
+//# sourceMappingURL=provider-catalog.d.ts.map

package/dist/provider-catalog.js

@@ -0,0 +1,6 @@
+/**
+ * Neutral catalog contracts consumed by UI and implemented by host adapters.
+ * Vendor identities, aliases and endpoint defaults belong to integrations.
+ */
+export {};
+//# sourceMappingURL=provider-catalog.js.map

package/dist/provider-registry.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @file The one keyed provider registry every provider seam shares (FROZEN CONTRACT, 2026-10-21).
+ *
+ * Four registries with four shapes grew independently (media `VendorAdapterRegistry`, visitor-auth,
+ * `OAuthProviderRegistry`, commerce `createPaymentProviderRegistry`). This is the shape new seams use
+ * and the four migrate to; `docs/provider-registry.md` in this package records the contract and the
+ * migration path for each. Other builds depend on the exported names and semantics below: change
+ * them only additively.
+ *
+ * Error policy is split by origin. A core/built-in registration that is malformed or duplicated is a
+ * composition-root programming error, so it THROWS at boot (same class as commerce's registry). A
+ * plugin contribution is third-party input, so a broken or duplicate one is recorded in
+ * `refusals()` and never crashes boot (same policy as `createPluginContributionLoader`).
+ */
+/** Provider ids share the plugin-tool name grammar (agent-plugins lifecycle/tools/manifest.ts). */
+export declare const PROVIDER_ID_PATTERN: RegExp;
+export type ProviderOrigin = 'core' | 'plugin';
+/** One registered provider. Stored frozen; the `provider` value keeps its identity. */
+export interface ProviderDefinition<T> {
+    readonly id: string;
+    readonly provider: T;
+    readonly label?: string;
+}
+export interface RegisteredProvider<T> extends ProviderDefinition<T> {
+    readonly origin: ProviderOrigin;
+    /** Set only for `origin: 'plugin'`. */
+    readonly pluginId?: string;
+}
+export type ProviderRefusalCode = 'invalid_id' | 'invalid_provider' | 'duplicate' | 'contract_mismatch' | 'displaced_by_core';
+export interface ProviderRefusal {
+    readonly code: ProviderRefusalCode;
+    readonly pluginId: string;
+    readonly providerId: string;
+    readonly message: string;
+}
+export interface ProviderRegistry<T> {
+    readonly contract: string;
+    /** Core/built-in registration. @throws {ProviderRegistryError} on a bad id, invalid provider or duplicate. */
+    register(required: {
+        readonly definition: ProviderDefinition<T>;
+    }, _optional?: Record<string, never>): void;
+    /** Plugin registration. Never throws (a throwing validator or provider getter is an `invalid_provider`
+     * refusal); returns false and records a refusal instead. */
+    contribute(required: {
+        readonly definition: ProviderDefinition<T>;
+        readonly pluginId: string;
+        readonly contract?: string;
+    }, _optional?: Record<string, never>): boolean;
+    get(required: {
+        readonly id: string;
+    }, _optional?: Record<string, never>): RegisteredProvider<T> | undefined;
+    has(required: {
+        readonly id: string;
+    }, _optional?: Record<string, never>): boolean;
+    /** Frozen snapshot in registration order. */
+    list(_required?: Record<string, never>, _optional?: Record<string, never>): readonly RegisteredProvider<T>[];
+    /** The configured default provider, if one was named and is registered. */
+    getDefault(_required?: Record<string, never>, _optional?: Record<string, never>): RegisteredProvider<T> | undefined;
+    /** Frozen snapshot of every refused plugin contribution, in refusal order. */
+    refusals(_required?: Record<string, never>, _optional?: Record<string, never>): readonly ProviderRefusal[];
+}
+export declare class ProviderRegistryError extends Error {
+    readonly code: ProviderRefusalCode;
+    constructor(required: {
+        readonly code: ProviderRefusalCode;
+        readonly message: string;
+    });
+}
+/**
+ * Build an independent registry for one provider contract (e.g. `mail`, `dns`, `payments`).
+ * Core always wins an id: a core registration displaces an earlier plugin entry (recording a
+ * `displaced_by_core` refusal) so a plugin loaded first can never turn a later core registration
+ * into a boot crash.
+ * @param required.contract - Contract name used in messages and checked against contributions.
+ * @param optional.defaultProviderId - Validated eagerly; need not be registered yet.
+ * @param optional.validate - Contract-specific shape check; a string is the reason it is invalid.
+ * @param optional.seed - Core definitions registered in order (throwing policy).
+ * @throws {ProviderRegistryError} When the default id or a seed definition is invalid.
+ * @complexity register/contribute/get/has O(1); list/refusals O(n) snapshot.
+ */
+export declare function createProviderRegistry<T>(required: {
+    readonly contract: string;
+}, optional?: {
+    readonly defaultProviderId?: string;
+    readonly validate?: (required: {
+        readonly provider: T;
+    }) => string | undefined;
+    readonly seed?: readonly ProviderDefinition<T>[];
+}): ProviderRegistry<T>;
+export type ProviderMode = 'test' | 'live';
+/** Who a provider call acts for. Credentials are pre-resolved by the host, never carried here. */
+export interface ProviderContext {
+    readonly workspaceId: string;
+    readonly siteId?: string;
+    /** The connected account at the provider (e.g. a Stripe account or a mail domain id). */
+    readonly providerAccountId?: string;
+    readonly mode: ProviderMode;
+}
+/** The provider definitively refused: nothing happened, the caller may correct and retry. */
+export type ProviderRejectedCode = 'invalid_request' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'rate_limited' | 'quota_exceeded' | 'unsupported' | 'not_configured' | 'provider_error';
+/** The outcome is indeterminate (it may have happened): the caller must reconcile, not blindly retry. */
+export type ProviderUnknownCode = 'timeout' | 'network' | 'provider_unavailable' | 'unexpected_response';
+export interface ProviderError<C extends string> {
+    readonly code: C;
+    /** Caller-safe: no credentials, tokens, or raw provider payloads. */
+    readonly message: string;
+    readonly retryAfterMs?: number;
+}
+export type ProviderResult<T> = {
+    readonly status: 'ok';
+    readonly value: T;
+} | {
+    readonly status: 'rejected';
+    readonly error: ProviderError<ProviderRejectedCode>;
+} | {
+    readonly status: 'unknown';
+    readonly error: ProviderError<ProviderUnknownCode>;
+};
+export declare function providerOk<T>(required: {
+    readonly value: T;
+}, _optional?: Record<string, never>): ProviderResult<T>;
+export declare function providerRejected<T = never>(required: ProviderError<ProviderRejectedCode>, _optional?: Record<string, never>): ProviderResult<T>;
+export declare function providerUnknown<T = never>(required: ProviderError<ProviderUnknownCode>, _optional?: Record<string, never>): ProviderResult<T>;
+export type DomainPurpose = 'mail' | 'site' | 'tls';
+export type DnsRecordType = 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX' | 'CAA' | 'NS' | 'SRV';
+export interface DomainRecordRequirement {
+    readonly type: DnsRecordType;
+    /** Fully-qualified record name, e.g. `send.example.com`. */
+    readonly name: string;
+    readonly value: string;
+    readonly ttl?: number;
+    /** MX / SRV priority. */
+    readonly priority?: number;
+    /** Operator-facing explanation, e.g. "DKIM signing key". */
+    readonly note?: string;
+}
+/** What one provider needs from a domain before it can serve `purpose` for it. */
+export interface DomainRequirement {
+    readonly purpose: DomainPurpose;
+    readonly domain: string;
+    readonly providerId: string;
+    readonly records: readonly DomainRecordRequirement[];
+}
+//# sourceMappingURL=provider-registry.d.ts.map

package/dist/provider-registry.js

@@ -0,0 +1,138 @@
+/**
+ * @file The one keyed provider registry every provider seam shares (FROZEN CONTRACT, 2026-10-21).
+ *
+ * Four registries with four shapes grew independently (media `VendorAdapterRegistry`, visitor-auth,
+ * `OAuthProviderRegistry`, commerce `createPaymentProviderRegistry`). This is the shape new seams use
+ * and the four migrate to; `docs/provider-registry.md` in this package records the contract and the
+ * migration path for each. Other builds depend on the exported names and semantics below: change
+ * them only additively.
+ *
+ * Error policy is split by origin. A core/built-in registration that is malformed or duplicated is a
+ * composition-root programming error, so it THROWS at boot (same class as commerce's registry). A
+ * plugin contribution is third-party input, so a broken or duplicate one is recorded in
+ * `refusals()` and never crashes boot (same policy as `createPluginContributionLoader`).
+ */
+/** Provider ids share the plugin-tool name grammar (agent-plugins lifecycle/tools/manifest.ts). */
+export const PROVIDER_ID_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+export class ProviderRegistryError extends Error {
+    code;
+    constructor(required) {
+        super(required.message);
+        this.name = 'ProviderRegistryError';
+        this.code = required.code;
+    }
+}
+/** @returns The first validation fault of a definition, or undefined when it may be registered. */
+function definitionFault(required, optional = {}) {
+    const { contract, definition } = required;
+    if (typeof definition.id !== 'string' || !PROVIDER_ID_PATTERN.test(definition.id)) {
+        return { code: 'invalid_id', message: `${contract} provider id '${String(definition.id)}' must match ${PROVIDER_ID_PATTERN.source}` };
+    }
+    const reason = optional.validate?.({ provider: definition.provider });
+    if (reason !== undefined)
+        return { code: 'invalid_provider', message: `${contract} provider '${definition.id}' is invalid: ${reason}` };
+    return undefined;
+}
+/** The id for a refusal line; a hostile definition whose id cannot even be read is recorded as ''. */
+function safeId(required, _optional = {}) {
+    try {
+        return String(required.definition.id);
+    }
+    catch {
+        return '';
+    }
+}
+function frozenEntry(required, optional = {}) {
+    const { id, provider, label } = required.definition;
+    return Object.freeze({
+        id, provider, origin: required.origin,
+        ...(label === undefined ? {} : { label }),
+        ...(optional.pluginId === undefined ? {} : { pluginId: optional.pluginId }),
+    });
+}
+/**
+ * Build an independent registry for one provider contract (e.g. `mail`, `dns`, `payments`).
+ * Core always wins an id: a core registration displaces an earlier plugin entry (recording a
+ * `displaced_by_core` refusal) so a plugin loaded first can never turn a later core registration
+ * into a boot crash.
+ * @param required.contract - Contract name used in messages and checked against contributions.
+ * @param optional.defaultProviderId - Validated eagerly; need not be registered yet.
+ * @param optional.validate - Contract-specific shape check; a string is the reason it is invalid.
+ * @param optional.seed - Core definitions registered in order (throwing policy).
+ * @throws {ProviderRegistryError} When the default id or a seed definition is invalid.
+ * @complexity register/contribute/get/has O(1); list/refusals O(n) snapshot.
+ */
+export function createProviderRegistry(required, optional = {}) {
+    const { contract } = required;
+    const { defaultProviderId, validate } = optional;
+    if (defaultProviderId !== undefined && !PROVIDER_ID_PATTERN.test(defaultProviderId)) {
+        throw new ProviderRegistryError({ code: 'invalid_id', message: `${contract} default provider id '${defaultProviderId}' must match ${PROVIDER_ID_PATTERN.source}` });
+    }
+    const providers = new Map();
+    const refused = [];
+    const refuse = (input) => {
+        refused.push(Object.freeze({ ...input.fault, pluginId: input.pluginId, providerId: input.providerId }));
+        return false;
+    };
+    const registry = {
+        contract,
+        register({ definition }) {
+            const fault = definitionFault({ contract, definition }, { ...(validate ? { validate } : {}) });
+            if (fault)
+                throw new ProviderRegistryError(fault);
+            const existing = providers.get(definition.id);
+            if (existing?.origin === 'core') {
+                throw new ProviderRegistryError({ code: 'duplicate', message: `${contract} provider '${definition.id}' is already registered` });
+            }
+            if (existing?.pluginId !== undefined) {
+                refuse({ fault: { code: 'displaced_by_core', message: `${contract} provider '${definition.id}' from plugin '${existing.pluginId}' was replaced by the built-in provider` }, pluginId: existing.pluginId, providerId: definition.id });
+                providers.delete(definition.id);
+            }
+            providers.set(definition.id, frozenEntry({ definition, origin: 'core' }));
+        },
+        contribute(input) {
+            // Third-party input: a throwing validator, id or provider getter is refused, never propagated
+            // (core registrations keep the throwing policy above).
+            try {
+                return contributeChecked(input);
+            }
+            catch {
+                return refuse({ fault: { code: 'invalid_provider', message: `${contract} provider from plugin '${input.pluginId}' was not loaded: its definition could not be validated` }, pluginId: input.pluginId, providerId: safeId({ definition: input.definition }) });
+            }
+        },
+        get({ id }) { return providers.get(id); },
+        has({ id }) { return providers.has(id); },
+        list() { return Object.freeze([...providers.values()]); },
+        getDefault() { return defaultProviderId === undefined ? undefined : providers.get(defaultProviderId); },
+        refusals() { return Object.freeze([...refused]); },
+    };
+    function contributeChecked({ definition, pluginId, contract: declared }) {
+        const providerId = String(definition.id);
+        if (declared !== undefined && declared !== contract) {
+            return refuse({ fault: { code: 'contract_mismatch', message: `plugin '${pluginId}' contributed provider '${providerId}' for contract '${declared}', not '${contract}'` }, pluginId, providerId });
+        }
+        const fault = definitionFault({ contract, definition }, { ...(validate ? { validate } : {}) });
+        if (fault)
+            return refuse({ fault, pluginId, providerId });
+        const existing = providers.get(providerId);
+        if (existing) {
+            const owner = existing.pluginId === undefined ? 'the built-in provider' : `plugin '${existing.pluginId}'`;
+            return refuse({ fault: { code: 'duplicate', message: `${contract} provider '${providerId}' from plugin '${pluginId}' was not loaded: already registered by ${owner}` }, pluginId, providerId });
+        }
+        providers.set(providerId, frozenEntry({ definition, origin: 'plugin' }, { pluginId }));
+        return true;
+    }
+    for (const definition of optional.seed ?? [])
+        registry.register({ definition });
+    return registry;
+}
+export function providerOk(required, _optional = {}) {
+    return { status: 'ok', value: required.value };
+}
+export function providerRejected(required, _optional = {}) {
+    return { status: 'rejected', error: { ...required } };
+}
+export function providerUnknown(required, _optional = {}) {
+    return { status: 'unknown', error: { ...required } };
+}
+//# sourceMappingURL=provider-registry.js.map