agentprov-capture 0.1.1__py3-none-any.whl

agentprov_capture/__init__.py

@@ -0,0 +1,5 @@
+"""agentprov_capture: the capture/0.1 raw-evidence event log shared by the AgentPROV core (reader and
+verifier) and the isolated live backends (writer). Stdlib + rfc8785 only, Python >= 3.12."""
+
+FORMAT = "capture/0.1"
+__version__ = "0.1.1"  # equals capture/pyproject.toml (tests/unit/test_versions_source.py)

agentprov_capture/endpoints.py

@@ -0,0 +1,252 @@
+"""The endpoint registry: ``endpoints.toml`` as validated data (MN M.1.10 item 2; N.2.1, N.2.1a; G.9.2).
+
+Stdlib only (``tomllib``; Python >= 3.12). The registry names environment variables, never values. Rules enforced here:
+
+* a base URL is https, except loopback (``127.0.0.1``, ``[::1]``, ``localhost``);
+* a base URL has no userinfo, query or fragment (a key could hide in them; G.6.4);
+* a ``local`` entry is loopback and names its ``server`` kind (D-690). Its ``api_key_env`` is optional: a server set up
+  with an API key (oMLX's, D-827) gets it as a bearer header when the key is set, and none otherwise. A non-local entry
+  names ``api_key_env`` and has no ``server``;
+* a custom base URL's host must equal the registered host unless the caller passes ``allow_custom=True``
+  (the CLI's ``--allow-custom-endpoint``, recorded in the manifest);
+* ``api`` names the wire format the endpoint speaks: ``openai_chat`` (the default; OpenAI-compatible chat completions)
+  or ``anthropic_messages`` (the Anthropic Messages API; D-656).
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import tomllib
+from dataclasses import dataclass
+from importlib import resources
+from typing import Any, Final
+from urllib.parse import urlsplit
+
+__all__ = [
+    "API_KINDS",
+    "LOCAL_SERVERS",
+    "LOOPBACK_HOSTS",
+    "Endpoint",
+    "EndpointError",
+    "check_base_url",
+    "get_endpoint",
+    "is_loopback_host",
+    "is_private_lan_host",
+    "load_endpoints",
+    "parse_registry",
+    "validate_base_url",
+]
+
+#: The loopback hosts of G.9.2, as ``urllib.parse`` reports them (brackets removed from the IPv6 literal).
+LOOPBACK_HOSTS: Final = frozenset({"127.0.0.1", "::1", "localhost"})
+
+#: The wire formats an endpoint may speak (``api``); the first is the default.
+API_KINDS: Final = ("openai_chat", "anthropic_messages")
+#: The local server kinds of D-690. ``server`` selects the discovery and fingerprint probes of ``agentprov models``.
+LOCAL_SERVERS: Final = frozenset({"ollama", "omlx", "lmstudio", "mlx_lm", "llamacpp", "vllm"})
+
+_ENV_NAME: Final = re.compile(r"[A-Z][A-Z0-9_]{0,63}")
+_ENDPOINT_NAME: Final = re.compile(r"[a-z][a-z0-9_-]{0,31}")
+_HEADER_NAME: Final = re.compile(r"[a-z0-9][a-z0-9-]{0,63}")
+_ENTRY_KEYS: Final = frozenset(
+    {
+        "base_url",
+        "base_url_env",
+        "api_key_env",
+        "model_env",
+        "local",
+        "server_max_concurrency",
+        "request_headers",
+        "response_headers",
+        "api",
+        "server",
+    }
+)
+
+
+class EndpointError(ValueError):
+    """A registry or base-URL violation. ``code`` is stable; messages never carry values from the environment."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+
+
+@dataclass(frozen=True, slots=True)
+class Endpoint:
+    """One registry entry. ``*_env`` fields are environment-variable NAMES (or None), never values."""
+
+    name: str
+    base_url: str
+    host: str
+    base_url_env: str | None
+    api_key_env: str | None
+    model_env: str | None
+    local: bool
+    server_max_concurrency: int | None
+    #: header NAMES (lower case) whose values wire-capture redaction may record besides the global allowlist
+    #: (``redact_allowlist.toml``): for example an API-version header (request) or a request-id header (response).
+    #: The hard denylist of G.6.4 wins over them.
+    request_headers: tuple[str, ...] = ()
+    response_headers: tuple[str, ...] = ()
+    #: the wire format (one of :data:`API_KINDS`): which LLM element and recorder the harness uses (D-656)
+    api: str = API_KINDS[0]
+    #: the local server kind (one of :data:`LOCAL_SERVERS`) for a ``local`` entry; ``None`` for a remote one (D-690)
+    server: str | None = None
+
+
+def is_loopback_host(host: str) -> bool:
+    return host.lower() in LOOPBACK_HOSTS
+
+
+#: The private ranges a LAN endpoint may use (D-698): RFC 1918, the shared address space of RFC 6598 (CGNAT, used by
+#: Tailscale-style overlays), and IPv6 unique local addresses. Link-local, loopback and every public range are not.
+LAN_NETWORKS: Final = tuple(ipaddress.ip_network(n) for n in (
+    "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10", "fc00::/7"))
+
+
+def is_private_lan_host(host: str) -> bool:
+    """A literal IP address in :data:`LAN_NETWORKS` (never a name: a name can be made to resolve anywhere), without an
+    IPv6 zone id (``%en0`` names an interface of this host, not a LAN peer)."""
+    if "%" in host:
+        return False
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    return any(address in net for net in LAN_NETWORKS if net.version == address.version)
+
+
+def validate_base_url(base_url: str, *, allow_lan: bool = False) -> str:
+    """Check the G.9.2 / G.6.4 rules on ``base_url`` and return its host (lower case).
+
+    http is allowed on a loopback host, and, with ``allow_lan`` (the CLI's ``--allow-lan-endpoint``, D-698), on a
+    literal private address. Raises :class:`EndpointError` (``endpoint.url.*``). Nothing is fetched or resolved.
+    """
+    if not isinstance(base_url, str) or not base_url or any(ord(c) < 0x21 or ord(c) == 0x7F for c in base_url):
+        raise EndpointError("endpoint.url.malformed", "base URL is empty or contains whitespace or control characters")
+    try:
+        parts = urlsplit(base_url)
+        host = parts.hostname
+        parts.port  # noqa: B018 - raises ValueError on a bad port
+    except ValueError:
+        raise EndpointError("endpoint.url.malformed", "base URL cannot be parsed") from None
+    if parts.scheme not in ("http", "https") or not host:
+        raise EndpointError("endpoint.url.malformed", "base URL needs an http(s) scheme and a host")
+    if parts.username is not None or parts.password is not None or "@" in parts.netloc:
+        raise EndpointError("endpoint.url.userinfo", "base URL must not carry userinfo")
+    if parts.query or "?" in base_url:
+        raise EndpointError("endpoint.url.query", "base URL must not carry a query string")
+    if parts.fragment or "#" in base_url:
+        raise EndpointError("endpoint.url.fragment", "base URL must not carry a fragment")
+    host = host.lower()
+    if parts.scheme != "https" and not is_loopback_host(host) and not (allow_lan and is_private_lan_host(host)):
+        raise EndpointError("endpoint.url.not_https", "base URL must be https unless the host is loopback")
+    return host
+
+
+def check_base_url(endpoint: Endpoint, base_url: str, *, allow_custom: bool = False) -> bool:
+    """Validate a base URL given for ``endpoint`` (e.g. from its ``base_url_env``). Returns True when it is a custom
+    endpoint (its host differs from the registered one), which the caller must record in the manifest.
+
+    The https/loopback/userinfo/query rules always apply. A host mismatch raises ``endpoint.url.host_mismatch``
+    unless ``allow_custom`` (the CLI's ``--allow-custom-endpoint``, R-39).
+    """
+    host = validate_base_url(base_url)
+    if host == endpoint.host:
+        return False
+    if not allow_custom:
+        raise EndpointError("endpoint.url.host_mismatch", f"host does not match the registered host of {endpoint.name!r}")
+    return True
+
+
+def _opt_env(entry: dict[str, Any], key: str, name: str) -> str | None:
+    value = entry.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not _ENV_NAME.fullmatch(value):
+        raise EndpointError("endpoint.registry.env_name", f"endpoint {name!r}: {key} must be an upper-case variable name")
+    return value
+
+
+def _opt_headers(entry: dict[str, Any], key: str, name: str) -> tuple[str, ...]:
+    value = entry.get(key, [])
+    if not isinstance(value, list) or not all(isinstance(h, str) and _HEADER_NAME.fullmatch(h) for h in value):
+        raise EndpointError("endpoint.registry.header", f"endpoint {name!r}: {key} must be a list of lower-case header names")
+    return tuple(sorted(set(value)))
+
+
+def parse_registry(data: dict[str, Any]) -> dict[str, Endpoint]:
+    """Validate a parsed ``endpoints.toml`` document and return the entries by name, sorted."""
+    if data.get("version") != 1:
+        raise EndpointError("endpoint.registry.version", "unsupported registry version")
+    entries = data.get("endpoints")
+    if not isinstance(entries, dict) or not entries:
+        raise EndpointError("endpoint.registry.empty", "registry has no [endpoints.*] tables")
+    out: dict[str, Endpoint] = {}
+    for name in sorted(entries):
+        entry = entries[name]
+        if not _ENDPOINT_NAME.fullmatch(name) or not isinstance(entry, dict):
+            raise EndpointError("endpoint.registry.name", "bad endpoint name or entry")
+        unknown = set(entry) - _ENTRY_KEYS
+        if unknown:
+            raise EndpointError("endpoint.registry.key", f"endpoint {name!r}: unknown key {sorted(unknown)[0]!r}")
+        base_url = entry.get("base_url")
+        if not isinstance(base_url, str):
+            raise EndpointError("endpoint.registry.base_url", f"endpoint {name!r}: base_url is required")
+        host = validate_base_url(base_url)
+        local = entry.get("local", False)
+        if not isinstance(local, bool):
+            raise EndpointError("endpoint.registry.local", f"endpoint {name!r}: local must be a boolean")
+        if local and not is_loopback_host(host):
+            raise EndpointError("endpoint.registry.local", f"endpoint {name!r}: a local entry must be loopback")
+        api_key_env = _opt_env(entry, "api_key_env", name)
+        if not local and api_key_env is None:
+            raise EndpointError("endpoint.registry.api_key_env", f"endpoint {name!r}: api_key_env is required")
+        server = entry.get("server")
+        if local and (not isinstance(server, str) or server not in LOCAL_SERVERS):
+            raise EndpointError("endpoint.registry.server", f"endpoint {name!r}: a local entry needs server, one of "
+                                f"{sorted(LOCAL_SERVERS)}")
+        if not local and server is not None:
+            raise EndpointError("endpoint.registry.server", f"endpoint {name!r}: server belongs to local entries")
+        conc = entry.get("server_max_concurrency")
+        if conc is not None and (isinstance(conc, bool) or not isinstance(conc, int) or conc < 1):
+            raise EndpointError(
+                "endpoint.registry.concurrency", f"endpoint {name!r}: server_max_concurrency must be an integer >= 1"
+            )
+        api = entry.get("api", API_KINDS[0])
+        if api not in API_KINDS:
+            raise EndpointError("endpoint.registry.api", f"endpoint {name!r}: api must be one of {list(API_KINDS)}")
+        if local and api != API_KINDS[0]:  # every local server kind of D-690 speaks the OpenAI chat wire
+            raise EndpointError("endpoint.registry.local_api", f"endpoint {name!r}: a local entry speaks {API_KINDS[0]}")
+        out[name] = Endpoint(
+            name=name,
+            base_url=base_url,
+            host=host,
+            base_url_env=_opt_env(entry, "base_url_env", name),
+            api_key_env=api_key_env,
+            model_env=_opt_env(entry, "model_env", name),
+            local=local,
+            server_max_concurrency=conc,
+            request_headers=_opt_headers(entry, "request_headers", name),
+            response_headers=_opt_headers(entry, "response_headers", name),
+            api=api,
+            server=server,
+        )
+    return out
+
+
+def load_endpoints() -> dict[str, Endpoint]:
+    """Load and validate the packaged ``endpoints.toml`` (read through ``importlib.resources``)."""
+    raw = resources.files("agentprov_capture").joinpath("endpoints.toml").read_bytes()
+    return parse_registry(tomllib.loads(raw.decode("utf-8")))
+
+
+def get_endpoint(name: str) -> Endpoint:
+    """The registry entry ``name`` (``EndpointError("endpoint.unknown")`` if absent)."""
+    registry = load_endpoints()
+    try:
+        return registry[name]
+    except KeyError:
+        raise EndpointError("endpoint.unknown", f"unknown endpoint shorthand; known: {sorted(registry)}") from None

