@skaile/forge-settings 1.3.3 → 2.0.0

package/src/runtime/server/provider-layers.ts

@@ -9,15 +9,15 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import {
-  type AIProviderRegistryPatch,
-  PROVIDERS_FILENAME,
-  saveProviderRegistryFile,
-} from "@skaile/workspaces/core";
-import { AI_PROVIDER_PRESETS, type AIProviderPreset } from "@skaile/workspaces/sdk/bridge";
+import type { AIProviderRegistryPatch } from "@skaile/provider-registry";
+import { AI_PROVIDER_PRESETS, type AIProviderPreset } from "@skaile/provider-registry/catalog";
+import { saveProviderRegistryFile } from "@skaile/provider-registry/files";
 import { parse as parseYaml } from "yaml";
 import { isPlainObject } from "../shared/guards";
 
+/** A layer document's file name, as every registry host spells it. */
+const PROVIDERS_FILENAME = "providers.yml";
+
 /** The `.yaml` spelling of {@link PROVIDERS_FILENAME}. */
 const PROVIDERS_FILENAME_ALIAS = "providers.yaml";
 

package/src/runtime/server/provider-service.ts

@@ -19,17 +19,21 @@
  *     `listModelsForHarness(harnessId, registry)` in the runtime.
  */
 
+import { entryDataZone } from "../shared/data-zone";
 import type {
   AIProviderCapabilities,
   AIProviderCredentialKind,
+  AIProviderDataZone,
   AIProviderKind,
   AIProviderRegistryView,
   AIProviderSurface,
+  AIProviderTransport,
   AIProviderVoiceParams,
 } from "../shared/provider-registry";
 import {
   entriesOfKind,
   isEntryEnabled,
+  isModelAllowed,
   isVoiceEntry,
   parseCredentialRef,
   registryEntries,
@@ -76,6 +80,14 @@ export interface ProviderInfo {
   preset?: string;
   /** Wire protocol of an `llm`/`embed` entry (its own or its preset's). */
   surface?: AIProviderSurface;
+  /** How requests of an `llm`/`embed` entry reach its surface, when not `direct`. */
+  transport?: AIProviderTransport;
+  /**
+   * Routing parameters of an `llm`/`embed` entry (`resource`, `deployment`,
+   * `api_version`, `region`, `project`, `location`, …), when it has any.
+   * Voice entries carry theirs in {@link params}.
+   */
+  transportParams?: Record<string, string>;
   /** The entry's `enabled` flag; `false` only in a listing with `includeDisabled`. */
   enabled: boolean;
   /**
@@ -87,6 +99,21 @@ export interface ProviderInfo {
   params?: AIProviderVoiceParams;
   /** Frozen by the control plane: a lower layer cannot change or disable it. */
   locked: boolean;
+  /** Where the entry processes data: its `data_zone`, else its preset's, else `transfer`. */
+  dataZone: AIProviderDataZone;
+  /** The entry's `eu_processing` switch (an `eu_option` entry counts as EU only with it on). */
+  euProcessing: boolean;
+  /**
+   * The entry's `allowed_models`, when it sets one: the only models it may be
+   * used with (`[]` = none). Absent: every model.
+   */
+  allowedModels?: string[];
+  /**
+   * Logical model ids an `llm`/`embed` entry declares (`model_map` keys, then
+   * ids only `capabilities` names), when it declares any. An entry without
+   * them lists its models through discovery.
+   */
+  modelIds?: string[];
 }
 
 /** One selectable model of one provider. */
@@ -162,21 +189,45 @@ export function listAIProviders(
       ...(entry.base_url ? { baseUrl: entry.base_url } : {}),
       ...(entry.preset ? { preset: entry.preset } : {}),
       ...(!isVoiceEntry(entry) && entry.surface ? { surface: entry.surface } : {}),
+      ...(!isVoiceEntry(entry) && entry.transport && entry.transport !== "direct"
+        ? { transport: entry.transport }
+        : {}),
+      ...(!isVoiceEntry(entry) && entry.params && Object.keys(entry.params).length > 0
+        ? { transportParams: { ...(entry.params as Record<string, string>) } }
+        : {}),
       enabled,
       ...(isVoiceEntry(entry) && entry.params ? { params: entry.params } : {}),
       locked: entry.locked === true,
+      dataZone: entryDataZone(entry),
+      euProcessing: entry.eu_processing === true,
+      ...(!isVoiceEntry(entry) && entry.allowed_models
+        ? { allowedModels: [...entry.allowed_models] }
+        : {}),
+      ...(!isVoiceEntry(entry) ? declaredModelIds(entry) : {}),
     });
   }
   return providers;
 }
 
