jev-mcp-python 0.1.0__py3-none-any.whl

jev_mcp/policy/claims.py

@@ -0,0 +1,103 @@
+"""Claim policy: per-claim actions, gate reason codes, and decide's requirement contradictions.
+
+Sources: `claimAction` (`lib.ts:344-353`), the gate's reason-code assembly (`index.ts:1471-1482`),
+and `contradictsRecommendation` (`lib.ts:153-160`).
+"""
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from jev_mcp.policy.actions import Action
+from jev_mcp.policy.thresholds import PolicyThresholds
+
+type ClaimVerdict = Literal["verified", "contradicted", "unsupported"]
+
+GATE_REASON_CODES = (
+    "incomplete_context",
+    "invalid_response",
+    "review_escalated",
+    "review_required",
+    "claims_contradicted",
+    "claims_unsupported",
+    "claim_confidence_low",
+    "claim_confidence_below_auto_accept",
+    "accepted",
+)
+"""Every gate reason code, in the frozen order they are emitted (`parity-manifest.json` `policy`)."""
+
+
+def claim_action(verdict: ClaimVerdict, confidence: float | None, auto_accept: float, review_at: float) -> Action:
+    """`claimAction`: unknown or low confidence and confident contradictions escalate.
+
+    Only confident verification is auto. Unknown confidence never satisfies a threshold, even a zero one.
+    """
+    if confidence is None or confidence < review_at:
+        return "escalate"
+    if verdict == "contradicted" and confidence >= auto_accept:
+        return "escalate"
+    return "auto" if verdict == "verified" and confidence >= auto_accept else "review"
+
+
+@dataclass(frozen=True, slots=True)
+class ClaimJudgment:
+    """A gate claim whose Choice answer validated."""
+
+    verdict: ClaimVerdict
+    confidence: float | None
+
+
+def gate_reason_codes(
+    *,
+    truncated: bool,
+    review_action: Action,
+    review_invalid: bool,
+    claims: Sequence[ClaimJudgment | None],
+    action: Action,
+    thresholds: PolicyThresholds,
+) -> list[str]:
+    """The gate's reason codes, in `GATE_REASON_CODES` order (`index.ts:1472-1482`).
+
+    `claims` holds one entry per claim, `None` for a claim whose answer failed validation. `action` is
+    the gate's overall action. A valid claim with unknown confidence counts as confidence -1, so it
+    reports `claim_confidence_low` rather than nothing.
+    """
+    valid = [claim for claim in claims if claim is not None]
+    codes: list[str] = []
+    if truncated:
+        codes.append("incomplete_context")
+    if review_invalid or len(valid) < len(claims):
+        codes.append("invalid_response")
+    if review_action == "escalate":
+        codes.append("review_escalated")
+    if review_action == "review":
+        codes.append("review_required")
+    if any(claim.verdict == "contradicted" for claim in valid):
+        codes.append("claims_contradicted")
+    if any(claim.verdict == "unsupported" for claim in valid):
+        codes.append("claims_unsupported")
+    confidences = [claim.confidence if claim.confidence is not None else -1 for claim in valid]
+    if any(c < thresholds.review_at for c in confidences):
+        codes.append("claim_confidence_low")
+    if any(thresholds.review_at <= c < thresholds.auto_accept for c in confidences):
+        codes.append("claim_confidence_below_auto_accept")
+    if action == "auto":
+        codes.append("accepted")
+    return codes
+
+
+@dataclass(frozen=True, slots=True)
+class RequirementCheck:
+    """One validated jev_decide requirement check: a candidate id, a requirement index, and the answer."""
+
+    candidate: str
+    requirement: int
+    answer: str
+
+
+def contradicts_recommendation(checks: Iterable[RequirementCheck], recommended: str) -> list[int]:
+    """`contradictsRecommendation`: requirement indexes whose check contradicts the recommended candidate.
+
+    Independent questions may disagree with the recommendation; surface it, do not average it away.
+    """
+    return [c.requirement for c in checks if c.candidate == recommended and c.answer == "contradicted"]

jev_mcp/policy/extract.py