agentprov_capture/endpoints.toml

@@ -0,0 +1,156 @@
+# AgentPROV endpoint registry (MN M.1.10 item 2; N.2.1 `--model`; N.2.1a; G.9.2).
+# Data, not code: read through importlib.resources by agentprov_capture.endpoints (no __init__.py needed here).
+#
+# Names only: `base_url_env`, `api_key_env` and `model_env` name environment variables (the .env keys); no value is
+# ever stored here. There are no default model ids (Q5, closed): a model id comes from `--model-id` or `model_env`.
+# `base_url` is the public default. Its host is the registered host that any other base URL must match unless
+# `--allow-custom-endpoint` is given (R-39). A base URL MUST be https, except loopback (127.0.0.1, [::1], localhost),
+# and MUST carry no userinfo, query or fragment (G.6.4).
+#
+# `request_headers` / `response_headers` (optional, lower-case header NAMES) extend the global header allowlist of
+# redact_allowlist.toml for that endpoint (G.6.4: "per-endpoint names declared in endpoints.toml"); the hard denylist
+# wins over them. Only request-id style headers are declared; add a name here, with a test, when a provider needs it.
+#
+# `api` (optional) is the wire format: `openai_chat` (default) or `anthropic_messages` (D-656). It selects the LLM
+# element and the wire recorder's decoding; the CLI sets the agent's provider from it.
+#
+# Baseline set from AgentDojo-PROV `runtime.py` (build_* functions and _LLM_BUILDERS); `omlx` is new (D-10); `lmstudio`,
+# `mlx_lm`, `llamacpp` and `vllm` are new (D-690).
+
+version = 1
+
+[endpoints.deepseek]
+base_url = "https://api.deepseek.com/v1"
+base_url_env = "DEEPSEEK_BASE_URL"
+api_key_env = "DEEPSEEK_API_KEY"
+model_env = "DEEPSEEK_MODEL"
+local = false
+
+[endpoints.openai]
+base_url = "https://api.openai.com/v1"
+base_url_env = "OPENAI_BASE_URL"
+api_key_env = "OPENAI_API_KEY"
+model_env = "OPENAI_MODEL"
+local = false
+response_headers = ["x-request-id", "openai-version"]
+
+# One OpenRouter key and base URL serve openrouter, gemini, llama, qwen and glm (baseline `_build_openrouter_llm`).
+[endpoints.openrouter]
+base_url = "https://openrouter.ai/api/v1"
+base_url_env = "OPENROUTER_BASE_URL"
+api_key_env = "OPENROUTER_API_KEY"
+model_env = "OPENROUTER_MODEL"
+local = false
+response_headers = ["x-request-id"]
+
+[endpoints.gemini]
+base_url = "https://openrouter.ai/api/v1"
+base_url_env = "OPENROUTER_BASE_URL"
+api_key_env = "OPENROUTER_API_KEY"
+model_env = "GEMINI_MODEL"
+local = false
+response_headers = ["x-request-id"]
+
+[endpoints.llama]
+base_url = "https://openrouter.ai/api/v1"
+base_url_env = "OPENROUTER_BASE_URL"
+api_key_env = "OPENROUTER_API_KEY"
+model_env = "LLAMA_MODEL"
+local = false
+response_headers = ["x-request-id"]
+
+[endpoints.qwen]
+base_url = "https://openrouter.ai/api/v1"
+base_url_env = "OPENROUTER_BASE_URL"
+api_key_env = "OPENROUTER_API_KEY"
+model_env = "QWEN_MODEL"
+local = false
+response_headers = ["x-request-id"]
+
+[endpoints.glm]
+base_url = "https://openrouter.ai/api/v1"
+base_url_env = "OPENROUTER_BASE_URL"
+api_key_env = "OPENROUTER_API_KEY"
+model_env = "GLM_MODEL"
+local = false
+response_headers = ["x-request-id"]
+
+# The Anthropic Messages API, direct (D-656). The SDK appends /v1/messages to the base URL. Model ids are the bare API
+# ids (claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, ...), never date-suffixed. Recorded header values: the
+# API version and beta flags sent, and the request id and the two retry headers the SDK's retry decision reads. The
+# organisation id and the rate-limit headers keep their names only; x-api-key is on the hard denylist.
+[endpoints.anthropic]
+base_url = "https://api.anthropic.com"
+base_url_env = "ANTHROPIC_BASE_URL"
+api_key_env = "ANTHROPIC_API_KEY"
+model_env = "ANTHROPIC_MODEL"
+local = false
+api = "anthropic_messages"
+request_headers = ["anthropic-beta", "anthropic-version"]
+response_headers = ["request-id", "retry-after", "x-should-retry"]
+
+# Local OpenAI-compatible servers (N.2.1a; D-690): http on loopback is allowed and no key is needed (an optional
+# `api_key_env` sends one when it is set, D-827). `server` names the server kind; `agentprov models` uses it to
+# fingerprint the server that answers (two kinds share a default port: 8000 omlx/vllm, 8080 mlx_lm/llamacpp) and to
+# read the model identity it exposes. Base URLs are pinned to 127.0.0.1, not `localhost`, which may resolve to ::1.
+# Tool calls: whether a model's replies carry structured `tool_calls` depends on the server, its flags and the model's
+# template; the preflight probe decides (D.10.9 A4), and text-encoded calls need
+# `--allow-text-tool-calls`. `server_max_concurrency` is set only where the server's default is fixed; LM Studio and
+# llama.cpp report their own value, and `--server-max-concurrency` overrides.
+
+# Ollama. Structured tool calls for models whose capabilities include "tools"; others are refused by the server (400).
+# OLLAMA_NUM_PARALLEL depends on the version and memory, and is not reported, so no concurrency default is set.
+[endpoints.ollama]
+base_url = "http://127.0.0.1:11434/v1"
+base_url_env = "LOCAL_LLM_BASE_URL"
+model_env = "LOCAL_MODEL_ID"
+local = true
+server = "ollama"
+
+# oMLX (MLX inference server, Apple Silicon). The model id is the oMLX model directory name or alias (`--model-id`).
+# `server_max_concurrency` is oMLX's `--max-concurrent-requests` default. Structured tool calls through oMLX's parser.
+# `api_key_env` is optional on a local entry (D-827): oMLX can be set up with an API key. When `OMLX_API_KEY` is set
+# (keychain first, then .env), it is sent as a bearer header to the loopback server, and never to a LAN address; when
+# it is not set, no key is sent, as for every other local server. `model_env` (D-827 addendum): `OMLX_MODEL` in .env
+# names the served model id (oMLX's own id, e.g. its folder name, not a Hugging Face repo id) when `--model-id` is not
+# given; without either, a terminal offers a pick.
+[endpoints.omlx]
+base_url = "http://127.0.0.1:8000/v1"
+base_url_env = "OMLX_BASE_URL"
+api_key_env = "OMLX_API_KEY"
+model_env = "OMLX_MODEL"
+local = true
+server = "omlx"
+server_max_concurrency = 8
+
+# LM Studio's server (`lms server start`). Native tool calls for models with `trained_for_tool_use`; for other models LM
+# Studio adds its own tool-use system prompt on the server (invisible to the wire capture), which `run` refuses unless
+# `--allow-text-tool-calls`. The parallel-request limit is read from the loaded instance (`/api/v1/models`).
+[endpoints.lmstudio]
+base_url = "http://127.0.0.1:1234/v1"
+base_url_env = "LMSTUDIO_BASE_URL"
+local = true
+server = "lmstudio"
+
+# mlx_lm.server (MLX LM). The model id is a Hugging Face repo id or a local path. Requests are served one at a time by
+# default. Tool calls depend on the mlx-lm version and the model's chat template; text-encoded calls are common.
+[endpoints.mlx_lm]
+base_url = "http://127.0.0.1:8080/v1"
+base_url_env = "MLX_LM_BASE_URL"
+local = true
+server = "mlx_lm"
+server_max_concurrency = 1
+
+# llama.cpp `llama-server`. Structured tool calls only when started with `--jinja`; the slot count is read from /props.
+[endpoints.llamacpp]
+base_url = "http://127.0.0.1:8080/v1"
+base_url_env = "LLAMACPP_BASE_URL"
+local = true
+server = "llamacpp"
+
+# vLLM's OpenAI-compatible server. Structured tool calls only with `--enable-auto-tool-choice --tool-call-parser <p>`.
+[endpoints.vllm]
+base_url = "http://127.0.0.1:8000/v1"
+base_url_env = "VLLM_BASE_URL"
+local = true
+server = "vllm"