+/** `{ modelIds }` of an `llm`/`embed` entry that declares models, else `{}`. */
+function declaredModelIds(entry: {
+  model_map?: Record<string, string>;
+  capabilities?: Record<string, unknown>;
+}): { modelIds?: string[] } {
+  const ids = [
+    ...new Set([...Object.keys(entry.model_map ?? {}), ...Object.keys(entry.capabilities ?? {})]),
+  ];
+  return ids.length > 0 ? { modelIds: ids } : {};
+}
+
 /**
  * List the models the registry declares, as `"<providerId>/<modelId>"`
  * selectors.
  *
  * Sourced from each `llm`/`embed` entry's `model_map` (plus any id that only
  * appears in `capabilities`) — the same two tables the runtime's model-reference
- * resolver reads, so a selector built from this list always resolves.
+ * resolver reads, so a selector built from this list always resolves. A model
+ * outside the entry's `allowed_models` is left out, as the runtime refuses it.
  *
  * @param providerId - Restrict to one entry; omit for every enabled entry.
  */
@@ -193,6 +244,7 @@ export function listAIProviderModels(
         ...Object.keys(entry.capabilities ?? {}),
       ]);
       for (const modelId of logicalIds) {
+        if (!isModelAllowed(entry, modelId)) continue;
         const capabilities = entry.capabilities?.[modelId];
         models.push({
           id: `${id}/${modelId}`,

package/src/runtime/server/provider-write.ts

@@ -28,18 +28,20 @@ import {
   type AIProviderRegistryLayer,
   type AIProviderRegistryPatch,
   isSafeProviderId,
-  loadProviderRegistryFile,
   mergeRegistries,
   parseCredentialRef,
   validateMergedRegistry,
   validateRegistry,
-} from "@skaile/workspaces/core";
+} from "@skaile/provider-registry";
 import {
   AI_PROVIDER_PRESETS,
   type AIProviderPreset,
   expandPreset,
-} from "@skaile/workspaces/sdk/bridge";
+} from "@skaile/provider-registry/catalog";
+import { loadProviderRegistryFile } from "@skaile/provider-registry/files";
+import { isDataZone } from "../shared/data-zone";
 import { isPlainObject } from "../shared/guards";
+import { missingRequiredParams } from "../shared/provider-accounts";
 import type { AIProviderEntry, AIProviderRegistry } from "../shared/provider-registry";
 import { type CredentialPolicy, entryPolicyRefusal } from "./credential-policy";
 import { catalogPreset, readProviderLayer, writeProviderLayer } from "./provider-layers";
@@ -77,9 +79,8 @@ const PATCH_REFUSAL =
   "A workspace may only patch credential and enabled of an inherited entry; add it as a workspace entry to change anything else.";
 
 /**
- * Entry keys a `PUT` body may set, and that an omitting body removes. `kind`
- * may be set too — an entry without a `preset` (the settings modal's
- * "Custom") has nothing else to supply it — but, omitted, it keeps its
+ * Entry keys a `PUT` body may set, and that an omitting body removes. The
+ * keys of {@link KEPT_BODY_KEYS} may be set too but, omitted, keep their
  * written value like every other key of a stored entry.
  */
 const BODY_KEYS: Record<string, true> = {
@@ -93,6 +94,44 @@ const BODY_KEYS: Record<string, true> = {
   enabled: true,
 };
 
+/**
+ * Keys a `PUT` body may set that an omitting body keeps. `kind`: an entry
+ * without a `preset` (the settings modal's "Custom") has nothing else to
+ * supply it. `params`: transport routing (`resource`, `deployment`,
+ * `api_version`, `region`, …) or voice parameters, which an edit that does
+ * not show them must not drop; `params: {}` removes them. `data_zone`,
+ * `eu_processing`, `allowed_models` ({@link NULLABLE_BODY_KEYS}): the zone
+ * override, the account's EU-processing switch and the model allow-list,
+ * each changed on its own by the settings panel; `null` removes them.
+ */
+const KEPT_BODY_KEYS: Record<string, true> = {
+  kind: true,
+  params: true,
+  data_zone: true,
+  eu_processing: true,
+  allowed_models: true,
+};
+
+/** Kept keys a body removes by sending `null`. */
+const NULLABLE_BODY_KEYS = ["data_zone", "eu_processing", "allowed_models"] as const;
+
+/**
+ * A body's `allowed_models`, normalized (ids trimmed), or the refusal: a list
+ * of distinct, non-empty model ids. `[]` is valid and allows no model.
+ */
+function readAllowedModels(value: unknown): string[] | string {
+  const refusal = "allowed_models must be a list of distinct, non-empty model ids, or null";
+  if (!Array.isArray(value)) return refusal;
+  const ids: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string" || item.trim() === "") return refusal;
+    const id = item.trim();
+    if (ids.includes(id)) return `allowed_models lists '${id}' twice`;
+    ids.push(id);
+  }
+  return ids;
+}
+
 /** Entry fields a higher scope may set on an entry a lower document defines. */
 export const PATCH_KEYS = ["credential", "enabled"] as const;
 
@@ -168,8 +207,29 @@ function readEntryBody(body: unknown): Record<string, unknown> | string {
   ) {
     return PROVIDER_SECRET_REFUSAL;
   }
-  const unknown = Object.keys(body).find((key) => !Object.hasOwn(BODY_KEYS, key) && key !== "kind");
+  const unknown = Object.keys(body).find(
+    (key) => !Object.hasOwn(BODY_KEYS, key) && !Object.hasOwn(KEPT_BODY_KEYS, key),
+  );
   if (unknown) return `'${unknown}' is not a provider entry field`;
+  if (body.params !== undefined && !isPlainObject(body.params)) {
+    return "params must be a map of parameter name to value";
+  }
+  if (body.data_zone !== undefined && body.data_zone !== null && !isDataZone(body.data_zone)) {
+    return "data_zone must be one of eu, eu_option, transfer, local, or null";
+  }
+  if (
+    body.eu_processing !== undefined &&
+    body.eu_processing !== null &&
+    typeof body.eu_processing !== "boolean"
+  ) {
+    return "eu_processing must be true, false or null";
+  }
+  let allowedModels: string[] | undefined;
+  if (body.allowed_models !== undefined && body.allowed_models !== null) {
+    const read = readAllowedModels(body.allowed_models);
+    if (typeof read === "string") return read;
+    allowedModels = read;
+  }
   if (body.preset !== undefined && !catalogPreset(body.preset)) {
     return `Unknown preset '${String(body.preset)}'`;
   }
@@ -179,7 +239,7 @@ function readEntryBody(body: unknown): Record<string, unknown> | string {
     if (ref !== undefined && (typeof ref !== "string" || !parseCredentialRef(ref)))
       return CREDENTIAL_REF_REFUSAL;
   }
-  return body;
+  return allowedModels ? { ...body, allowed_models: allowedModels } : body;
 }
 
 /**
@@ -230,12 +290,40 @@ function isPatchOrAbsent(entry: unknown): boolean {
   );
 }
 
+/** The `preset` the lowest-to-highest lower documents give entry `id`, the last one winning. */
+function lowerPreset(lowerEntries: unknown[]): unknown {
+  let preset: unknown;
+  for (const entry of lowerEntries)
+    if (isPlainObject(entry) && entry.preset !== undefined) preset = entry.preset;
+  return preset;
+}
+
+/**
+ * The required parameters of the entry's catalog preset that neither the
+ * entry nor a lower document's entry under the same id supplies. An entry
+ * without a catalog preset has none here; the SDK's schema checks its
+ * transport's parameters.
+ */
+function missingPresetParams(entry: Record<string, unknown>, lowerEntries: unknown[]): string[] {
+  const preset = catalogPreset(entry.preset ?? lowerPreset(lowerEntries));
+  if (!preset) return [];
+  const params: Record<string, unknown> = {};
+  for (const lower of lowerEntries) {
+    if (isPlainObject(lower) && isPlainObject(lower.params)) Object.assign(params, lower.params);
+  }
+  if (isPlainObject(entry.params)) Object.assign(params, entry.params);
+  return missingRequiredParams(preset, params);
+}
+
 /**
  * Upsert entry `id` in the scope's document.
  *
  * - **Own entry** — the body sets the editable fields (`BODY_KEYS`) — one it
- *   omits is removed — and optionally `kind`; fields it does not set (`kind`,
- *   `transport`, `params`, …) keep their written value.
+ *   omits is removed — and optionally `kind`, `params`, `data_zone`,
+ *   `eu_processing` and `allowed_models`; fields it does not set (`kind`,
+ *   `transport`, `params`, `data_zone`, …) keep their written value,
+ *   `params: {}` removes the parameters and `null` removes `data_zone`,
+ *   `eu_processing` or `allowed_models` (`[]` allows no model).
  * - **Patch** — when a lower document defines `id` and the body holds only
  *   {@link PATCH_KEYS}, the body is merged into the scope's stored entry for
  *   `id` (created when absent), leaving every other stored field alone.
@@ -243,11 +331,16 @@ function isPatchOrAbsent(entry: unknown): boolean {
  * The file and its directory are created when absent; other entries are kept
  * as written.
  *
- * 400: invalid id, secret-bearing or malformed body, a body for an inherited
- * entry that is neither a patch nor over an own full entry, or any error
- * diagnostic for the entry (as `data.diagnostics`; nothing is written). 403:
- * the entry is `locked: true` in some document. 409: the document on disk is
- * not a registry.
+ * 400: invalid id, secret-bearing or malformed body (`data_zone` outside
+ * eu | eu_option | transfer | local, a non-boolean `eu_processing`, an
+ * `allowed_models` that is not a list of distinct non-empty ids), a body for
+ * an inherited entry that is neither a patch nor over an own full entry, a
+ * preset's required parameter left out of `params` (named in the message,
+ * `data.missingParams`), or any error diagnostic for the entry (as
+ * `data.diagnostics`; nothing is written — `params` keys a transport does not
+ * accept are refused this way, by the SDK's schema). 403: the entry is
+ * `locked: true` in some document. 409: the document on disk is not a
+ * registry.
  */
 export function upsertProviderEntry(
   scope: ProviderWriteScope,
@@ -294,6 +387,16 @@ export function upsertProviderEntry(
         )
       : {};
     entry = { ...kept, ...fields };
+    if (isPlainObject(entry.params) && Object.keys(entry.params).length === 0) delete entry.params;
+    for (const key of NULLABLE_BODY_KEYS) if (entry[key] === null) delete entry[key];
+    const missing = missingPresetParams(entry, lowerEntries);
+    if (missing.length > 0) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: `Provider '${id}' needs ${missing.map((key) => `params.${key}`).join(", ")} (required by preset '${String(entry.preset ?? lowerPreset(lowerEntries))}')`,
+        data: { missingParams: missing },
+      });
+    }
   }
   const next = { ...providers, [id]: entry };
 
