rapier-runtime 0.1.0__py3-none-any.whl

rapier/mcp/server.py

@@ -0,0 +1,184 @@
+"""The ``rapier mcp`` stdio server — spar / sparring / doctor as MCP tools.
+
+Optional: requires the ``mcp`` extra (``pip install "rapier-runtime[mcp]"``). The
+SDK is imported lazily inside :func:`build_server`, so importing this module (and
+the rest of the CLI) never needs it. Keys are supplied by the MCP client in the
+server's ``env`` block and read from the environment like everywhere else — the
+engine still reads no secret from a file.
+
+Tools return a **structured** result (recommendation + trust rider markdown, the
+definitiveness verdict, the live grounding summary, cross-vendor status, and any
+forwarded standing objections). A ceremony is many model calls and can run for
+minutes, so the tools **stream per-stage progress** to the client: the engine's
+run-log lines are bridged from the worker thread to MCP ``info`` + ``report_progress``
+notifications, so the client shows life instead of a hang.
+
+NOTE: this module deliberately does *not* use ``from __future__ import
+annotations`` — FastMCP evaluates each tool's signature, and the lazily-imported
+``Context`` annotation must be a real class object at definition time, not a
+string it cannot resolve.
+"""
+import os
+import sys
+from typing import Any, Callable
+
+
+async def _run_with_progress(
+    fn: Callable[..., dict],
+    ctx: Any,
+    total: int,
+    timeout_s: float | None = None,
+    ledger_root: str | None = None,
+    **kwargs: Any,
+) -> dict:
+    """Run a blocking tool ``fn(log=…, cancel=…, ledger_root=…, **kwargs)`` in a
+    worker thread while streaming its log lines to the MCP client as info +
+    progress notifications, with cooperative cancellation and an optional timeout.
+
+    ``ctx`` may be ``None`` (a unit test with no session), in which case the run
+    proceeds silently. On client cancellation or timeout the cancel flag is set,
+    so the (abandoned) worker stops at the next stage boundary rather than being
+    killed mid-call. Progress ticks once per pipeline stage (``stage:`` log lines).
+    """
+    import queue as _queue
+    import threading
+
+    import anyio
+
+    q: _queue.Queue = _queue.Queue()
+    sentinel = object()
+    box: dict[str, dict] = {}
+    cancel_event = threading.Event()
+
+    def _log(msg: str) -> None:
+        q.put(str(msg))
+
+    def _work() -> None:
+        box["result"] = fn(
+            log=_log, cancel=cancel_event.is_set, ledger_root=ledger_root, **kwargs
+        )
+
+    async def _drain() -> None:
+        done = 0
+        while True:
+            try:
+                msg = q.get_nowait()
+            except _queue.Empty:
+                await anyio.sleep(0.02)
+                continue
+            if msg is sentinel:
+                return
+            if ctx is not None:
+                await ctx.info(msg)
+                if msg.startswith("stage:"):
+                    done += 1
+                    try:
+                        await ctx.report_progress(done, total)
+                    except Exception:
+                        pass  # progress is best-effort; never fail a run over it
+
+    timed_out = False
+    try:
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(_drain)
+            if timeout_s:
+                try:
+                    with anyio.fail_after(timeout_s):
+                        await anyio.to_thread.run_sync(_work, abandon_on_cancel=True)
+                except TimeoutError:
+                    timed_out = True
+            else:
+                await anyio.to_thread.run_sync(_work, abandon_on_cancel=True)
+            q.put(sentinel)
+    finally:
+        cancel_event.set()  # stop the (possibly abandoned) worker at the next boundary
+
+    if timed_out:
+        return {"ok": False, "error": f"timed out after {timeout_s}s; partial run abandoned"}
+    return box.get("result", {"ok": False, "error": "run produced no result"})
+
+
+def build_server():
+    """Construct the FastMCP server with Rapier's tools.
+
+    Raises ``ImportError`` if the ``mcp`` extra is not installed (handled by
+    :func:`serve`).
+    """
+    from mcp.server.fastmcp import Context, FastMCP  # optional dependency
+
+    from ..presets import load_preset
+    from . import tools
+
+    server = FastMCP("rapier")
+    # Opt-in run persistence: when set, ceremonies are written here and become
+    # retrievable via list_runs / get_run. Off by default (no surprise disk writes).
+    ledger_root = os.environ.get("RAPIER_MCP_LEDGER") or None
+
+    def _stage_total(name: str, settle: int, verify: str) -> int:
+        try:
+            return len(load_preset(name, settle=settle, verify=verify).stages)
+        except Exception:
+            return 0
+
+    @server.tool()
+    async def spar(
+        request: str, settle: int = 0, verify: str = "gate",
+        timeout_s: float = 0, ctx: Context = None,
+    ) -> dict:
+        """Run the SPARRING Resolver on a decision: one grounded, cross-vendor
+        challenge plus a definitiveness gate. Returns a recommendation, a trust
+        rider, and the grounding verdict. ``settle`` adds review-and-revise rounds
+        (default 0); ``verify`` is off|gate|round for the external-canon gate;
+        ``timeout_s`` > 0 caps the run (partial run abandoned on timeout)."""
+        return await _run_with_progress(
+            tools.run_spar, ctx, _stage_total("spar", settle, verify),
+            timeout_s=timeout_s or None, ledger_root=ledger_root,
+            request=request, settle=settle, verify=verify,
+        )
+
+    @server.tool()
+    async def sparring(
+        request: str, settle: int = 0, verify: str = "gate",
+        report_all: bool = False, timeout_s: float = 0, ctx: Context = None,
+    ) -> dict:
+        """Run the full SPARRING ceremony (Proposer, then Resolver) on a decision.
+        ``report_all`` also returns the Proposer handoff (the committed option and
+        its standing objections); ``timeout_s`` > 0 caps the run."""
+        return await _run_with_progress(
+            tools.run_sparring, ctx, _stage_total("sparring", settle, verify),
+            timeout_s=timeout_s or None, ledger_root=ledger_root,
+            request=request, settle=settle, verify=verify, report_all=report_all,
+        )
+
+    @server.tool()
+    def rapier_doctor() -> dict:
+        """Report which AI vendor keys this server has (env-var names only, never
+        values) and whether cross-vendor review is available."""
+        return tools.doctor()
+
+    @server.tool()
+    def list_runs() -> dict:
+        """List persisted run ids (requires the server's RAPIER_MCP_LEDGER)."""
+        return tools.list_runs(ledger_root)
+
+    @server.tool()
+    def get_run(run_id: str) -> dict:
+        """Fetch a persisted run's report + verdict by id (requires RAPIER_MCP_LEDGER)."""
+        return tools.get_run(ledger_root, run_id)
+
+    return server
+
+
+def serve() -> int:
+    """Run the stdio MCP server. Returns non-zero with a hint if the SDK is absent."""
+    try:
+        server = build_server()
+    except ImportError:
+        print(
+            'The MCP server needs the optional "mcp" extra:\n'
+            '    pip install "rapier-runtime[mcp]"',
+            file=sys.stderr,
+        )
+        return 1
+    server.run()  # stdio transport by default
+    return 0

