xoonya 3.1.16 → 3.2.0

package/reference/python/xnya_reference.py

@@ -1,810 +0,0 @@
-"""Independent Python candidate reference helpers for XNYA atom/payload vectors.
-
-This module intentionally does not import or shell out to the JavaScript
-implementation. It is a vector-parity scaffold, not yet a full
-XNYA-compatible reference implementation.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import base64
-from dataclasses import dataclass
-from typing import Any
-
-
-XNYA_MAGIC = bytes.fromhex("584e5941")
-VERSION_V1 = 0x01
-VERSION_V2 = 0x02
-VALID_RECORD_TYPES = {0x01, 0x02, 0x03}
-ZERO_HASH32 = bytes(32)
-IDENTITY_PREFIXES = {"01", "02", "03", "04", "05", "06", "07"}
-
-XNYA_DS_AGENT_V1 = b"xoonya:agent:v1:"
-XNYA_DS_AGENT_V2 = b"xoonya:agent:v2:"
-XNYA_DS_PAYLOAD_V1 = b"xoonya:payload:v1:"
-XNYA_DS_PAYLOAD_V2 = b"xoonya:payload:v2:"
-XNYA_DS_PAYLOAD_PROFILE_V1 = b"xoonya:payload-profile:v1:"
-XNYA_DS_LINE_RATE_FRAME_V1 = b"xoonya:line-rate-frame:v1:"
-CANONICAL_EVENT_BUNDLE_VERSION = "canonical-event-bundle/v1"
-CANONICAL_RECEIPT_VERSION = "receipt/v1"
-PROOF_BUNDLE_VERSION = "proof-bundle/v1"
-XOONYA_NATIVE_SHA256_METHOD = "xoonya-native-sha256-v1"
-XOONYA_NATIVE_SIGNED_METHOD = "xoonya-native-signed-v1"
-XOONYA_NATIVE_ANCHORED_METHOD = "xoonya-native-anchored-v1"
-XOONYA_NATIVE_HYBRID_METHOD = "xoonya-native-hybrid-v1"
-XOONYA_NATIVE_PROOF_FORMAT_VERSION = "xoonya-native-proof/v1"
-LEGACY_OPRETURN_METHOD = "legacy-opreturn-v1"
-DETACHED_ASSERTION_METHOD = "detached-assertion-v1"
-EXTERNAL_ASSERTION_METHODS = {
-    "detached-assertion-v1",
-    "jwt-assertion-v1",
-    "did-vc-v1",
-    "sd-jwt-vc-v1",
-    "signed-envelope-v1",
-    "partner-proof-envelope-v1",
-}
-
-FIELD_TYPES = {
-    "bytes32": (1, 32),
-    "bytes20": (2, 20),
-    "uint64": (3, 8),
-    "utf8": (4, None),
-    "bool": (5, 1),
-}
-FIELD_TYPES_BY_ID = {spec[0]: (name, spec[1]) for name, spec in FIELD_TYPES.items()}
-
-
-class XnyaReferenceError(ValueError):
-    def __init__(self, code: str, message: str):
-        super().__init__(message)
-        self.code = code
-
-
-@dataclass(frozen=True)
-class ParsedAtom:
-    atom_version: str
-    spec_version: str
-    byte_length: int
-    record_type_hex: str
-    agent_id: str
-    payload_hash_sha256: str
-    atom_hash_sha256: str
-    atom_hex: str
-
-
-def sha256(data: bytes) -> bytes:
-    return hashlib.sha256(data).digest()
-
-
-def sha256_hex(data: bytes) -> str:
-    return sha256(data).hex()
-
-
-def hash160_hex(data: bytes) -> str:
-    return hashlib.new("ripemd160", sha256(data)).hexdigest()
-
-
-def canonicalize(value: Any) -> str:
-    if isinstance(value, list):
-        return "[" + ",".join(canonicalize(item) for item in value) + "]"
-    if isinstance(value, dict):
-        return "{" + ",".join(
-            json.dumps(str(key), separators=(",", ":"), ensure_ascii=False) + ":" + canonicalize(value[key])
-            for key in sorted(value.keys())
-        ) + "}"
-    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
-
-
-def canonical_json_sha256_hex(value: Any) -> str:
-    return sha256_hex(canonicalize(value).encode("utf-8"))
-
-
-def normalize_string(value: Any) -> str:
-    return str("" if value is None else value).strip()
-
-
-def normalize_string_array(values: Any, label: str) -> list[str] | None:
-    if values is None:
-        return None
-    if not isinstance(values, list):
-        raise ValueError(f"{label} must be an array")
-    normalized = [normalize_string(value) for value in values]
-    normalized = [value for value in normalized if value]
-    return normalized or None
-
-
-def canonicalize_event(event: dict[str, Any]) -> dict[str, Any]:
-    if not isinstance(event, dict):
-        raise ValueError("event must be an object")
-    normalized = {
-        "version": normalize_string(event.get("version") or CANONICAL_EVENT_BUNDLE_VERSION),
-        "domain_id": normalize_string(event.get("domain_id")),
-        "sequence": normalize_string(event.get("sequence")),
-        "actor_id": normalize_string(event.get("actor_id")),
-        "adapter_source": normalize_string(event.get("adapter_source")),
-        "event_type": normalize_string(event.get("event_type")),
-        "event_hash": normalize_string(event.get("event_hash")).lower(),
-    }
-    for key, value in normalized.items():
-        if not value:
-            raise ValueError(f"event.{key} required")
-    if normalized["version"] != CANONICAL_EVENT_BUNDLE_VERSION:
-        raise ValueError(f"event.version must be {CANONICAL_EVENT_BUNDLE_VERSION}")
-    assert_hex(normalized["event_hash"], "event_hash_invalid", "event.event_hash must be 32 byte hex")
-
-    timestamp_ns = normalize_string(event.get("timestamp_ns"))
-    if timestamp_ns:
-        normalized["timestamp_ns"] = timestamp_ns
-    parent_refs = normalize_string_array(event.get("parent_refs"), "event.parent_refs")
-    if parent_refs:
-        normalized["parent_refs"] = parent_refs
-    capability_refs = normalize_string_array(event.get("capability_refs"), "event.capability_refs")
-    if capability_refs:
-        normalized["capability_refs"] = capability_refs
-    attestation_ref = normalize_string(event.get("attestation_ref"))
-    if attestation_ref:
-        normalized["attestation_ref"] = attestation_ref
-    semantic_slots = event.get("semantic_slots")
-    if semantic_slots is not None:
-        if not isinstance(semantic_slots, dict):
-            raise ValueError("event.semantic_slots must be an object")
-        normalized["semantic_slots"] = semantic_slots
-    return normalized
-
-
-def hash_event(event: dict[str, Any]) -> str:
-    return canonical_json_sha256_hex(canonicalize_event(event))
-
-
-def build_canonical_receipt_signing_material(receipt: dict[str, Any]) -> dict[str, Any]:
-    return {
-        "agent_identity": receipt.get("agent_identity"),
-        "domain_id": receipt.get("domain_id"),
-        "event_commitment": receipt.get("event_commitment"),
-        "receipt_id": receipt.get("receipt_id"),
-        "sequence": receipt.get("sequence"),
-        "version": receipt.get("version"),
-    }
-
-
-def create_legacy_receipt(identity_material_hex: str, payload: bytes) -> dict[str, Any]:
-    material = bytes.fromhex(assert_hex(identity_material_hex, "non_hex", "identityMaterialHex must be hex"))
-    agent_id = hash160_hex(material)
-    payload_hash = sha256_hex(payload) if payload else ZERO_HASH32.hex()
-    opreturn_hex = "50524654" + "01" + "01" + agent_id + payload_hash
-    return {
-        "agent_id": agent_id,
-        "opreturn_hex": opreturn_hex,
-        "payload_hash": payload_hash,
-        "spec_version": "v1",
-    }
-
-
-def verify_legacy_receipt(opreturn_hex: str, payload: bytes) -> dict[str, Any]:
-    normalized = str(opreturn_hex or "").strip().lower()
-    try:
-        bytes.fromhex(normalized)
-    except ValueError:
-        return {"valid": False, "reason": "non_hex", "agent_id": None}
-    if len(normalized) != 116:
-        return {"valid": False, "reason": "invalid_length", "agent_id": None}
-    if normalized[:8] != "50524654":
-        return {"valid": False, "reason": "bad_magic", "agent_id": None}
-    if normalized[8:10] != "01":
-        return {"valid": False, "reason": "bad_version", "agent_id": None}
-    if normalized[10:12] not in {"01", "02", "03"}:
-        return {"valid": False, "reason": "bad_type", "agent_id": None}
-    expected_payload = sha256_hex(payload) if payload else ZERO_HASH32.hex()
-    if normalized[52:116] != expected_payload:
-        return {"valid": False, "reason": "payload_mismatch", "agent_id": normalized[12:52]}
-    return {"valid": True, "reason": None, "agent_id": normalized[12:52]}
-
-
-def select_receipt_algorithm(options: dict[str, Any], compatibility: dict[str, Any] | None) -> str:
-    requested = normalize_string(options.get("algorithm"))
-    if requested:
-        return requested
-    if compatibility:
-        return LEGACY_OPRETURN_METHOD
-    if options.get("signature") is not None:
-        return DETACHED_ASSERTION_METHOD
-    return XOONYA_NATIVE_SHA256_METHOD
-
-
-def build_native_receipt_signature(receipt: dict[str, Any], canonical_event: dict[str, Any]) -> str:
-    material = {
-        "method": XOONYA_NATIVE_SHA256_METHOD,
-        "receipt_signing_material": build_canonical_receipt_signing_material(receipt),
-        "event_commitment": hash_event(canonical_event),
-    }
-    return XOONYA_NATIVE_SHA256_METHOD + ":" + sha256_hex(canonicalize(material).encode("utf-8"))
-
-
-def _base64url_decode(value: str) -> bytes:
-    normalized = normalize_string(value)
-    padded = normalized + ("=" * ((4 - (len(normalized) % 4)) % 4))
-    return base64.urlsafe_b64decode(padded.encode("ascii"))
-
-
-def _spki_der_from_pem(public_key_pem: str) -> bytes:
-    pem = str(public_key_pem or "").replace("\r\n", "\n").strip()
-    begin = "-----BEGIN PUBLIC KEY-----"
-    end = "-----END PUBLIC KEY-----"
-    if begin not in pem or end not in pem:
-        raise ValueError("native public key must be SPKI PEM")
-    body = pem.split(begin, 1)[1].split(end, 1)[0]
-    return base64.b64decode("".join(body.split()))
-
-
-def _ed25519_crypto_available() -> bool:
-    try:
-        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey  # noqa: F401
-        from cryptography.hazmat.primitives.serialization import load_pem_public_key  # noqa: F401
-    except Exception:
-        return False
-    return True
-
-
-def build_native_signed_proof_material(receipt: dict[str, Any], canonical_event: dict[str, Any], proof_descriptor: dict[str, Any]) -> dict[str, Any]:
-    return {
-        "identity_ref": proof_descriptor.get("identity_ref"),
-        "method": XOONYA_NATIVE_SIGNED_METHOD,
-        "public_key_ref": proof_descriptor.get("public_key_ref"),
-        "receipt_signing_material": build_canonical_receipt_signing_material(receipt),
-        "event_commitment": hash_event(canonical_event),
-        "signature_suite": proof_descriptor.get("signature_suite"),
-        "standard_version": XOONYA_NATIVE_PROOF_FORMAT_VERSION,
-    }
-
-
-def verify_native_signed_receipt_proof(receipt: dict[str, Any], ceb: dict[str, Any]) -> dict[str, Any]:
-    proof = receipt.get("native_proof")
-    if not isinstance(proof, dict):
-        return {"valid": False, "reason": "native_proof_missing"}
-    if normalize_string(proof.get("method")) != XOONYA_NATIVE_SIGNED_METHOD:
-        return {"valid": False, "reason": "native_proof_method_mismatch"}
-    signature_suite = normalize_string(proof.get("signature_suite"))
-    if signature_suite != "ed25519":
-        return {"valid": False, "reason": "native_signature_suite_crypto_unavailable_in_python_candidate"}
-    identity_ref = normalize_string(proof.get("identity_ref"))
-    if not identity_ref:
-        return {"valid": False, "reason": "native_identity_ref_missing"}
-    public_key_material = proof.get("public_key_material")
-    if not isinstance(public_key_material, dict):
-        return {"valid": False, "reason": "native_public_key_material_missing"}
-    if normalize_string(public_key_material.get("format")) != "spki-pem":
-        return {"valid": False, "reason": "native_public_key_format_mismatch"}
-    try:
-        der = _spki_der_from_pem(public_key_material.get("value", ""))
-    except Exception as error:
-        return {"valid": False, "reason": str(error)}
-    expected_public_key_ref = "ed25519-spki-sha256:" + sha256_hex(der)
-    if normalize_string(proof.get("public_key_ref")) != expected_public_key_ref:
-        return {"valid": False, "reason": "native_public_key_ref_mismatch"}
-    proof_material = proof.get("proof_material")
-    if not isinstance(proof_material, dict):
-        return {"valid": False, "reason": "native_proof_material_missing"}
-    signature = normalize_string(proof_material.get("signature"))
-    if not signature:
-        return {"valid": False, "reason": "native_signature_missing"}
-    if normalize_string(receipt.get("signature")) != XOONYA_NATIVE_SIGNED_METHOD + ":ed25519:" + signature:
-        return {"valid": False, "reason": "signature_native_signed_mismatch"}
-    signing_material = build_native_signed_proof_material(receipt, ceb, {
-        "identity_ref": identity_ref,
-        "public_key_ref": expected_public_key_ref,
-        "signature_suite": "ed25519",
-    })
-    signing_bytes = canonicalize(signing_material).encode("utf-8")
-    if normalize_string(proof_material.get("signing_material_sha256")).lower() != sha256_hex(signing_bytes):
-        return {"valid": False, "reason": "native_signing_material_hash_mismatch"}
-    if not _ed25519_crypto_available():
-        return {
-            "valid": False,
-            "reason": "native_signature_crypto_dependency_missing",
-            "dependency": "cryptography",
-        }
-    try:
-        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
-        from cryptography.hazmat.primitives.serialization import load_pem_public_key
-
-        public_key = load_pem_public_key(public_key_material["value"].encode("utf-8"))
-        if not isinstance(public_key, Ed25519PublicKey):
-            return {"valid": False, "reason": "native_public_key_suite_mismatch"}
-        public_key.verify(_base64url_decode(signature), signing_bytes)
-    except Exception:
-        return {"valid": False, "reason": "native_signature_invalid"}
-    return {
-        "valid": True,
-        "verification_state": "verified_native_signature",
-        "signature_suite": "ed25519",
-    }
-
-
-def assert_hex(value: str, code: str, message: str) -> str:
-    normalized = str(value or "").strip().lower()
-    if not normalized or len(normalized) % 2 != 0:
-        raise XnyaReferenceError(code, message)
-    try:
-        bytes.fromhex(normalized)
-    except ValueError as exc:
-        raise XnyaReferenceError(code, message) from exc
-    return normalized
-
-
-def normalize_identity_material(identity_material_hex: str) -> bytes:
-    material_hex = assert_hex(
-        identity_material_hex,
-        "identity_unsupported_type_prefix",
-        "identityMaterialHex has unsupported identity type prefix",
-    )
-    prefix = material_hex[:2]
-    if prefix not in IDENTITY_PREFIXES:
-        raise XnyaReferenceError(
-            "identity_unsupported_type_prefix",
-            "identityMaterialHex has unsupported identity type prefix",
-        )
-    if len(material_hex) == 2:
-        raise XnyaReferenceError(
-            "identity_missing_raw_bytes",
-            "identityMaterialHex must include raw identity bytes",
-        )
-    return bytes.fromhex(material_hex)
-
-
-def hash_payload(payload: bytes | None, domain: bytes) -> bytes:
-    if not payload:
-        return ZERO_HASH32
-    digest = sha256(domain + payload)
-    if digest == ZERO_HASH32:
-        raise XnyaReferenceError("payload_hash_mismatch", "payload hash cannot equal absent sentinel")
-    return digest
-
-
-def create_atom_v1(identity_material_hex: str, payload: bytes | None, record_type_hex: str = "01") -> dict[str, Any]:
-    material = normalize_identity_material(identity_material_hex)
-    record_type = int(record_type_hex, 16)
-    if record_type not in VALID_RECORD_TYPES:
-        raise XnyaReferenceError("atom_unsupported_record_type", "atomHex has unsupported record type")
-    agent_id = bytes.fromhex(hash160_hex(XNYA_DS_AGENT_V1 + material))
-    payload_hash = hash_payload(payload, XNYA_DS_PAYLOAD_V1)
-    atom = XNYA_MAGIC + bytes([VERSION_V1, record_type]) + agent_id + payload_hash
-    return {
-        "atom_hex": atom.hex(),
-        "atom_version": "xoonya-native-atom/v1",
-        "spec_version": "v1",
-        "byte_length": len(atom),
-        "record_type_hex": f"{record_type:02x}",
-        "agent_id": agent_id.hex(),
-        "payload_hash_sha256": payload_hash.hex(),
-        "atom_hash_sha256": sha256_hex(atom),
-    }
-
-
-def create_atom_v2(identity_material_hex: str, payload: bytes | None, record_type_hex: str = "01") -> dict[str, Any]:
-    material = normalize_identity_material(identity_material_hex)
-    record_type = int(record_type_hex, 16)
-    if record_type not in VALID_RECORD_TYPES:
-        raise XnyaReferenceError("atom_unsupported_record_type", "atomHex has unsupported record type")
-    agent_id = sha256(XNYA_DS_AGENT_V2 + material)
-    payload_hash = hash_payload(payload, XNYA_DS_PAYLOAD_V2)
-    atom = XNYA_MAGIC + bytes([VERSION_V2, record_type]) + agent_id + payload_hash
-    return {
-        "atom_hex": atom.hex(),
-        "atom_version": "xoonya-native-atom/v2",
-        "spec_version": "v2",
-        "byte_length": len(atom),
-        "record_type_hex": f"{record_type:02x}",
-        "agent_id": agent_id.hex(),
-        "payload_hash_sha256": payload_hash.hex(),
-        "atom_hash_sha256": sha256_hex(atom),
-    }
-
-
-def parse_atom(atom_hex: str) -> ParsedAtom:
-    hex_value = str(atom_hex or "").strip().lower()
-    try:
-        atom = bytes.fromhex(hex_value)
-    except ValueError as exc:
-        raise XnyaReferenceError("atom_hex_not_hex", "atomHex must be hex") from exc
-    if len(atom) not in (58, 70):
-        raise XnyaReferenceError("atom_unsupported_length", "atomHex must be a supported xoonya native atom")
-    if atom[:4] != XNYA_MAGIC:
-        raise XnyaReferenceError("atom_bad_magic", "atomHex has bad xoonya native atom magic")
-    record_type = atom[5]
-    if record_type not in VALID_RECORD_TYPES:
-        raise XnyaReferenceError("atom_unsupported_record_type", "atomHex has unsupported record type")
-    version = atom[4]
-    if version == VERSION_V1 and len(atom) == 58:
-        return ParsedAtom(
-            atom_version="xoonya-native-atom/v1",
-            spec_version="v1",
-            byte_length=58,
-            record_type_hex=f"{record_type:02x}",
-            agent_id=atom[6:26].hex(),
-            payload_hash_sha256=atom[26:58].hex(),
-            atom_hash_sha256=sha256_hex(atom),
-            atom_hex=hex_value,
-        )
-    if version == VERSION_V2 and len(atom) == 70:
-        return ParsedAtom(
-            atom_version="xoonya-native-atom/v2",
-            spec_version="v2",
-            byte_length=70,
-            record_type_hex=f"{record_type:02x}",
-            agent_id=atom[6:38].hex(),
-            payload_hash_sha256=atom[38:70].hex(),
-            atom_hash_sha256=sha256_hex(atom),
-            atom_hex=hex_value,
-        )
-    raise XnyaReferenceError("atom_version_length_mismatch", "atomHex/version length mismatch")
-
-
-def verify_atom(atom_hex: str, *, identity_material_hex: str | None = None, payload: bytes | None = None) -> dict[str, Any]:
-    parsed = parse_atom(atom_hex)
-    if identity_material_hex is not None:
-        material = normalize_identity_material(identity_material_hex)
-        expected_agent_id = (
-            hash160_hex(XNYA_DS_AGENT_V1 + material)
-            if parsed.spec_version == "v1"
-            else sha256_hex(XNYA_DS_AGENT_V2 + material)
-        )
-        if parsed.agent_id != expected_agent_id:
-            return {"valid": False, "reason": "agent_id_mismatch", "error_code": "agent_id_mismatch"}
-    if payload is not None:
-        expected_payload_hash = (
-            hash_payload(payload, XNYA_DS_PAYLOAD_V1)
-            if parsed.spec_version == "v1"
-            else hash_payload(payload, XNYA_DS_PAYLOAD_V2)
-        ).hex()
-        if parsed.payload_hash_sha256 != expected_payload_hash:
-            return {"valid": False, "reason": "payload_hash_mismatch", "error_code": "payload_hash_mismatch"}
-    return {"valid": True, "reason": None, "error_code": None, "parsed": parsed}
-
-
-def _encode_field(field: dict[str, Any]) -> tuple[int, int, bytes]:
-    field_id = int(field.get("field_id", field.get("id")))
-    field_type = str(field.get("field_type", field.get("type"))).strip()
-    if field_id < 1 or field_id > 0xFFFF:
-        raise ValueError("payload profile field_id must be uint16")
-    if field_type not in FIELD_TYPES:
-        raise ValueError("payload profile field_type unsupported")
-    field_type_id, fixed_len = FIELD_TYPES[field_type]
-    if field_type in ("bytes32", "bytes20"):
-        value = bytes.fromhex(str(field.get("value_hex", field.get("value"))).strip().lower())
-        if len(value) != fixed_len:
-            raise ValueError("payload profile fixed field length mismatch")
-    elif field_type == "uint64":
-        n = int(field.get("value"))
-        if n < 0 or n > 0xFFFFFFFFFFFFFFFF:
-            raise ValueError("payload profile uint64 out of range")
-        value = n.to_bytes(8, "big")
-    elif field_type == "utf8":
-        value = str(field.get("value", "")).encode("utf-8")
-        if not value or len(value) > 1024:
-            raise ValueError("payload profile utf8 length unsupported")
-    elif field_type == "bool":
-        raw = field.get("value")
-        if not isinstance(raw, bool):
-            raise ValueError("payload profile bool must be boolean")
-        value = b"\x01" if raw else b"\x00"
-    return field_id, field_type_id, value
-
-
-def encode_payload_profile(input_value: dict[str, Any]) -> dict[str, Any]:
-    schema_ref = str(input_value.get("schema_ref", input_value.get("schemaRef", "xoonya.payload.schema.generic.v1"))).strip()
-    schema_hash = sha256_hex(f"xoonya:payload-schema:v1:{schema_ref}".encode("utf-8"))
-    encoded_fields = sorted((_encode_field(field) for field in input_value["fields"]), key=lambda item: (item[0], item[1]))
-    canonical = bytearray()
-    canonical.extend(b"XNYP")
-    canonical.append(1)
-    canonical.extend(bytes.fromhex(schema_hash))
-    canonical.append(len(encoded_fields))
-    for field_id, field_type_id, value in encoded_fields:
-        canonical.extend(field_id.to_bytes(2, "big"))
-        canonical.append(field_type_id)
-        canonical.extend(len(value).to_bytes(2, "big"))
-        canonical.extend(value)
-    canonical_bytes = bytes(canonical)
-    return {
-        "profile": "xoonya-native-payload-profile/v1",
-        "schema_ref": schema_ref,
-        "schema_hash_sha256": schema_hash,
-        "field_count": len(encoded_fields),
-        "canonical_bytes_hex": canonical_bytes.hex(),
-        "payload_hash_sha256": sha256_hex(XNYA_DS_PAYLOAD_PROFILE_V1 + canonical_bytes),
-        "field_order": [field_id for field_id, _, _ in encoded_fields],
-    }
-
-
-def parse_payload_profile(canonical_bytes_hex: str) -> dict[str, Any]:
-    canonical = bytes.fromhex(canonical_bytes_hex)
-    if len(canonical) < 38:
-        raise ValueError("payload profile bytes too short")
-    if canonical[:4] != b"XNYP":
-        raise ValueError("payload profile magic mismatch")
-    if canonical[4] != 1:
-        raise ValueError("payload profile version unsupported")
-    field_count = canonical[37]
-    offset = 38
-    fields = []
-    for _ in range(field_count):
-        if offset + 5 > len(canonical):
-            raise ValueError("payload profile truncated field header")
-        field_id = int.from_bytes(canonical[offset : offset + 2], "big")
-        field_type_id = canonical[offset + 2]
-        length = int.from_bytes(canonical[offset + 3 : offset + 5], "big")
-        offset += 5
-        value = canonical[offset : offset + length]
-        offset += length
-        if field_type_id not in FIELD_TYPES_BY_ID:
-            raise ValueError("payload profile field type unsupported")
-        field_type, fixed_len = FIELD_TYPES_BY_ID[field_type_id]
-        if fixed_len is not None and len(value) != fixed_len:
-            raise ValueError("payload profile fixed field length mismatch")
-        fields.append({"field_id": field_id, "field_type": field_type, "field_type_id": field_type_id, "value_hex": value.hex()})
-    if offset != len(canonical):
-        raise ValueError("payload profile trailing bytes")
-    sorted_fields = sorted(fields, key=lambda item: (item["field_id"], item["field_type_id"]))
-    if fields != sorted_fields:
-        raise ValueError("payload profile fields not canonical order")
-    return {
-        "profile": "xoonya-native-payload-profile/v1",
-        "schema_hash_sha256": canonical[5:37].hex(),
-        "field_count": field_count,
-        "fields": fields,
-        "canonical_bytes_hex": canonical.hex(),
-        "payload_hash_sha256": sha256_hex(XNYA_DS_PAYLOAD_PROFILE_V1 + canonical),
-    }
-
-
-def line_rate_frame_checksum(atom: bytes) -> str:
-    return sha256_hex(XNYA_DS_LINE_RATE_FRAME_V1 + atom)[:4]
-
-
-def normalize_anchor_refs(anchor_refs: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    if not isinstance(anchor_refs, list) or not anchor_refs:
-        raise ValueError("native anchors must be a non-empty array")
-    normalized = []
-    for index, anchor in enumerate(anchor_refs):
-        if not isinstance(anchor, dict):
-            raise ValueError(f"native anchors[{index}] must be an object")
-        entry = {
-            "anchor_id": normalize_string(anchor.get("anchor_id") or anchor.get("id")),
-            "anchor_kind": normalize_string(anchor.get("anchor_kind") or anchor.get("kind")),
-            "anchor_ref": normalize_string(anchor.get("anchor_ref") or anchor.get("ref")),
-            "anchor_hash_sha256": normalize_string(anchor.get("anchor_hash_sha256") or anchor.get("hash_sha256") or anchor.get("anchor_hash")).lower(),
-        }
-        if not entry["anchor_id"]:
-            raise ValueError(f"native anchors[{index}].anchor_id required")
-        if not entry["anchor_kind"]:
-            raise ValueError(f"native anchors[{index}].anchor_kind required")
-        if not entry["anchor_ref"]:
-            raise ValueError(f"native anchors[{index}].anchor_ref required")
-        assert_hex(entry["anchor_hash_sha256"], "anchor_hash_invalid", f"native anchors[{index}].anchor_hash_sha256 must be 32 byte hex")
-        for key in ("network", "finality_state", "observed_at_iso", "provider_ref", "inclusion_proof_ref"):
-            value = normalize_string(anchor.get(key))
-            if value:
-                entry[key] = value
-        normalized.append(entry)
-    return sorted(normalized, key=canonicalize)
-
-
-def build_native_anchor_binding_material(receipt: dict[str, Any], canonical_event: dict[str, Any], anchor_refs: list[dict[str, Any]]) -> dict[str, Any]:
-    return {
-        "anchor_refs": normalize_anchor_refs(anchor_refs),
-        "base_method": XOONYA_NATIVE_SHA256_METHOD,
-        "event_commitment": hash_event(canonical_event),
-        "method": XOONYA_NATIVE_ANCHORED_METHOD,
-        "receipt_signing_material": build_canonical_receipt_signing_material(receipt),
-        "standard_version": "xoonya-native-proof/v1",
-    }
-
-
-def build_native_anchored_receipt_proof(receipt: dict[str, Any], canonical_event: dict[str, Any], anchors: list[dict[str, Any]]) -> dict[str, Any]:
-    anchor_refs = normalize_anchor_refs(anchors)
-    binding_material = build_native_anchor_binding_material(receipt, canonical_event, anchor_refs)
-    binding_hash = sha256_hex(canonicalize(binding_material).encode("utf-8"))
-    anchor_root_hash = canonical_json_sha256_hex(anchor_refs)
-    return {
-        "method": XOONYA_NATIVE_ANCHORED_METHOD,
-        "base_method": XOONYA_NATIVE_SHA256_METHOD,
-        "anchor_refs": anchor_refs,
-        "proof_material": {
-            "anchor_root_sha256": anchor_root_hash,
-            "binding_material_sha256": binding_hash,
-        },
-        "compact_signature": XOONYA_NATIVE_ANCHORED_METHOD + ":" + binding_hash,
-    }
-
-
-def emit_receipt(event: dict[str, Any], options: dict[str, Any] | None = None) -> dict[str, Any]:
-    options = options or {}
-    canonical_event = canonicalize_event(event)
-    event_commitment = hash_event(canonical_event)
-    agent_identity = normalize_string(options.get("agent_identity") or options.get("agentIdentity") or canonical_event["actor_id"])
-    if not agent_identity:
-        raise ValueError("agent_identity required")
-    compatibility = None
-    legacy_identity = options.get("legacy_identity_material_hex")
-    if legacy_identity:
-        legacy_receipt = create_legacy_receipt(str(legacy_identity).strip().lower(), canonicalize(canonical_event).encode("utf-8"))
-        compatibility = {"legacy_receipt": legacy_receipt}
-    receipt_id = sha256_hex(canonicalize({
-        "agent_identity": agent_identity,
-        "domain_id": canonical_event["domain_id"],
-        "event_commitment": event_commitment,
-        "sequence": canonical_event["sequence"],
-        "version": CANONICAL_RECEIPT_VERSION,
-    }).encode("utf-8"))
-    receipt = {
-        "version": CANONICAL_RECEIPT_VERSION,
-        "receipt_id": receipt_id,
-        "agent_identity": agent_identity,
-        "domain_id": canonical_event["domain_id"],
-        "sequence": canonical_event["sequence"],
-        "event_commitment": event_commitment,
-        "algorithm": select_receipt_algorithm(options, compatibility),
-    }
-    if compatibility:
-        receipt["compatibility"] = compatibility
-    signature = normalize_string(options.get("signature"))
-    native_proof = options.get("native_proof") if isinstance(options.get("native_proof"), dict) else None
-    if not signature and receipt["algorithm"] == XOONYA_NATIVE_ANCHORED_METHOD:
-        native_proof = build_native_anchored_receipt_proof(receipt, canonical_event, options.get("anchors") or options.get("anchor_refs") or [])
-        signature = native_proof.pop("compact_signature")
-    if not signature and receipt["algorithm"] == XOONYA_NATIVE_SHA256_METHOD:
-        signature = build_native_receipt_signature(receipt, canonical_event)
-    if not signature and compatibility:
-        signature = compatibility["legacy_receipt"]["opreturn_hex"]
-    if not signature:
-        raise ValueError("signature or legacy_identity_material_hex required")
-    if native_proof:
-        receipt["native_proof"] = native_proof
-    receipt["signature"] = signature
-    return receipt
-
-
-def build_proof_bundle(input_value: dict[str, Any]) -> dict[str, Any]:
-    ceb = canonicalize_event(input_value.get("ceb") or input_value.get("event"))
-    anchors = input_value.get("anchors") if isinstance(input_value.get("anchors"), list) else None
-    receipt_options = input_value.get("receipt_options") if isinstance(input_value.get("receipt_options"), dict) else {}
-    if anchors and not any(key in receipt_options for key in ("anchors", "native_anchor_refs", "anchor_refs")):
-        receipt_options = {**receipt_options, "anchors": anchors}
-    receipt = input_value.get("receipt") if isinstance(input_value.get("receipt"), dict) else emit_receipt(ceb, receipt_options)
-    bundle = {
-        "version": PROOF_BUNDLE_VERSION,
-        "ceb": ceb,
-        "receipt": receipt,
-    }
-    if anchors is not None:
-        bundle["anchors"] = anchors
-    for key in ("attestations", "evidence_refs", "batch_refs"):
-        if isinstance(input_value.get(key), list):
-            bundle[key] = input_value[key]
-    if isinstance(input_value.get("metadata"), dict):
-        bundle["metadata"] = input_value["metadata"]
-    return bundle
-
-
-def _verify_native_anchored(receipt: dict[str, Any], ceb: dict[str, Any], bundle: dict[str, Any]) -> dict[str, Any]:
-    proof = receipt.get("native_proof")
-    if not isinstance(proof, dict):
-        return {"valid": False, "reason": "native_proof_missing"}
-    if normalize_string(proof.get("method")) != XOONYA_NATIVE_ANCHORED_METHOD:
-        return {"valid": False, "reason": "native_proof_method_mismatch"}
-    if normalize_string(proof.get("base_method")) != XOONYA_NATIVE_SHA256_METHOD:
-        return {"valid": False, "reason": "native_anchor_base_method_unsupported"}
-    if not isinstance(bundle.get("anchors"), list):
-        return {"valid": False, "reason": "native_anchor_bundle_missing"}
-    proof_anchors = normalize_anchor_refs(proof.get("anchor_refs"))
-    bundle_anchors = normalize_anchor_refs(bundle.get("anchors"))
-    if canonicalize(proof_anchors) != canonicalize(bundle_anchors):
-        return {"valid": False, "reason": "native_anchor_bundle_mismatch"}
-    proof_material = proof.get("proof_material")
-    if not isinstance(proof_material, dict):
-        return {"valid": False, "reason": "native_anchor_proof_material_missing"}
-    expected_anchor_root = canonical_json_sha256_hex(proof_anchors)
-    if normalize_string(proof_material.get("anchor_root_sha256")).lower() != expected_anchor_root:
-        return {"valid": False, "reason": "native_anchor_root_mismatch"}
-    binding_material = build_native_anchor_binding_material(receipt, ceb, proof_anchors)
-    binding_hash = sha256_hex(canonicalize(binding_material).encode("utf-8"))
-    if normalize_string(proof_material.get("binding_material_sha256")).lower() != binding_hash:
-        return {"valid": False, "reason": "native_anchor_binding_hash_mismatch"}
-    if normalize_string(receipt.get("signature")) != XOONYA_NATIVE_ANCHORED_METHOD + ":" + binding_hash:
-        return {"valid": False, "reason": "signature_native_anchored_mismatch"}
-    return {"valid": True, "verification_state": "verified_native_anchor_binding", "anchor_count": len(proof_anchors), "anchor_root_sha256": expected_anchor_root}
-
-
-def verify_proof_bundle(bundle: dict[str, Any]) -> dict[str, Any]:
-    try:
-        if not isinstance(bundle, dict):
-            return {"valid": False, "reason": "bundle_not_object"}
-        if normalize_string(bundle.get("version")) != PROOF_BUNDLE_VERSION:
-            return {"valid": False, "reason": "bad_bundle_version"}
-        ceb = canonicalize_event(bundle.get("ceb"))
-        receipt = bundle.get("receipt")
-        if not isinstance(receipt, dict):
-            return {"valid": False, "reason": "receipt_not_object"}
-        if normalize_string(receipt.get("version")) != CANONICAL_RECEIPT_VERSION:
-            return {"valid": False, "reason": "bad_receipt_version"}
-        if normalize_string(receipt.get("domain_id")) != ceb["domain_id"]:
-            return {"valid": False, "reason": "receipt_domain_mismatch"}
-        if normalize_string(receipt.get("sequence")) != ceb["sequence"]:
-            return {"valid": False, "reason": "receipt_sequence_mismatch"}
-        expected_commitment = hash_event(ceb)
-        if normalize_string(receipt.get("event_commitment")).lower() != expected_commitment:
-            return {"valid": False, "reason": "event_commitment_mismatch"}
-        expected_receipt_id = sha256_hex(canonicalize({
-            "agent_identity": normalize_string(receipt.get("agent_identity")),
-            "domain_id": ceb["domain_id"],
-            "event_commitment": expected_commitment,
-            "sequence": ceb["sequence"],
-            "version": CANONICAL_RECEIPT_VERSION,
-        }).encode("utf-8"))
-        if normalize_string(receipt.get("receipt_id")).lower() != expected_receipt_id:
-            return {"valid": False, "reason": "receipt_id_mismatch"}
-        if not normalize_string(receipt.get("agent_identity")):
-            return {"valid": False, "reason": "agent_identity_missing"}
-        if not normalize_string(receipt.get("signature")):
-            return {"valid": False, "reason": "signature_missing"}
-        algorithm = normalize_string(receipt.get("algorithm"))
-        if not algorithm:
-            return {"valid": False, "reason": "verification_method_missing"}
-        if algorithm == "none":
-            return {"valid": False, "reason": "verification_method_none"}
-        if algorithm == XOONYA_NATIVE_HYBRID_METHOD:
-            return {"valid": False, "reason": "native_hybrid_runtime_unavailable_in_python_candidate"}
-        if algorithm == LEGACY_OPRETURN_METHOD:
-            legacy_receipt = (receipt.get("compatibility") or {}).get("legacy_receipt")
-            if not isinstance(legacy_receipt, dict):
-                return {"valid": False, "reason": "legacy_receipt_missing"}
-            legacy_verification = verify_legacy_receipt(legacy_receipt.get("opreturn_hex"), canonicalize(ceb).encode("utf-8"))
-            if not legacy_verification["valid"]:
-                return {"valid": False, "reason": "legacy_receipt_" + legacy_verification["reason"]}
-            if normalize_string(receipt.get("signature")).lower() != normalize_string(legacy_receipt.get("opreturn_hex")).lower():
-                return {"valid": False, "reason": "signature_legacy_mismatch"}
-            state = "verified_legacy_opreturn"
-        elif algorithm == XOONYA_NATIVE_SHA256_METHOD:
-            expected_signature = build_native_receipt_signature(receipt, ceb)
-            if normalize_string(receipt.get("signature")) != expected_signature:
-                return {"valid": False, "reason": "signature_native_mismatch"}
-            state = "verified_native_digest"
-        elif algorithm == XOONYA_NATIVE_ANCHORED_METHOD:
-            anchored = _verify_native_anchored(receipt, ceb, bundle)
-            if not anchored["valid"]:
-                return {"valid": False, "reason": anchored["reason"]}
-            state = anchored["verification_state"]
-        elif algorithm == XOONYA_NATIVE_SIGNED_METHOD:
-            signed = verify_native_signed_receipt_proof(receipt, ceb)
-            if not signed["valid"]:
-                return {
-                    "valid": False,
-                    "reason": signed["reason"],
-                    **({"dependency": signed["dependency"]} if signed.get("dependency") else {}),
-                }
-            state = signed["verification_state"]
-        elif algorithm in EXTERNAL_ASSERTION_METHODS:
-            signature = normalize_string(receipt.get("signature"))
-            if signature.startswith((
-                XOONYA_NATIVE_SHA256_METHOD + ":",
-                XOONYA_NATIVE_SIGNED_METHOD + ":",
-                XOONYA_NATIVE_ANCHORED_METHOD + ":",
-                XOONYA_NATIVE_HYBRID_METHOD + ":",
-            )):
-                return {"valid": False, "reason": "signature_method_mismatch"}
-            state = "accepted_detached_assertion" if algorithm == DETACHED_ASSERTION_METHOD else "accepted_external_proof_envelope"
-        else:
-            return {"valid": False, "reason": "verification_method_unsupported"}
-        return {
-            "valid": True,
-            "reason": None,
-            "version": PROOF_BUNDLE_VERSION,
-            "event_commitment": expected_commitment,
-            "receipt_id": expected_receipt_id,
-            "verification_method": algorithm,
-            "verification_state": state,
-        }
-    except Exception as error:
-        return {"valid": False, "reason": str(error)}