@@ -336,9 +439,15 @@ export interface ProviderPresetSummary {
   label: string;
   kind: AIProviderPreset["kind"];
   surface?: AIProviderPreset["surface"];
+  /** How requests reach the surface; absent = `direct`. Azure transports offer Entra ID sign-in. */
+  transport?: AIProviderPreset["transport"];
   base_url?: string;
   base_url_env?: string;
   credential: { kind: AIProviderPreset["credential"]["kind"]; env?: string };
+  /** Default routing / voice parameters. */
+  params?: Record<string, string>;
+  /** `params` keys an entry naming this preset must supply. */
+  required_params?: string[];
 }
 
 /** Catalog presets (all of them by default), in catalog order. */
@@ -350,9 +459,12 @@ export function providerPresetSummaries(
     label: preset.label,
     kind: preset.kind,
     surface: preset.surface,
+    ...(preset.transport ? { transport: preset.transport } : {}),
     base_url: preset.base_url,
     base_url_env: preset.base_url_env,
     credential: { kind: preset.credential.kind, env: preset.credential.env },
+    ...(preset.params ? { params: { ...preset.params } } : {}),
+    ...(preset.required_params?.length ? { required_params: [...preset.required_params] } : {}),
   }));
 }
 
@@ -385,17 +497,19 @@ export type ProviderLayerName = ProviderWriteScope["name"];
 
 /**
  * The defining document's values for the `PUT`-editable fields a settings UI
- * edit dialog does not show. A `PUT` removes every editable field it omits,
- * so an edit sends these back unchanged instead of dropping them.
+ * edit dialog does not show (or shows only in part, as `params`). A `PUT`
+ * removes every editable field it omits, so an edit sends these back
+ * unchanged instead of dropping them.
  */
 export interface ProviderLayerFields {
   label?: unknown;
   headers?: unknown;
   model_map?: unknown;
   enabled?: unknown;
+  params?: unknown;
 }
 