rapier/mcp/tools.py

@@ -0,0 +1,125 @@
+"""MCP tool logic — pure functions the MCP server wraps.
+
+No dependency on the ``mcp`` SDK, so this is testable without the extra installed
+and reusable outside MCP. Each function runs a preset through the engine and
+returns a structured result: a human-readable ``report_md`` plus machine fields
+(verdict, grounding, cross-vendor, standing objections). Honest first: if no
+vendor key is configured, it returns ``{"ok": False, "error": …}`` rather than an
+empty run.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Callable
+
+from ..onboarding import configured_vendors, doctor_report, preflight_error
+from ..presets import load_preset
+
+
+def _result(env, report_all: bool) -> dict[str, Any]:
+    report = env.meta.get("report_md") or env.recommendation or ""
+    proposer_md = env.meta.get("proposer_report_md")
+    if report_all and proposer_md:
+        report = f"{proposer_md}\n\n---\n\n{report}"
+    gate = env.meta.get("citation_gate") or {}
+    review = env.meta.get("review") or {}
+    cut = (env.meta.get("proposer") or {}).get("cut") or {}
+    cancelled = any(t.kind == "control" and "cancelled" in t.summary for t in env.trace)
+    return {
+        "ok": True,
+        "cancelled": cancelled,
+        "run_id": env.meta.get("run_id"),
+        "report_md": report,
+        "verdict": env.verdict,
+        "grounding": (
+            {
+                "gate": gate.get("gate"),
+                "grounding_rate": gate.get("grounding_rate"),
+                "counts": gate.get("counts"),
+            }
+            if gate
+            else None
+        ),
+        "cross_vendor": review.get("cross_vendor"),
+        "author_vendor": env.meta.get("author_vendor"),
+        "reviewer_vendor": review.get("reviewer_vendor"),
+        "standing_objections": cut.get("standing_objections") or [],
+    }
+
+
+def _run(
+    name: str,
+    request: str,
+    settle: int,
+    verify: str,
+    report_all: bool,
+    log: Callable[[str], None] | None,
+    cancel: Callable[[], bool] | None = None,
+    ledger_root: str | None = None,
+) -> dict[str, Any]:
+    err = preflight_error()
+    if err:
+        return {"ok": False, "error": err}
+    preset = load_preset(name, settle=settle, verify=verify)
+    env = preset.build().run(
+        request, ledger_root=ledger_root, log=log or (lambda _m: None), cancel=cancel
+    )
+    return _result(env, report_all)
+
+
+def run_spar(
+    request: str, settle: int = 0, verify: str = "gate",
+    log: Callable[[str], None] | None = None,
+    cancel: Callable[[], bool] | None = None,
+    ledger_root: str | None = None,
+) -> dict[str, Any]:
+    return _run("spar", request, settle, verify, False, log, cancel, ledger_root)
+
+
+def run_sparring(
+    request: str, settle: int = 0, verify: str = "gate", report_all: bool = False,
+    log: Callable[[str], None] | None = None,
+    cancel: Callable[[], bool] | None = None,
+    ledger_root: str | None = None,
+) -> dict[str, Any]:
+    return _run("sparring", request, settle, verify, report_all, log, cancel, ledger_root)
+
+
+def doctor() -> dict[str, Any]:
+    return {"report": doctor_report(), "configured_vendors": configured_vendors()}
+
+
+def _safe_run_id(run_id: str) -> bool:
+    """Reject path-traversal / separators — a run id is a single dir name."""
+    return bool(run_id) and os.sep not in run_id and "/" not in run_id and ".." not in run_id
+
+
+def list_runs(ledger_root: str | None) -> dict[str, Any]:
+    """List persisted run ids under the server's ledger dir (newest last)."""
+    if not ledger_root or not os.path.isdir(ledger_root):
+        return {"ok": False, "error": "run persistence is not enabled (set RAPIER_MCP_LEDGER)"}
+    runs = sorted(
+        d for d in os.listdir(ledger_root) if os.path.isdir(os.path.join(ledger_root, d))
+    )
+    return {"ok": True, "runs": runs}
+
+
+def get_run(ledger_root: str | None, run_id: str) -> dict[str, Any]:
+    """Return a persisted run's report + verdict by id (from its envelope.json)."""
+    if not ledger_root or not os.path.isdir(ledger_root):
+        return {"ok": False, "error": "run persistence is not enabled (set RAPIER_MCP_LEDGER)"}
+    if not _safe_run_id(run_id):
+        return {"ok": False, "error": "invalid run id"}
+    path = os.path.join(ledger_root, run_id, "envelope.json")
+    if not os.path.isfile(path):
+        return {"ok": False, "error": f"run '{run_id}' not found"}
+    with open(path, encoding="utf-8") as fh:
+        env = json.load(fh)
+    meta = env.get("meta") or {}
+    return {
+        "ok": True,
+        "run_id": run_id,
+        "report_md": meta.get("report_md") or env.get("recommendation") or "",
+        "verdict": env.get("verdict"),
+    }

