mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/agent_runtime.py

@@ -0,0 +1,2743 @@
+"""Provider-neutral, deterministic runtime for bounded data-agent proposals.
+
+The runtime deliberately has no provider-package dependency. Provider adapters receive only a
+strict, versioned request and a closed tool policy.  They return untrusted structured data plus
+integer accounting; this module validates both before returning anything to a caller.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import re
+import stat
+import threading
+from collections.abc import Callable, Mapping, Sequence
+from copy import deepcopy
+from dataclasses import dataclass
+from datetime import UTC, date, datetime
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+AGENT_REQUEST_VERSION = "agent-request.v1"
+AGENT_RESPONSE_VERSION = "agent-response.v2"
+AGENT_EVIDENCE_VERSION = "agent-call-evidence.v1"
+AGENT_RUNTIME_VERSION = "agent-runtime.v1"
+REPLAY_CATALOG_VERSION = "agent-replay-catalog.v1"
+TOOL_POLICY_VERSION = "agent-tools.v1"
+SEMANTIC_REVIEW_INPUT_VERSION = "semantic-reviewer-input.v2"
+SEMANTIC_REVIEW_OUTPUT_VERSION = "semantic-reviewer-output.v2"
+MAX_ACCOUNTING_INTEGER = (1 << 63) - 1
+
+# One role per (input, output) schema pair, except semantic_reviewer, which accepts two live
+# input schemas rather than being split into two roles; the ROLE_PAYLOAD_SCHEMAS comment below
+# is the detail.
+AGENT_ROLES = frozenset(
+    {
+        "question_framer",
+        "feasibility_analyst",
+        "data_scout",
+        "source_auditor",
+        "plan_proposer",
+        "semantic_reviewer",
+        "repair_proposer",
+    }
+)
+# Every role uses an (input, output) schema pair derived from its own name.  The semantic
+# reviewer is the one exception: its output schema is v2, and its input accepts two live
+# schemas.  The v1 entry below is the identifier-only payload checked by _validate_role_input;
+# SEMANTIC_REVIEW_INPUT_VERSION names the v2 payload, which additionally requires the full
+# candidate evidence bundle and its digests.  _validate_role_payload dispatches on whichever
+# input version a request declares, so this table names only the v1 input.
+ROLE_PAYLOAD_SCHEMAS: Mapping[str, tuple[str, str]] = {
+    role: (
+        f"{role.replace('_', '-')}-input.v1",
+        f"{role.replace('_', '-')}-output.v1",
+    )
+    for role in sorted(AGENT_ROLES)
+}
+ROLE_PAYLOAD_SCHEMAS = {
+    **ROLE_PAYLOAD_SCHEMAS,
+    "data_scout": (
+        "data-scout-input.v1",
+        "data-scout-output.v2",
+    ),
+    "semantic_reviewer": (
+        "semantic-reviewer-input.v1",
+        SEMANTIC_REVIEW_OUTPUT_VERSION,
+    ),
+}
+_OUTCOMES = frozenset(
+    {
+        "succeeded",
+        "budget_exhausted_before_call",
+        "budget_exhausted_after_call",
+        "provider_exception",
+        "malformed_response",
+        "timed_out",
+        "cancelled",
+        "tool_policy_denied",
+    }
+)
+_IDENTIFIER = re.compile(r"^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$")
+_SECRET_HANDLE = re.compile(r"^shr_[A-Za-z0-9_-]{24,120}$")
+_SCOPE_IDENTIFIER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
+_SECRET_PURPOSES = frozenset({"provider_auth", "source_acquisition", "web_extraction"})
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+_WIRE_SHA256 = re.compile(r"^sha256:[0-9a-f]{64}$")
+_UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$")
+_FINDING_CODE = re.compile(r"^[A-Z][A-Z0-9_]{2,127}$")
+_ARTIFACT_KIND = re.compile(r"^[a-z][a-z0-9_]{1,63}$")
+_SEMANTIC_VERSION = re.compile(
+    r"^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)"
+    r"(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$"
+)
+_CANONICAL_UTC = re.compile(
+    r"^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])"
+    r"T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\.[0-9]{1,6})?Z$"
+)
+_CANONICAL_DATE = re.compile(r"^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$")
+_ACCOUNTING_STATUSES = frozenset({"reported", "unavailable_reserved", "not_applicable"})
+_PRE_DISPATCH_OUTCOMES = frozenset({"budget_exhausted_before_call", "tool_policy_denied"})
+
+
+class AgentRuntimeError(RuntimeError):
+    """Base class for typed runtime failures."""
+
+
+class RuntimeContractError(AgentRuntimeError, ValueError):
+    """A request, response, fixture, or provider accounting value is invalid."""
+
+
+class ToolPolicyError(RuntimeContractError):
+    """An agent request asks for a capability outside the closed policy."""
+
+
+class ReplayError(AgentRuntimeError):
+    """Base class for replay-catalog failures."""
+
+
+class ReplayMissError(ReplayError):
+    """No replay entry has the exact canonical request identity."""
+
+
+class ReplayAmbiguityError(ReplayError):
+    """More than one replay entry claims the same canonical request identity."""
+
+
+class ReplayTamperError(ReplayError):
+    """A replay member no longer matches its recorded hash."""
+
+
+class ReplayVersionError(ReplayError):
+    """A replay catalog or member uses an unsupported schema/policy version."""
+
+
+class ProviderTimeoutError(TimeoutError):
+    """Provider adapter reports a deterministic timeout."""
+
+
+@dataclass(frozen=True)
+class TimingEvidence:
+    """Integer-only timing metadata supplied by an injected monotonic clock."""
+
+    started_micros: int
+    finished_micros: int
+    elapsed_micros: int
+
+    def __post_init__(self) -> None:
+        _nonnegative_int(self.started_micros, "timing.started_micros")
+        _nonnegative_int(self.finished_micros, "timing.finished_micros")
+        _nonnegative_int(self.elapsed_micros, "timing.elapsed_micros")
+        if self.finished_micros < self.started_micros:
+            raise RuntimeContractError("timing.finished_micros cannot precede started_micros")
+        if self.elapsed_micros != self.finished_micros - self.started_micros:
+            raise RuntimeContractError("timing.elapsed_micros must equal finished minus started")
+
+    def to_dict(self) -> dict[str, int]:
+        return {
+            "started_micros": self.started_micros,
+            "finished_micros": self.finished_micros,
+            "elapsed_micros": self.elapsed_micros,
+        }
+
+
+@dataclass(frozen=True)
+class Usage:
+    """Validated, integer-safe provider usage."""
+
+    input_tokens: int
+    output_tokens: int
+    cost_micros: int
+    cached_input_tokens: int = 0
+    reasoning_tokens: int = 0
+    accounting_status: str = "reported"
+
+    def __post_init__(self) -> None:
+        _accounting_int(self.input_tokens, "usage.input_tokens")
+        _accounting_int(self.output_tokens, "usage.output_tokens")
+        _accounting_int(self.cost_micros, "usage.cost_micros")
+        _accounting_int(self.cached_input_tokens, "usage.cached_input_tokens")
+        _accounting_int(self.reasoning_tokens, "usage.reasoning_tokens")
+        if self.accounting_status not in _ACCOUNTING_STATUSES:
+            raise RuntimeContractError("usage.accounting_status is unsupported")
+        if self.cached_input_tokens > self.input_tokens:
+            raise RuntimeContractError("usage.cached_input_tokens cannot exceed input_tokens")
+        if self.reasoning_tokens > self.output_tokens:
+            raise RuntimeContractError("usage.reasoning_tokens cannot exceed output_tokens")
+        _checked_add(self.input_tokens, self.output_tokens, "usage.total_tokens")
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+    @property
+    def cost_usd_micros(self) -> int:
+        return self.cost_micros
+
+    def to_dict(self) -> dict[str, int]:
+        return {
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "total_tokens": self.total_tokens,
+            "cost_usd_micros": self.cost_usd_micros,
+            "cached_input_tokens": self.cached_input_tokens,
+            "reasoning_tokens": self.reasoning_tokens,
+            "accounting_status": self.accounting_status,
+        }
+
+
+@dataclass(frozen=True)
+class SecretReference:
+    """A server-issued, scoped handle; it can never contain a provider storage coordinate."""
+
+    name: str
+    handle_id: str
+    workspace_id: str
+    connector_id: str
+    attempt_id: str
+    purpose: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.name, "secret_reference.name")
+        if not isinstance(self.handle_id, str) or not _SECRET_HANDLE.fullmatch(self.handle_id):
+            raise RuntimeContractError("secret_reference.handle_id must be a server-issued handle")
+        for field_name in ("workspace_id", "connector_id", "attempt_id"):
+            value = getattr(self, field_name)
+            if not isinstance(value, str) or not _SCOPE_IDENTIFIER.fullmatch(value):
+                raise RuntimeContractError(
+                    f"secret_reference.{field_name} must be a canonical scoped identifier"
+                )
+        if self.purpose not in _SECRET_PURPOSES:
+            raise RuntimeContractError("secret_reference.purpose is unsupported")
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "name": self.name,
+            "handle_id": self.handle_id,
+            "workspace_id": self.workspace_id,
+            "connector_id": self.connector_id,
+            "attempt_id": self.attempt_id,
+            "purpose": self.purpose,
+        }
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> SecretReference:
+        data = _object(value, path)
+        _exact_fields(
+            data,
+            {
+                "name",
+                "handle_id",
+                "workspace_id",
+                "connector_id",
+                "attempt_id",
+                "purpose",
+            },
+            path,
+        )
+        return cls(
+            name=_required_string(data["name"], f"{path}.name", maximum=64),
+            handle_id=_required_string(data["handle_id"], f"{path}.handle_id", maximum=128),
+            workspace_id=_required_string(
+                data["workspace_id"], f"{path}.workspace_id", maximum=128
+            ),
+            connector_id=_required_string(
+                data["connector_id"], f"{path}.connector_id", maximum=128
+            ),
+            attempt_id=_required_string(data["attempt_id"], f"{path}.attempt_id", maximum=128),
+            purpose=_required_string(data["purpose"], f"{path}.purpose", maximum=64),
+        )
+
+
+@dataclass(frozen=True)
+class ToolInvocation:
+    """A bounded invocation of a capability registered by the trusted coordinator."""
+
+    name: str
+    arguments: Mapping[str, Any]
+
+    def __post_init__(self) -> None:
+        _identifier(self.name, "tool.name")
+        normalized = _strict_json_object(self.arguments, "tool.arguments")
+        object.__setattr__(self, "arguments", normalized)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"name": self.name, "arguments": deepcopy(dict(self.arguments))}
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> ToolInvocation:
+        data = _object(value, path)
+        _exact_fields(data, {"name", "arguments"}, path)
+        return cls(
+            name=_required_string(data["name"], f"{path}.name", maximum=64),
+            arguments=_object(data["arguments"], f"{path}.arguments"),
+        )
+
+
+@dataclass(frozen=True)
+class ToolCallEvidence:
+    """Exact digest binding for one sanctioned tool invocation."""
+
+    sequence: int
+    name: str
+    arguments_sha256: str
+    invocation_sha256: str
+
+    def __post_init__(self) -> None:
+        _positive_int(self.sequence, "tool_evidence.sequence")
+        _identifier(self.name, "tool_evidence.name")
+        _digest(self.arguments_sha256, "tool_evidence.arguments_sha256")
+        _digest(self.invocation_sha256, "tool_evidence.invocation_sha256")
+
+    @classmethod
+    def from_invocation(cls, sequence: int, invocation: ToolInvocation) -> ToolCallEvidence:
+        arguments_sha256 = _sha256(_canonical_json_bytes(invocation.arguments))
+        invocation_sha256 = _sha256(_canonical_json_bytes(invocation.to_dict()))
+        return cls(
+            sequence=sequence,
+            name=invocation.name,
+            arguments_sha256=arguments_sha256,
+            invocation_sha256=invocation_sha256,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "sequence": self.sequence,
+            "name": self.name,
+            "arguments_sha256": self.arguments_sha256,
+            "invocation_sha256": self.invocation_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class ToolPolicy:
+    """Closed V1 policy: registered search and result-reference browsing only."""
+
+    version: str = TOOL_POLICY_VERSION
+    max_search_query_chars: int = 500
+    max_search_results: int = 20
+    max_browse_chars: int = 100_000
+
+    def __post_init__(self) -> None:
+        if self.version != TOOL_POLICY_VERSION:
+            raise RuntimeContractError(f"tool policy version must be {TOOL_POLICY_VERSION!r}")
+        _positive_int(self.max_search_query_chars, "max_search_query_chars")
+        _positive_int(self.max_search_results, "max_search_results")
+        _positive_int(self.max_browse_chars, "max_browse_chars")
+
+    def validate(self, invocation: ToolInvocation, *, path: str = "tool") -> None:
+        try:
+            if invocation.name == "search":
+                self._validate_search(invocation.arguments, path)
+                return
+            if invocation.name == "browse":
+                self._validate_browse(invocation.arguments, path)
+                return
+            raise ToolPolicyError(
+                f"{path}.name is not sanctioned; only registered search and browse are available"
+            )
+        except ToolPolicyError:
+            raise
+        except RuntimeContractError as exc:
+            raise ToolPolicyError(str(exc)) from None
+
+    def _validate_search(self, arguments: Mapping[str, Any], path: str) -> None:
+        _exact_fields(arguments, {"query", "limit"}, f"{path}.arguments")
+        _required_string(
+            arguments["query"],
+            f"{path}.arguments.query",
+            maximum=self.max_search_query_chars,
+        )
+        limit = _positive_int(arguments["limit"], f"{path}.arguments.limit")
+        if limit > self.max_search_results:
+            raise ToolPolicyError(
+                f"{path}.arguments.limit exceeds the sanctioned search result limit"
+            )
+
+    def _validate_browse(self, arguments: Mapping[str, Any], path: str) -> None:
+        required = {"result_ref", "max_chars"}
+        optional = {"cursor"}
+        _exact_fields(arguments, required, f"{path}.arguments", optional=optional)
+        result_ref = _required_string(
+            arguments["result_ref"], f"{path}.arguments.result_ref", maximum=256
+        )
+        if not result_ref.startswith("searchref://") or "://" in result_ref[12:]:
+            raise ToolPolicyError(
+                f"{path}.arguments.result_ref must be an opaque searchref:// reference"
+            )
+        max_chars = _positive_int(arguments["max_chars"], f"{path}.arguments.max_chars")
+        if max_chars > self.max_browse_chars:
+            raise ToolPolicyError(f"{path}.arguments.max_chars exceeds the browse limit")
+        if "cursor" in arguments:
+            _required_string(arguments["cursor"], f"{path}.arguments.cursor", maximum=256)
+
+
+@dataclass(frozen=True)
+class AgentRequest:
+    """Strict provider-neutral request envelope."""
+
+    role: str
+    prompt_template_version: str
+    payload_schema_version: str
+    payload: Mapping[str, Any]
+    tools: tuple[ToolInvocation, ...] = ()
+    secret_references: tuple[SecretReference, ...] = ()
+    input_token_budget: int = 1
+    max_output_tokens: int = 1
+    timeout_micros: int = 1
+    max_cost_micros: int = 0
+    schema_version: str = AGENT_REQUEST_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != AGENT_REQUEST_VERSION:
+            raise RuntimeContractError(f"request.schema_version must be {AGENT_REQUEST_VERSION!r}")
+        if self.role not in AGENT_ROLES:
+            raise RuntimeContractError(f"request.role is unsupported: {self.role!r}")
+        _version(self.prompt_template_version, "request.prompt_template_version")
+        _version(self.payload_schema_version, "request.payload_schema_version")
+        object.__setattr__(self, "payload", _strict_json_object(self.payload, "request.payload"))
+        _validate_role_payload(
+            self.role,
+            self.payload_schema_version,
+            self.payload,
+            direction="input",
+        )
+        if not isinstance(self.tools, tuple):
+            raise RuntimeContractError("request.tools must be a tuple")
+        if not all(isinstance(item, ToolInvocation) for item in self.tools):
+            raise RuntimeContractError("request.tools contains an invalid invocation")
+        if not isinstance(self.secret_references, tuple):
+            raise RuntimeContractError("request.secret_references must be a tuple")
+        if not all(isinstance(item, SecretReference) for item in self.secret_references):
+            raise RuntimeContractError("request.secret_references contains an invalid reference")
+        _require_unique((item.name for item in self.secret_references), "secret reference names")
+        _require_unique((item.handle_id for item in self.secret_references), "secret handle IDs")
+        _positive_accounting_int(self.input_token_budget, "request.input_token_budget")
+        _positive_accounting_int(self.max_output_tokens, "request.max_output_tokens")
+        _positive_accounting_int(self.timeout_micros, "request.timeout_micros")
+        _accounting_int(self.max_cost_micros, "request.max_cost_micros")
+
+    @property
+    def canonical_bytes(self) -> bytes:
+        return _canonical_json_bytes(self.to_dict())
+
+    @property
+    def request_sha256(self) -> str:
+        return _sha256(self.canonical_bytes)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "role": self.role,
+            "prompt_template_version": self.prompt_template_version,
+            "payload_schema_version": self.payload_schema_version,
+            "payload": deepcopy(dict(self.payload)),
+            "tools": [item.to_dict() for item in self.tools],
+            "secret_references": [item.to_dict() for item in self.secret_references],
+            "input_token_budget": self.input_token_budget,
+            "max_output_tokens": self.max_output_tokens,
+            "timeout_micros": self.timeout_micros,
+            "max_cost_micros": self.max_cost_micros,
+        }
+
+    @classmethod
+    def from_value(cls, value: Any) -> AgentRequest:
+        data = _object(value, "request")
+        _exact_fields(
+            data,
+            {
+                "schema_version",
+                "role",
+                "prompt_template_version",
+                "payload_schema_version",
+                "payload",
+                "tools",
+                "secret_references",
+                "input_token_budget",
+                "max_output_tokens",
+                "timeout_micros",
+                "max_cost_micros",
+            },
+            "request",
+        )
+        tools = _array(data["tools"], "request.tools", maximum=16)
+        secrets = _array(data["secret_references"], "request.secret_references", maximum=32)
+        return cls(
+            schema_version=_required_string(
+                data["schema_version"], "request.schema_version", maximum=64
+            ),
+            role=_required_string(data["role"], "request.role", maximum=64),
+            prompt_template_version=_required_string(
+                data["prompt_template_version"],
+                "request.prompt_template_version",
+                maximum=128,
+            ),
+            payload_schema_version=_required_string(
+                data["payload_schema_version"],
+                "request.payload_schema_version",
+                maximum=128,
+            ),
+            payload=_object(data["payload"], "request.payload"),
+            tools=tuple(
+                ToolInvocation.from_value(item, f"request.tools[{index}]")
+                for index, item in enumerate(tools)
+            ),
+            secret_references=tuple(
+                SecretReference.from_value(item, f"request.secret_references[{index}]")
+                for index, item in enumerate(secrets)
+            ),
+            input_token_budget=data["input_token_budget"],
+            max_output_tokens=data["max_output_tokens"],
+            timeout_micros=data["timeout_micros"],
+            max_cost_micros=data["max_cost_micros"],
+        )
+
+
+@dataclass(frozen=True)
+class AgentResponse:
+    """Strict structured response envelope; role output remains an untrusted proposal."""
+
+    role: str
+    payload_schema_version: str
+    payload: Mapping[str, Any]
+    schema_version: str = AGENT_RESPONSE_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != AGENT_RESPONSE_VERSION:
+            raise RuntimeContractError(
+                f"response.schema_version must be {AGENT_RESPONSE_VERSION!r}"
+            )
+        if self.role not in AGENT_ROLES:
+            raise RuntimeContractError(f"response.role is unsupported: {self.role!r}")
+        _version(self.payload_schema_version, "response.payload_schema_version")
+        object.__setattr__(self, "payload", _strict_json_object(self.payload, "response.payload"))
+        _validate_role_payload(
+            self.role,
+            self.payload_schema_version,
+            self.payload,
+            direction="output",
+        )
+
+    @property
+    def canonical_bytes(self) -> bytes:
+        return _canonical_json_bytes(self.to_dict())
+
+    @property
+    def response_sha256(self) -> str:
+        return _sha256(self.canonical_bytes)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "role": self.role,
+            "payload_schema_version": self.payload_schema_version,
+            "payload": deepcopy(dict(self.payload)),
+        }
+
+    @classmethod
+    def from_value(cls, value: Any) -> AgentResponse:
+        data = _object(value, "response")
+        _exact_fields(
+            data,
+            {"schema_version", "role", "payload_schema_version", "payload"},
+            "response",
+        )
+        return cls(
+            schema_version=_required_string(
+                data["schema_version"], "response.schema_version", maximum=64
+            ),
+            role=_required_string(data["role"], "response.role", maximum=64),
+            payload_schema_version=_required_string(
+                data["payload_schema_version"],
+                "response.payload_schema_version",
+                maximum=128,
+            ),
+            payload=_object(data["payload"], "response.payload"),
+        )
+
+
+@dataclass(frozen=True)
+class ProviderResult:
+    """Untrusted structured response and provider-reported integer usage."""
+
+    response: Any
+    input_tokens: Any
+    output_tokens: Any
+    cost_micros: Any
+
+
+@runtime_checkable
+class ProviderAdapter(Protocol):
+    """Minimal provider boundary implemented outside the deterministic core."""
+
+    @property
+    def provider(self) -> str: ...
+
+    @property
+    def model_identifier(self) -> str: ...
+
+    def invoke(self, request: AgentRequest, tool_policy: ToolPolicy) -> ProviderResult: ...
+
+
+@runtime_checkable
+class AgentRuntime(Protocol):
+    """Common protocol for live adapters and checked-in replay."""
+
+    def call(self, request: AgentRequest) -> AgentCallResult: ...
+
+
+@dataclass(frozen=True)
+class BudgetLimits:
+    """Per-call and aggregate run limits. All amounts are inclusive."""
+
+    max_calls: int
+    max_input_tokens_per_call: int
+    max_output_tokens_per_call: int
+    max_total_tokens_per_call: int
+    max_cost_micros_per_call: int
+    max_time_micros_per_call: int
+    max_input_tokens_per_run: int
+    max_output_tokens_per_run: int
+    max_total_tokens_per_run: int
+    max_cost_micros_per_run: int
+    max_time_micros_per_run: int
+
+    def __post_init__(self) -> None:
+        _positive_accounting_int(self.max_calls, "budget.max_calls")
+        for name, value in self.to_dict().items():
+            if name != "max_calls":
+                _accounting_int(value, f"budget.{name}")
+        if self.max_total_tokens_per_call < max(
+            self.max_input_tokens_per_call, self.max_output_tokens_per_call
+        ):
+            raise RuntimeContractError(
+                "budget.max_total_tokens_per_call cannot be smaller than a component limit"
+            )
+        if self.max_total_tokens_per_run < max(
+            self.max_input_tokens_per_run, self.max_output_tokens_per_run
+        ):
+            raise RuntimeContractError(
+                "budget.max_total_tokens_per_run cannot be smaller than a component limit"
+            )
+
+    def to_dict(self) -> dict[str, int]:
+        return {
+            "max_calls": self.max_calls,
+            "max_input_tokens_per_call": self.max_input_tokens_per_call,
+            "max_output_tokens_per_call": self.max_output_tokens_per_call,
+            "max_total_tokens_per_call": self.max_total_tokens_per_call,
+            "max_cost_micros_per_call": self.max_cost_micros_per_call,
+            "max_time_micros_per_call": self.max_time_micros_per_call,
+            "max_input_tokens_per_run": self.max_input_tokens_per_run,
+            "max_output_tokens_per_run": self.max_output_tokens_per_run,
+            "max_total_tokens_per_run": self.max_total_tokens_per_run,
+            "max_cost_micros_per_run": self.max_cost_micros_per_run,
+            "max_time_micros_per_run": self.max_time_micros_per_run,
+        }
+
+    @classmethod
+    def generous(cls) -> BudgetLimits:
+        """Wide limits that back the default ledger when a runtime is built without a budget.
+
+        ProviderAgentRuntime uses these whenever its budget argument is None.  Pass an explicit
+        BudgetLedger to enforce narrower limits.
+        """
+
+        return cls(
+            max_calls=1_000,
+            max_input_tokens_per_call=1_000_000,
+            max_output_tokens_per_call=1_000_000,
+            max_total_tokens_per_call=2_000_000,
+            max_cost_micros_per_call=1_000_000_000,
+            max_time_micros_per_call=3_600_000_000,
+            max_input_tokens_per_run=100_000_000,
+            max_output_tokens_per_run=100_000_000,
+            max_total_tokens_per_run=200_000_000,
+            max_cost_micros_per_run=100_000_000_000,
+            max_time_micros_per_run=86_400_000_000,
+        )
+
+
+@dataclass(frozen=True)
+class BudgetSnapshot:
+    calls: int
+    input_tokens: int
+    output_tokens: int
+    cost_micros: int
+    time_micros: int
+    active_reservations: int
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+@dataclass(frozen=True)
+class _Reservation:
+    reservation_id: int
+    input_tokens: int
+    output_tokens: int
+    cost_micros: int
+    time_micros: int
+
+
+class BudgetLedger:
+    """Concurrency-safe reservation and final accounting for a single run."""
+
+    def __init__(self, limits: BudgetLimits) -> None:
+        self._limits = limits
+        self._lock = threading.Lock()
+        self._next_id = 1
+        self._reservations: dict[int, _Reservation] = {}
+        self._calls = 0
+        self._input_tokens = 0
+        self._output_tokens = 0
+        self._cost_micros = 0
+        self._time_micros = 0
+
+    @property
+    def limits(self) -> BudgetLimits:
+        return self._limits
+
+    def snapshot(self) -> BudgetSnapshot:
+        with self._lock:
+            return BudgetSnapshot(
+                calls=self._calls,
+                input_tokens=self._input_tokens,
+                output_tokens=self._output_tokens,
+                cost_micros=self._cost_micros,
+                time_micros=self._time_micros,
+                active_reservations=len(self._reservations),
+            )
+
+    def reserve(self, request: AgentRequest) -> _Reservation:
+        requested_total = _checked_add(
+            request.input_token_budget,
+            request.max_output_tokens,
+            "request reserved total tokens",
+        )
+        per_call_checks = (
+            (
+                request.input_token_budget,
+                self._limits.max_input_tokens_per_call,
+                "input_tokens_per_call",
+            ),
+            (
+                request.max_output_tokens,
+                self._limits.max_output_tokens_per_call,
+                "output_tokens_per_call",
+            ),
+            (
+                requested_total,
+                self._limits.max_total_tokens_per_call,
+                "total_tokens_per_call",
+            ),
+            (
+                request.max_cost_micros,
+                self._limits.max_cost_micros_per_call,
+                "cost_micros_per_call",
+            ),
+            (
+                request.timeout_micros,
+                self._limits.max_time_micros_per_call,
+                "time_micros_per_call",
+            ),
+        )
+        for requested, limit, label in per_call_checks:
+            if requested > limit:
+                raise _ReservationDenied(f"budget {label} would be exceeded")
+
+        with self._lock:
+            reserved = self._reserved_totals_locked()
+            run_checks = (
+                (self._calls + reserved.calls + 1, self._limits.max_calls, "calls"),
+                (
+                    self._input_tokens + reserved.input_tokens + request.input_token_budget,
+                    self._limits.max_input_tokens_per_run,
+                    "input_tokens_per_run",
+                ),
+                (
+                    self._output_tokens + reserved.output_tokens + request.max_output_tokens,
+                    self._limits.max_output_tokens_per_run,
+                    "output_tokens_per_run",
+                ),
+                (
+                    self._input_tokens
+                    + self._output_tokens
+                    + reserved.total_tokens
+                    + requested_total,
+                    self._limits.max_total_tokens_per_run,
+                    "total_tokens_per_run",
+                ),
+                (
+                    self._cost_micros + reserved.cost_micros + request.max_cost_micros,
+                    self._limits.max_cost_micros_per_run,
+                    "cost_micros_per_run",
+                ),
+                (
+                    self._time_micros + reserved.time_micros + request.timeout_micros,
+                    self._limits.max_time_micros_per_run,
+                    "time_micros_per_run",
+                ),
+            )
+            for requested, limit, label in run_checks:
+                if requested > limit:
+                    raise _ReservationDenied(f"budget {label} would be exceeded")
+            reservation = _Reservation(
+                reservation_id=self._next_id,
+                input_tokens=request.input_token_budget,
+                output_tokens=request.max_output_tokens,
+                cost_micros=request.max_cost_micros,
+                time_micros=request.timeout_micros,
+            )
+            self._next_id += 1
+            self._reservations[reservation.reservation_id] = reservation
+            return reservation
+
+    def finalize(
+        self,
+        reservation: _Reservation,
+        *,
+        input_tokens: Any,
+        output_tokens: Any,
+        cost_micros: Any,
+        time_micros: Any,
+        accounting_status: str = "reported",
+    ) -> tuple[Usage, tuple[str, ...]]:
+        input_value, input_overflow = _provider_accounting(input_tokens, "input_tokens")
+        output_value, output_overflow = _provider_accounting(output_tokens, "output_tokens")
+        cost_value, cost_overflow = _provider_accounting(cost_micros, "cost_micros")
+        time_value, time_overflow = _provider_accounting(time_micros, "time_micros")
+        overflow_fields = tuple(
+            name
+            for name, overflow in (
+                ("input_tokens", input_overflow),
+                ("output_tokens", output_overflow),
+                ("cost_micros", cost_overflow),
+                ("time_micros", time_overflow),
+            )
+            if overflow
+        )
+        if input_value + output_value > MAX_ACCOUNTING_INTEGER:
+            overflow_fields = (*overflow_fields, "total_tokens")
+        total_value = min(MAX_ACCOUNTING_INTEGER, input_value + output_value)
+        usage = Usage(
+            input_tokens=min(input_value, total_value),
+            output_tokens=min(output_value, MAX_ACCOUNTING_INTEGER - min(input_value, total_value)),
+            cost_micros=cost_value,
+            accounting_status=accounting_status,
+        )
+        with self._lock:
+            current = self._reservations.pop(reservation.reservation_id, None)
+            if current != reservation:
+                raise RuntimeContractError("budget reservation was not active")
+            self._calls = min(MAX_ACCOUNTING_INTEGER, self._calls + 1)
+            self._input_tokens = min(
+                MAX_ACCOUNTING_INTEGER, self._input_tokens + usage.input_tokens
+            )
+            self._output_tokens = min(
+                MAX_ACCOUNTING_INTEGER, self._output_tokens + usage.output_tokens
+            )
+            self._cost_micros = min(MAX_ACCOUNTING_INTEGER, self._cost_micros + usage.cost_micros)
+            self._time_micros = min(MAX_ACCOUNTING_INTEGER, self._time_micros + time_value)
+            exceeded = list(f"{field}_overflow" for field in overflow_fields)
+            actual_total = min(MAX_ACCOUNTING_INTEGER, usage.input_tokens + usage.output_tokens)
+            after_checks = (
+                (
+                    usage.input_tokens,
+                    reservation.input_tokens,
+                    "reserved_input_tokens",
+                ),
+                (
+                    usage.output_tokens,
+                    reservation.output_tokens,
+                    "reserved_output_tokens",
+                ),
+                (
+                    usage.cost_micros,
+                    reservation.cost_micros,
+                    "reserved_cost_micros",
+                ),
+                (
+                    time_value,
+                    reservation.time_micros,
+                    "reserved_time_micros",
+                ),
+                (
+                    usage.input_tokens,
+                    self._limits.max_input_tokens_per_call,
+                    "input_tokens_per_call",
+                ),
+                (
+                    usage.output_tokens,
+                    self._limits.max_output_tokens_per_call,
+                    "output_tokens_per_call",
+                ),
+                (
+                    actual_total,
+                    self._limits.max_total_tokens_per_call,
+                    "total_tokens_per_call",
+                ),
+                (
+                    usage.cost_micros,
+                    self._limits.max_cost_micros_per_call,
+                    "cost_micros_per_call",
+                ),
+                (
+                    time_value,
+                    self._limits.max_time_micros_per_call,
+                    "time_micros_per_call",
+                ),
+                (self._calls, self._limits.max_calls, "calls"),
+                (
+                    self._input_tokens,
+                    self._limits.max_input_tokens_per_run,
+                    "input_tokens_per_run",
+                ),
+                (
+                    self._output_tokens,
+                    self._limits.max_output_tokens_per_run,
+                    "output_tokens_per_run",
+                ),
+                (
+                    min(
+                        MAX_ACCOUNTING_INTEGER,
+                        self._input_tokens + self._output_tokens,
+                    ),
+                    self._limits.max_total_tokens_per_run,
+                    "total_tokens_per_run",
+                ),
+                (
+                    self._cost_micros,
+                    self._limits.max_cost_micros_per_run,
+                    "cost_micros_per_run",
+                ),
+                (
+                    self._time_micros,
+                    self._limits.max_time_micros_per_run,
+                    "time_micros_per_run",
+                ),
+            )
+            for actual, limit, label in after_checks:
+                if actual > limit:
+                    exceeded.append(label)
+        return usage, tuple(sorted(set(exceeded)))
+
+    def _reserved_totals_locked(self) -> BudgetSnapshot:
+        reservations = tuple(self._reservations.values())
+        return BudgetSnapshot(
+            calls=len(reservations),
+            input_tokens=sum(item.input_tokens for item in reservations),
+            output_tokens=sum(item.output_tokens for item in reservations),
+            cost_micros=sum(item.cost_micros for item in reservations),
+            time_micros=sum(item.time_micros for item in reservations),
+            active_reservations=len(reservations),
+        )
+
+
+class _ReservationDenied(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class AgentCallEvidence:
+    """Complete, canonical evidence for every terminal call outcome."""
+
+    runtime_version: str
+    request_contract_version: str
+    response_contract_version: str
+    replay_fixture_version: str | None
+    provider: str
+    model_identifier: str
+    provider_configuration_sha256: str
+    role: str
+    prompt_template_version: str
+    prompt_sha256: str
+    tool_policy_version: str
+    request_sha256: str
+    response_sha256: str | None
+    raw_response_sha256: str | None
+    secret_references: tuple[SecretReference, ...]
+    tool_evidence: tuple[ToolCallEvidence, ...]
+    outcome: str
+    usage: Usage
+    timing: TimingEvidence
+    deadline_micros: int
+    failure_code: str | None = None
+    schema_version: str = AGENT_EVIDENCE_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != AGENT_EVIDENCE_VERSION:
+            raise RuntimeContractError(
+                f"evidence.schema_version must be {AGENT_EVIDENCE_VERSION!r}"
+            )
+        if self.runtime_version != AGENT_RUNTIME_VERSION:
+            raise RuntimeContractError(
+                f"evidence.runtime_version must be {AGENT_RUNTIME_VERSION!r}"
+            )
+        if self.request_contract_version != AGENT_REQUEST_VERSION:
+            raise RuntimeContractError(
+                f"evidence.request_contract_version must be {AGENT_REQUEST_VERSION!r}"
+            )
+        if self.response_contract_version != AGENT_RESPONSE_VERSION:
+            raise RuntimeContractError(
+                f"evidence.response_contract_version must be {AGENT_RESPONSE_VERSION!r}"
+            )
+        if self.replay_fixture_version is not None:
+            _version(self.replay_fixture_version, "evidence.replay_fixture_version")
+        _identifier(self.provider, "evidence.provider")
+        _required_string(self.model_identifier, "evidence.model_identifier", maximum=256)
+        _digest(
+            self.provider_configuration_sha256,
+            "evidence.provider_configuration_sha256",
+        )
+        if self.role not in AGENT_ROLES:
+            raise RuntimeContractError("evidence.role is unsupported")
+        _version(self.prompt_template_version, "evidence.prompt_template_version")
+        _digest(self.prompt_sha256, "evidence.prompt_sha256")
+        _version(self.tool_policy_version, "evidence.tool_policy_version")
+        _digest(self.request_sha256, "evidence.request_sha256")
+        if self.response_sha256 is not None:
+            _digest(self.response_sha256, "evidence.response_sha256")
+        if self.raw_response_sha256 is not None:
+            _digest(self.raw_response_sha256, "evidence.raw_response_sha256")
+        if not isinstance(self.secret_references, tuple) or not all(
+            isinstance(item, SecretReference) for item in self.secret_references
+        ):
+            raise RuntimeContractError("evidence.secret_references must be scoped handles")
+        if not isinstance(self.tool_evidence, tuple) or not all(
+            isinstance(item, ToolCallEvidence) for item in self.tool_evidence
+        ):
+            raise RuntimeContractError("evidence.tool_evidence must contain tool call evidence")
+        _require_unique(
+            (item.handle_id for item in self.secret_references),
+            "evidence secret handle IDs",
+        )
+        expected_sequences = tuple(range(1, len(self.tool_evidence) + 1))
+        if tuple(item.sequence for item in self.tool_evidence) != expected_sequences:
+            raise RuntimeContractError("evidence.tool_evidence sequences must be contiguous")
+        _nonnegative_int(self.deadline_micros, "evidence.deadline_micros")
+        if self.deadline_micros < self.timing.started_micros:
+            raise RuntimeContractError("evidence.deadline_micros precedes call start")
+        if self.outcome not in _OUTCOMES:
+            raise RuntimeContractError(f"evidence.outcome is unsupported: {self.outcome!r}")
+        if self.outcome in _PRE_DISPATCH_OUTCOMES:
+            if self.usage.accounting_status != "not_applicable":
+                raise RuntimeContractError("pre-dispatch evidence usage must be not_applicable")
+            if self.usage.input_tokens or self.usage.output_tokens or self.usage.cost_micros:
+                raise RuntimeContractError("pre-dispatch evidence usage must be zero")
+        elif self.usage.accounting_status == "not_applicable":
+            raise RuntimeContractError("post-dispatch evidence usage cannot be not_applicable")
+        if self.outcome == "succeeded" and self.usage.accounting_status != "reported":
+            raise RuntimeContractError("successful evidence usage must be provider-reported")
+        if self.outcome == "succeeded":
+            if self.response_sha256 is None or self.failure_code is not None:
+                raise RuntimeContractError("successful evidence needs a response and no failure")
+        elif self.failure_code is None:
+            raise RuntimeContractError("failed evidence needs a stable failure_code")
+        if self.failure_code is not None:
+            _identifier(self.failure_code, "evidence.failure_code")
+
+    @property
+    def evidence_sha256(self) -> str:
+        return _sha256(_canonical_json_bytes(self.to_dict()))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "runtime_version": self.runtime_version,
+            "request_contract_version": self.request_contract_version,
+            "response_contract_version": self.response_contract_version,
+            "replay_fixture_version": self.replay_fixture_version,
+            "provider": self.provider,
+            "model_identifier": self.model_identifier,
+            "provider_configuration_sha256": self.provider_configuration_sha256,
+            "role": self.role,
+            "prompt_template_version": self.prompt_template_version,
+            "prompt_sha256": self.prompt_sha256,
+            "tool_policy_version": self.tool_policy_version,
+            "request_sha256": self.request_sha256,
+            "response_sha256": self.response_sha256,
+            "raw_response_sha256": self.raw_response_sha256,
+            "secret_references": [item.to_dict() for item in self.secret_references],
+            "tool_evidence": [item.to_dict() for item in self.tool_evidence],
+            "outcome": self.outcome,
+            "usage": self.usage.to_dict(),
+            "timing": self.timing.to_dict(),
+            "deadline_micros": self.deadline_micros,
+            "failure_code": self.failure_code,
+        }
+
+
+@dataclass(frozen=True)
+class AgentCallResult:
+    response: AgentResponse
+    evidence: AgentCallEvidence
+
+
+class AgentCallFailure(AgentRuntimeError):
+    """A typed terminal failure carrying complete deterministic evidence."""
+
+    def __init__(self, evidence: AgentCallEvidence) -> None:
+        self.evidence = evidence
+        super().__init__(f"agent call failed: {evidence.failure_code}")
+
+
+class BudgetExceededBeforeCall(AgentCallFailure):
+    """The call was not sent because its reservation could not be made."""
+
+
+class BudgetExceededAfterCall(AgentCallFailure):
+    """Provider work was accounted, but the actual result exceeded a limit."""
+
+
+class ProviderCallFailed(AgentCallFailure):
+    """Provider raised an exception before yielding a structured result."""
+
+
+class MalformedProviderResponse(AgentCallFailure):
+    """Provider output or accounting failed strict validation."""
+
+
+class AgentCallTimedOut(AgentCallFailure):
+    """The adapter reported or consumed more than its bounded call time."""
+
+
+class AgentCallCancelled(AgentCallFailure):
+    """The provider call was cancelled; the reservation was still finalized."""
+
+
+class ToolPolicyDenied(AgentCallFailure, ToolPolicyError):
+    """The invocation was rejected before provider execution with complete evidence."""
+
+
+class ProviderAgentRuntime:
+    """Deterministic coordinator around one provider adapter and one run ledger."""
+
+    def __init__(
+        self,
+        adapter: ProviderAdapter,
+        *,
+        budget: BudgetLedger | None = None,
+        tool_policy: ToolPolicy | None = None,
+        clock: Callable[[], int] | None = None,
+        replay_fixture_version: str | None = None,
+    ) -> None:
+        if not isinstance(adapter, ProviderAdapter):
+            raise RuntimeContractError("adapter does not implement ProviderAdapter")
+        _identifier(adapter.provider, "provider")
+        _required_string(adapter.model_identifier, "model_identifier", maximum=256)
+        self._adapter = adapter
+        self._budget = budget or BudgetLedger(BudgetLimits.generous())
+        self._tool_policy = tool_policy or ToolPolicy()
+        self._clock = clock or _monotonic_micros
+        if replay_fixture_version is not None:
+            _version(replay_fixture_version, "replay_fixture_version")
+        self._replay_fixture_version = replay_fixture_version
+
+    @property
+    def budget(self) -> BudgetLedger:
+        return self._budget
+
+    def call(self, request: AgentRequest) -> AgentCallResult:
+        if not isinstance(request, AgentRequest):
+            raise RuntimeContractError("call request must be an AgentRequest")
+        started = self._now()
+        try:
+            for index, tool in enumerate(request.tools):
+                self._tool_policy.validate(tool, path=f"request.tools[{index}]")
+        except ToolPolicyError:
+            finished = self._now()
+            evidence = self._evidence(
+                request,
+                outcome="tool_policy_denied",
+                started=started,
+                finished=finished,
+                usage=Usage(0, 0, 0, accounting_status="not_applicable"),
+                failure_code="tool_policy_denied",
+            )
+            raise ToolPolicyDenied(evidence) from None
+        try:
+            reservation = self._budget.reserve(request)
+        except _ReservationDenied as exc:
+            finished = self._now()
+            evidence = self._evidence(
+                request,
+                outcome="budget_exhausted_before_call",
+                started=started,
+                finished=finished,
+                usage=Usage(0, 0, 0, accounting_status="not_applicable"),
+                failure_code=_stable_failure_code(exc),
+            )
+            raise BudgetExceededBeforeCall(evidence) from None
+
+        try:
+            result = self._adapter.invoke(request, self._tool_policy)
+        except asyncio.CancelledError:
+            evidence = self._finish_exception(
+                request,
+                reservation,
+                started,
+                outcome="cancelled",
+                failure_code="provider_cancelled",
+            )
+            raise AgentCallCancelled(evidence) from None
+        except (ProviderTimeoutError, TimeoutError):
+            evidence = self._finish_exception(
+                request,
+                reservation,
+                started,
+                outcome="timed_out",
+                failure_code="provider_timeout",
+            )
+            raise AgentCallTimedOut(evidence) from None
+        except Exception:
+            evidence = self._finish_exception(
+                request,
+                reservation,
+                started,
+                outcome="provider_exception",
+                failure_code="provider_exception",
+            )
+            raise ProviderCallFailed(evidence) from None
+
+        finished = self._now()
+        elapsed = self._elapsed(started, finished)
+        if not isinstance(result, ProviderResult):
+            usage, exceeded = self._budget.finalize(
+                reservation,
+                input_tokens=reservation.input_tokens,
+                output_tokens=reservation.output_tokens,
+                cost_micros=reservation.cost_micros,
+                time_micros=elapsed,
+                accounting_status="unavailable_reserved",
+            )
+            if exceeded:
+                evidence = self._evidence(
+                    request,
+                    outcome="budget_exhausted_after_call",
+                    started=started,
+                    finished=finished,
+                    usage=usage,
+                    raw_response_sha256=_safe_response_hash(result),
+                    failure_code=_after_budget_code(exceeded),
+                )
+                raise BudgetExceededAfterCall(evidence)
+            evidence = self._evidence(
+                request,
+                outcome="malformed_response",
+                started=started,
+                finished=finished,
+                usage=usage,
+                raw_response_sha256=_safe_response_hash(result),
+                failure_code="invalid_provider_result",
+            )
+            raise MalformedProviderResponse(evidence)
+        raw_response_hash = _safe_response_hash(result.response)
+        try:
+            usage, exceeded = self._budget.finalize(
+                reservation,
+                input_tokens=result.input_tokens,
+                output_tokens=result.output_tokens,
+                cost_micros=result.cost_micros,
+                time_micros=elapsed,
+            )
+        except RuntimeContractError:
+            # Invalid accounting cannot be trusted. Conservatively charge the full reservation.
+            usage, exceeded = self._budget.finalize(
+                reservation,
+                input_tokens=reservation.input_tokens,
+                output_tokens=reservation.output_tokens,
+                cost_micros=reservation.cost_micros,
+                time_micros=elapsed,
+                accounting_status="unavailable_reserved",
+            )
+            if exceeded:
+                evidence = self._evidence(
+                    request,
+                    outcome="budget_exhausted_after_call",
+                    started=started,
+                    finished=finished,
+                    usage=usage,
+                    raw_response_sha256=raw_response_hash,
+                    failure_code=_after_budget_code(exceeded),
+                )
+                raise BudgetExceededAfterCall(evidence) from None
+            evidence = self._evidence(
+                request,
+                outcome="malformed_response",
+                started=started,
+                finished=finished,
+                usage=usage,
+                raw_response_sha256=raw_response_hash,
+                failure_code="invalid_provider_accounting",
+            )
+            raise MalformedProviderResponse(evidence) from None
+
+        if elapsed > request.timeout_micros:
+            exceeded = tuple(sorted(set((*exceeded, "request_timeout"))))
+        if exceeded:
+            evidence = self._evidence(
+                request,
+                outcome="budget_exhausted_after_call",
+                started=started,
+                finished=finished,
+                usage=usage,
+                raw_response_sha256=raw_response_hash,
+                failure_code=_after_budget_code(exceeded),
+            )
+            if "request_timeout" in exceeded:
+                raise AgentCallTimedOut(evidence)
+            raise BudgetExceededAfterCall(evidence)
+
+        try:
+            response = AgentResponse.from_value(result.response)
+            if response.role != request.role:
+                raise RuntimeContractError("response.role does not match request.role")
+            _validate_request_response_semantics(request, response)
+        except RuntimeContractError:
+            evidence = self._evidence(
+                request,
+                outcome="malformed_response",
+                started=started,
+                finished=finished,
+                usage=usage,
+                raw_response_sha256=raw_response_hash,
+                failure_code="malformed_structured_output",
+            )
+            raise MalformedProviderResponse(evidence) from None
+
+        evidence = self._evidence(
+            request,
+            outcome="succeeded",
+            started=started,
+            finished=finished,
+            usage=usage,
+            response_sha256=response.response_sha256,
+            raw_response_sha256=raw_response_hash,
+        )
+        return AgentCallResult(response=response, evidence=evidence)
+
+    def _finish_exception(
+        self,
+        request: AgentRequest,
+        reservation: _Reservation,
+        started: int,
+        *,
+        outcome: str,
+        failure_code: str,
+    ) -> AgentCallEvidence:
+        finished = self._now()
+        elapsed = self._elapsed(started, finished)
+        usage, _ = self._budget.finalize(
+            reservation,
+            input_tokens=reservation.input_tokens,
+            output_tokens=reservation.output_tokens,
+            cost_micros=reservation.cost_micros,
+            time_micros=elapsed,
+            accounting_status="unavailable_reserved",
+        )
+        return self._evidence(
+            request,
+            outcome=outcome,
+            started=started,
+            finished=finished,
+            usage=usage,
+            failure_code=failure_code,
+        )
+
+    def _evidence(
+        self,
+        request: AgentRequest,
+        *,
+        outcome: str,
+        started: int,
+        finished: int,
+        usage: Usage,
+        failure_code: str | None = None,
+        response_sha256: str | None = None,
+        raw_response_sha256: str | None = None,
+    ) -> AgentCallEvidence:
+        return AgentCallEvidence(
+            runtime_version=AGENT_RUNTIME_VERSION,
+            request_contract_version=AGENT_REQUEST_VERSION,
+            response_contract_version=AGENT_RESPONSE_VERSION,
+            replay_fixture_version=self._replay_fixture_version,
+            provider=self._adapter.provider,
+            model_identifier=self._adapter.model_identifier,
+            provider_configuration_sha256=_provider_configuration_digest(self._adapter),
+            role=request.role,
+            prompt_template_version=request.prompt_template_version,
+            prompt_sha256=_prompt_digest(request),
+            tool_policy_version=self._tool_policy.version,
+            request_sha256=request.request_sha256,
+            response_sha256=response_sha256,
+            raw_response_sha256=raw_response_sha256,
+            secret_references=request.secret_references,
+            tool_evidence=tuple(
+                ToolCallEvidence.from_invocation(index, invocation)
+                for index, invocation in enumerate(request.tools, start=1)
+            ),
+            outcome=outcome,
+            usage=usage,
+            timing=TimingEvidence(
+                started_micros=started,
+                finished_micros=finished,
+                elapsed_micros=self._elapsed(started, finished),
+            ),
+            deadline_micros=_checked_add(
+                started,
+                request.timeout_micros,
+                "evidence.deadline_micros",
+            ),
+            failure_code=failure_code,
+        )
+
+    def _now(self) -> int:
+        return _nonnegative_int(self._clock(), "clock result")
+
+    @staticmethod
+    def _elapsed(started: int, finished: int) -> int:
+        if finished < started:
+            raise RuntimeContractError("injected clock moved backwards")
+        return finished - started
+
+
+@dataclass(frozen=True)
+class _ReplayEntry:
+    request: AgentRequest
+    response: Mapping[str, Any]
+    response_sha256: str
+    provider: str
+    model_identifier: str
+    usage: Usage
+
+
+class _ReplayAdapter:
+    def __init__(self, entries: Mapping[str, tuple[_ReplayEntry, ...]]) -> None:
+        self._entries = entries
+        self._local = threading.local()
+
+    @property
+    def provider(self) -> str:
+        return getattr(self._local, "provider", "recorded-replay")
+
+    @property
+    def model_identifier(self) -> str:
+        return getattr(self._local, "model_identifier", "fixture-catalog.v1")
+
+    def bind(self, entry: _ReplayEntry) -> None:
+        """Bind recorded provider identity before reservation or invocation."""
+
+        self._local.provider = entry.provider
+        self._local.model_identifier = entry.model_identifier
+
+    def invoke(self, request: AgentRequest, tool_policy: ToolPolicy) -> ProviderResult:
+        del tool_policy
+        matches = self._entries.get(request.request_sha256, ())
+        if not matches:
+            raise ReplayMissError(
+                f"no recorded replay for canonical request {request.request_sha256}"
+            )
+        if len(matches) != 1:
+            raise ReplayAmbiguityError(
+                f"multiple recorded replays for canonical request {request.request_sha256}"
+            )
+        entry = matches[0]
+        if entry.request.canonical_bytes != request.canonical_bytes:
+            raise ReplayTamperError("replay request hash collision or request fixture drift")
+        self.bind(entry)
+        return ProviderResult(
+            response=deepcopy(dict(entry.response)),
+            input_tokens=entry.usage.input_tokens,
+            output_tokens=entry.usage.output_tokens,
+            cost_micros=entry.usage.cost_micros,
+        )
+
+
+class ReplayAgentRuntime(ProviderAgentRuntime):
+    """Offline runtime backed only by duplicate-strict canonical checked-in fixtures.
+
+    Construct it with from_catalog (a checked-in catalog file) or from_recorded (one
+    request/response pair already in memory).  The __init__ entries mapping is the
+    already-validated internal form those two classmethods build.
+    """
+
+    def __init__(
+        self,
+        entries: Mapping[str, tuple[_ReplayEntry, ...]],
+        *,
+        budget: BudgetLedger | None = None,
+        tool_policy: ToolPolicy | None = None,
+        clock: Callable[[], int] | None = None,
+    ) -> None:
+        self._entries = entries
+        self._replay_adapter = _ReplayAdapter(entries)
+        super().__init__(
+            self._replay_adapter,
+            budget=budget,
+            tool_policy=tool_policy,
+            clock=clock,
+            replay_fixture_version=REPLAY_CATALOG_VERSION,
+        )
+
+    def call(self, request: AgentRequest) -> AgentCallResult:
+        if not isinstance(request, AgentRequest):
+            raise RuntimeContractError("call request must be an AgentRequest")
+        matches = self._entries.get(request.request_sha256, ())
+        if not matches:
+            raise ReplayMissError(
+                f"no recorded replay for canonical request {request.request_sha256}"
+            )
+        if len(matches) != 1:
+            raise ReplayAmbiguityError(
+                f"multiple recorded replays for canonical request {request.request_sha256}"
+            )
+        if matches[0].request.canonical_bytes != request.canonical_bytes:
+            raise ReplayTamperError("replay request hash collision or request fixture drift")
+        self._replay_adapter.bind(matches[0])
+        return super().call(request)
+
+    @classmethod
+    def from_recorded(
+        cls,
+        *,
+        request: AgentRequest,
+        response: AgentResponse,
+        provider: str,
+        model_identifier: str,
+        input_tokens: int,
+        output_tokens: int,
+        cost_micros: int,
+        budget: BudgetLedger | None = None,
+        tool_policy: ToolPolicy | None = None,
+        clock: Callable[[], int] | None = None,
+    ) -> ReplayAgentRuntime:
+        """Create one exact in-memory replay after strict request/response binding."""
+
+        if not isinstance(request, AgentRequest) or not isinstance(response, AgentResponse):
+            raise RuntimeContractError("recorded replay requires typed request and response")
+        _validate_request_response_semantics(request, response)
+        normalized_provider = _required_string(provider, "provider", maximum=64)
+        _identifier(normalized_provider, "provider")
+        normalized_model = _required_string(
+            model_identifier,
+            "model_identifier",
+            maximum=256,
+        )
+        usage = Usage(
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cost_micros=cost_micros,
+        )
+        entry = _ReplayEntry(
+            request=request,
+            response=response.to_dict(),
+            response_sha256=response.response_sha256,
+            provider=normalized_provider,
+            model_identifier=normalized_model,
+            usage=usage,
+        )
+        return cls(
+            {request.request_sha256: (entry,)},
+            budget=budget,
+            tool_policy=tool_policy,
+            clock=clock,
+        )
+
+    @classmethod
+    def from_catalog(
+        cls,
+        catalog_path: Path | str,
+        *,
+        budget: BudgetLedger | None = None,
+        tool_policy: ToolPolicy | None = None,
+        clock: Callable[[], int] | None = None,
+    ) -> ReplayAgentRuntime:
+        path = Path(catalog_path)
+        catalog = _load_canonical_json_file(path, "replay catalog")
+        data = _object(catalog, "catalog")
+        _exact_fields(data, {"schema_version", "tool_policy_version", "entries"}, "catalog")
+        if data["schema_version"] != REPLAY_CATALOG_VERSION:
+            raise ReplayVersionError(f"catalog.schema_version must be {REPLAY_CATALOG_VERSION!r}")
+        if data["tool_policy_version"] != TOOL_POLICY_VERSION:
+            raise ReplayVersionError(f"catalog.tool_policy_version must be {TOOL_POLICY_VERSION!r}")
+        raw_entries = _array(data["entries"], "catalog.entries", nonempty=True, maximum=10_000)
+        entries: dict[str, list[_ReplayEntry]] = {}
+        root = path.parent.resolve()
+        for index, raw_entry in enumerate(raw_entries):
+            entry_path = f"catalog.entries[{index}]"
+            item = _object(raw_entry, entry_path)
+            _exact_fields(
+                item,
+                {
+                    "request_file",
+                    "response_file",
+                    "request_sha256",
+                    "response_sha256",
+                    "provider",
+                    "model_identifier",
+                    "input_tokens",
+                    "output_tokens",
+                    "cost_micros",
+                },
+                entry_path,
+            )
+            request_file = _fixture_member(
+                root,
+                _required_string(item["request_file"], f"{entry_path}.request_file", maximum=256),
+            )
+            response_file = _fixture_member(
+                root,
+                _required_string(item["response_file"], f"{entry_path}.response_file", maximum=256),
+            )
+            request_value = _load_canonical_json_file(request_file, "replay request")
+            response_value = _load_canonical_json_file(response_file, "replay response")
+            try:
+                request = AgentRequest.from_value(request_value)
+                response = AgentResponse.from_value(response_value)
+            except RuntimeContractError as exc:
+                error_type = ReplayVersionError if "schema" in str(exc) else ReplayTamperError
+                raise error_type(f"{entry_path} member contract drift: {exc}") from None
+            if response.role != request.role:
+                raise ReplayTamperError(f"{entry_path} response role does not match request")
+            try:
+                _validate_request_response_semantics(request, response)
+            except RuntimeContractError as exc:
+                raise ReplayTamperError(
+                    f"{entry_path} response cross-reference mismatch: {exc}"
+                ) from None
+            expected_request = _digest(item["request_sha256"], f"{entry_path}.request_sha256")
+            expected_response = _digest(item["response_sha256"], f"{entry_path}.response_sha256")
+            if request.request_sha256 != expected_request:
+                raise ReplayTamperError(f"{entry_path} request fixture hash mismatch")
+            if response.response_sha256 != expected_response:
+                raise ReplayTamperError(f"{entry_path} response fixture hash mismatch")
+            replay_entry = _ReplayEntry(
+                request=request,
+                response=response.to_dict(),
+                response_sha256=expected_response,
+                provider=_required_string(item["provider"], f"{entry_path}.provider", maximum=64),
+                model_identifier=_required_string(
+                    item["model_identifier"],
+                    f"{entry_path}.model_identifier",
+                    maximum=256,
+                ),
+                usage=Usage(
+                    input_tokens=item["input_tokens"],
+                    output_tokens=item["output_tokens"],
+                    cost_micros=item["cost_micros"],
+                ),
+            )
+            _identifier(replay_entry.provider, f"{entry_path}.provider")
+            entries.setdefault(expected_request, []).append(replay_entry)
+        return cls(
+            {key: tuple(value) for key, value in entries.items()},
+            budget=budget,
+            tool_policy=tool_policy,
+            clock=clock,
+        )
+
+
+def _load_canonical_json_file(path: Path, label: str) -> Any:
+    try:
+        file_stat = path.lstat()
+        if stat.S_ISLNK(file_stat.st_mode) or not stat.S_ISREG(file_stat.st_mode):
+            raise ReplayTamperError(f"{label} must be a regular non-symlink file")
+        raw = path.read_bytes()
+    except ReplayTamperError:
+        raise
+    except OSError as exc:
+        raise ReplayTamperError(f"cannot read {label}: {path.name}") from exc
+    try:
+        value = json.loads(
+            raw.decode("utf-8"),
+            object_pairs_hook=_reject_duplicate_pairs,
+            parse_constant=_reject_json_constant,
+        )
+    except (UnicodeDecodeError, json.JSONDecodeError, RuntimeContractError) as exc:
+        raise ReplayTamperError(f"{label} is not duplicate-strict UTF-8 JSON") from exc
+    try:
+        canonical = _canonical_json_bytes(value)
+    except RuntimeContractError as exc:
+        raise ReplayTamperError(f"{label} contains unsupported values") from exc
+    if raw != canonical:
+        raise ReplayTamperError(f"{label} is not canonical JSON")
+    return value
+
+
+def _fixture_member(root: Path, relative: str) -> Path:
+    if "\\" in relative or relative.startswith("/") or "//" in relative:
+        raise ReplayTamperError("replay member path must be canonical relative POSIX text")
+    parts = relative.split("/")
+    if not parts or any(part in {"", ".", ".."} for part in parts):
+        raise ReplayTamperError("replay member path must be canonical relative POSIX text")
+    candidate = root.joinpath(*parts)
+    if candidate.parent != root or candidate.is_symlink():
+        raise ReplayTamperError("replay members must be siblings of the catalog")
+    return candidate
+
+
+def _strict_json_object(value: Any, path: str) -> dict[str, Any]:
+    data = _object(value, path)
+    state = [0]
+    normalized = _strict_json_value(data, path, depth=0, state=state)
+    assert isinstance(normalized, dict)
+    return normalized
+
+
+def _validate_role_payload(
+    role: str,
+    schema_version: str,
+    payload: Mapping[str, Any],
+    *,
+    direction: str,
+) -> None:
+    if (
+        role == "semantic_reviewer"
+        and direction == "input"
+        and schema_version == SEMANTIC_REVIEW_INPUT_VERSION
+    ):
+        _validate_hosted_semantic_review_input(payload)
+        return
+    expected = ROLE_PAYLOAD_SCHEMAS[role][0 if direction == "input" else 1]
+    if schema_version != expected:
+        raise RuntimeContractError(f"{direction} payload schema for {role!r} must be {expected!r}")
+    if direction == "input":
+        _validate_role_input(role, payload)
+    else:
+        _validate_role_output(role, payload)
+
+
+def _validate_hosted_semantic_review_input(payload: Mapping[str, Any]) -> None:
+    """Check a semantic-reviewer payload declared as SEMANTIC_REVIEW_INPUT_VERSION."""
+
+    _exact_fields(payload, {"candidate_evidence", "requirements"}, "request.payload")
+    candidate = _object(payload["candidate_evidence"], "request.payload.candidate_evidence")
+    _exact_fields(
+        candidate,
+        {
+            "candidate_id",
+            "candidate_digest",
+            "plan_digest",
+            "artifact_scope_digest",
+            "candidate_contract_version",
+            "artifact_digests",
+            "inspection",
+            "inspection_digest",
+        },
+        "request.payload.candidate_evidence",
+    )
+    _required_string(
+        candidate["candidate_id"],
+        "request.payload.candidate_evidence.candidate_id",
+        maximum=128,
+    )
+    for name in (
+        "candidate_digest",
+        "plan_digest",
+        "artifact_scope_digest",
+        "inspection_digest",
+    ):
+        _digest(candidate[name], f"request.payload.candidate_evidence.{name}")
+    candidate_contract_version = _required_string(
+        candidate["candidate_contract_version"],
+        "request.payload.candidate_evidence.candidate_contract_version",
+        maximum=128,
+    )
+    if not _SEMANTIC_VERSION.fullmatch(candidate_contract_version):
+        raise RuntimeContractError(
+            "request.payload.candidate_evidence.candidate_contract_version "
+            "must be a canonical semantic version"
+        )
+    artifact_digests = _object(
+        candidate["artifact_digests"],
+        "request.payload.candidate_evidence.artifact_digests",
+    )
+    expected_kinds = {
+        "candidate_parquet",
+        "table_preview",
+        "profile",
+        "quality_report",
+        "lineage",
+        "candidate_evidence",
+        "raw_snapshot",
+        "table_package",
+    }
+    _exact_fields(
+        artifact_digests,
+        expected_kinds,
+        "request.payload.candidate_evidence.artifact_digests",
+    )
+    for kind in sorted(expected_kinds):
+        _digest(
+            artifact_digests[kind],
+            f"request.payload.candidate_evidence.artifact_digests.{kind}",
+        )
+    inspection = _object(
+        candidate["inspection"],
+        "request.payload.candidate_evidence.inspection",
+    )
+    if _sha256(_canonical_json_bytes(inspection)) != candidate["inspection_digest"]:
+        raise RuntimeContractError(
+            "request.payload.candidate_evidence.inspection_digest mismatches inspection"
+        )
+
+    requirements = _object(payload["requirements"], "request.payload.requirements")
+    _exact_fields(
+        requirements,
+        {
+            "requirements_id",
+            "output_grain",
+            "validation_policy_digest",
+            "release_policy_digest",
+            "required_check_ids",
+        },
+        "request.payload.requirements",
+    )
+    _required_string(
+        requirements["requirements_id"],
+        "request.payload.requirements.requirements_id",
+        maximum=128,
+    )
+    _string_array(
+        requirements["output_grain"],
+        "request.payload.requirements.output_grain",
+        nonempty=True,
+        maximum=64,
+    )
+    _digest(
+        requirements["validation_policy_digest"],
+        "request.payload.requirements.validation_policy_digest",
+    )
+    _digest(
+        requirements["release_policy_digest"],
+        "request.payload.requirements.release_policy_digest",
+    )
+    _string_array(
+        requirements["required_check_ids"],
+        "request.payload.requirements.required_check_ids",
+        nonempty=True,
+        maximum=256,
+    )
+
+
+def _validate_role_input(role: str, payload: Mapping[str, Any]) -> None:
+    if role == "question_framer":
+        _exact_fields(payload, {"question"}, "request.payload", optional={"context"})
+        _required_string(payload["question"], "request.payload.question", maximum=10_000)
+        if "context" in payload:
+            _object(payload["context"], "request.payload.context")
+        return
+    input_fields = {
+        "feasibility_analyst": ({"framed_question"}, {"context"}),
+        "data_scout": ({"requirements"}, {"context"}),
+        "source_auditor": ({"source", "requirements"}, set()),
+        "plan_proposer": ({"requirements", "sources"}, set()),
+        "semantic_reviewer": ({"candidate_evidence", "requirements"}, set()),
+        "repair_proposer": ({"finding", "candidate_evidence"}, set()),
+    }
+    required, optional = input_fields[role]
+    _exact_fields(payload, required, "request.payload", optional=optional)
+    for name in required:
+        value = payload[name]
+        if name == "sources":
+            sources = _array(value, f"request.payload.{name}", nonempty=True, maximum=256)
+            for index, source in enumerate(sources):
+                _identifier_object(
+                    source,
+                    f"request.payload.{name}[{index}]",
+                    "source_id",
+                )
+        else:
+            identifier_field = {
+                "framed_question": "question_id",
+                "requirements": "requirements_id",
+                "source": "source_id",
+                "candidate_evidence": "candidate_id",
+                "finding": "finding_id",
+            }[name]
+            _identifier_object(value, f"request.payload.{name}", identifier_field)
+    if "context" in payload:
+        _object(payload["context"], "request.payload.context")
+
+
+def _validate_request_response_semantics(
+    request: AgentRequest,
+    response: AgentResponse,
+) -> None:
+    if response.role != request.role:
+        raise RuntimeContractError("response.role does not match request.role")
+    if request.role == "source_auditor":
+        requested_source_id = request.payload["source"]["source_id"]
+        if response.payload["source_id"] != requested_source_id:
+            raise RuntimeContractError(
+                "source_auditor response.source_id does not match request source_id"
+            )
+    elif request.role == "plan_proposer":
+        requested_source_ids = [source["source_id"] for source in request.payload["sources"]]
+        if response.payload["plan"]["source_ids"] != requested_source_ids:
+            raise RuntimeContractError(
+                "plan_proposer response source_ids do not exactly match request sources"
+            )
+    elif request.role == "repair_proposer":
+        requested_finding_id = request.payload["finding"]["finding_id"]
+        if response.payload["repair"]["finding_ids"] != [requested_finding_id]:
+            raise RuntimeContractError(
+                "repair_proposer response finding_ids do not exactly match request finding"
+            )
+
+
+def _validate_role_output(role: str, payload: Mapping[str, Any]) -> None:
+    if role == "question_framer":
+        _exact_fields(
+            payload,
+            {
+                "question",
+                "population",
+                "time_range",
+                "output_grain",
+                "success_criteria",
+            },
+            "response.payload",
+        )
+        _required_string(payload["question"], "response.payload.question", maximum=10_000)
+        _required_string(payload["population"], "response.payload.population", maximum=10_000)
+        time_range = _object(payload["time_range"], "response.payload.time_range")
+        _exact_fields(time_range, {"start", "end"}, "response.payload.time_range")
+        _half_open_dates(
+            time_range["start"],
+            time_range["end"],
+            "response.payload.time_range",
+        )
+        _string_array(
+            payload["output_grain"],
+            "response.payload.output_grain",
+            nonempty=True,
+            maximum=64,
+        )
+        _string_array(
+            payload["success_criteria"],
+            "response.payload.success_criteria",
+            nonempty=True,
+            maximum=128,
+        )
+        return
+    output_fields = {
+        "feasibility_analyst": {"decision", "rationale"},
+        "data_scout": {"candidates"},
+        "source_auditor": {"source_id", "assessment"},
+        "plan_proposer": {"plan"},
+        "semantic_reviewer": {"findings"},
+        "repair_proposer": {"repair"},
+    }
+    _exact_fields(payload, output_fields[role], "response.payload")
+    if role == "feasibility_analyst":
+        decision = _required_string(payload["decision"], "response.payload.decision", maximum=64)
+        if decision not in {"feasible", "conditionally_feasible", "not_feasible"}:
+            raise RuntimeContractError("response.payload.decision is unsupported")
+        _string_array(
+            payload["rationale"],
+            "response.payload.rationale",
+            nonempty=True,
+            maximum=128,
+        )
+    elif role == "data_scout":
+        candidates = _array(
+            payload["candidates"],
+            "response.payload.candidates",
+            nonempty=True,
+            maximum=256,
+        )
+        source_ids: list[str] = []
+        for index, candidate in enumerate(candidates):
+            source_ids.append(
+                _validate_source_candidate(
+                    candidate,
+                    f"response.payload.candidates[{index}]",
+                )
+            )
+        _require_unique(source_ids, "response.payload.candidates source IDs")
+    elif role == "source_auditor":
+        _identifier(payload["source_id"], "response.payload.source_id")
+        _validate_source_assessment(
+            payload["assessment"],
+            "response.payload.assessment",
+        )
+    elif role == "plan_proposer":
+        _validate_plan(payload["plan"], "response.payload.plan")
+    elif role == "semantic_reviewer":
+        findings = _array(payload["findings"], "response.payload.findings", maximum=1_024)
+        finding_ids: list[str] = []
+        for index, finding in enumerate(findings):
+            finding_ids.append(
+                _validate_semantic_finding(
+                    finding,
+                    f"response.payload.findings[{index}]",
+                )
+            )
+        _require_unique(finding_ids, "response.payload.findings finding IDs")
+    else:
+        _validate_repair(payload["repair"], "response.payload.repair")
+
+
+def _identifier_object(value: Any, path: str, field: str) -> Mapping[str, Any]:
+    item = _object(value, path)
+    _exact_fields(item, {field}, path)
+    _required_string(item[field], f"{path}.{field}", maximum=128)
+    return item
+
+
+def _half_open_dates(start: Any, end: Any, path: str) -> None:
+    start_text = _required_string(start, f"{path}.start", maximum=10)
+    end_text = _required_string(end, f"{path}.end", maximum=10)
+    if not _CANONICAL_DATE.fullmatch(start_text) or not _CANONICAL_DATE.fullmatch(end_text):
+        raise RuntimeContractError(f"{path} must contain canonical ISO dates")
+    try:
+        start_date = date.fromisoformat(start_text)
+        end_date = date.fromisoformat(end_text)
+    except ValueError as exc:
+        raise RuntimeContractError(f"{path} must contain valid ISO dates") from exc
+    if end_date <= start_date:
+        raise RuntimeContractError(f"{path} must be a non-empty half-open range")
+
+
+def _canonical_utc_datetime(value: Any, path: str) -> datetime:
+    text = _required_string(value, path, maximum=64)
+    if not _CANONICAL_UTC.fullmatch(text):
+        raise RuntimeContractError(f"{path} must be a canonical UTC timestamp ending in Z")
+    try:
+        parsed = datetime.fromisoformat(text[:-1] + "+00:00")
+    except ValueError as exc:
+        raise RuntimeContractError(f"{path} must be a valid UTC timestamp") from exc
+    if parsed.tzinfo != UTC:
+        raise RuntimeContractError(f"{path} must be UTC")
+    return parsed
+
+
+def _enum_string(value: Any, path: str, allowed: frozenset[str]) -> str:
+    result = _required_string(value, path, maximum=128)
+    if result not in allowed:
+        raise RuntimeContractError(f"{path} is unsupported")
+    return result
+
+
+def _validate_source_candidate(value: Any, path: str) -> str:
+    item = _object(value, path)
+    _exact_fields(
+        item,
+        {
+            "source_id",
+            "name",
+            "source_class",
+            "locator",
+            "observed_at",
+            "coverage",
+            "delay",
+            "liveness",
+            "rights_status",
+            "evidence",
+        },
+        path,
+    )
+    source_id = _identifier(item["source_id"], f"{path}.source_id")
+    _required_string(item["name"], f"{path}.name", maximum=512)
+    # Coarse source-class family; see the vocabulary map in sources/contracts.py.
+    _enum_string(
+        item["source_class"],
+        f"{path}.source_class",
+        frozenset({"external", "user"}),
+    )
+    _required_string(item["locator"], f"{path}.locator", maximum=2_048)
+    observed_at = _canonical_utc_datetime(item["observed_at"], f"{path}.observed_at")
+    coverage = _object(item["coverage"], f"{path}.coverage")
+    _exact_fields(coverage, {"start", "end", "population"}, f"{path}.coverage")
+    _half_open_dates(coverage["start"], coverage["end"], f"{path}.coverage")
+    _required_string(coverage["population"], f"{path}.coverage.population", maximum=1_000)
+    delay_observed_at = _validate_delay(item["delay"], f"{path}.delay")
+    liveness_checked_at = _validate_liveness(item["liveness"], f"{path}.liveness")
+    if delay_observed_at > observed_at:
+        raise RuntimeContractError(f"{path}.delay.observed_at cannot follow observed_at")
+    if liveness_checked_at > observed_at:
+        raise RuntimeContractError(f"{path}.liveness.checked_at cannot follow observed_at")
+    # Spelling is shared with local_contracts and sources/contracts; see the vocabulary map.
+    _enum_string(
+        item["rights_status"],
+        f"{path}.rights_status",
+        frozenset({"approved", "conditional", "unclear", "prohibited"}),
+    )
+    _string_array(item["evidence"], f"{path}.evidence", nonempty=True, maximum=64)
+    return source_id
+
+
+def _validate_delay(value: Any, path: str) -> datetime:
+    delay = _object(value, path)
+    _exact_fields(delay, {"typical_seconds", "maximum_seconds", "observed_at"}, path)
+    typical = _nonnegative_int(delay["typical_seconds"], f"{path}.typical_seconds")
+    maximum = _nonnegative_int(delay["maximum_seconds"], f"{path}.maximum_seconds")
+    if maximum < typical:
+        raise RuntimeContractError(f"{path}.maximum_seconds cannot be below typical_seconds")
+    return _canonical_utc_datetime(delay["observed_at"], f"{path}.observed_at")
+
+
+def _validate_liveness(value: Any, path: str) -> datetime:
+    liveness = _object(value, path)
+    _exact_fields(liveness, {"status", "checked_at"}, path)
+    # unknown has no local_contracts counterpart; see the vocabulary map in sources/contracts.py.
+    _enum_string(
+        liveness["status"],
+        f"{path}.status",
+        frozenset({"live", "delayed", "dead", "unknown"}),
+    )
+    return _canonical_utc_datetime(liveness["checked_at"], f"{path}.checked_at")
+
+
+def _validate_source_assessment(value: Any, path: str) -> None:
+    assessment = _object(value, path)
+    _exact_fields(
+        assessment,
+        {
+            "fitness",
+            "coverage",
+            "delay",
+            "liveness",
+            "rights_status",
+            "data_classification",
+            "retention",
+            "evidence",
+            "rejection_codes",
+        },
+        path,
+    )
+    # Stage-specific triplet; see the vocabulary map in sources/contracts.py.
+    _enum_string(
+        assessment["fitness"],
+        f"{path}.fitness",
+        frozenset({"fit", "conditional", "reject"}),
+    )
+    coverage = _object(assessment["coverage"], f"{path}.coverage")
+    _exact_fields(coverage, {"start", "end", "population"}, f"{path}.coverage")
+    _half_open_dates(coverage["start"], coverage["end"], f"{path}.coverage")
+    _required_string(coverage["population"], f"{path}.coverage.population", maximum=1_000)
+    delay_observed_at = _validate_delay(assessment["delay"], f"{path}.delay")
+    liveness_checked_at = _validate_liveness(assessment["liveness"], f"{path}.liveness")
+    if delay_observed_at > liveness_checked_at:
+        raise RuntimeContractError(f"{path}.delay.observed_at cannot follow liveness.checked_at")
+    # Spelling is shared with local_contracts and sources/contracts; see the vocabulary map.
+    _enum_string(
+        assessment["rights_status"],
+        f"{path}.rights_status",
+        frozenset({"approved", "conditional", "unclear", "prohibited"}),
+    )
+    # sources/contracts adds a terminal rejected state; see the vocabulary map.
+    _enum_string(
+        assessment["data_classification"],
+        f"{path}.data_classification",
+        frozenset({"public", "internal", "confidential", "restricted"}),
+    )
+    retention = _object(assessment["retention"], f"{path}.retention")
+    _exact_fields(
+        retention,
+        {"raw_days", "derived_days", "tombstone_required"},
+        f"{path}.retention",
+    )
+    _nonnegative_int(retention["raw_days"], f"{path}.retention.raw_days")
+    _nonnegative_int(retention["derived_days"], f"{path}.retention.derived_days")
+    if type(retention["tombstone_required"]) is not bool:
+        raise RuntimeContractError(f"{path}.retention.tombstone_required must be a boolean")
+    _string_array(assessment["evidence"], f"{path}.evidence", nonempty=True, maximum=128)
+    _string_array(
+        assessment["rejection_codes"],
+        f"{path}.rejection_codes",
+        nonempty=False,
+        maximum=64,
+    )
+
+
+def _validate_operation(value: Any, path: str) -> tuple[str, tuple[str, ...], tuple[str, ...]]:
+    operation = _object(value, path)
+    _exact_fields(
+        operation,
+        {"operation_id", "kind", "inputs", "outputs", "parameters"},
+        path,
+    )
+    operation_id = _identifier(operation["operation_id"], f"{path}.operation_id")
+    _enum_string(
+        operation["kind"],
+        f"{path}.kind",
+        frozenset(
+            {
+                "profile",
+                "clean",
+                "normalize",
+                "resolve",
+                "join",
+                "label",
+                "validate",
+            }
+        ),
+    )
+    inputs = _string_array(operation["inputs"], f"{path}.inputs", nonempty=True, maximum=128)
+    outputs = _string_array(operation["outputs"], f"{path}.outputs", nonempty=True, maximum=128)
+    _object(operation["parameters"], f"{path}.parameters")
+    return operation_id, inputs, outputs
+
+
+def _validate_plan(value: Any, path: str) -> None:
+    plan = _object(value, path)
+    _exact_fields(
+        plan,
+        {
+            "plan_id",
+            "source_ids",
+            "output_grain",
+            "operations",
+            "validation_rules",
+            "temporal_policy",
+        },
+        path,
+    )
+    _identifier(plan["plan_id"], f"{path}.plan_id")
+    source_ids = _string_array(plan["source_ids"], f"{path}.source_ids", nonempty=True, maximum=256)
+    for index, source_id in enumerate(source_ids):
+        _identifier(source_id, f"{path}.source_ids[{index}]")
+    _string_array(plan["output_grain"], f"{path}.output_grain", nonempty=True, maximum=128)
+    operations = _array(plan["operations"], f"{path}.operations", nonempty=True, maximum=512)
+    operation_ids: list[str] = []
+    available_inputs = set(source_ids)
+    referenced_sources: set[str] = set()
+    for index, operation in enumerate(operations):
+        operation_id, inputs, outputs = _validate_operation(
+            operation, f"{path}.operations[{index}]"
+        )
+        if operation_id in operation_ids:
+            raise RuntimeContractError(f"{path}.operations operation IDs must be unique")
+        operation_ids.append(operation_id)
+        unknown_inputs = set(inputs) - available_inputs
+        if unknown_inputs:
+            raise RuntimeContractError(
+                f"{path}.operations[{index}].inputs has unknown references {sorted(unknown_inputs)}"
+            )
+        referenced_sources.update(set(inputs) & set(source_ids))
+        collisions = set(outputs) & available_inputs
+        if collisions:
+            raise RuntimeContractError(
+                f"{path}.operations[{index}].outputs redefines references {sorted(collisions)}"
+            )
+        available_inputs.update(outputs)
+    _require_unique(operation_ids, f"{path}.operations operation IDs")
+    if referenced_sources != set(source_ids):
+        raise RuntimeContractError(f"{path}.source_ids must all be referenced by operations")
+    rules = _array(
+        plan["validation_rules"],
+        f"{path}.validation_rules",
+        nonempty=True,
+        maximum=512,
+    )
+    rule_ids: list[str] = []
+    for index, value_rule in enumerate(rules):
+        rule_path = f"{path}.validation_rules[{index}]"
+        rule = _object(value_rule, rule_path)
+        _exact_fields(rule, {"rule_id", "kind", "columns", "severity"}, rule_path)
+        rule_ids.append(_identifier(rule["rule_id"], f"{rule_path}.rule_id"))
+        _required_string(rule["kind"], f"{rule_path}.kind", maximum=128)
+        _string_array(rule["columns"], f"{rule_path}.columns", nonempty=True, maximum=128)
+        _enum_string(
+            rule["severity"],
+            f"{rule_path}.severity",
+            frozenset({"blocker", "critical", "high", "medium", "low"}),
+        )
+    _require_unique(rule_ids, f"{path}.validation_rules rule IDs")
+    temporal = _object(plan["temporal_policy"], f"{path}.temporal_policy")
+    _exact_fields(
+        temporal,
+        {"cutoff", "event_time_column", "knowledge_time_column"},
+        f"{path}.temporal_policy",
+    )
+    _canonical_utc_datetime(temporal["cutoff"], f"{path}.temporal_policy.cutoff")
+    event_time_column = _required_string(
+        temporal["event_time_column"],
+        f"{path}.temporal_policy.event_time_column",
+        maximum=128,
+    )
+    knowledge_time_column = _required_string(
+        temporal["knowledge_time_column"],
+        f"{path}.temporal_policy.knowledge_time_column",
+        maximum=128,
+    )
+    if event_time_column == knowledge_time_column:
+        raise RuntimeContractError(f"{path}.temporal_policy time columns must be distinct")
+
+
+def _validate_semantic_finding(value: Any, path: str) -> str:
+    finding = _object(value, path)
+    _exact_fields(
+        finding,
+        {
+            "evaluator_finding_id",
+            "severity",
+            "category",
+            "summary",
+            "evidence_digest",
+            "affected_artifact",
+            "acceptance_conditions",
+            "code",
+        },
+        path,
+    )
+    finding_id = _required_string(
+        finding["evaluator_finding_id"],
+        f"{path}.evaluator_finding_id",
+        maximum=128,
+    )
+    if not _SCOPE_IDENTIFIER.fullmatch(finding_id):
+        raise RuntimeContractError(f"{path}.evaluator_finding_id is not canonical")
+    code = _required_string(finding["code"], f"{path}.code", maximum=128)
+    if not _FINDING_CODE.fullmatch(code):
+        raise RuntimeContractError(f"{path}.code is not canonical")
+    _enum_string(
+        finding["severity"],
+        f"{path}.severity",
+        frozenset({"blocker", "critical", "high", "medium", "low"}),
+    )
+    _enum_string(
+        finding["category"],
+        f"{path}.category",
+        frozenset(
+            {
+                "source_fitness",
+                "schema",
+                "data_quality",
+                "temporal_integrity",
+                "join_cardinality",
+                "lineage",
+                "rights",
+                "security",
+                "reproducibility",
+                "other",
+            }
+        ),
+    )
+    _required_string(finding["summary"], f"{path}.summary", maximum=2_000)
+    evidence_digest = _required_string(
+        finding["evidence_digest"],
+        f"{path}.evidence_digest",
+        maximum=71,
+    )
+    if not _WIRE_SHA256.fullmatch(evidence_digest):
+        raise RuntimeContractError(f"{path}.evidence_digest is not a canonical wire digest")
+    affected = _object(finding["affected_artifact"], f"{path}.affected_artifact")
+    _exact_fields(
+        affected,
+        {"artifact_id", "kind", "content_digest"},
+        f"{path}.affected_artifact",
+    )
+    artifact_id = _required_string(
+        affected["artifact_id"],
+        f"{path}.affected_artifact.artifact_id",
+        maximum=36,
+    )
+    if not _UUID.fullmatch(artifact_id):
+        raise RuntimeContractError(f"{path}.affected_artifact.artifact_id is not canonical")
+    kind = _required_string(
+        affected["kind"],
+        f"{path}.affected_artifact.kind",
+        maximum=64,
+    )
+    if not _ARTIFACT_KIND.fullmatch(kind):
+        raise RuntimeContractError(f"{path}.affected_artifact.kind is not canonical")
+    content_digest = _required_string(
+        affected["content_digest"],
+        f"{path}.affected_artifact.content_digest",
+        maximum=71,
+    )
+    if not _WIRE_SHA256.fullmatch(content_digest):
+        raise RuntimeContractError(
+            f"{path}.affected_artifact.content_digest is not a canonical wire digest"
+        )
+    conditions = _string_array(
+        finding["acceptance_conditions"],
+        f"{path}.acceptance_conditions",
+        nonempty=True,
+        maximum=32,
+    )
+    if any(len(condition) > 1_000 for condition in conditions):
+        raise RuntimeContractError(f"{path}.acceptance_conditions contains oversized text")
+    return finding_id
+
+
+def _validate_repair(value: Any, path: str) -> None:
+    repair = _object(value, path)
+    _exact_fields(
+        repair,
+        {
+            "repair_id",
+            "finding_ids",
+            "operations",
+            "acceptance_evidence",
+            "successor_required",
+        },
+        path,
+    )
+    _identifier(repair["repair_id"], f"{path}.repair_id")
+    _string_array(repair["finding_ids"], f"{path}.finding_ids", nonempty=True, maximum=256)
+    operations = _array(
+        repair["operations"],
+        f"{path}.operations",
+        nonempty=True,
+        maximum=256,
+    )
+    operation_ids: list[str] = []
+    for index, value_operation in enumerate(operations):
+        operation_path = f"{path}.operations[{index}]"
+        operation = _object(value_operation, operation_path)
+        _exact_fields(
+            operation,
+            {"operation_id", "kind", "target", "parameters"},
+            operation_path,
+        )
+        operation_ids.append(
+            _identifier(
+                operation["operation_id"],
+                f"{operation_path}.operation_id",
+            )
+        )
+        _required_string(operation["kind"], f"{operation_path}.kind", maximum=128)
+        _required_string(operation["target"], f"{operation_path}.target", maximum=512)
+        _object(operation["parameters"], f"{operation_path}.parameters")
+    _require_unique(operation_ids, f"{path}.operations operation IDs")
+    _string_array(
+        repair["acceptance_evidence"],
+        f"{path}.acceptance_evidence",
+        nonempty=True,
+        maximum=128,
+    )
+    if repair["successor_required"] is not True:
+        raise RuntimeContractError(f"{path}.successor_required must be true")
+
+
+def _strict_json_value(value: Any, path: str, *, depth: int, state: list[int]) -> Any:
+    state[0] += 1
+    if state[0] > 4_096:
+        raise RuntimeContractError(f"{path} exceeds the structured payload node limit")
+    if depth > 16:
+        raise RuntimeContractError(f"{path} exceeds the structured payload depth limit")
+    if value is None or type(value) is bool:
+        return value
+    if type(value) is int:
+        if not -MAX_ACCOUNTING_INTEGER <= value <= MAX_ACCOUNTING_INTEGER:
+            raise RuntimeContractError(f"{path} integer is outside the supported range")
+        return value
+    if isinstance(value, str):
+        if len(value) > 100_000:
+            raise RuntimeContractError(f"{path} string exceeds 100000 characters")
+        return value
+    if isinstance(value, Mapping):
+        if len(value) > 1_024 or any(not isinstance(key, str) for key in value):
+            raise RuntimeContractError(f"{path} must be a bounded object with string keys")
+        return {
+            key: _strict_json_value(item, f"{path}.{key}", depth=depth + 1, state=state)
+            for key, item in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        if len(value) > 1_024:
+            raise RuntimeContractError(f"{path} array exceeds 1024 entries")
+        return [
+            _strict_json_value(item, f"{path}[{index}]", depth=depth + 1, state=state)
+            for index, item in enumerate(value)
+        ]
+    raise RuntimeContractError(f"{path} contains unsupported value type {type(value).__name__}")
+
+
+def _canonical_json_bytes(value: Any) -> bytes:
+    normalized = _strict_json_value(value, "value", depth=0, state=[0])
+    return (
+        json.dumps(
+            normalized,
+            ensure_ascii=False,
+            allow_nan=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode("utf-8")
+        + b"\n"
+    )
+
+
+def _safe_response_hash(value: Any) -> str:
+    try:
+        raw = _canonical_json_bytes(value)
+    except RuntimeContractError:
+        raw = f"<unsupported:{type(value).__module__}.{type(value).__qualname__}>".encode()
+    return _sha256(raw)
+
+
+def _provider_configuration_digest(adapter: ProviderAdapter) -> str:
+    declared = getattr(adapter, "configuration_sha256", None)
+    if declared is not None:
+        return _digest(declared, "adapter.configuration_sha256")
+    return _sha256(
+        _canonical_json_bytes(
+            {
+                "provider": adapter.provider,
+                "model_identifier": adapter.model_identifier,
+            }
+        )
+    )
+
+
+def _prompt_digest(request: AgentRequest) -> str:
+    return _sha256(
+        _canonical_json_bytes(
+            {
+                "prompt_template_version": request.prompt_template_version,
+                "payload_schema_version": request.payload_schema_version,
+                "payload": request.payload,
+            }
+        )
+    )
+
+
+def _reject_duplicate_pairs(pairs: Sequence[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise RuntimeContractError(f"duplicate JSON key: {key!r}")
+        result[key] = value
+    return result
+
+
+def _reject_json_constant(value: str) -> Any:
+    raise RuntimeContractError(f"unsupported JSON constant: {value}")
+
+
+def _object(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value):
+        raise RuntimeContractError(f"{path} must be an object with string keys")
+    return value
+
+
+def _array(
+    value: Any,
+    path: str,
+    *,
+    nonempty: bool = False,
+    maximum: int,
+) -> Sequence[Any]:
+    if not isinstance(value, list):
+        raise RuntimeContractError(f"{path} must be an array")
+    if nonempty and not value:
+        raise RuntimeContractError(f"{path} cannot be empty")
+    if len(value) > maximum:
+        raise RuntimeContractError(f"{path} exceeds {maximum} entries")
+    return value
+
+
+def _string_array(
+    value: Any,
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+) -> tuple[str, ...]:
+    values = _array(value, path, nonempty=nonempty, maximum=maximum)
+    parsed = tuple(
+        _required_string(item, f"{path}[{index}]", maximum=10_000)
+        for index, item in enumerate(values)
+    )
+    _require_unique(parsed, path)
+    return parsed
+
+
+def _exact_fields(
+    data: Mapping[str, Any],
+    required: set[str],
+    path: str,
+    *,
+    optional: set[str] | None = None,
+) -> None:
+    optional = optional or set()
+    missing = required - data.keys()
+    extra = data.keys() - required - optional
+    if missing or extra:
+        raise RuntimeContractError(
+            f"{path} has invalid fields; missing={sorted(missing)}, extra={sorted(extra)}"
+        )
+
+
+def _required_string(value: Any, path: str, *, maximum: int) -> str:
+    if not isinstance(value, str) or not value or value != value.strip():
+        raise RuntimeContractError(f"{path} must be nonempty trimmed text")
+    if len(value) > maximum:
+        raise RuntimeContractError(f"{path} exceeds {maximum} characters")
+    if any(ord(char) < 0x20 and char not in "\t\n\r" for char in value):
+        raise RuntimeContractError(f"{path} contains a control character")
+    return value
+
+
+def _identifier(value: Any, path: str) -> str:
+    text = _required_string(value, path, maximum=128)
+    if not _IDENTIFIER.fullmatch(text):
+        raise RuntimeContractError(f"{path} must be a canonical lowercase identifier")
+    return text
+
+
+def _version(value: Any, path: str) -> str:
+    text = _required_string(value, path, maximum=128)
+    if not _IDENTIFIER.fullmatch(text) or "." not in text:
+        raise RuntimeContractError(f"{path} must be a canonical version identifier")
+    return text
+
+
+def _digest(value: Any, path: str) -> str:
+    if not isinstance(value, str) or not _SHA256.fullmatch(value):
+        raise RuntimeContractError(f"{path} must be a lowercase SHA-256 digest")
+    return value
+
+
+def _nonnegative_int(value: Any, path: str) -> int:
+    if type(value) is not int or value < 0:
+        raise RuntimeContractError(f"{path} must be a nonnegative integer")
+    return value
+
+
+def _positive_int(value: Any, path: str) -> int:
+    if type(value) is not int or value < 1:
+        raise RuntimeContractError(f"{path} must be a positive integer")
+    return value
+
+
+def _accounting_int(value: Any, path: str) -> int:
+    _nonnegative_int(value, path)
+    if value > MAX_ACCOUNTING_INTEGER:
+        raise RuntimeContractError(f"{path} exceeds the signed 64-bit accounting range")
+    return value
+
+
+def _positive_accounting_int(value: Any, path: str) -> int:
+    _positive_int(value, path)
+    if value > MAX_ACCOUNTING_INTEGER:
+        raise RuntimeContractError(f"{path} exceeds the signed 64-bit accounting range")
+    return value
+
+
+def _provider_accounting(value: Any, path: str) -> tuple[int, bool]:
+    _nonnegative_int(value, f"provider.{path}")
+    return min(value, MAX_ACCOUNTING_INTEGER), value > MAX_ACCOUNTING_INTEGER
+
+
+def _checked_add(left: int, right: int, path: str) -> int:
+    result = left + right
+    if result > MAX_ACCOUNTING_INTEGER:
+        raise RuntimeContractError(f"{path} exceeds the signed 64-bit accounting range")
+    return result
+
+
+def _require_unique(values: Sequence[str] | Any, path: str) -> None:
+    sequence = tuple(values)
+    if len(sequence) != len(set(sequence)):
+        raise RuntimeContractError(f"{path} must be unique")
+
+
+def _sha256(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _stable_failure_code(error: Exception) -> str:
+    text = str(error)
+    for candidate in (
+        "input_tokens_per_call",
+        "output_tokens_per_call",
+        "total_tokens_per_call",
+        "cost_micros_per_call",
+        "time_micros_per_call",
+        "input_tokens_per_run",
+        "output_tokens_per_run",
+        "total_tokens_per_run",
+        "cost_micros_per_run",
+        "time_micros_per_run",
+        "calls",
+    ):
+        if candidate in text:
+            return f"{candidate}_exhausted"
+    return "budget_reservation_denied"
+
+
+def _after_budget_code(exceeded: Sequence[str]) -> str:
+    return f"{sorted(exceeded)[0]}_exceeded"
+
+
+def _monotonic_micros() -> int:
+    import time
+
+    return time.monotonic_ns() // 1_000
+
+
+__all__ = [
+    "AGENT_EVIDENCE_VERSION",
+    "AGENT_REQUEST_VERSION",
+    "AGENT_RESPONSE_VERSION",
+    "AGENT_ROLES",
+    "AGENT_RUNTIME_VERSION",
+    "MAX_ACCOUNTING_INTEGER",
+    "REPLAY_CATALOG_VERSION",
+    "ROLE_PAYLOAD_SCHEMAS",
+    "SEMANTIC_REVIEW_INPUT_VERSION",
+    "SEMANTIC_REVIEW_OUTPUT_VERSION",
+    "TOOL_POLICY_VERSION",
+    "AgentCallCancelled",
+    "AgentCallEvidence",
+    "AgentCallFailure",
+    "AgentCallResult",
+    "AgentCallTimedOut",
+    "AgentRequest",
+    "AgentResponse",
+    "AgentRuntime",
+    "BudgetExceededAfterCall",
+    "BudgetExceededBeforeCall",
+    "BudgetLedger",
+    "BudgetLimits",
+    "BudgetSnapshot",
+    "MalformedProviderResponse",
+    "ProviderAdapter",
+    "ProviderAgentRuntime",
+    "ProviderCallFailed",
+    "ProviderResult",
+    "ProviderTimeoutError",
+    "ReplayAgentRuntime",
+    "ReplayAmbiguityError",
+    "ReplayError",
+    "ReplayMissError",
+    "ReplayTamperError",
+    "ReplayVersionError",
+    "RuntimeContractError",
+    "SecretReference",
+    "TimingEvidence",
+    "ToolCallEvidence",
+    "ToolInvocation",
+    "ToolPolicy",
+    "ToolPolicyDenied",
+    "ToolPolicyError",
+    "Usage",
+]