perathos 0.2.0__py3-none-any.whl

perathos/__init__.py

@@ -0,0 +1,98 @@
+"""Perathos — cryptographic proof layer for AI outputs.
+
+Provides a clean Python API for creating, signing, and verifying tamper-evident
+VRL Proof Bundles on AI-generated content. Each bundle captures the input hash,
+output hash, execution trace, and optional cryptographic signature.
+
+Example:
+    >>> from perathos import prove, verify, sign
+    >>> bundle = prove("The capital of France is Paris.")
+    >>> bundle = sign(bundle)  # attach Ed25519 signature
+    >>> valid, err = verify(bundle)
+    >>> print(valid)  # True
+"""
+from .bundle import create_bundle, sign_bundle, verify_bundle
+from .calibration import (
+    BinningCalibrator,
+    TemperatureCalibrator,
+    expected_calibration_error,
+)
+from .engines import (
+    HallucinationDetector,
+    SchemaValidator,
+    SymbolicSolver,
+    TemporalConsistency,
+    all_engines,
+)
+from .inspector import inspect_bundle
+from .keytrust import (
+    KmsSigner,
+    LocalSigner,
+    Signer,
+    TrustStore,
+    kid_for,
+)
+from .pipeline import (
+    MultiVerifierPipeline,
+    VerificationResult,
+    verify_output,
+)
+from .signing import generate_keypair, verify_signature
+from .verdict import VerdictRecord
+from .verifiers import (
+    ClaimEntailmentVerifier,
+    CrossExaminer,
+    VerificationContext,
+    Verifier,
+    default_verifiers,
+)
+
+__version__ = "0.2.0"
+
+# Public API aliases for library users. These are the SAME function objects as
+# create_bundle/sign_bundle/verify_bundle/inspect_bundle — deliberately not
+# reassigning __doc__ here, because doing so would clobber the underlying
+# functions' own docstrings (an alias shares the object, not a copy).
+prove = create_bundle
+sign = sign_bundle
+verify = verify_bundle
+inspect = inspect_bundle
+
+__all__ = [
+    "prove",
+    "verify",
+    "sign",
+    "inspect",
+    "create_bundle",
+    "sign_bundle",
+    "verify_bundle",
+    "inspect_bundle",
+    "generate_keypair",
+    "verify_signature",
+    # key management & trust anchoring
+    "LocalSigner",
+    "KmsSigner",
+    "Signer",
+    "TrustStore",
+    "kid_for",
+    # multi-verifier pipeline
+    "verify_output",
+    "MultiVerifierPipeline",
+    "VerificationResult",
+    "VerificationContext",
+    "VerdictRecord",
+    "Verifier",
+    "CrossExaminer",
+    "ClaimEntailmentVerifier",
+    "default_verifiers",
+    # real verifier engines
+    "SymbolicSolver",
+    "HallucinationDetector",
+    "SchemaValidator",
+    "TemporalConsistency",
+    "all_engines",
+    # calibration (real-confidence honesty)
+    "TemperatureCalibrator",
+    "BinningCalibrator",
+    "expected_calibration_error",
+]

perathos/bundle.py