rapier/models.py

@@ -0,0 +1,352 @@
+"""The model layer — the ONLY place a vendor or model name lives.
+
+A ``ModelSpec`` (vendor + model + prompt) comes straight from the manifest.
+``build_client`` turns it into a ``ModelClient``. Cross-vendor independence is
+therefore a config property, not a code change: point two roles at two vendors.
+
+Real provider SDKs are imported lazily and only when a real call is made, so
+the package imports and the M0 echo pipeline run with no SDKs and no keys.
+Secrets are read exclusively through :mod:`rapier.secrets` (env-only, redacted).
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from .secrets import register_secret_value, require_secret
+
+
+@dataclass
+class ModelSpec:
+    vendor: str  # mock | anthropic | openai
+    model: str
+    prompt_template: str | None = None
+    max_tokens: int = 4096  # generative floor; 1024 truncates real recommendations
+    temperature: float = 1.0
+
+
+@dataclass
+class ModelResponse:
+    text: str
+    vendor: str
+    model: str
+    raw: dict[str, Any] | None = None
+
+
+# --- one HTTP path + one transcript hook for EVERY vendor -------------------
+# Every model call — native Anthropic/OpenAI, Gemini/Grok, any compatible
+# endpoint — goes through _post_with_retry and _record(), so retry/backoff and
+# transcript capture are identical regardless of the LLM pairing.
+
+_transcript_sink = None  # set per run; called with one dict per model call
+
+
+def set_transcript_sink(fn) -> None:
+    global _transcript_sink
+    _transcript_sink = fn
+
+
+def _record(vendor: str, model: str, system: str, prompt: str, response: str) -> None:
+    if _transcript_sink is not None:
+        try:
+            _transcript_sink(
+                {"vendor": vendor, "model": model, "system": system, "prompt": prompt, "response": response}
+            )
+        except Exception:  # transcript capture must never break a run
+            pass
+
+
+def _post_with_retry(url: str, headers: dict, payload: dict, timeout: int = 120) -> dict:
+    """POST JSON with exponential backoff on 429/5xx (respects Retry-After)."""
+    import time
+
+    import requests
+
+    delay, last = 2.0, None
+    for _ in range(6):
+        try:
+            resp = requests.post(url, headers=headers, json=payload, timeout=timeout)
+        except requests.RequestException as exc:
+            last = str(exc)
+            time.sleep(delay)
+            delay = min(delay * 2, 30)
+            continue
+        if resp.status_code == 429 or resp.status_code >= 500:
+            retry_after = resp.headers.get("Retry-After")
+            wait = float(retry_after) if (retry_after or "").replace(".", "", 1).isdigit() else delay
+            last = f"HTTP {resp.status_code}"
+            time.sleep(min(wait, 30))
+            delay = min(delay * 2, 30)
+            continue
+        resp.raise_for_status()
+        return resp.json()
+    raise RuntimeError(f"request to {url} failed after retries: {last}")
+
+
+class ModelClient(ABC):
+    def __init__(self, spec: ModelSpec):
+        self.spec = spec
+
+    @abstractmethod
+    def complete(self, system: str, prompt: str) -> ModelResponse:
+        ...
+
+
+class MockModelClient(ModelClient):
+    """Deterministic, no network, no key. Used by the echo pipeline and tests."""
+
+    def complete(self, system: str, prompt: str) -> ModelResponse:
+        text = f"[mock:{self.spec.model}] {prompt.strip()}"
+        _record("mock", self.spec.model, system, prompt, text)
+        return ModelResponse(text=text, vendor="mock", model=self.spec.model)
+
+
+class AnthropicModelClient(ModelClient):
+    def complete(self, system: str, prompt: str) -> ModelResponse:
+        key = require_secret("ANTHROPIC_API_KEY")
+        register_secret_value(key)
+        data = _post_with_retry(
+            "https://api.anthropic.com/v1/messages",
+            {"x-api-key": key, "anthropic-version": "2023-06-01", "content-type": "application/json"},
+            {
+                "model": self.spec.model,
+                "max_tokens": self.spec.max_tokens,
+                "system": system,
+                "messages": [{"role": "user", "content": prompt}],
+            },
+        )
+        text = "".join(b.get("text", "") for b in data.get("content", []) if b.get("type") == "text")
+        _record("anthropic", self.spec.model, system, prompt, text)
+        return ModelResponse(text=text, vendor="anthropic", model=self.spec.model)
+
+
+class OpenAIModelClient(ModelClient):
+    def complete(self, system: str, prompt: str) -> ModelResponse:
+        key = require_secret("OPENAI_API_KEY")
+        register_secret_value(key)
+        data = _post_with_retry(
+            "https://api.openai.com/v1/chat/completions",
+            {"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+            {
+                "model": self.spec.model,
+                "messages": [
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": prompt},
+                ],
+                "max_completion_tokens": self.spec.max_tokens,
+            },
+        )
+        text = (data.get("choices") or [{}])[0].get("message", {}).get("content") or ""
+        _record("openai", self.spec.model, system, prompt, text)
+        return ModelResponse(text=text, vendor="openai", model=self.spec.model)
+
+
+class OpenAICompatibleModelClient(ModelClient):
+    """Any OpenAI-wire-format endpoint — Grok (xAI), DeepSeek, Mistral, Groq,
+    Together, OpenRouter, local Ollama/vLLM. One client, parameterized by
+    ``base_url`` + the env var holding its key. Uses ``requests`` directly (no
+    SDK), so adding a vendor is a config entry, not new code.
+    """
+
+    def __init__(self, spec: ModelSpec, base_url: str, key_env: str):
+        super().__init__(spec)
+        self.base_url = base_url.rstrip("/")
+        self.key_env = key_env
+
+    def complete(self, system: str, prompt: str) -> ModelResponse:
+        key = require_secret(self.key_env)
+        register_secret_value(key)
+        data = _post_with_retry(
+            f"{self.base_url}/chat/completions",
+            {"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+            {
+                "model": self.spec.model,
+                "messages": [
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": prompt},
+                ],
+                "max_tokens": self.spec.max_tokens,
+            },
+        )
+        text = (data.get("choices") or [{}])[0].get("message", {}).get("content") or ""
+        _record(self.spec.vendor, self.spec.model, system, prompt, text)
+        return ModelResponse(text=text, vendor=self.spec.vendor, model=self.spec.model)
+
+
+# vendor -> (base_url, key_env, default_model). Defaults are overridable in the
+# manifest; only xai's default is live-validated (2026-07-06 — Grok's API is
+# OpenAI-compatible). Others are best-effort until validated with a real key.
+_OPENAI_COMPATIBLE: dict[str, tuple[str, str, str]] = {
+    "gemini":     ("https://generativelanguage.googleapis.com/v1beta/openai", "GEMINI_API_KEY", "gemini-2.5-flash"),  # frontier; also has a native API
+    "xai":        ("https://api.x.ai/v1",            "XAI_API_KEY",        "grok-4.3"),
+    "deepseek":   ("https://api.deepseek.com/v1",    "DEEPSEEK_API_KEY",   "deepseek-chat"),
+    "mistral":    ("https://api.mistral.ai/v1",      "MISTRAL_API_KEY",    "mistral-large-latest"),
+    "groq":       ("https://api.groq.com/openai/v1", "GROQ_API_KEY",       "llama-3.3-70b-versatile"),
+    "together":   ("https://api.together.xyz/v1",    "TOGETHER_API_KEY",   "meta-llama/Llama-3.3-70B-Instruct-Turbo"),
+    "openrouter": ("https://openrouter.ai/api/v1",   "OPENROUTER_API_KEY", "openai/gpt-4o"),
+    "ollama":     ("http://localhost:11434/v1",      "OLLAMA_API_KEY",     "llama3.1"),  # local, zero-egress
+}
+
+# vendor -> env var holding its key (for auto-detect). Native + compatible.
+_VENDOR_KEY_ENV: dict[str, str] = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    **{v: cfg[1] for v, cfg in _OPENAI_COMPATIBLE.items()},
+}
+
+
+def build_client(spec: ModelSpec) -> ModelClient:
+    vendor = spec.vendor
+    if vendor == "mock":
+        return MockModelClient(spec)
+    if vendor == "anthropic":
+        return AnthropicModelClient(spec)
+    if vendor == "openai":
+        return OpenAIModelClient(spec)
+    if vendor in _OPENAI_COMPATIBLE:
+        base_url, key_env, default_model = _OPENAI_COMPATIBLE[vendor]
+        if not spec.model:
+            spec.model = default_model
+        return OpenAICompatibleModelClient(spec, base_url, key_env)
+    known = ["mock", "anthropic", "openai", *sorted(_OPENAI_COMPATIBLE)]
+    raise ValueError(f"unknown vendor '{vendor}'; known vendors: {known}")
+
+
+def available_vendors() -> list[str]:
+    """Which vendors have a key present in the environment (auto-detect).
+
+    ``mock`` is always available; ``ollama`` is local and only appears if its
+    (optional) key env is set. Keys are read env-only (threat model S1).
+    """
+    from .secrets import get_secret
+
+    avail = ["mock"]
+    for vendor, key_env in _VENDOR_KEY_ENV.items():
+        if get_secret(key_env):
+            avail.append(vendor)
+    return avail
+
+
+# vendor -> a sensible default model (used when a role has no explicit model).
+_DEFAULT_MODEL: dict[str, str] = {
+    "anthropic": "claude-opus-4-8",
+    "openai": "gpt-5.2",
+    **{v: cfg[2] for v, cfg in _OPENAI_COMPATIBLE.items()},
+}
+
+# preference order when auto-assigning frontier vendors to roles.
+_FRONTIER_ORDER = ["anthropic", "openai", "gemini", "xai"]
+
+
+def default_model(vendor: str) -> str:
+    return _DEFAULT_MODEL.get(vendor, "")
+
+
+def vendor_key_envs() -> dict[str, str]:
+    """Vendor -> the env var holding its key (public, for onboarding / doctor)."""
+    return dict(_VENDOR_KEY_ENV)
+
+
+def frontier_vendors() -> list[str]:
+    """The frontier vendors, in preference order (for onboarding hints)."""
+    return list(_FRONTIER_ORDER)
+
+
+def resolve_pair(
+    available: list[str],
+    primary_pref: str | None = None,
+    secondary_pref: str | None = None,
+) -> tuple[str | None, str | None]:
+    """Choose ``(primary, secondary)`` vendors from the available set.
+
+    ``primary`` backs the author/primary slot; ``secondary`` is a **distinct**
+    vendor for the reviewer/cross-vendor slot, or ``None`` when only one vendor
+    is available (honest single-vendor degradation). Preferences win when
+    available; otherwise frontier vendors are assigned in order.
+    """
+    avail = [v for v in available if v != "mock"]
+    if not avail:
+        return None, None
+
+    def pick(pref: str | None, exclude: str | None = None) -> str | None:
+        if pref and pref in avail and pref != exclude:
+            return pref
+        for v in _FRONTIER_ORDER:
+            if v in avail and v != exclude:
+                return v
+        for v in avail:
+            if v != exclude:
+                return v
+        return None
+
+    primary = pick(primary_pref)
+    secondary = pick(secondary_pref, exclude=primary)
+    return primary, secondary
+
+
+# vendor -> hosting jurisdiction (for egress/data-residency policy; threat model S5).
+_VENDOR_JURISDICTION: dict[str, str] = {
+    "anthropic": "us", "openai": "us", "gemini": "us", "xai": "us",
+    "groq": "us", "together": "us", "openrouter": "us",
+    "mistral": "eu", "deepseek": "cn", "qwen": "cn", "ollama": "local",
+}
+
+
+class PolicyError(RuntimeError):
+    """Raised when the policy cannot be satisfied (e.g. independence=required,
+    but only one vendor is available)."""
+
+
+@dataclass
+class Policy:
+    """Declarative vendor policy (V3). Governs role->vendor assignment.
+
+    - ``vendors``: preference order (falls back to the frontier order).
+    - ``independence``: ``required`` (error if no distinct 2nd vendor) |
+      ``preferred`` (use a distinct 2nd if available, else single-vendor) |
+      ``off`` (single-vendor; don't seek a 2nd).
+    - ``avoid_jurisdictions``: drop vendors hosted in these (e.g. ``["cn"]``).
+    """
+
+    vendors: list[str] | None = None
+    independence: str = "preferred"
+    avoid_jurisdictions: list[str] = field(default_factory=list)
+
+    def _available(self, available: list[str]) -> list[str]:
+        avail = [v for v in available if v != "mock"]
+        if self.avoid_jurisdictions:
+            avail = [v for v in avail if _VENDOR_JURISDICTION.get(v) not in self.avoid_jurisdictions]
+        return avail
+
+    def resolve(
+        self, available: list[str], primary_pref: str | None = None, secondary_pref: str | None = None
+    ) -> tuple[str | None, str | None]:
+        avail = self._available(available)
+        if not avail:
+            if self.independence == "required":
+                raise PolicyError("independence=required but no vendors are available")
+            return None, None
+        order = self.vendors or _FRONTIER_ORDER
+
+        def pick(pref: str | None, exclude: str | None = None) -> str | None:
+            if pref and pref in avail and pref != exclude:
+                return pref
+            for v in order:
+                if v in avail and v != exclude:
+                    return v
+            for v in avail:
+                if v != exclude:
+                    return v
+            return None
+
+        primary = pick(primary_pref)
+        if self.independence == "off":
+            return primary, None
+        secondary = pick(secondary_pref, exclude=primary)
+        if self.independence == "required" and secondary is None:
+            raise PolicyError(
+                f"independence=required but only one vendor available ({primary}); "
+                "add a second vendor's key or set independence: preferred/off"
+            )
+        return primary, secondary