blun-king-cli 9.1.587 → 9.1.588

package/standard-skills/translate-native/integrations/website_localization_deepl_baseline.py

@@ -0,0 +1,922 @@
+#!/usr/bin/env python3
+"""Secure acquisition of DeepL benchmark baselines and lawful fixtures.
+
+The adapter calls only DeepL's documented API origins. It discovers stable
+language support at runtime, sends exactly one complete source document, and
+returns text-free provenance evidence beside the attested baseline artifact.
+The durable store binds an exact acquisition to its route, policy, and job so a
+worker restart cannot silently replace it. Credentials never enter artifacts,
+evidence, exceptions, persisted state, or object reprs.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import math
+import re
+import socket
+import sqlite3
+import sys
+import time
+import unicodedata
+import urllib.error
+import urllib.request
+from contextlib import contextmanager
+from dataclasses import dataclass, fields, is_dataclass
+from pathlib import Path
+from typing import Any, Callable, Iterator, Mapping, Protocol
+
+
+EVIDENCE_SCHEMA = "blun.website-localization-deepl-api-evidence.v1"
+FIXTURE_EVIDENCE_SCHEMA = "blun.website-localization-lawful-baseline-fixture.v1"
+OFFICIAL_ORIGINS = {
+    "free": "https://api-free.deepl.com",
+    "pro": "https://api.deepl.com",
+}
+LANGUAGES_PATH = "/v3/languages?resource=translate_text"
+TRANSLATE_PATH = "/v2/translate"
+MAX_REQUEST_BYTES = 128 * 1024
+MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+MAX_AUTH_BYTES = 16 * 1024
+MAX_LANGUAGES = 10_000
+BCP47 = re.compile(r"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8}){0,8}$")
+ERROR_CODE = re.compile(r"^[a-z][a-z0-9_.-]{0,127}$")
+RIGHTS_BASES = frozenset(("owned", "licensed", "permission"))
+STORE_SCHEMA = "blun.website-localization-baseline-acquisition-store.v1"
+STORE_COLUMNS = (
+    "acquisition_id", "route_id", "policy_sha256", "job_sha256",
+    "artifact_json", "artifact_sha256", "evidence_json", "evidence_sha256",
+    "created_at",
+)
+
+
+def _load_module(name: str, path: Path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot load baseline dependency: {path.name}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+_ROOT = Path(__file__).resolve().parents[1]
+_BENCHMARK = _load_module(
+    "blun_website_localization_deepl_benchmark",
+    _ROOT / "integrations" / "website_localization_benchmark.py",
+)
+_WORKER = _BENCHMARK._WORKER
+_SUITE = _BENCHMARK._SUITE
+
+
+class DeepLBaselineFailed(RuntimeError):
+    """Content-free acquisition failure understood by durable orchestration."""
+
+    benchmark_campaign_dependency_failure = True
+
+    def __init__(self, code: str, *, retryable: bool):
+        if not isinstance(code, str) or ERROR_CODE.fullmatch(code) is None:
+            raise ValueError("baseline error code is invalid")
+        if not isinstance(retryable, bool):
+            raise ValueError("baseline retryability must be boolean")
+        super().__init__(code)
+        self.code = code
+        self.retryable = retryable
+
+
+@dataclass(frozen=True)
+class HTTPResult:
+    status: int
+    headers: tuple[tuple[str, str], ...]
+    body: bytes
+
+
+class HTTPTransport(Protocol):
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        *,
+        timeout: float,
+    ) -> HTTPResult: ...
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class URLTransport:
+    """One bounded stdlib HTTPS attempt with redirects disabled."""
+
+    def __init__(self):
+        self._opener = urllib.request.build_opener(_NoRedirect)
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        *,
+        timeout: float,
+    ) -> HTTPResult:
+        request = urllib.request.Request(
+            url, data=body, headers=dict(headers), method=method,
+        )
+        try:
+            response = self._opener.open(request, timeout=timeout)
+        except urllib.error.HTTPError as error:
+            return HTTPResult(
+                int(error.code),
+                tuple(error.headers.items()) if error.headers is not None else (),
+                b"",
+            )
+        except (urllib.error.URLError, TimeoutError, socket.timeout, OSError):
+            raise DeepLBaselineFailed("deepl.network", retryable=True) from None
+        try:
+            content = response.read(MAX_RESPONSE_BYTES + 1)
+            return HTTPResult(
+                int(response.status), tuple(response.headers.items()), content,
+            )
+        except (TimeoutError, socket.timeout, OSError):
+            raise DeepLBaselineFailed("deepl.network", retryable=True) from None
+        finally:
+            response.close()
+
+
+@dataclass(frozen=True)
+class BaselineAcquisition:
+    artifact: dict[str, Any]
+    evidence: dict[str, Any]
+
+
+def _canonical_json(value: Any, *, code: str, maximum: int) -> str:
+    return _json_bytes(value, code=code, maximum=maximum).decode("utf-8")
+
+
+def _parse_stored_json(value: Any) -> Any:
+    if not isinstance(value, str) or not value:
+        raise DeepLBaselineFailed("baseline.store.state_invalid", retryable=False)
+    try:
+        if len(value.encode("utf-8")) > MAX_RESPONSE_BYTES:
+            raise ValueError("stored JSON is too large")
+        return json.loads(
+            value, object_pairs_hook=_pairs, parse_constant=_constant,
+        )
+    except (UnicodeEncodeError, ValueError, RecursionError):
+        raise DeepLBaselineFailed("baseline.store.state_invalid", retryable=False) from None
+
+
+def _timestamp(value: Any) -> float:
+    value = time.time() if value is None else value
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(float(value))
+        or float(value) < 0
+    ):
+        raise DeepLBaselineFailed("baseline.store.time_invalid", retryable=False)
+    return float(value)
+
+
+def _policy_sha256(policy: Any) -> str:
+    try:
+        validated = _BENCHMARK._validate_policy(policy)
+        payload = {
+            field: getattr(validated, field)
+            for field in validated.__dataclass_fields__
+        }
+    except Exception:
+        raise DeepLBaselineFailed("baseline.store.binding_invalid", retryable=False) from None
+    return _hash_bytes(_json_bytes(
+        payload, code="baseline.store.binding_invalid", maximum=MAX_RESPONSE_BYTES,
+    ))
+
+
+def _job_sha256(job_payload: Any, policy: Any) -> tuple[dict[str, Any], str]:
+    job = _validated_job(job_payload, policy)
+    return job, _hash_bytes(_json_bytes(
+        job, code="baseline.store.binding_invalid", maximum=MAX_RESPONSE_BYTES,
+    ))
+
+
+def _validate_acquisition(
+    acquisition: Any,
+    job_payload: Any,
+    policy: Any,
+    evidence_authority: Any,
+) -> BaselineAcquisition:
+    if not isinstance(acquisition, BaselineAcquisition):
+        expected = tuple(field.name for field in fields(BaselineAcquisition))
+        try:
+            actual = tuple(field.name for field in fields(acquisition))
+            parameters = type(acquisition).__dataclass_params__
+            valid = (
+                is_dataclass(acquisition)
+                and not isinstance(acquisition, type)
+                and type(acquisition).__name__ == BaselineAcquisition.__name__
+                and parameters.frozen is True
+                and actual == expected
+            )
+            if not valid:
+                raise TypeError("incompatible baseline acquisition")
+            acquisition = BaselineAcquisition(**{
+                field: getattr(acquisition, field) for field in expected
+            })
+        except Exception:
+            raise DeepLBaselineFailed(
+                "baseline.store.acquisition_invalid", retryable=False,
+            ) from None
+    job = _validated_job(job_payload, policy)
+    try:
+        artifact = _BENCHMARK._validate_baseline(
+            job, acquisition.artifact, policy, evidence_authority,
+        )
+    except Exception:
+        raise DeepLBaselineFailed("baseline.store.acquisition_invalid", retryable=False) from None
+    evidence = acquisition.evidence
+    if not isinstance(evidence, dict):
+        raise DeepLBaselineFailed("baseline.store.acquisition_invalid", retryable=False)
+    evidence_json = _canonical_json(
+        evidence, code="baseline.store.acquisition_invalid",
+        maximum=MAX_RESPONSE_BYTES,
+    )
+    evidence_sha256 = _hash_text(evidence_json)
+    provenance = artifact["provenance"]
+    method = provenance["method"]
+    common = (
+        provenance["evidence_sha256"] == evidence_sha256,
+        evidence.get("source_sha256") == job["source"]["sha256"],
+        evidence.get("target_locale") == job["target"]["locale"],
+        evidence.get("target_sha256") == artifact["target_sha256"],
+    )
+    if method == "official_api":
+        expected = {
+            "schema", "provider", "origin", "languages_response_sha256",
+            "request_sha256", "response_sha256", "source_sha256",
+            "source_locale", "source_language", "target_locale",
+            "target_language", "target_sha256", "model_type_used",
+        }
+        valid = (
+            set(evidence) == expected
+            and evidence.get("schema") == EVIDENCE_SCHEMA
+            and evidence.get("provider") == "DeepL"
+            and evidence.get("origin") in OFFICIAL_ORIGINS.values()
+            and evidence.get("source_locale") == job["source"]["locale"]
+            and provenance["evidence_id"] == "deepl-api:" + evidence_sha256
+        )
+        for field in (
+            "languages_response_sha256", "request_sha256", "response_sha256",
+        ):
+            try:
+                _sha256(
+                    evidence.get(field),
+                    code="baseline.store.acquisition_invalid",
+                )
+            except DeepLBaselineFailed:
+                valid = False
+        for field in ("source_language", "target_language"):
+            if (
+                not isinstance(evidence.get(field), str)
+                or BCP47.fullmatch(evidence[field]) is None
+            ):
+                valid = False
+        model = evidence.get("model_type_used")
+        if model is not None and (
+            not isinstance(model, str) or not model or len(model) > 128
+        ):
+            valid = False
+    elif method == "lawful_fixture":
+        expected = {
+            "schema", "fixture_id", "fixture_revision", "supplier_id",
+            "rights_basis", "rights_evidence_sha256", "source_sha256",
+            "target_locale", "target_sha256",
+        }
+        valid = (
+            set(evidence) == expected
+            and evidence.get("schema") == FIXTURE_EVIDENCE_SCHEMA
+            and evidence.get("rights_basis") in RIGHTS_BASES
+            and provenance["evidence_id"] == "lawful-fixture:" + evidence_sha256
+        )
+        try:
+            for field in ("fixture_id", "fixture_revision", "supplier_id"):
+                _identifier(evidence.get(field), code="baseline.store.acquisition_invalid")
+            _sha256(
+                evidence.get("rights_evidence_sha256"),
+                code="baseline.store.acquisition_invalid",
+            )
+        except DeepLBaselineFailed:
+            valid = False
+    else:
+        valid = False
+    if not valid or not all(common):
+        raise DeepLBaselineFailed("baseline.store.acquisition_invalid", retryable=False)
+    return BaselineAcquisition(artifact=artifact, evidence=json.loads(evidence_json))
+
+
+@contextmanager
+def _transaction(connection: sqlite3.Connection) -> Iterator[None]:
+    if connection.in_transaction:
+        raise DeepLBaselineFailed("baseline.store.external_transaction", retryable=False)
+    try:
+        connection.execute("BEGIN IMMEDIATE")
+        yield
+    except Exception:
+        connection.rollback()
+        raise
+    else:
+        connection.commit()
+
+
+class BaselineAcquisitionStore:
+    """Durable exact-output recovery for one attested baseline acquisition."""
+
+    def __init__(self, connection: sqlite3.Connection):
+        if not isinstance(connection, sqlite3.Connection):
+            raise DeepLBaselineFailed(
+                "baseline.store.connection_invalid", retryable=False,
+            )
+        self.connection = connection
+        self.connection.row_factory = sqlite3.Row
+        self.connection.execute("PRAGMA busy_timeout = 5000")
+        with _transaction(self.connection):
+            self.connection.execute("""
+                CREATE TABLE IF NOT EXISTS benchmark_baseline_acquisitions (
+                    acquisition_id TEXT PRIMARY KEY,
+                    route_id TEXT NOT NULL,
+                    policy_sha256 TEXT NOT NULL,
+                    job_sha256 TEXT NOT NULL,
+                    artifact_json TEXT NOT NULL,
+                    artifact_sha256 TEXT NOT NULL,
+                    evidence_json TEXT NOT NULL,
+                    evidence_sha256 TEXT NOT NULL,
+                    created_at REAL NOT NULL,
+                    UNIQUE(route_id, policy_sha256, job_sha256)
+                )
+            """)
+        columns = tuple(
+            row[1] for row in self.connection.execute(
+                "PRAGMA table_info(benchmark_baseline_acquisitions)"
+            ).fetchall()
+        )
+        if columns != STORE_COLUMNS:
+            raise DeepLBaselineFailed(
+                "baseline.store.schema_unsupported", retryable=False,
+            )
+
+    @staticmethod
+    def _identity(
+        job_payload: Any, policy: Any, route_id: Any,
+    ) -> tuple[str, str, str, str]:
+        route = _identifier(route_id, code="baseline.store.route_invalid")
+        _, job_sha256 = _job_sha256(job_payload, policy)
+        policy_sha256 = _policy_sha256(policy)
+        acquisition_id = "baseline-acquisition:" + _hash_bytes(_json_bytes(
+            {
+                "schema": STORE_SCHEMA,
+                "route_id": route,
+                "policy_sha256": policy_sha256,
+                "job_sha256": job_sha256,
+            },
+            code="baseline.store.binding_invalid", maximum=MAX_RESPONSE_BYTES,
+        ))
+        return acquisition_id, route, policy_sha256, job_sha256
+
+    def load(
+        self, job_payload: Any, policy: Any, route_id: Any, *,
+        evidence_authority: Any,
+    ) -> BaselineAcquisition | None:
+        identity = self._identity(job_payload, policy, route_id)
+        row = self.connection.execute("""
+            SELECT * FROM benchmark_baseline_acquisitions
+            WHERE acquisition_id = ?
+        """, (identity[0],)).fetchone()
+        if row is None:
+            return None
+        if (
+            tuple(row.keys()) != STORE_COLUMNS
+            or tuple(row[name] for name in STORE_COLUMNS[:4]) != identity
+            or isinstance(row["created_at"], bool)
+            or not isinstance(row["created_at"], (int, float))
+            or not math.isfinite(float(row["created_at"]))
+            or float(row["created_at"]) < 0
+        ):
+            raise DeepLBaselineFailed("baseline.store.state_invalid", retryable=False)
+        artifact_json = row["artifact_json"]
+        evidence_json = row["evidence_json"]
+        if (
+            not isinstance(artifact_json, str)
+            or not isinstance(evidence_json, str)
+            or row["artifact_sha256"] != _hash_text(artifact_json)
+            or row["evidence_sha256"] != _hash_text(evidence_json)
+        ):
+            raise DeepLBaselineFailed("baseline.store.state_invalid", retryable=False)
+        acquisition = BaselineAcquisition(
+            artifact=_parse_stored_json(artifact_json),
+            evidence=_parse_stored_json(evidence_json),
+        )
+        return _validate_acquisition(
+            acquisition, job_payload, policy, evidence_authority,
+        )
+
+    def save(
+        self, job_payload: Any, policy: Any, route_id: Any,
+        acquisition: Any, *, evidence_authority: Any, now: Any = None,
+    ) -> BaselineAcquisition:
+        identity = self._identity(job_payload, policy, route_id)
+        verified = _validate_acquisition(
+            acquisition, job_payload, policy, evidence_authority,
+        )
+        artifact_json = _canonical_json(
+            verified.artifact, code="baseline.store.acquisition_invalid",
+            maximum=MAX_RESPONSE_BYTES,
+        )
+        evidence_json = _canonical_json(
+            verified.evidence, code="baseline.store.acquisition_invalid",
+            maximum=MAX_RESPONSE_BYTES,
+        )
+        values = identity + (
+            artifact_json, _hash_text(artifact_json), evidence_json,
+            _hash_text(evidence_json), _timestamp(now),
+        )
+        with _transaction(self.connection):
+            self.connection.execute("""
+                INSERT OR IGNORE INTO benchmark_baseline_acquisitions
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, values)
+        stored = self.load(
+            job_payload, policy, route_id,
+            evidence_authority=evidence_authority,
+        )
+        if stored != verified:
+            raise DeepLBaselineFailed("baseline.store.conflict", retryable=False)
+        return stored
+
+
+def resolve_baseline_acquisition(
+    store: BaselineAcquisitionStore,
+    job_payload: Any,
+    policy: Any,
+    route_id: Any,
+    acquire: Callable[[], BaselineAcquisition],
+    *,
+    evidence_authority: Any,
+    now: Any = None,
+) -> BaselineAcquisition:
+    """Reuse exact verified state, otherwise acquire once and persist before review."""
+    if not isinstance(store, BaselineAcquisitionStore):
+        raise TypeError("store must be BaselineAcquisitionStore")
+    if not callable(acquire):
+        raise TypeError("acquire must be callable")
+    cached = store.load(
+        job_payload, policy, route_id, evidence_authority=evidence_authority,
+    )
+    if cached is not None:
+        return cached
+    acquired = acquire()
+    return store.save(
+        job_payload, policy, route_id, acquired,
+        evidence_authority=evidence_authority, now=now,
+    )
+
+
+@dataclass(frozen=True)
+class _LanguageCapability:
+    code: str
+    source: bool
+    target: bool
+
+
+def _pairs(items):
+    result = {}
+    for key, value in items:
+        if key in result:
+            raise ValueError("duplicate JSON key")
+        result[key] = value
+    return result
+
+
+def _constant(value):
+    raise ValueError("non-finite JSON number")
+
+
+def _json_bytes(value: Any, *, code: str, maximum: int) -> bytes:
+    try:
+        encoded = json.dumps(
+            value, ensure_ascii=False, allow_nan=False, sort_keys=True,
+            separators=(",", ":"),
+        ).encode("utf-8")
+    except (TypeError, ValueError, RecursionError):
+        raise DeepLBaselineFailed(code, retryable=False) from None
+    if not encoded or len(encoded) > maximum:
+        raise DeepLBaselineFailed(code, retryable=False)
+    return encoded
+
+
+def _hash_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _hash_text(value: str) -> str:
+    return _hash_bytes(value.encode("utf-8"))
+
+
+def _sha256(value: Any, *, code: str) -> str:
+    if not isinstance(value, str) or re.fullmatch(r"[0-9a-f]{64}", value) is None:
+        raise DeepLBaselineFailed(code, retryable=False)
+    return value
+
+
+def _identifier(value: Any, *, code: str) -> str:
+    if not isinstance(value, str) or _BENCHMARK.IDENTIFIER.fullmatch(value) is None:
+        raise DeepLBaselineFailed(code, retryable=False)
+    return value
+
+
+def _response_headers(headers: Any) -> dict[str, str]:
+    if not isinstance(headers, tuple):
+        raise DeepLBaselineFailed("deepl.transport_invalid", retryable=True)
+    selected: dict[str, str] = {}
+    for item in headers:
+        if (
+            not isinstance(item, tuple)
+            or len(item) != 2
+            or not all(isinstance(part, str) for part in item)
+        ):
+            raise DeepLBaselineFailed("deepl.transport_invalid", retryable=True)
+        name, value = item[0].lower(), item[1].strip()
+        if name in {"content-type", "content-length"}:
+            if name in selected:
+                raise DeepLBaselineFailed("deepl.response_headers", retryable=True)
+            selected[name] = value
+    return selected
+
+
+def _parse_success(result: Any) -> tuple[Any, str]:
+    if (
+        not isinstance(result, HTTPResult)
+        or isinstance(result.status, bool)
+        or not isinstance(result.status, int)
+    ):
+        raise DeepLBaselineFailed("deepl.transport_invalid", retryable=True)
+    status = result.status
+    if status != 200:
+        retryable = status == 429 or 500 <= status <= 599
+        if status == 403:
+            code = "deepl.authentication"
+        elif status == 456:
+            code = "deepl.quota_exceeded"
+        elif status == 429:
+            code = "deepl.rate_limited"
+        elif 500 <= status <= 599:
+            code = "deepl.unavailable"
+        else:
+            code = "deepl.http_error"
+        raise DeepLBaselineFailed(code, retryable=retryable)
+    headers = _response_headers(result.headers)
+    content_type = headers.get("content-type", "").lower()
+    if content_type.split(";", 1)[0].strip() != "application/json":
+        raise DeepLBaselineFailed("deepl.response_headers", retryable=True)
+    if not isinstance(result.body, bytes) or len(result.body) > MAX_RESPONSE_BYTES:
+        raise DeepLBaselineFailed("deepl.response_too_large", retryable=True)
+    length = headers.get("content-length")
+    if length:
+        if not length.isdigit() or int(length) != len(result.body):
+            raise DeepLBaselineFailed("deepl.response_headers", retryable=True)
+    if not result.body or result.body.startswith(b"\xef\xbb\xbf"):
+        raise DeepLBaselineFailed("deepl.response_invalid", retryable=True)
+    try:
+        value = json.loads(
+            result.body.decode("utf-8"), object_pairs_hook=_pairs,
+            parse_constant=_constant,
+        )
+    except (UnicodeDecodeError, ValueError, RecursionError):
+        raise DeepLBaselineFailed("deepl.response_invalid", retryable=True) from None
+    return value, _hash_bytes(result.body)
+
+
+def _validated_job(job_payload: Any, policy: Any) -> dict[str, Any]:
+    try:
+        policy = _BENCHMARK._validate_policy(policy)
+        job = _WORKER._validated_job(job_payload)
+        _BENCHMARK._validate_candidate_job_binding(job, policy)
+        if job["target"]["locale"] not in policy.required_locales:
+            raise DeepLBaselineFailed("deepl.locale_not_required", retryable=False)
+        _SUITE.case_for_job(job)
+    except DeepLBaselineFailed:
+        raise
+    except Exception:
+        raise DeepLBaselineFailed("deepl.job_invalid", retryable=False) from None
+    return job
+
+
+class DeepLBaselineAdapter:
+    """Acquire one current official-API baseline for one exact benchmark job."""
+
+    def __init__(
+        self,
+        account_tier: str,
+        api_key_provider: Callable[[], str],
+        *,
+        transport: HTTPTransport | None = None,
+        timeout: float = 30.0,
+        language_cache_seconds: float = 3600.0,
+        clock: Callable[[], float] = time.time,
+        operation_guard: Callable[[], Any] | None = None,
+    ):
+        if account_tier not in OFFICIAL_ORIGINS:
+            raise ValueError("account_tier must be free or pro")
+        if not callable(api_key_provider):
+            raise TypeError("api_key_provider must be callable")
+        if (
+            isinstance(timeout, bool)
+            or not isinstance(timeout, (int, float))
+            or not math.isfinite(float(timeout))
+            or not 0 < float(timeout) <= 300
+        ):
+            raise ValueError("timeout is outside the supported range")
+        if (
+            isinstance(language_cache_seconds, bool)
+            or not isinstance(language_cache_seconds, (int, float))
+            or not math.isfinite(float(language_cache_seconds))
+            or not 0 <= float(language_cache_seconds) <= 3600
+        ):
+            raise ValueError("language_cache_seconds is outside the supported range")
+        if not callable(clock):
+            raise TypeError("clock must be callable")
+        if operation_guard is not None and not callable(operation_guard):
+            raise TypeError("operation_guard must be callable")
+        self._origin = OFFICIAL_ORIGINS[account_tier]
+        self._api_key_provider = api_key_provider
+        self._transport = URLTransport() if transport is None else transport
+        if not callable(getattr(self._transport, "request", None)):
+            raise TypeError("transport must provide request")
+        self._timeout = float(timeout)
+        self._cache_seconds = float(language_cache_seconds)
+        self._clock = clock
+        self._operation_guard = operation_guard
+        self._language_cache: tuple[
+            float, dict[str, _LanguageCapability], str
+        ] | None = None
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(origin={self._origin!r})"
+
+    def _headers(self, *, content: bool) -> dict[str, str]:
+        try:
+            key = self._api_key_provider()
+        except Exception:
+            raise DeepLBaselineFailed("deepl.authentication", retryable=False) from None
+        if (
+            not isinstance(key, str)
+            or not key
+            or key != key.strip()
+            or not key.isascii()
+            or len(key.encode("ascii")) > MAX_AUTH_BYTES
+            or any(ord(character) < 33 or ord(character) == 127 for character in key)
+        ):
+            raise DeepLBaselineFailed("deepl.authentication", retryable=False)
+        headers = {
+            "Accept": "application/json",
+            "Authorization": "DeepL-Auth-Key " + key,
+            "User-Agent": "translate-native-benchmark/1",
+        }
+        if content:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+    def _request(
+        self, method: str, path: str, body: bytes | None,
+    ) -> tuple[Any, str]:
+        if self._operation_guard is not None:
+            try:
+                self._operation_guard()
+            except Exception:
+                raise DeepLBaselineFailed(
+                    "deepl.operation_guard_failed", retryable=True,
+                ) from None
+        try:
+            result = self._transport.request(
+                method, self._origin + path,
+                self._headers(content=body is not None), body,
+                timeout=self._timeout,
+            )
+        except DeepLBaselineFailed:
+            raise
+        except Exception:
+            raise DeepLBaselineFailed("deepl.transport_failed", retryable=True) from None
+        return _parse_success(result)
+
+    def _languages(self) -> tuple[dict[str, _LanguageCapability], str]:
+        try:
+            now = float(self._clock())
+        except Exception:
+            raise DeepLBaselineFailed("deepl.clock_invalid", retryable=False) from None
+        if not math.isfinite(now) or now < 0:
+            raise DeepLBaselineFailed("deepl.clock_invalid", retryable=False)
+        if self._language_cache is not None:
+            cached_at, capabilities, response_sha256 = self._language_cache
+            if now - cached_at < self._cache_seconds:
+                return capabilities, response_sha256
+        payload, response_sha256 = self._request("GET", LANGUAGES_PATH, None)
+        if not isinstance(payload, list) or not 1 <= len(payload) <= MAX_LANGUAGES:
+            raise DeepLBaselineFailed("deepl.languages_invalid", retryable=True)
+        capabilities: dict[str, _LanguageCapability] = {}
+        for item in payload:
+            if not isinstance(item, dict):
+                raise DeepLBaselineFailed("deepl.languages_invalid", retryable=True)
+            code = item.get("lang")
+            source = item.get("usable_as_source")
+            target = item.get("usable_as_target")
+            if (
+                not isinstance(code, str)
+                or BCP47.fullmatch(code) is None
+                or not isinstance(source, bool)
+                or not isinstance(target, bool)
+                or item.get("status") != "stable"
+            ):
+                raise DeepLBaselineFailed("deepl.languages_invalid", retryable=True)
+            normalized = code.lower()
+            if normalized in capabilities:
+                raise DeepLBaselineFailed("deepl.languages_invalid", retryable=True)
+            capabilities[normalized] = _LanguageCapability(code, source, target)
+        self._language_cache = (now, capabilities, response_sha256)
+        return capabilities, response_sha256
+
+    @staticmethod
+    def _resolve_language(
+        locale: Any,
+        capabilities: Mapping[str, _LanguageCapability],
+        *,
+        source: bool,
+    ) -> str:
+        if not isinstance(locale, str) or BCP47.fullmatch(locale) is None:
+            raise DeepLBaselineFailed("deepl.locale_invalid", retryable=False)
+        normalized = locale.lower()
+        candidates = (normalized, normalized.split("-", 1)[0])
+        for candidate in dict.fromkeys(candidates):
+            capability = capabilities.get(candidate)
+            if capability is not None and (
+                capability.source if source else capability.target
+            ):
+                return capability.code
+        role = "source" if source else "target"
+        raise DeepLBaselineFailed(
+            f"deepl.{role}_language_unsupported", retryable=False,
+        )
+
+    def acquire(
+        self,
+        job_payload: Any,
+        policy: Any,
+        *,
+        evidence_authority: Any,
+    ) -> BaselineAcquisition:
+        job = _validated_job(job_payload, policy)
+        capabilities, capabilities_sha256 = self._languages()
+        source_code = self._resolve_language(
+            job["source"]["locale"], capabilities, source=True,
+        )
+        target_code = self._resolve_language(
+            job["target"]["locale"], capabilities, source=False,
+        )
+        if source_code.lower() == target_code.lower():
+            raise DeepLBaselineFailed("deepl.language_pair_invalid", retryable=False)
+        request_payload = {
+            "model_type": "prefer_quality_optimized",
+            "preserve_formatting": True,
+            "source_lang": source_code,
+            "target_lang": target_code,
+            "text": [job["source"]["text"]],
+        }
+        body = _json_bytes(
+            request_payload, code="deepl.request_too_large",
+            maximum=MAX_REQUEST_BYTES,
+        )
+        response, response_sha256 = self._request("POST", TRANSLATE_PATH, body)
+        if (
+            not isinstance(response, dict)
+            or set(response) != {"translations"}
+            or not isinstance(response["translations"], list)
+            or len(response["translations"]) != 1
+            or not isinstance(response["translations"][0], dict)
+        ):
+            raise DeepLBaselineFailed("deepl.translation_invalid", retryable=True)
+        translated = response["translations"][0]
+        target_text = translated.get("text")
+        detected = translated.get("detected_source_language")
+        model = translated.get("model_type_used")
+        if (
+            not isinstance(target_text, str)
+            or not target_text.strip()
+            or "\x00" in target_text
+            or not unicodedata.is_normalized("NFC", target_text)
+            or len(target_text.encode("utf-8")) > _BENCHMARK.MAX_TEXT_BYTES
+            or (detected is not None and (
+                not isinstance(detected, str)
+                or detected.lower().split("-", 1)[0]
+                != source_code.lower().split("-", 1)[0]
+            ))
+            or (model is not None and (
+                not isinstance(model, str)
+                or not model
+                or len(model) > 128
+            ))
+        ):
+            raise DeepLBaselineFailed("deepl.translation_invalid", retryable=True)
+        evidence = {
+            "schema": EVIDENCE_SCHEMA,
+            "provider": "DeepL",
+            "origin": self._origin,
+            "languages_response_sha256": capabilities_sha256,
+            "request_sha256": _hash_bytes(body),
+            "response_sha256": response_sha256,
+            "source_sha256": job["source"]["sha256"],
+            "source_locale": job["source"]["locale"],
+            "source_language": source_code,
+            "target_locale": job["target"]["locale"],
+            "target_language": target_code,
+            "target_sha256": _hash_text(target_text),
+            "model_type_used": model,
+        }
+        evidence_bytes = _json_bytes(
+            evidence, code="deepl.evidence_invalid", maximum=MAX_RESPONSE_BYTES,
+        )
+        evidence_sha256 = _hash_bytes(evidence_bytes)
+        provenance = {
+            "schema": _BENCHMARK.BASELINE_PROVENANCE_SCHEMA,
+            "method": "official_api",
+            "evidence_id": "deepl-api:" + evidence_sha256,
+            "evidence_sha256": evidence_sha256,
+        }
+        try:
+            artifact = _BENCHMARK.create_baseline_artifact(
+                job_payload, target_text, policy, provenance,
+                evidence_authority=evidence_authority,
+            )
+        except Exception:
+            raise DeepLBaselineFailed("deepl.attestation_failed", retryable=False) from None
+        return BaselineAcquisition(artifact=artifact, evidence=evidence)
+
+
+def create_lawful_fixture_acquisition(
+    job_payload: Any,
+    target_text: Any,
+    policy: Any,
+    fixture_evidence: Mapping[str, Any],
+    *,
+    evidence_authority: Any,
+) -> BaselineAcquisition:
+    """Attest a host-supplied fixed baseline with explicit rights evidence."""
+    job = _validated_job(job_payload, policy)
+    if (
+        not isinstance(target_text, str)
+        or not target_text.strip()
+        or "\x00" in target_text
+        or not unicodedata.is_normalized("NFC", target_text)
+        or len(target_text.encode("utf-8")) > _BENCHMARK.MAX_TEXT_BYTES
+    ):
+        raise DeepLBaselineFailed("fixture.target_invalid", retryable=False)
+    expected = {
+        "schema", "fixture_id", "fixture_revision", "supplier_id",
+        "rights_basis", "rights_evidence_sha256", "source_sha256",
+        "target_locale", "target_sha256",
+    }
+    if not isinstance(fixture_evidence, Mapping) or set(fixture_evidence) != expected:
+        raise DeepLBaselineFailed("fixture.evidence_invalid", retryable=False)
+    evidence = dict(fixture_evidence)
+    _identifier(evidence.get("fixture_id"), code="fixture.evidence_invalid")
+    _identifier(evidence.get("fixture_revision"), code="fixture.evidence_invalid")
+    _identifier(evidence.get("supplier_id"), code="fixture.evidence_invalid")
+    _sha256(evidence.get("rights_evidence_sha256"), code="fixture.evidence_invalid")
+    if (
+        evidence.get("schema") != FIXTURE_EVIDENCE_SCHEMA
+        or evidence.get("rights_basis") not in RIGHTS_BASES
+        or evidence.get("source_sha256") != job["source"]["sha256"]
+        or evidence.get("target_locale") != job["target"]["locale"]
+        or evidence.get("target_sha256") != _hash_text(target_text)
+    ):
+        raise DeepLBaselineFailed("fixture.evidence_invalid", retryable=False)
+    evidence_bytes = _json_bytes(
+        evidence, code="fixture.evidence_invalid", maximum=MAX_RESPONSE_BYTES,
+    )
+    evidence_sha256 = _hash_bytes(evidence_bytes)
+    provenance = {
+        "schema": _BENCHMARK.BASELINE_PROVENANCE_SCHEMA,
+        "method": "lawful_fixture",
+        "evidence_id": "lawful-fixture:" + evidence_sha256,
+        "evidence_sha256": evidence_sha256,
+    }
+    try:
+        artifact = _BENCHMARK.create_baseline_artifact(
+            job_payload, target_text, policy, provenance,
+            evidence_authority=evidence_authority,
+        )
+    except Exception:
+        raise DeepLBaselineFailed("fixture.attestation_failed", retryable=False) from None
+    return BaselineAcquisition(artifact=artifact, evidence=evidence)