@@ -0,0 +1,347 @@
+"""VRL Proof Bundle creation and verification logic.
+
+Handles the construction of tamper-evident bundles that capture the hash chain
+from input/output through execution trace to the integrity root, plus optional
+Ed25519 cryptographic signatures. All hashes are SHA-256 and deterministically
+encoded to ensure offline verifiability.
+"""
+import hashlib
+import uuid
+from datetime import datetime, timezone
+
+from .canonical import canonical_bytes
+
+# Deterministic namespace: all Perathos bundle IDs live under this UUID.
+# Derived itself via uuid5 so it's auditable, not magic.
+PERATHOS_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_URL, "https://perathos.io/vrl/v1")
+
+# The model identity descriptor — in production this would encode model weights
+# fingerprint, version, and serving config.
+_MODEL_DESCRIPTOR = "perathos-demo-model:sha256-deterministic:v1"
+
+
+def _sha256(data: bytes) -> str:
+    """Compute SHA-256 digest of bytes and return as hex string.
+
+    Used internally for all hash operations in the bundle: input, output,
+    trace, and integrity payload. The result is always a 64-character
+    lowercase hex string suitable for use in bundles and hashing chains.
+
+    Args:
+        data: Bytes to hash.
+
+    Returns:
+        Lowercase hex-encoded SHA-256 digest (64 characters).
+
+    Examples:
+        _sha256(b"hello") → "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+        _sha256(b"") → "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    """
+    return hashlib.sha256(data).hexdigest()
+
+
+def ai_id() -> str:
+    """Stable AI identity: SHA-256 of the model descriptor string.
+
+    Returns the same hash across all invocations and machines, since it
+    derives from a fixed model descriptor string. In production, this would
+    reflect actual model weights fingerprint and serving configuration,
+    enabling verifiers to confirm which model produced a given output.
+
+    The model descriptor is a colon-separated string:
+        <name>:<proof_system>:<version>
+    Example: "openai-gpt4-serving:sha256-deterministic:v20240101"
+
+    Returns:
+        Lowercase hex-encoded SHA-256 (64 characters) of the model descriptor.
+        In production, this would reflect actual model weights and serving config.
+
+    Examples:
+        ai_id() → "7f9c2ba4e88fb81860ea5e70f527f31f..." (deterministic, always same)
+    """
+    return _sha256(_MODEL_DESCRIPTOR.encode("utf-8"))
+
+
+BUNDLE_VERSION = "2.0"
+
+
+def create_bundle(output_text: str, input_text: str = "", verification: dict | None = None,
+                  *, model: str = "unspecified", include_answer: bool = False,
+                  bundle_version: str = BUNDLE_VERSION) -> dict:
+    """Build a VRL Proof Bundle for a given AI output.
+
+    Constructs a tamper-evident bundle by hashing the input and output,
+    capturing execution metadata in a trace, and computing an integrity root
+    hash. The bundle_id is derived deterministically via UUIDv5 from the
+    integrity hash, so it is reconstructable offline without any state.
+
+    Args:
+        output_text: The AI-generated text to prove (e.g., model completion).
+            Must be a string (empty string is allowed).
+        input_text: Original prompt or request that produced output_text.
+            Defaults to empty string for prove-from-output-only use cases.
+            Must be a string.
+        verification: Optional verification block (verdict records + aggregate
+            verdict) produced by the multi-verifier pipeline. When present, its
+            digest is folded into integrity_hash so the verdicts are signed and
+            tamper-evident; stripping or altering them breaks verification.
+
+    Returns:
+        A dictionary containing:
+            - bundle_id: UUIDv5 derived from integrity_hash.
+            - ai_id: SHA-256 of the model descriptor.
+            - input_hash: SHA-256 of input_text.
+            - output_hash: SHA-256 of output_text.
+            - trace_hash: SHA-256 of execution metadata.
+            - integrity_hash: SHA-256 of the canonical integrity payload.
+            - issued_at: ISO 8601 timestamp (UTC).
+            - proof_system: String identifier for the hash scheme ("sha256-deterministic").
+            - _trace: Verbatim execution metadata dict (used by verifiers).
+
+    Raises:
+        ValueError: If output_text is not a string, or if input_text is not a string.
+        TypeError: If output_text or input_text have wrong type.
+    """
+    if not isinstance(output_text, str):
+        raise ValueError(
+            f"output_text must be a string, got {type(output_text).__name__}"
+        )
+    if not isinstance(input_text, str):
+        raise ValueError(
+            f"input_text must be a string, got {type(input_text).__name__}"
+        )
+    if verification is not None and not isinstance(verification, dict):
+        raise ValueError(
+            f"verification must be a dict or None, got {type(verification).__name__}"
+        )
+    is_v2 = bundle_version == BUNDLE_VERSION
+
+    issued_at = datetime.now(timezone.utc).isoformat()
+    proof_system = "sha256-deterministic"
+
+    input_hash = _sha256(input_text.encode("utf-8"))
+    output_hash = _sha256(output_text.encode("utf-8"))
+
+    # Trace captures execution metadata needed to reproduce / audit the run.
+    # Hashed separately so it can grow without breaking the integrity chain.
+    trace = {
+        "model_descriptor": _MODEL_DESCRIPTOR,
+        "proof_system": proof_system,
+        "input_length": len(input_text),
+        "output_length": len(output_text),
+    }
+    trace_hash = _sha256(canonical_bytes(trace))
+
+    model_ai_id = ai_id()
+
+    # Integrity payload — the tamper-evident root. Every semantically
+    # significant field is included; changing any one of them rotates the
+    # integrity_hash and therefore the bundle_id.
+    integrity_payload = {
+        "ai_id": model_ai_id,
+        "input_hash": input_hash,
+        "issued_at": issued_at,
+        "output_hash": output_hash,
+        "proof_system": proof_system,
+        "trace_hash": trace_hash,
+    }
+    # v2 binds the format version and the human-readable model id into the root.
+    if is_v2:
+        integrity_payload["bundle_version"] = bundle_version
+        integrity_payload["model"] = model
+    # Bind the verification block (if any) into the integrity root. Including
+    # verification_hash only when verification is present keeps bundles without
+    # verification byte-for-byte backward compatible, and any later attempt to
+    # add, remove, or edit the block flips this recomputation -> tamper detected.
+    if verification is not None:
+        integrity_payload["verification_hash"] = _sha256(canonical_bytes(verification))
+    integrity_hash = _sha256(canonical_bytes(integrity_payload))
+
+    # UUIDv5: deterministic, reconstructable from integrity_hash alone.
+    bundle_id = str(uuid.uuid5(PERATHOS_NAMESPACE, integrity_hash))
+
+    bundle = {
+        "bundle_id": bundle_id,
+        "proof_system": proof_system,
+        "issued_at": issued_at,
+        "ai_id": model_ai_id,
+        "input_hash": input_hash,
+        "output_hash": output_hash,
+        "trace_hash": trace_hash,
+        "integrity_hash": integrity_hash,
+        # _trace stored verbatim so verifiers can recompute trace_hash offline.
+        "_trace": trace,
+    }
+    if is_v2:
+        # Top-level convenience fields. `model` and `bundle_version` are bound
+        # into integrity_hash; `verdict` is a copy of the aggregate (cross-checked
+        # on verify); `answer` is bound via output_hash (cross-checked on verify).
+        bundle["bundle_version"] = bundle_version
+        bundle["model"] = model
+        if verification is not None:
+            bundle["verdict"] = verification.get("aggregate", {}).get("verdict")
+        if include_answer:
+            bundle["answer"] = output_text
+    if verification is not None:
+        # Stored verbatim so a consumer can recompute verification_hash offline.
+        bundle["verification"] = verification
+    return bundle
+
+
+def sign_bundle(bundle: dict, signing_key_hex: str) -> dict:
+    """Attach an Ed25519 provider_signature over integrity_hash.
+
+    Computes an Ed25519 signature on the raw bytes of integrity_hash and
+    adds it to the bundle as a provider_signature field. Does not mutate
+    the input bundle; returns a new dict with the signature attached.
+
+    Args:
+        bundle: A bundle dict from create_bundle() (or compatible structure).
+            Must be a dict and must contain the 'integrity_hash' field.
+        signing_key_hex: 64-character hex-encoded Ed25519 signing key.
+            Must be a string containing exactly 64 hex characters (0-9, a-f).
+
+    Returns:
+        A new dict with all fields from bundle plus a "provider_signature" field:
+            - algorithm: "ed25519"
+            - verify_key: 64-character hex-encoded public key
+            - signature: 128-character hex-encoded signature bytes
+
+    Raises:
+        TypeError: If bundle is not a dict or signing_key_hex is not a string.
+        KeyError: If bundle does not contain the 'integrity_hash' field.
+        ValueError: If signing_key_hex is not a valid 64-character hex string.
+    """
+    if not isinstance(bundle, dict):
+        raise TypeError(f"bundle must be a dict, got {type(bundle).__name__}")
+    from .keytrust import LocalSigner, Signer  # local import to avoid cycles
+    is_signer = isinstance(signing_key_hex, Signer)
+    if not is_signer and not isinstance(signing_key_hex, str):
+        raise TypeError(
+            f"signing_key_hex must be a string or a Signer, got {type(signing_key_hex).__name__}"
+        )
+    if "integrity_hash" not in bundle:
+        raise KeyError("bundle must contain 'integrity_hash' field")
+
+    if is_signer:
+        signer = signing_key_hex
+    else:
+        if len(signing_key_hex) != 64:
+            raise ValueError(
+                f"signing_key_hex must be exactly 64 hex characters, got {len(signing_key_hex)}"
+            )
+        if any(c not in "0123456789abcdef" for c in signing_key_hex):
+            raise ValueError(
+                f"signing_key_hex must contain only lowercase hex characters (0-9, a-f), got: {signing_key_hex}"
+            )
+        signer = LocalSigner.from_hex(signing_key_hex)
+
+    from .signing import sign_hash_with_signer
+    sig = sign_hash_with_signer(bundle["integrity_hash"], signer)
+    return {**bundle, "provider_signature": sig}
+
+
+def verify_bundle(bundle: dict, expected_verify_key: str | None = None, trust_store=None) -> tuple[bool, str]:
+    """Recompute all hashes from stored data and check they match.
+
+    Verifies the integrity chain: _trace → trace_hash → integrity_hash → bundle_id,
+    and — if the bundle carries a provider_signature — that the Ed25519 signature
+    validates over integrity_hash. Does not re-hash the original input/output text
+    (those are gone); only checks that the stored hashes are self-consistent and
+    form a valid chain.
+
+    Args:
+        bundle: A bundle dict from create_bundle() (optionally with signature).
+        expected_verify_key: If given, a signed bundle is only accepted when its
+            provider_signature.verify_key equals this 64-char hex public key. This
+            pins provenance: the signature itself only proves *some* key signed the
+            hash, and verify_key lives outside integrity_hash, so without pinning an
+            attacker can strip the signature and re-sign with their own key.
+
+    Returns:
+        A tuple (valid, error_code) where:
+            - valid is True and error_code is "" on successful verification.
+            - valid is False and error_code is a string like "ERR_TRACE_HASH_MISMATCH"
+              on any failure. Check for 'ERR' substring to detect invalid bundles.
+    """
+    try:
+        trace = bundle.get("_trace")
+        if trace is None:
+            return False, "ERR_MISSING_TRACE"
+
+        # Step 1: trace integrity
+        if _sha256(canonical_bytes(trace)) != bundle["trace_hash"]:
+            return False, "ERR_TRACE_HASH_MISMATCH"
+
+        # Dual-read: a bundle with no bundle_version is a v1 bundle and verifies
+        # exactly as before; "2.0" adds bound fields + cross-checks. Existing v1
+        # bundles keep verifying unchanged.
+        version = bundle.get("bundle_version", "1.0")
+
+        # Step 2: integrity root
+        integrity_payload = {
+            "ai_id": bundle["ai_id"],
+            "input_hash": bundle["input_hash"],
+            "issued_at": bundle["issued_at"],
+            "output_hash": bundle["output_hash"],
+            "proof_system": bundle["proof_system"],
+            "trace_hash": bundle["trace_hash"],
+        }
+        if version == BUNDLE_VERSION:
+            integrity_payload["bundle_version"] = bundle["bundle_version"]
+            integrity_payload["model"] = bundle["model"]
+        # The verification block is bound into integrity_hash iff it is present
+        # (see create_bundle). Recompute symmetrically so that adding, removing,
+        # or editing the verdicts is detected as a hash mismatch.
+        verification = bundle.get("verification")
+        if verification is not None:
+            integrity_payload["verification_hash"] = _sha256(canonical_bytes(verification))
+        if _sha256(canonical_bytes(integrity_payload)) != bundle["integrity_hash"]:
+            return False, "ERR_INTEGRITY_HASH_MISMATCH"
+
+        # Step 3: bundle_id derivation
+        expected_id = str(uuid.uuid5(PERATHOS_NAMESPACE, bundle["integrity_hash"]))
+        if expected_id != bundle["bundle_id"]:
+            return False, "ERR_BUNDLE_ID_MISMATCH"
+
+        # Step 3b (v2): cross-check the convenience copies. The top-level verdict
+        # must equal the bound aggregate verdict, and a stored answer must hash to
+        # output_hash — so neither can be tampered without detection.
+        if version == BUNDLE_VERSION:
+            if verification is not None:
+                if bundle.get("verdict") != verification.get("aggregate", {}).get("verdict"):
+                    return False, "ERR_VERDICT_MISMATCH"
+            if "answer" in bundle:
+                if _sha256(bundle["answer"].encode("utf-8")) != bundle["output_hash"]:
+                    return False, "ERR_ANSWER_MISMATCH"
+
+        # Step 4: signature. A bundle that carries a provider_signature must NOT
+        # pass verification if that signature does not validate — otherwise the
+        # public verify() reports a forged signature as valid.
+        sig = bundle.get("provider_signature")
+        if sig is not None:
+            from .signing import verify_signature  # local import avoids a cycle
+            sig_valid, sig_err = verify_signature(bundle["integrity_hash"], sig)
+            if not sig_valid:
+                return False, sig_err
+            # Step 5: optional signer pinning (provenance).
+            if expected_verify_key is not None and sig.get("verify_key") != expected_verify_key:
+                return False, "ERR_UNEXPECTED_SIGNER"
+            # Step 6: optional trust-anchor check — the signer's key must be one
+            # the consumer has explicitly trusted (by derived kid), not just any
+            # key the bundle embeds. Scales signer pinning to many keys via JWKS.
+            if trust_store is not None:
+                from .keytrust import kid_for
+                vk_bytes = bytes.fromhex(sig["verify_key"])
+                if trust_store.get(kid_for(vk_bytes)) != vk_bytes:
+                    return False, "ERR_UNTRUSTED_SIGNER"
+
+        return True, ""
+
+    except KeyError as exc:
+        return False, f"ERR_MISSING_FIELD:{exc}"
+    except (TypeError, ValueError) as exc:
+        # A hostile/malformed bundle (e.g. _trace with mixed-type keys that
+        # json.dumps(sort_keys=True) cannot order) must return an error, not
+        # crash a verifier that is documented to return (False, error_code).
+        return False, f"ERR_MALFORMED_BUNDLE:{exc}"