agentprov_capture/envstate.py

@@ -0,0 +1,182 @@
+"""Environment-state digests, snapshots and diffs (C.13.3 ``pass.start``/``pass.end``/``state``; B CAP-18, F-12).
+
+Extracted from the baseline ``agentdojo_prov/envstate.py`` (rules E-1...E-5 of the audit) and changed in exactly the
+ways the specification decided:
+
+* **E-1** ``dump_state``: a duck-typed ``model_dump(mode="json")`` (pydantic), else a JSON round trip with ``default=str``.
+  No benchmark import.
+* **E-2 (changed)** the canonical form is **JCS** (RFC 8785) of the dump, and the digest is a mapping
+  ``{"sha256": <hex, no prefix>, "canon": "jcs-rfc8785"}`` that is the ``env`` member of ``pass.start`` as is
+  (C.13.8). The baseline's ``sort_keys``/``ensure_ascii=False`` form is *not* reproduced; baseline digests are
+  imported with ``canon: "adprov.envstate@1"`` (C.3) and never recomputed. Values JCS cannot carry are encoded as in
+  C.11.2-C.11.3 before hashing: integers beyond +-(2^53-1) as ``{"$int": "<decimal>"}``, ``NaN``/``Infinity``/
+  ``-0.0`` as ``{"$float": ...}``, lone surrogates as ``{"$utf16": <base64>}``, objects whose first-level member
+  starts with ``$`` as ``{"$lit": <object>}``.
+* **E-3** keys are walked in sorted order; list elements are matched by canonical content (multiset), and a
+  same-multiset different-order list gives one ``reordered`` entry.
+* **E-4 (F-12 fixed)** values are cut at ``VALUE_CAP`` characters and entries at ``ENTRY_CAP``; ``truncated`` is
+  true if **any** entry or value was cut (the baseline ignored value cuts).
+* **E-5** the end record carries ``changed`` and a ``diff`` only when the state changed.
+
+Paths in diff entries are RFC 6901 JSON Pointers (the baseline used dotted paths, ambiguous for keys containing a
+dot); an element added to or removed from a list is reported at the pointer of the *list* with ``"element": true``.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import math
+from typing import Any, Final
+
+import rfc8785
+
+__all__ = [
+    "CANON",
+    "DIFF_FORMAT",
+    "ENTRY_CAP",
+    "VALUE_CAP",
+    "diff",
+    "digest",
+    "dump_state",
+    "end_env",
+    "normalise",
+    "snapshot",
+]
+
+CANON: Final = "jcs-rfc8785"
+DIFF_FORMAT: Final = "agentprov.envdiff@1"
+VALUE_CAP: Final = 400
+ENTRY_CAP: Final = 200
+_MAX_SAFE_INT: Final = 2**53 - 1
+
+
+def dump_state(env: Any) -> Any:
+    """The environment as plain JSON-able data (E-1): a pydantic-style ``model_dump(mode="json")`` or a JSON round trip
+    with ``default=str``."""
+    if hasattr(env, "model_dump"):
+        return env.model_dump(mode="json")
+    return json.loads(json.dumps(env, default=str))
+
+
+def normalise(value: Any) -> Any:
+    """Encode what JCS cannot carry (C.11.2-C.11.3) so ``rfc8785`` accepts any plain JSON-able value."""
+    if isinstance(value, bool) or value is None:
+        return value
+    if isinstance(value, int):
+        return value if abs(value) <= _MAX_SAFE_INT else {"$int": str(value)}
+    if isinstance(value, float):
+        if math.isnan(value):
+            return {"$float": "NaN"}
+        if math.isinf(value):
+            return {"$float": "Infinity" if value > 0 else "-Infinity"}
+        if value == 0.0 and math.copysign(1.0, value) < 0:
+            return {"$float": "-0"}
+        return value
+    if isinstance(value, str):
+        try:
+            value.encode("utf-8")
+        except UnicodeEncodeError:
+            units = value.encode("utf-16-be", "surrogatepass")
+            return {"$utf16": base64.b64encode(units).decode("ascii")}
+        return value
+    if isinstance(value, dict):
+        out = {normalise_key(k): normalise(v) for k, v in value.items()}
+        if any(k.startswith("$") for k in out):
+            return {"$lit": out}
+        return out
+    if isinstance(value, (list, tuple)):
+        return [normalise(v) for v in value]
+    raise TypeError(f"cannot canonicalise a {type(value).__name__}; dump_state() the environment first")
+
+
+def normalise_key(key: Any) -> str:
+    if not isinstance(key, str):
+        raise TypeError("object keys must be strings; dump_state() the environment first")
+    return key
+
+
+def snapshot(dump: Any) -> bytes:
+    """The canonical bytes of an environment dump: JCS of :func:`normalise` (store as a blob for a full snapshot)."""
+    return rfc8785.dumps(normalise(dump))
+
+
+def digest(dump: Any) -> dict[str, str]:
+    """``{"sha256": <hex>, "canon": "jcs-rfc8785"}`` of the dump (E-2): the ``env`` of ``pass.start``."""
+    return {"sha256": hashlib.sha256(snapshot(dump)).hexdigest(), "canon": CANON}
+
+
+def _canon_text(value: Any) -> str:
+    """JCS text of an already normalised value."""
+    return rfc8785.dumps(value).decode("utf-8")
+
+
+def _ptr(parts: list[str]) -> str:
+    return "".join("/" + p.replace("~", "~0").replace("/", "~1") for p in parts)
+
+
+def _cut(value: Any, cuts: list[bool]) -> str:
+    text = _canon_text(value)
+    if len(text) > VALUE_CAP:
+        cuts[0] = True
+        return text[:VALUE_CAP] + "…"
+    return text
+
+
+def _walk(before: Any, after: Any, path: list[str], out: list[dict[str, Any]], cuts: list[bool]) -> None:
+    if isinstance(before, dict) and isinstance(after, dict):
+        for key in sorted(set(before) | set(after), key=str):
+            sub = [*path, str(key)]
+            if key not in after:
+                out.append({"op": "removed", "path": _ptr(sub), "before": _cut(before[key], cuts)})
+            elif key not in before:
+                out.append({"op": "added", "path": _ptr(sub), "after": _cut(after[key], cuts)})
+            else:
+                _walk(before[key], after[key], sub, out, cuts)
+    elif isinstance(before, list) and isinstance(after, list):
+        # elements are matched by content, not position: deleting the first element must not report every later one
+        canon_before = [_canon_text(x) for x in before]
+        canon_after = [_canon_text(x) for x in after]
+        remaining = list(canon_after)
+        gone = []
+        for item, c in zip(before, canon_before, strict=True):
+            if c in remaining:
+                remaining.remove(c)
+            else:
+                gone.append(item)
+        if not gone and not remaining and canon_before != canon_after:
+            out.append({"op": "reordered", "path": _ptr(path)})
+        for item in gone:
+            out.append({"op": "removed", "path": _ptr(path), "element": True, "before": _cut(item, cuts)})
+        for c in remaining:
+            out.append({"op": "added", "path": _ptr(path), "element": True, "after": _cut(json.loads(c), cuts)})
+    elif _canon_text(before) != _canon_text(after):
+        out.append({"op": "changed", "path": _ptr(path), "before": _cut(before, cuts), "after": _cut(after, cuts)})
+
+
+def diff(before: Any, after: Any) -> dict[str, Any]:
+    """What a pass changed, as the ``env.diff`` mapping ``{"format", "value": {"n_changes", "entries"}, "truncated"}``.
+
+    Lossy by design (value and entry caps); the digests, not the diff, decide whether two states are equal.
+    """
+    entries: list[dict[str, Any]] = []
+    cuts = [False]
+    _walk(normalise(before), normalise(after), [], entries, cuts)
+    return {
+        "format": DIFF_FORMAT,
+        "value": {"n_changes": len(entries), "entries": entries[:ENTRY_CAP]},
+        "truncated": cuts[0] or len(entries) > ENTRY_CAP,
+    }
+
+
+def end_env(before: Any, after: Any, *, snapshot_ref: dict[str, Any] | None = None, with_diff: bool = True) -> dict[str, Any]:
+    """The ``env`` member of ``pass.end`` (E-5): the digest of ``after``, ``changed`` (digest differs from ``before``),
+    a ``diff`` only when changed (and ``with_diff``), and an optional ``snapshot`` blob reference."""
+    after_digest = digest(after)
+    out: dict[str, Any] = {**after_digest, "changed": digest(before) != after_digest}
+    if out["changed"] and with_diff:
+        out["diff"] = diff(before, after)
+    if snapshot_ref is not None:
+        out["snapshot"] = snapshot_ref
+    return out

agentprov_capture/errors.py

@@ -0,0 +1,37 @@
+"""Exceptions of ``agentprov_capture``. Each carries a stable dotted ``code``; messages never carry secret values."""
+
+from __future__ import annotations
+
+__all__ = ["CaptureError", "CaptureLogError", "CaptureWriteError", "RedactionError"]
+
+
+class CaptureError(Exception):
+    """Base class. ``code`` is stable and dotted (``cap.<area>.<what>``)."""
+
+    code = "cap.error"
+
+    def __init__(self, message: str, *, code: str | None = None) -> None:
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+
+
+class CaptureLogError(CaptureError):
+    """The log file or its state does not allow the operation (exists, closed, poisoned, too large, ...)."""
+
+    code = "cap.log.error"
+
+
+class CaptureWriteError(CaptureError):
+    """An event, blob or call violates the capture/0.1 model; nothing was written."""
+
+    code = "cap.write.invalid"
+
+
+class RedactionError(CaptureError):
+    """Redaction failed or its configuration is unusable (G.6.4, fail closed): nothing was written.
+
+    The message never includes the content being scanned; the original exception is deliberately not chained.
+    """
+
+    code = "cap.redact.failed"