-const LAYER_FIELD_KEYS = ["label", "headers", "model_map", "enabled"] as const;
+const LAYER_FIELD_KEYS = ["label", "headers", "model_map", "enabled", "params"] as const;
 
 /**
  * Tag each provider view of a scope with every registry document that holds

package/src/runtime/server/voice-provider.ts

@@ -0,0 +1,110 @@
+/**
+ * Voice selection: which `kind: stt|tts` registry entry serves a request and
+ * with which parameters.
+ *
+ * `sttProvider`/`ttsProvider` are registry ids of `kind: stt|tts` entries; the
+ * endpoint and the voice parameters live on the entry, and
+ * `sttLanguage`/`ttsVoice` are per-request overrides of two of those
+ * parameters. Resolving all of that used to be three apps' worth of hardcoded
+ * endpoints and voice ids.
+ */
+
+import type {
+  AIProviderRegistryView,
+  AIProviderVoiceEntry,
+  AIProviderVoiceKind,
+  AIProviderVoiceParams,
+} from "../shared/provider-registry";
+import {
+  entriesOfKind,
+  selectVoiceEntryId,
+  VOICE_OVERRIDE_PARAM,
+} from "../shared/provider-registry";
+
+/**
+ * Settings fields that name a voice entry and override its parameters — the
+ * same field names as the Workspaces `settings.json` document, so a
+ * `SkaileSettings` (`@skaile/forge-settings/workspaces`) can be passed as is.
+ */
+export interface VoiceSettings {
+  /** Registry id of the `kind: stt` entry. */
+  sttProvider?: string;
+  /** Registry id of the `kind: tts` entry. */
+  ttsProvider?: string;
+  /** Overrides the stt entry's `language` parameter. */
+  sttLanguage?: string;
+  /** Overrides the tts entry's `voice_id` parameter. */
+  ttsVoice?: string;
+}
+
+/** The `kind: stt|tts` entry a request runs against, with its parameters resolved. */
+export interface VoiceProviderSelection {
+  /** Registry id of the entry. */
+  providerId: string;
+  entry: AIProviderVoiceEntry;
+  /** Endpoint from the entry; absent when the entry inherits its preset's default. */
+  baseUrl?: string;
+  /**
+   * The entry's `params` with overrides applied — Deepgram `{model, language}`,
+   * ElevenLabs `{voice_id, output_format}`. This is the only place a forge app
+   * should read voice defaults from.
+   */
+  params: AIProviderVoiceParams;
+  /** True when settings named no usable entry and registry order decided. */
+  fallback: boolean;
+  /** Non-fatal notes, e.g. settings naming an entry the registry does not have. */
+  warnings: string[];
+}
+
+/**
+ * Resolve which registry entry serves speech-to-text or text-to-speech.
+ *
+ * Selection is `settings.sttProvider`/`settings.ttsProvider`, falling back to
+ * the first enabled entry of that kind in registry order when the setting is
+ * absent or names an entry that is gone — a missing setting must not silence an
+ * app that has a perfectly good entry configured.
+ *
+ * Parameter precedence, lowest first: the entry's `params`, then the settings
+ * overrides (`sttLanguage` → `language`, `ttsVoice` → `voice_id`), then
+ * `overrides` from the request. The per-request override is the contract
+ * forge-concept already honoured and the other apps silently dropped.
+ *
+ * @returns The selection, or `undefined` when the registry has no enabled entry
+ *          of that kind.
+ */
+export function resolveVoiceProvider(
+  registry: AIProviderRegistryView,
+  kind: AIProviderVoiceKind,
+  settings: VoiceSettings = {},
+  overrides: AIProviderVoiceParams = {},
+): VoiceProviderSelection | undefined {
+  const candidates = entriesOfKind(registry, kind);
+  if (candidates.length === 0) return undefined;
+
+  const warnings: string[] = [];
+  const wanted = (kind === "stt" ? settings.sttProvider : settings.ttsProvider)?.trim();
+  const ids = candidates.map(([id]) => id);
+  // `candidates` is non-empty, so the shared rule always names one of these ids.
+  const providerId = selectVoiceEntryId(ids, wanted) as string;
+  const entry = candidates[ids.indexOf(providerId)][1];
+  if (wanted && wanted !== providerId) {
+    warnings.push(
+      `settings name '${wanted}' for ${kind}, which is not an enabled ${kind} entry — ` +
+        `using '${providerId}' instead`,
+    );
+  }
+  const fallback = wanted !== providerId;
+
+  const settingsOverride: AIProviderVoiceParams = {};
+  const override = (kind === "stt" ? settings.sttLanguage : settings.ttsVoice)?.trim();
+  if (override) settingsOverride[VOICE_OVERRIDE_PARAM[kind]] = override;
+
+  return {
+    providerId,
+    entry,
+    ...(entry.base_url ? { baseUrl: entry.base_url } : {}),
+    params: { ...entry.params, ...settingsOverride, ...overrides },
+    fallback,
+    warnings,
+  };
+}