perathos/calibration.py

@@ -0,0 +1,134 @@
+"""Confidence calibration for verifier scores.
+
+A verifier's raw score (e.g. an NLI entailment probability) is NOT the same as
+the probability the verdict is correct. confidence_bps makes an honesty promise
+— "0.8 means ~80% right" — and that promise has to be *fit and measured*, not
+assumed. This module fits a mapping from raw score -> calibrated probability
+using held-out labeled (score, correct) pairs, and reports Expected Calibration
+Error (ECE) so the promise is testable.
+
+Pure-Python (math only), no heavy dependencies, so it lives in the core package.
+Persist with to_dict()/from_dict() and store the calibrator alongside the
+verifier version that produced the scores.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import List, Sequence, Tuple
+
+_EPS = 1e-6
+
+
+def _clamp01(p: float) -> float:
+    return min(1.0 - _EPS, max(_EPS, p))
+
+
+def expected_calibration_error(
+    scores: Sequence[float], labels: Sequence[int], n_bins: int = 10
+) -> float:
+    """Binned ECE: weighted average gap between confidence and accuracy."""
+    if not scores:
+        return 0.0
+    n = len(scores)
+    total = 0.0
+    for b in range(n_bins):
+        lo, hi = b / n_bins, (b + 1) / n_bins
+        idx = [i for i, s in enumerate(scores) if (s > lo or (b == 0 and s >= lo)) and s <= hi]
+        if not idx:
+            continue
+        conf = sum(scores[i] for i in idx) / len(idx)
+        acc = sum(labels[i] for i in idx) / len(idx)
+        total += (len(idx) / n) * abs(conf - acc)
+    return total
+
+
+@dataclass
+class TemperatureCalibrator:
+    """One-parameter temperature scaling on the logit of a [0,1] score.
+
+    calibrate(p) = sigmoid(logit(p) / T). T is fit by minimizing log-loss over
+    labeled data via a 1-D ternary search. T>1 softens overconfident scores.
+    """
+
+    temperature: float = 1.0
+
+    def calibrate(self, score: float) -> float:
+        p = _clamp01(float(score))
+        logit = math.log(p / (1.0 - p))
+        return 1.0 / (1.0 + math.exp(-logit / self.temperature))
+
+    def confidence_bps(self, score: float) -> int:
+        return int(round(self.calibrate(score) * 1000))
+
+    def _nll(self, scores: Sequence[float], labels: Sequence[int], t: float) -> float:
+        total = 0.0
+        for s, y in zip(scores, labels):
+            p = _clamp01(self.__class__(temperature=t).calibrate(s))
+            total += -(y * math.log(p) + (1 - y) * math.log(1.0 - p))
+        return total / max(1, len(scores))
+
+    def fit(self, scores: Sequence[float], labels: Sequence[int]) -> "TemperatureCalibrator":
+        if not scores:
+            return self
+        lo, hi = 0.05, 20.0
+        for _ in range(60):  # ternary search converges quickly on a convex-ish NLL
+            m1 = lo + (hi - lo) / 3.0
+            m2 = hi - (hi - lo) / 3.0
+            if self._nll(scores, labels, m1) < self._nll(scores, labels, m2):
+                hi = m2
+            else:
+                lo = m1
+        self.temperature = (lo + hi) / 2.0
+        return self
+
+    def to_dict(self) -> dict:
+        return {"method": "temperature", "temperature": self.temperature}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "TemperatureCalibrator":
+        return cls(temperature=float(d["temperature"]))
+
+
+@dataclass
+class BinningCalibrator:
+    """Reliability-binning calibrator: map a score to the empirical accuracy of
+    its bin on the fit data. Isotonic-free, robust on small samples."""
+
+    n_bins: int = 10
+    bin_accuracy: List[float] = None  # type: ignore[assignment]
+
+    def fit(self, scores: Sequence[float], labels: Sequence[int]) -> "BinningCalibrator":
+        acc = []
+        for b in range(self.n_bins):
+            lo, hi = b / self.n_bins, (b + 1) / self.n_bins
+            idx = [i for i, s in enumerate(scores) if (s > lo or (b == 0 and s >= lo)) and s <= hi]
+            acc.append(sum(labels[i] for i in idx) / len(idx) if idx else (b + 0.5) / self.n_bins)
+        self.bin_accuracy = acc
+        return self
+
+    def calibrate(self, score: float) -> float:
+        if not self.bin_accuracy:
+            return _clamp01(float(score))
+        b = min(self.n_bins - 1, max(0, int(float(score) * self.n_bins)))
+        return self.bin_accuracy[b]
+
+    def confidence_bps(self, score: float) -> int:
+        return int(round(self.calibrate(score) * 1000))
+
+    def to_dict(self) -> dict:
+        return {"method": "binning", "n_bins": self.n_bins, "bin_accuracy": self.bin_accuracy}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "BinningCalibrator":
+        c = cls(n_bins=int(d["n_bins"]))
+        c.bin_accuracy = list(d["bin_accuracy"])
+        return c
+
+
+def reliability(scores: Sequence[float], labels: Sequence[int], n_bins: int = 10) -> Tuple[float, float]:
+    """Convenience: (ECE before, ECE after) temperature calibration on the data."""
+    before = expected_calibration_error(scores, labels, n_bins)
+    cal = TemperatureCalibrator().fit(scores, labels)
+    after = expected_calibration_error([cal.calibrate(s) for s in scores], labels, n_bins)
+    return before, after

perathos/canonical.py

@@ -0,0 +1,92 @@
+"""Deterministic canonical JSON encoding for tamper-evident hashing.
+
+Provides a stable JSON representation where key order and formatting are
+fixed, enabling reproducible hashes across independent verifiers. This is
+critical for Perathos because bundles must be verifiable offline: the same
+input dict must always produce identical bytes, regardless of Python version,
+platform, or execution order. Without canonical encoding, an attacker could
+reorder keys or change whitespace to produce a different hash while keeping
+the same logical dict.
+
+Why determinism matters:
+  - Bundle integrity relies on hashing dicts (trace, integrity payload).
+  - If two Python processes hash the same dict differently, one verifier
+    will reject a valid bundle (false negative) or accept a tampered one
+    (false positive).
+  - Canonical encoding ensures byte-for-byte reproducibility across all
+    verifiers, even offline and across languages (via JSON spec).
+"""
+import json
+
+
+def _assert_canonicalizable(obj) -> None:
+    """Reject inputs that would break byte-for-byte cross-language determinism.
+
+    Non-string dict keys are rejected because json coerces them to strings
+    ({1: 'a'} and {'1': 'a'} would collide to identical bytes, defeating
+    injectivity). Non-finite floats are handled separately by allow_nan=False.
+    """
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            if not isinstance(k, str):
+                raise ValueError(
+                    f"canonical JSON requires string object keys, got {type(k).__name__}"
+                )
+            _assert_canonicalizable(v)
+    elif isinstance(obj, (list, tuple)):
+        for v in obj:
+            _assert_canonicalizable(v)
+
+
+def canonical_json(obj: dict) -> str:
+    """Convert a dict to deterministic JSON string with sorted keys and no whitespace.
+
+    Ensures that the same Python dict always produces identical JSON bytes,
+    enabling reproducible hashing. Keys are sorted lexicographically, separators
+    are compact (no spaces), and non-ASCII characters (e.g., Japanese text) are
+    preserved as-is rather than escaped, improving human readability while
+    maintaining byte-for-byte determinism across Python versions and platforms.
+
+    Args:
+        obj: A dictionary to serialize (typically a bundle or trace dict).
+
+    Returns:
+        A JSON string with sorted keys, no whitespace, and preserved Unicode.
+
+    Examples:
+        Input:  {'b': 2, 'a': 1}
+        Output: '{"a":1,"b":2}'
+
+        Input:  {'name': '日本', 'count': 3}
+        Output: '{"count":3,"name":"日本"}'
+    """
+    _assert_canonicalizable(obj)
+    # allow_nan=False: NaN/Infinity are not valid JSON and are rejected by
+    # spec-compliant parsers (Go/JS), so they must never enter a proof bundle.
+    return json.dumps(
+        obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False
+    )
+
+
+def canonical_bytes(obj: dict) -> bytes:
+    """Convert a dict to deterministic JSON bytes (UTF-8 encoded).
+
+    Equivalent to canonical_json(obj).encode('utf-8'). Used internally
+    to hash dictionaries for bundle integrity checks and trace verification.
+    The bytes returned are passed directly to hashlib.sha256(), so encoding
+    is critical: UTF-8 is the standard for all hashing in Perathos.
+
+    Args:
+        obj: A dictionary to serialize.
+
+    Returns:
+        The canonical JSON representation encoded as UTF-8 bytes.
+
+    Examples:
+        Input:  {'b': 2, 'a': 1}
+        Output: b'{"a":1,"b":2}'
+
+        Input:  {'x': 1}
+        Output: b'{"x":1}'
+    """
+    return canonical_json(obj).encode("utf-8")