@@ -0,0 +1,73 @@
+"""jev_extract's per-field decision (`index.ts:1062-1110`): auto/review/not_found and its Reason Code.
+
+Validation has already accepted the answer (or the field had no candidates to ask about); pattern
+failures and invalid answers never reach here. The tool projects the decision into its payload.
+"""
+
+from dataclasses import dataclass
+from typing import Literal
+
+from jev_mcp.policy.actions import classification_decision
+
+type ExtractStatus = Literal["auto", "review", "not_found"]
+
+type ExtractReasonCode = Literal[
+    "no_regex_matches", "matches_too_long", "candidate_limit", "none_matched", "none_matched_ambiguous"
+]
+
+EXTRACT_REASON_CODES: tuple[ExtractReasonCode, ...] = (
+    "no_regex_matches",
+    "matches_too_long",
+    "candidate_limit",
+    "none_matched",
+    "none_matched_ambiguous",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractJudgment:
+    """Jev's validated pick for a field: a candidate, or none of them, with its top probability and gap."""
+
+    none_matched: bool
+    top_probability: float
+    gap: float
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractFieldEvidence:
+    """One field's candidate universe and, when it had candidates, the judgment over them.
+
+    The universe is incomplete when candidates were capped (`truncated`) or matches were skipped as
+    too long (`too_long > 0`): the right value may be among the matches never sent. `truncated` implies
+    candidates, so a field without any is judged on `too_long` alone, as the reference does.
+    """
+
+    too_long: int
+    truncated: bool
+    judgment: ExtractJudgment | None
+    """`None` iff the field had no candidates, so nothing was asked."""
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractFieldDecision:
+    status: ExtractStatus
+    reason: ExtractReasonCode | None
+
+
+def decide_extract_field(evidence: ExtractFieldEvidence, *, threshold: float, margin: float) -> ExtractFieldDecision:
+    """Gate the pick on top probability >= threshold and gap >= margin; an incomplete universe is never
+    `auto` and never a definite `not_found`, and a negative answer is gated like a positive one."""
+    judgment = evidence.judgment
+    if judgment is None:
+        if evidence.too_long > 0:
+            return ExtractFieldDecision("review", "matches_too_long")
+        return ExtractFieldDecision("not_found", "no_regex_matches")
+    incomplete = evidence.truncated or evidence.too_long > 0
+    if incomplete:
+        return ExtractFieldDecision("review", "candidate_limit")
+    decision = classification_decision(judgment.top_probability, judgment.gap, threshold, margin)
+    if judgment.none_matched:
+        if decision == "auto":
+            return ExtractFieldDecision("not_found", "none_matched")
+        return ExtractFieldDecision("review", "none_matched_ambiguous")
+    return ExtractFieldDecision(decision, None)

jev_mcp/policy/ranking.py

@@ -0,0 +1,41 @@
+"""Ranking policy for jev_find and jev_rerank (`lib.ts:90-104`, `lib.ts:210-214`)."""
+
+from collections.abc import Mapping, Sequence
+from typing import Literal
+
+from jev_mcp.policy.thresholds import EXISTS_ABSENT_BELOW, EXISTS_FOUND_AT
+
+type ExistsVerdict = Literal["answered", "partial", "absent"]
+
+
+def exists_verdict(exists: float, found: float = EXISTS_FOUND_AT, absent: float = EXISTS_ABSENT_BELOW) -> ExistsVerdict:
+    """`existsVerdict`: answered at or above `found`, absent below `absent`, else partial."""
+    if exists >= found:
+        return "answered"
+    return "absent" if exists < absent else "partial"
+
+
+def rank_candidates(
+    candidates: Sequence[Mapping[str, object]], probabilities: Mapping[str, float]
+) -> list[dict[str, object]]:
+    """`rankCandidates`: each candidate plus its `probability`, descending; ties keep caller order.
+
+    A candidate id missing from `probabilities` ranks at 0. `sorted` is stable, as the reference's
+    index tie-break is.
+    """
+    scored = [(probabilities.get(str(candidate["id"]), 0.0), candidate) for candidate in candidates]
+    return [{**candidate, "probability": p} for p, candidate in _descending(scored)]
+
+
+def rerank_by_score(candidates: Sequence[Mapping[str, object]], scores: Sequence[float]) -> list[dict[str, object]]:
+    """`rerankByScore`: each candidate plus its index-aligned `relevance`, descending; ties keep caller order.
+
+    Scores are validated before this runs. The 0 for a missing score only guards a wiring mistake
+    (fewer scores than candidates), never a model answer.
+    """
+    scored = [(scores[i] if i < len(scores) else 0.0, candidate) for i, candidate in enumerate(candidates)]
+    return [{**candidate, "relevance": r} for r, candidate in _descending(scored)]
+
+
+def _descending[T](scored: list[tuple[float, T]]) -> list[tuple[float, T]]:
+    return sorted(scored, key=lambda pair: pair[0], reverse=True)

jev_mcp/policy/review.py

@@ -0,0 +1,73 @@
+"""Patch-review policy: the weighted composite and the review action (`lib.ts:245-337`, `index.ts:1254-1257`)."""
+
+import math
+from collections.abc import Iterable
+
+from jev_mcp.policy.actions import Action
+
+REVIEW_WEIGHTS: dict[str, float] = {
+    "correctness": 0.4,
+    "spec_match": 0.3,
+    "test_gap": 0.15,
+    "blast_radius": 0.15,
+}
+"""`REVIEW_WEIGHTS` in its reference key order, which is also the serialized order of `weights`."""
+
+
+def _clamp(value: float, low: float, high: float) -> float:
+    """`Math.min(high, Math.max(low, value))`: NaN stays NaN, where Python's `min`/`max` would drop it."""
+    if math.isnan(value):
+        return value
+    return min(high, max(low, value))
+
+
+def review_composite(correctness: float, spec_match: float, test_gap: float, blast_radius: float) -> float:
+    """`reviewComposite`: weighted 0..1 composite of 0..2 rubric scores, test gap and blast radius inverted.
+
+    Inputs are clamped to [0, 2] first. The sum is written out left to right so each float64 add
+    happens in the reference's order.
+    """
+    c = _clamp(_clamp(correctness, 0.0, 2.0) / 2, 0.0, 1.0)
+    s = _clamp(_clamp(spec_match, 0.0, 2.0) / 2, 0.0, 1.0)
+    t = _clamp(1 - _clamp(test_gap, 0.0, 2.0) / 2, 0.0, 1.0)
+    b = _clamp(1 - _clamp(blast_radius, 0.0, 2.0) / 2, 0.0, 1.0)
+    return (
+        REVIEW_WEIGHTS["correctness"] * c
+        + REVIEW_WEIGHTS["spec_match"] * s
+        + REVIEW_WEIGHTS["test_gap"] * t
+        + REVIEW_WEIGHTS["blast_radius"] * b
+    )
+
+
+def min_confidence(confidences: Iterable[float | None]) -> float | None:
+    """The lowest rubric confidence, or `None` when any is unknown (`index.ts:1256-1257`).
+
+    Unknown on one rubric is unknown overall: it must not become a number that could satisfy a
+    threshold. No confidences at all is `inf`, as `Math.min()` is.
+    """
+    values = list(confidences)
+    if any(value is None for value in values):
+        return None
+    return min((value for value in values if value is not None), default=math.inf)
+
+
+def review_action(
+    *,
+    composite: float,
+    safe_to_apply: float,
+    min_confidence: float | None,
+    auto_accept: float,
+    review_at: float,
+    composite_floor: float,
+) -> Action:
+    """`reviewAction` (`lib.ts:319-337`).
+
+    Escalate when min_confidence is unknown or below review_at, or safe_to_apply is below review_at.
+    Auto when safe_to_apply and min_confidence reach auto_accept and composite reaches
+    composite_floor. Otherwise review. Truncation is applied after, by `require_complete_context`.
+    """
+    if min_confidence is None or min_confidence < review_at or safe_to_apply < review_at:
+        return "escalate"
+    if safe_to_apply >= auto_accept and composite >= composite_floor and min_confidence >= auto_accept:
+        return "auto"
+    return "review"

jev_mcp/policy/screen.py

@@ -0,0 +1,48 @@
+"""jev_screen recommendation (`screenRecommendation`, `lib.ts:70-87`) and its fail-closed fallback."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+from jev_mcp.policy.thresholds import SCREEN_RELEVANCE_SKIP_BELOW, SCREEN_SUBSTANCE_SKIP_BELOW
+from jev_mcp.serialize import number_to_string, to_fixed
+
+type ScreenAction = Literal["pass", "review", "block", "skip"]
+
+
+@dataclass(frozen=True, slots=True)
+class ScreenRecommendation:
+    action: ScreenAction
+    reason: str
+
+
+def screen_recommendation(
+    *,
+    injection: float,
+    block_at: float,
+    review_at: float,
+    relevance: float | None = None,
+    substance: float | None = None,
+) -> ScreenRecommendation:
+    """Block, then review, on injection; then skip on low substance, then low relevance; else pass.
+
+    `None` means the answer was not asked for. Probabilities print with `toFixed(2)` and thresholds
+    with `Number::toString`, as the reference's template literals do.
+    """
+    if injection >= block_at:
+        return ScreenRecommendation(
+            "block", f"injection probability {to_fixed(injection)} >= block threshold {number_to_string(block_at)}"
+        )
+    if injection >= review_at:
+        return ScreenRecommendation(
+            "review", f"injection probability {to_fixed(injection)} >= review threshold {number_to_string(review_at)}"
+        )
+    if substance is not None and substance < SCREEN_SUBSTANCE_SKIP_BELOW:
+        return ScreenRecommendation("skip", f"little substantive content (substance {to_fixed(substance)})")
+    if relevance is not None and relevance < SCREEN_RELEVANCE_SKIP_BELOW:
+        return ScreenRecommendation("skip", f"not relevant to the stated purpose (relevance {to_fixed(relevance)})")
+    return ScreenRecommendation("pass", "no signals above thresholds")
+
+
+def screen_fail_closed() -> ScreenRecommendation:
+    """A missing or malformed answer is not a clean bill of health: review, never pass."""
+    return ScreenRecommendation("review", "missing or malformed answers; cannot screen safely")

jev_mcp/policy/thresholds.py

@@ -0,0 +1,74 @@
+"""Policy thresholds: the reference defaults (`parity-manifest.json` `defaults`) and the review/gate pair.
+
+Every threshold a tool compares against lives here (ADR-0002); a tool that hardcodes one is a bug.
+"""
+
+import math
+from dataclasses import dataclass
+
+DEFAULT_AUTO_ACCEPT = 0.8
+"""jev_verify, jev_review, jev_gate (`index.ts:1304`, `index.ts:1378`)."""
+
+DEFAULT_REVIEW_AT_CAP = 0.5
+"""An omitted review_at becomes `min(0.5, auto_accept)` (`lib.ts:282`)."""
+
+DEFAULT_COMPOSITE_FLOOR = 0.7
+"""`lib.ts:238`."""
+
+DEFAULT_CLASSIFY_AUTO_ACCEPT = 0.85
+"""jev_classify, jev_compare, jev_extract."""
+
+DEFAULT_MINIMUM_MARGIN = 0.5
+"""jev_classify, jev_compare, jev_extract."""
+
+DEFAULT_SCREEN_BLOCK_AT = 0.75
+DEFAULT_SCREEN_REVIEW_AT = 0.25
+
+SCREEN_SUBSTANCE_SKIP_BELOW = 0.3
+"""Hardcoded in `screenRecommendation` (`lib.ts:82`), not a parameter."""
+
+SCREEN_RELEVANCE_SKIP_BELOW = 0.3
+"""Hardcoded in `screenRecommendation` (`lib.ts:84`), not a parameter."""
+
+EXISTS_FOUND_AT = 0.7
+"""`existsVerdict` default (`lib.ts:90`)."""
+
+EXISTS_ABSENT_BELOW = 0.35
+"""`existsVerdict` default (`lib.ts:90`)."""
+
+THRESHOLD_INVARIANT_MESSAGE = "Thresholds must satisfy 0 <= review_at <= auto_accept <= 1."
+"""The reference's thrown text (`lib.ts:273`); the tool reports it verbatim."""
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyThresholds:
+    """A validated review/gate threshold pair: 0 <= review_at <= auto_accept <= 1."""
+
+    auto_accept: float
+    review_at: float
+
+
+def validate_policy_thresholds(auto_accept: float, review_at: float) -> None:
+    """Raise `ValueError` unless both are finite and 0 <= review_at <= auto_accept <= 1 (`lib.ts:263-275`)."""
+    if (
+        not math.isfinite(auto_accept)
+        or not math.isfinite(review_at)
+        or auto_accept < 0
+        or auto_accept > 1
+        or review_at < 0
+        or review_at > 1
+        or review_at > auto_accept
+    ):
+        raise ValueError(THRESHOLD_INVARIANT_MESSAGE)
+
+
+def resolve_policy_thresholds(
+    auto_accept: float = DEFAULT_AUTO_ACCEPT, review_at: float | None = None
+) -> PolicyThresholds:
+    """Fill an omitted review_at so a lone low auto_accept cannot invert the pair, then validate (`lib.ts:278-285`).
+
+    Only `None` means omitted, as JS `??`: an explicit `review_at=0` stands.
+    """
+    resolved = review_at if review_at is not None else min(DEFAULT_REVIEW_AT_CAP, auto_accept)
+    validate_policy_thresholds(auto_accept, resolved)
+    return PolicyThresholds(auto_accept=auto_accept, review_at=resolved)

jev_mcp/providers/__init__.py

@@ -0,0 +1,26 @@
+"""Provider transports; they validate only the envelope (ADR-0003).
+
+`typesafe-sdk` is imported only when the TypeSafe provider sends its first request. A provider owns
+an HTTP client: whoever resolves one closes it with `aclose()`.
+"""
+
+from jev_mcp.providers.base import (
+    Evaluation,
+    JevProvider,
+    ProviderConfigError,
+    ProviderError,
+    ProviderName,
+    ProviderTimeoutError,
+)
+from jev_mcp.providers.resolver import resolve_model, resolve_provider
+
+__all__ = [
+    "Evaluation",
+    "JevProvider",
+    "ProviderConfigError",
+    "ProviderError",
+    "ProviderName",
+    "ProviderTimeoutError",
+    "resolve_model",
+    "resolve_provider",
+]

jev_mcp/providers/base.py

@@ -0,0 +1,236 @@
+"""The provider contract, uniform envelope validation (ADR-0003), and the shared error path.
+
+Every provider sends `{state, questions}` under a model name and returns an `Evaluation`. Adapters
+differ only in URL, auth, model slug, the request/response envelope, and usage. Everything else is
+here: the envelope rules the reference applies to `compatible` alone (`provider.ts:175-194`) apply to
+every provider, every error message passes through secret redaction (ADR-0008), and a timeout or an
+MCP cancellation aborts the in-flight request (ADR-0011).
+"""
+
+import logging
+import math
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import ClassVar, Literal, override
+from urllib.parse import urlsplit
+
+import anyio
+import httpx
+
+from jev_mcp.domain import JsonValue, Question, RawAnswer, Usage, as_number, decode_json, questions_to_wire
+from jev_mcp.errors import Redactor
+from jev_mcp.serialize import stringify_compact
+from jev_mcp.text import head
+
+type ProviderName = Literal["typesafe", "openrouter", "cloudflare", "compatible"]
+
+logger = logging.getLogger("jev_mcp.providers")
+
+ERROR_BODY_UNITS = 200
+"""Error bodies are cut to `.slice(0, 200)` UTF-16 units (`provider.ts:146,172,247`)."""
+
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+def _origin_of(url: str | httpx.URL) -> tuple[str, str, int]:
+    """The scheme/host/effective-port triple an origin comparison needs (ADR-0023)."""
+    parsed = url if isinstance(url, httpx.URL) else httpx.URL(url)
+    return (parsed.scheme, parsed.host or "", parsed.port or _DEFAULT_PORTS.get(parsed.scheme, 0))
+
+
+class ProviderError(Exception):
+    """A provider failure. Its text is MCP-visible, so `evaluate` redacts it before raising."""
+
+
+class ProviderConfigError(ProviderError):
+    """Provider resolution failed before any request (`provider.ts:35-77`)."""
+
+
+class ProviderTimeoutError(ProviderError):
+    """The request did not complete within the caller's timeout."""
+
+
+@dataclass(frozen=True, slots=True)
+class Evaluation:
+    """One provider reply: raw answers for per-tool validation, plus usage and the model to report."""
+
+    answers: dict[str, RawAnswer]
+    usage: Usage
+    provider: ProviderName
+    model: str
+
+
+@dataclass(frozen=True, slots=True)
+class Envelope:
+    """A reply envelope that passed `parse_envelope`. `model` is `None` when the body carried none."""
+
+    answers: dict[str, RawAnswer]
+    usage: Usage
+    model: str | None
+
+    def model_or(self, default: str) -> str:
+        return default if self.model is None else self.model
+
+
+def parse_envelope(body: object, label: str) -> Envelope:
+    """Validate the envelope only, with the reference's `compatible` rules and messages (`provider.ts:175-194`).
+
+    `usage` absent or null reports zeros; otherwise both counts must be finite non-negative numbers.
+    `model` must be absent, null, or a string. Per-answer validity is each tool's job.
+    """
+
+    def invalid(why: str) -> ProviderError:
+        return ProviderError(f"{label} returned an invalid response: {why}")
+
+    if not isinstance(body, dict):
+        raise invalid("expected a JSON object.")
+    envelope: dict[str, object] = body  # pyright: ignore[reportUnknownVariableType]
+    answers = envelope.get("answers")
+    if not isinstance(answers, dict):
+        raise invalid("expected an answers object.")
+    usage = Usage()
+    raw_usage = envelope.get("usage")
+    if raw_usage is not None:
+        counts = _usage_counts(raw_usage)
+        if counts is None:
+            raise invalid("usage must report finite non-negative input_tokens and output_tokens.")
+        usage = Usage(*counts)
+    model = envelope.get("model")
+    if model is not None and not isinstance(model, str):
+        raise invalid("model must be absent or a string.")
+    return Envelope(answers=answers, usage=usage, model=model)  # pyright: ignore[reportUnknownArgumentType]
+
+
+def _usage_counts(usage: object) -> tuple[int | float, int | float] | None:
+    if not isinstance(usage, dict):
+        return None
+    record: dict[str, object] = usage  # pyright: ignore[reportUnknownVariableType]
+    counts: list[int | float] = []
+    for key in ("input_tokens", "output_tokens"):
+        value = record.get(key)
+        number = as_number(value)
+        if number is None or not math.isfinite(number) or number < 0:
+            return None
+        counts.append(value if isinstance(value, int) else number)
+    return counts[0], counts[1]
+
+
+def decode_text(content: bytes) -> str:
+    """`await response.text()`: UTF-8 with replacement characters, a leading BOM dropped."""
+    return content.decode("utf-8", errors="replace").removeprefix("")
+
+
+def decode_body(content: bytes) -> object | None:
+    """`await response.json().catch(() => null)`: `None` for a body `JSON.parse` would reject."""
+    try:
+        return decode_json(decode_text(content))
+    except ValueError:
+        return None
+
+
+def refuse_credentials_in_url(url: str, label: str) -> None:
+    """Node `fetch` refuses a URL with userinfo, so the reference fails there; failing is also safer here.
+
+    `httpx` would turn the userinfo into Basic auth and overwrite the Bearer header. The text is
+    V8's minus the URL, which redaction would blank anyway (ADR-0008).
+    """
+    if urlsplit(url).netloc.rpartition("@")[1]:
+        raise ProviderError(
+            f"{label} request failed: Request cannot be constructed from a URL that includes credentials"
+        )
+
+
+def encode_json(value: object) -> bytes:
+    """`JSON.stringify(value)` as the request body."""
+    return stringify_compact(value).encode("utf-8")
+
+
+class JevProvider(ABC):
+    """A transport to Jev. `evaluate` is the only entry point; adapters implement `_send`."""
+
+    name: ClassVar[ProviderName]
+    label: ClassVar[str]
+    """Prefix of this provider's error messages."""
+
+    def __init__(self, redact: Redactor) -> None:
+        self._redact = redact
+
+    async def evaluate(
+        self, state: JsonValue, questions: Mapping[str, Question], model: str, timeout: float | None
+    ) -> Evaluation:
+        """Ask Jev `questions` about `state`. `timeout` bounds the whole call, in seconds; `None` waits.
+
+        Raises `ProviderError` with redacted text. Cancellation of the calling task propagates and
+        aborts the request (ADR-0011).
+        """
+        wire = questions_to_wire(questions)
+        try:
+            with anyio.fail_after(timeout):
+                return await self._send(state, wire, model, timeout)
+        except ProviderError as error:
+            raise type(error)(self._redact(str(error))) from None
+        except (TimeoutError, httpx.TimeoutException):
+            after = "" if timeout is None else f" after {timeout:g} s"
+            raise ProviderTimeoutError(f"{self.label} request timed out{after}.") from None
+        except Exception as error:
+            # The original may carry a secret-bearing URL or header; only the redacted text leaves.
+            # Some carry no message at all (a reset is a bare `RemoteProtocolError`): name the type.
+            cause = str(error) or type(error).__name__
+            raise ProviderError(self._redact(f"{self.label} request failed: {cause}")) from None
+
+    @abstractmethod
+    async def _send(
+        self, state: JsonValue, questions: dict[str, JsonValue], model: str, timeout: float | None
+    ) -> Evaluation: ...
+
+    def _status_error(self, status: int | str, body: str) -> ProviderError:
+        """`{label} {status}: {body}`, the body redacted and then cut to 200 units (`provider.ts:172`).
+
+        Redacting first means a secret straddling the cut cannot leak its head.
+        """
+        return ProviderError(f"{self.label} {status}: {head(self._redact(body), ERROR_BODY_UNITS)}")
+
+    @abstractmethod
+    async def aclose(self) -> None:
+        """Release network resources."""
+
+
+class HttpProvider(JevProvider):
+    """A provider that POSTs JSON with `httpx`, as the reference does with `fetch` — except that a
+    redirect may never leave the origin the first request used (ADR-0023): the reference's `fetch`
+    would re-send the caller's state to a cross-origin 307/308 target, and the state is more
+    sensitive than the credential (which httpx strips there anyway). httpx still builds every
+    redirect request itself — method semantics and the redirect cap are httpx's, not ours; the
+    hook below only refuses the hop before it is sent.
+    """
+
+    def __init__(self, redact: Redactor, client: httpx.AsyncClient | None = None) -> None:
+        super().__init__(redact)
+        # The allowed origin is fixed per instance: it comes from process config (ADR-0008), so the
+        # lazy first-request assignment races only with itself, writing the same value.
+        self._origin: tuple[str, str, int] | None = None
+        # Like `fetch`: no timeout of its own (`evaluate` owns the deadline), and redirects are followed.
+        self._client = client or httpx.AsyncClient(
+            timeout=None,  # noqa: S113 - `evaluate` owns the deadline
+            follow_redirects=True,
+            event_hooks={"request": [self._reject_cross_origin]},
+        )
+
+    async def _reject_cross_origin(self, request: httpx.Request) -> None:
+        """Async: the client awaits every request hook, redirects included."""
+        origin = _origin_of(request.url)
+        if self._origin is None:
+            self._origin = origin
+        elif origin != self._origin:
+            logger.warning("blocked a cross-origin redirect to %s://%s", request.url.scheme, request.url.host)
+            raise ProviderError(f"{self.label} request failed: a redirect left the configured origin and was blocked")
+
+    async def _post(self, url: str, headers: Mapping[str, str], body: object) -> httpx.Response:
+        return await self._client.post(
+            url, content=encode_json(body), headers={**headers, "Content-Type": "application/json"}
+        )
+
+    @override
+    async def aclose(self) -> None:
+        await self._client.aclose()