package/src/runtime/shared/data-zone.ts

@@ -0,0 +1,179 @@
+/**
+ * Data zones: where a provider entry processes data, and which entries a
+ * host's data-zone rule ("Where may AI process data?") keeps.
+ *
+ * `@skaile/provider-registry` owns the vocabulary (`AI_PROVIDER_DATA_ZONES`,
+ * `AI_PROVIDER_DATA_ZONE_RULES`, re-exported by `./provider-registry`) and the
+ * catalog's `data_zone` column with `entryDataZone`, `entryAllowedByDataZone`
+ * and `filterRegistryByDataZone` in its `/catalog` entry. forge-settings keeps
+ * the browser-side view here so the settings panel does not ship the catalog
+ * (and its generated model table) to the browser: the same semantics, plus
+ * labels, refusal wording and a filter that keeps a merged registry merged.
+ * {@link PRESET_DATA_ZONES} is a copy of the catalog's column; a test holds it
+ * equal to `@skaile/provider-registry/catalog`.
+ *
+ * Browser-safe on purpose — no `node:` imports.
+ */
+
+import {
+  AI_PROVIDER_DATA_ZONE_RULES,
+  AI_PROVIDER_DATA_ZONES,
+  type AIProviderDataZone,
+  type AIProviderDataZoneRule,
+  type AIProviderRegistry,
+  type AIProviderRegistryView,
+  isMergedRegistry,
+  type MergedAIProviderRegistry,
+} from "./provider-registry";
+
+/**
+ * The `data_zone` of each catalog preset, by preset id. Copied from
+ * `@skaile/provider-registry/catalog`'s `AI_PROVIDER_PRESETS`; change it there
+ * first. A preset this table does not name is `transfer`.
+ */
+export const PRESET_DATA_ZONES: Readonly<Record<string, AIProviderDataZone>> = {
+  anthropic: "transfer",
+  openai: "transfer",
+  google: "transfer",
+  groq: "transfer",
+  deepseek: "transfer",
+  openrouter: "transfer",
+  mistral: "eu",
+  xai: "transfer",
+  together: "transfer",
+  fireworks: "transfer",
+  bedrock: "eu_option",
+  vertex: "eu_option",
+  "azure-openai": "eu_option",
+  foundry: "eu_option",
+  ollama: "local",
+  lmstudio: "local",
+  vllm: "local",
+  litellm: "transfer",
+  deepgram: "transfer",
+  elevenlabs: "transfer",
+};
+
+/** What a provider row's zone chip says. */
+export const DATA_ZONE_LABELS: Readonly<Record<AIProviderDataZone, string>> = {
+  eu: "EU",
+  eu_option: "EU option",
+  transfer: "Transfer",
+  local: "Local",
+};
+
+/** What a host calls each rule when it names the rule that keeps an entry out. */
+export const DATA_ZONE_RULE_LABELS: Readonly<Record<AIProviderDataZoneRule, string>> = {
+  any: "Anywhere",
+  eu_options: "EU, or EU option with EU processing on",
+  eu: "EU only",
+};
+
+/** Whether `value` is one of `AI_PROVIDER_DATA_ZONES`. */
+export function isDataZone(value: unknown): value is AIProviderDataZone {
+  return typeof value === "string" && (AI_PROVIDER_DATA_ZONES as readonly string[]).includes(value);
+}
+
+/** Whether `value` is one of `AI_PROVIDER_DATA_ZONE_RULES`. */
+export function isDataZoneRule(value: unknown): value is AIProviderDataZoneRule {
+  return (
+    typeof value === "string" && (AI_PROVIDER_DATA_ZONE_RULES as readonly string[]).includes(value)
+  );
+}
+
+/** The zone of catalog preset `presetId`, or `undefined` for an id the catalog does not name. */
+export function presetDataZone(presetId: string | undefined): AIProviderDataZone | undefined {
+  return presetId !== undefined && Object.hasOwn(PRESET_DATA_ZONES, presetId)
+    ? PRESET_DATA_ZONES[presetId]
+    : undefined;
+}
+
+/**
+ * Where an entry processes data: its own `data_zone`, else the zone of the
+ * catalog preset it names, else `transfer` (an unknown endpoint is assumed to
+ * leave the EU).
+ */
+export function entryDataZone(entry: {
+  data_zone?: AIProviderDataZone;
+  preset?: string;
+}): AIProviderDataZone {
+  return entry.data_zone ?? presetDataZone(entry.preset) ?? "transfer";
+}
+
+/**
+ * Whether `rule` allows an entry in `zone`: `any` allows all; `eu` allows
+ * `eu` and `local`; `eu_options` additionally allows `eu_option` when
+ * `euProcessing` is `true`.
+ */
+export function dataZoneAllows(
+  rule: AIProviderDataZoneRule,
+  zone: AIProviderDataZone,
+  euProcessing: boolean | undefined,
+): boolean {
+  if (rule === "any") return true;
+  if (zone === "eu" || zone === "local") return true;
+  return rule === "eu_options" && zone === "eu_option" && euProcessing === true;
+}
+
+/** Whether `rule` allows `entry` ({@link dataZoneAllows} over {@link entryDataZone}). */
+export function entryAllowedByDataZone(
+  entry: { data_zone?: AIProviderDataZone; preset?: string; eu_processing?: boolean },
+  rule: AIProviderDataZoneRule,
+): boolean {
+  return dataZoneAllows(rule, entryDataZone(entry), entry.eu_processing);
+}
+
+/**
+ * Why `rule` keeps an entry in `zone` out, naming the rule, or `undefined`
+ * when the rule allows it. Secret-free, safe to render.
+ */
+export function dataZoneRefusal(
+  rule: AIProviderDataZoneRule,
+  zone: AIProviderDataZone,
+  euProcessing: boolean | undefined,
+): string | undefined {
+  if (dataZoneAllows(rule, zone, euProcessing)) return undefined;
+  const why =
+    zone === "eu_option" && rule === "eu_options"
+      ? "EU processing is not on for this account"
+      : `this provider is ${DATA_ZONE_LABELS[zone]}`;
+  return `Blocked by the data-zone rule "${DATA_ZONE_RULE_LABELS[rule]}": ${why}.`;
+}
+
+/**
+ * The registry with only the entries `rule` allows, every kind alike
+ * (`llm`, `embed`, `stt`, `tts`). Order is kept; the input is not mutated. A
+ * merged registry comes back merged, its `order`, `origin` and `locked`
+ * narrowed to the kept entries.
+ */
+export function filterRegistryByDataZone(
+  registry: AIProviderRegistry,
+  rule: AIProviderDataZoneRule,
+): AIProviderRegistry;
+export function filterRegistryByDataZone(
+  registry: MergedAIProviderRegistry,
+  rule: AIProviderDataZoneRule,
+): MergedAIProviderRegistry;
+export function filterRegistryByDataZone(
+  registry: AIProviderRegistryView,
+  rule: AIProviderDataZoneRule,
+): AIProviderRegistryView;
+export function filterRegistryByDataZone(
+  registry: AIProviderRegistryView,
+  rule: AIProviderDataZoneRule,
+): AIProviderRegistryView {
+  const entries = isMergedRegistry(registry) ? registry.providers : registry;
+  const providers: AIProviderRegistry = {};
+  for (const [id, entry] of Object.entries(entries)) {
+    if (entryAllowedByDataZone(entry, rule)) providers[id] = entry;
+  }
+  if (!isMergedRegistry(registry)) return providers;
+  const kept = (id: string) => Object.hasOwn(providers, id);
+  return {
+    ...registry,
+    providers,
+    order: registry.order.filter(kept),
+    origin: Object.fromEntries(Object.entries(registry.origin).filter(([id]) => kept(id))),
+    locked: registry.locked.filter(kept),
+  };
+}