xoonya 3.1.17 → 3.2.1

package/lib/native_verify.js

@@ -0,0 +1,1918 @@
+"use strict";
+
+// Standalone verifier for xoonya proof bundles, native receipts, XNYA atoms,
+// payload profiles, and line-rate frames.
+//
+// This module VERIFIES only. It recomputes digests and checks signatures that a
+// proof already carries; it never emits receipts, signs material, or builds
+// proof bundles. The canonicalization rules (sorted-key JSON, SHA-256, SPKI key
+// fingerprints, base64url signatures) are byte-for-byte the rules the hosted
+// xoonya proof engine uses, so a bundle that verifies here verifies there and
+// vice versa. Node built-ins only (node:crypto).
+//
+// What a valid result means: the proof is well-formed and bound to the canonical
+// event, and (for signed / hybrid methods) the carried public key really signed
+// it. It does not establish who controls that key, custody, settlement, or
+// external chain truth; supply `trusted_public_key_refs` / `expected_*_ref`
+// options to bind a key to an identity you already trust.
+
+const crypto = require("crypto");
+
+const MAGIC_HEX = "50524654";
+const XOONYA_NATIVE_ATOM_MAGIC_ASCII = "XNYA";
+const XOONYA_NATIVE_ATOM_MAGIC_HEX = "584e5941";
+const VERSION_V1_HEX = "01";
+const VERSION_V2_HEX = "02";
+const VALID_TYPES = new Set(["01", "02", "03"]);
+const ZERO_HASH32 = "00".repeat(32);
+const ZERO_CONTEXT12 = "00".repeat(12);
+const PROOF_ENVELOPE_VERSION = "proof-envelope-v1";
+const CANONICAL_EVENT_BUNDLE_VERSION = "canonical-event-bundle/v1";
+const CANONICAL_RECEIPT_VERSION = "receipt/v1";
+const PROOF_BUNDLE_VERSION = "proof-bundle/v1";
+const VERIFICATION_METHOD_NONE = "none";
+const LEGACY_OPRETURN_METHOD = "legacy-opreturn-v1";
+const DETACHED_ASSERTION_METHOD = "detached-assertion-v1";
+const XOONYA_NATIVE_SHA256_METHOD = "xoonya-native-sha256-v1";
+const JWT_ASSERTION_METHOD = "jwt-assertion-v1";
+const DID_VC_METHOD = "did-vc-v1";
+const SD_JWT_VC_METHOD = "sd-jwt-vc-v1";
+const SIGNED_ENVELOPE_METHOD = "signed-envelope-v1";
+const PARTNER_PROOF_ENVELOPE_METHOD = "partner-proof-envelope-v1";
+const XOONYA_NATIVE_PROOF_FORMAT_VERSION = "xoonya-native-proof/v1";
+const XOONYA_NATIVE_SIGNED_METHOD = "xoonya-native-signed-v1";
+const XOONYA_NATIVE_ANCHORED_METHOD = "xoonya-native-anchored-v1";
+const XOONYA_NATIVE_HYBRID_METHOD = "xoonya-native-hybrid-v1";
+const XOONYA_NATIVE_ATOM_V1 = "xoonya-native-atom/v1";
+const XOONYA_NATIVE_ATOM_V2 = "xoonya-native-atom/v2";
+const XOONYA_NATIVE_PAYLOAD_PROFILE_V1 = "xoonya-native-payload-profile/v1";
+const XOONYA_NATIVE_LINE_RATE_FRAME_V1 = "xoonya-native-line-rate-frame/v1";
+const XNYA_DS_AGENT_V1 = "xoonya:agent:v1:";
+const XNYA_DS_PAYLOAD_V1 = "xoonya:payload:v1:";
+const XNYA_DS_AGENT_V2 = "xoonya:agent:v2:";
+const XNYA_DS_PAYLOAD_V2 = "xoonya:payload:v2:";
+const XNYA_DS_PAYLOAD_PROFILE_V1 = "xoonya:payload-profile:v1:";
+const XNYA_DS_LINE_RATE_FRAME_V1 = "xoonya:line-rate-frame:v1:";
+const XNYA_NATIVE_ATOM_ERROR_CODES = Object.freeze({
+  ATOM_HEX_NOT_HEX: "atom_hex_not_hex",
+  ATOM_UNSUPPORTED_LENGTH: "atom_unsupported_length",
+  ATOM_BAD_MAGIC: "atom_bad_magic",
+  ATOM_UNSUPPORTED_RECORD_TYPE: "atom_unsupported_record_type",
+  ATOM_VERSION_LENGTH_MISMATCH: "atom_version_length_mismatch",
+  IDENTITY_UNSUPPORTED_TYPE_PREFIX: "identity_unsupported_type_prefix",
+  IDENTITY_MISSING_RAW_BYTES: "identity_missing_raw_bytes",
+  AGENT_ID_MISMATCH: "agent_id_mismatch",
+  PAYLOAD_HASH_MISMATCH: "payload_hash_mismatch"
+});
+const PROOF_VERIFICATION_METHODS = Object.freeze({
+  [LEGACY_OPRETURN_METHOD]: Object.freeze({
+    id: LEGACY_OPRETURN_METHOD,
+    family: "legacy_receipt",
+    verification_posture: "compatibility_verified",
+    description: "Verifies the compatibility OP_RETURN receipt and requires the receipt signature to match it."
+  }),
+  [DETACHED_ASSERTION_METHOD]: Object.freeze({
+    id: DETACHED_ASSERTION_METHOD,
+    family: "detached_assertion",
+    verification_posture: "structure_verified_external_signature",
+    description: "Accepts an explicit detached assertion signature after canonical receipt checks; cryptographic verification is external to this helper."
+  }),
+  [XOONYA_NATIVE_SHA256_METHOD]: Object.freeze({
+    id: XOONYA_NATIVE_SHA256_METHOD,
+    family: "xoonya_native",
+    verification_posture: "native_deterministic_digest",
+    description: "Verifies xoonya's native deterministic receipt digest format for method-agnostic proof bundles."
+  }),
+  [XOONYA_NATIVE_SIGNED_METHOD]: Object.freeze({
+    id: XOONYA_NATIVE_SIGNED_METHOD,
+    family: "xoonya_native",
+    verification_posture: "native_signature_verified",
+    description: "Verifies xoonya's native signed proof envelope with explicit signature-suite and public-key binding."
+  }),
+  [XOONYA_NATIVE_ANCHORED_METHOD]: Object.freeze({
+    id: XOONYA_NATIVE_ANCHORED_METHOD,
+    family: "xoonya_native",
+    verification_posture: "native_anchor_binding_verified",
+    description: "Verifies xoonya's native anchor-binding proof envelope for chain, batch, finality, or external attestation references."
+  }),
+  [JWT_ASSERTION_METHOD]: Object.freeze({
+    id: JWT_ASSERTION_METHOD,
+    family: "jwt",
+    verification_posture: "structure_verified_external_signature",
+    description: "Accepts a compact JWT assertion after canonical receipt checks; JWT signature verification is external to this helper."
+  }),
+  [DID_VC_METHOD]: Object.freeze({
+    id: DID_VC_METHOD,
+    family: "did_vc",
+    verification_posture: "structure_verified_external_signature",
+    description: "Accepts a DID/VC proof envelope after canonical receipt checks; DID resolution and VC proof verification are external to this helper."
+  }),
+  [SD_JWT_VC_METHOD]: Object.freeze({
+    id: SD_JWT_VC_METHOD,
+    family: "sd_jwt_vc",
+    verification_posture: "structure_verified_external_signature",
+    description: "Accepts an SD-JWT VC disclosure envelope after canonical receipt checks; disclosure and issuer verification are external to this helper."
+  }),
+  [SIGNED_ENVELOPE_METHOD]: Object.freeze({
+    id: SIGNED_ENVELOPE_METHOD,
+    family: "signed_envelope",
+    verification_posture: "structure_verified_external_signature",
+    description: "Accepts a signed envelope after canonical receipt checks; envelope-specific signature verification is external to this helper."
+  }),
+  [PARTNER_PROOF_ENVELOPE_METHOD]: Object.freeze({
+    id: PARTNER_PROOF_ENVELOPE_METHOD,
+    family: "partner_proof_envelope",
+    verification_posture: "structure_verified_external_signature",
+    description: "Accepts partner-specific proof envelopes after canonical receipt checks; partner verifier policy is external to this helper."
+  })
+});
+const NATIVE_HYBRID_METHOD_DESCRIPTOR = Object.freeze({
+  id: XOONYA_NATIVE_HYBRID_METHOD,
+  family: "xoonya_native",
+  verification_posture: "native_hybrid_signature_verified",
+  description: "Verifies xoonya's native hybrid proof envelope with a classical and PQ signature bound to one deterministic signing material."
+});
+const NATIVE_SIGNATURE_SUITES = Object.freeze({
+  ed25519: Object.freeze({
+    id: "ed25519",
+    maturity: "implemented",
+    public_key_format: "spki-pem",
+    verification_posture: "native_verified",
+    key_type: "ed25519"
+  }),
+  secp256k1: Object.freeze({
+    id: "secp256k1",
+    maturity: "implemented",
+    public_key_format: "spki-pem",
+    verification_posture: "native_verified",
+    key_type: "ec",
+    curve: "secp256k1",
+    signing_hash: "sha256"
+  }),
+  p256: Object.freeze({
+    id: "p256",
+    maturity: "implemented",
+    public_key_format: "spki-pem",
+    verification_posture: "native_verified",
+    key_type: "ec",
+    curve: "prime256v1",
+    signing_hash: "sha256"
+  }),
+  "webauthn-cose": Object.freeze({
+    id: "webauthn-cose",
+    maturity: "planned",
+    public_key_format: "cose-key",
+    verification_posture: "registry_declared_not_yet_verified"
+  }),
+  dilithium: Object.freeze({
+    id: "dilithium",
+    maturity: "planned_pqc",
+    status: "deprecated_placeholder",
+    deprecated_alias_of: "ml-dsa-65",
+    public_key_format: "suite_defined",
+    verification_posture: "registry_declared_not_yet_verified",
+    description: "Legacy pre-standard placeholder name. Use the implemented FIPS 204 suite `ml-dsa-65` instead; this entry never verifies."
+  }),
+  falcon: Object.freeze({
+    id: "falcon",
+    maturity: "planned_pqc",
+    status: "deprecated_placeholder",
+    deprecated_alias_of: null,
+    public_key_format: "suite_defined",
+    verification_posture: "registry_declared_not_yet_verified",
+    description: "Legacy pre-standard placeholder name (FN-DSA is not yet registered). This entry never verifies."
+  }),
+  "sphincs-plus": Object.freeze({
+    id: "sphincs-plus",
+    maturity: "planned_pqc",
+    status: "deprecated_placeholder",
+    deprecated_alias_of: "slh-dsa-sha2-128f",
+    public_key_format: "suite_defined",
+    verification_posture: "registry_declared_not_yet_verified",
+    description: "Legacy pre-standard placeholder name. Use the implemented FIPS 205 suite `slh-dsa-sha2-128f` instead; this entry never verifies."
+  }),
+  "ml-dsa-65": Object.freeze({
+    id: "ml-dsa-65",
+    maturity: "implemented",
+    public_key_format: "spki-pem",
+    verification_posture: "native_verified",
+    key_type: "ml-dsa-65"
+  }),
+  "slh-dsa-sha2-128f": Object.freeze({
+    id: "slh-dsa-sha2-128f",
+    maturity: "implemented",
+    public_key_format: "spki-pem",
+    verification_posture: "native_verified",
+    key_type: "slh-dsa-sha2-128f"
+  })
+});
+const XOONYA_NATIVE_IDENTITY_TYPES = Object.freeze({
+  "01": Object.freeze({
+    prefix: "01",
+    id: "secp256k1-public-key",
+    canonical_material: "compressed-sec1-public-key"
+  }),
+  "02": Object.freeze({
+    prefix: "02",
+    id: "device-identifier",
+    canonical_material: "raw-device-identifier-bytes"
+  }),
+  "03": Object.freeze({
+    prefix: "03",
+    id: "did-string",
+    canonical_material: "utf8-did-string-no-bom-no-normalization"
+  }),
+  "04": Object.freeze({
+    prefix: "04",
+    id: "opaque-agent-key",
+    canonical_material: "opaque-agent-key-bytes"
+  }),
+  "05": Object.freeze({
+    prefix: "05",
+    id: "dilithium-public-key",
+    canonical_material: "suite-defined-pqc-public-key-bytes",
+    status: "legacy_placeholder",
+    description: "Legacy placeholder prefix reserved before FIPS 204 finalization; the implemented PQ suite is `ml-dsa-65`. No verifier binds this prefix to a live suite."
+  }),
+  "06": Object.freeze({
+    prefix: "06",
+    id: "falcon-public-key",
+    canonical_material: "suite-defined-pqc-public-key-bytes",
+    status: "legacy_placeholder",
+    description: "Legacy placeholder prefix reserved before FN-DSA standardization. No verifier binds this prefix to a live suite."
+  }),
+  "07": Object.freeze({
+    prefix: "07",
+    id: "sphincs-plus-public-key",
+    canonical_material: "suite-defined-pqc-public-key-bytes",
+    status: "legacy_placeholder",
+    description: "Legacy placeholder prefix reserved before FIPS 205 finalization; the implemented PQ suite is `slh-dsa-sha2-128f`. No verifier binds this prefix to a live suite."
+  })
+});
+const EXTERNAL_PROOF_IMPORT_METHODS = Object.freeze([
+  DETACHED_ASSERTION_METHOD,
+  JWT_ASSERTION_METHOD,
+  DID_VC_METHOD,
+  SD_JWT_VC_METHOD,
+  SIGNED_ENVELOPE_METHOD,
+  PARTNER_PROOF_ENVELOPE_METHOD
+]);
+const VERIFICATION_CLASS_CRYPTOGRAPHIC = "cryptographic";
+const VERIFICATION_CLASS_DIGEST = "digest";
+const VERIFICATION_CLASS_STRUCTURAL = "structural";
+const VERIFICATION_CLASS_ANCHORED_BINDING = "anchored_binding";
+const PROOF_VERIFICATION_CLASSES = Object.freeze({
+  [VERIFICATION_CLASS_CRYPTOGRAPHIC]: Object.freeze({
+    id: VERIFICATION_CLASS_CRYPTOGRAPHIC,
+    cryptographically_verified: true,
+    strict_mode_accepted: true,
+    methods: Object.freeze([XOONYA_NATIVE_SIGNED_METHOD, XOONYA_NATIVE_HYBRID_METHOD]),
+    description: "A native classical and/or PQ signature was checked against the public key carried in the proof. Identity binding still requires a verifier-supplied trust root."
+  }),
+  [VERIFICATION_CLASS_DIGEST]: Object.freeze({
+    id: VERIFICATION_CLASS_DIGEST,
+    cryptographically_verified: false,
+    strict_mode_accepted: false,
+    methods: Object.freeze([XOONYA_NATIVE_SHA256_METHOD, LEGACY_OPRETURN_METHOD]),
+    description: "Only an unkeyed deterministic digest was recomputed. Anyone can produce a valid digest; this proves integrity and replayability, not authorship."
+  }),
+  [VERIFICATION_CLASS_ANCHORED_BINDING]: Object.freeze({
+    id: VERIFICATION_CLASS_ANCHORED_BINDING,
+    cryptographically_verified: false,
+    strict_mode_accepted: false,
+    methods: Object.freeze([XOONYA_NATIVE_ANCHORED_METHOD]),
+    description: "An unkeyed digest binding to declared anchor refs was recomputed. External anchor truth and authorship are not verified by xoonya."
+  }),
+  [VERIFICATION_CLASS_STRUCTURAL]: Object.freeze({
+    id: VERIFICATION_CLASS_STRUCTURAL,
+    cryptographically_verified: false,
+    strict_mode_accepted: false,
+    methods: Object.freeze(EXTERNAL_PROOF_IMPORT_METHODS.slice()),
+    description: "The envelope shape, method registration, and canonical receipt binding were checked. The external signature itself must be verified by the external verifier stack."
+  })
+});
+const STRICT_DIGEST_ONLY_REASON = "digest_only_not_cryptographically_verified";
+const STRICT_EXTERNAL_VERIFICATION_REASON = "external_verification_required";
+const NATIVE_PUBLIC_KEY_NOT_TRUSTED_REASON = "native_public_key_not_trusted";
+const NATIVE_HYBRID_PUBLIC_KEY_NOT_TRUSTED_REASON = "native_hybrid_public_key_not_trusted";
+const PROOF_VERIFICATION_STRICT_REJECTION_CODES = Object.freeze([
+  STRICT_DIGEST_ONLY_REASON,
+  STRICT_EXTERNAL_VERIFICATION_REASON
+]);
+const PROOF_VERIFICATION_TRUST_ROOT_REJECTION_CODES = Object.freeze([
+  NATIVE_PUBLIC_KEY_NOT_TRUSTED_REASON,
+  NATIVE_HYBRID_PUBLIC_KEY_NOT_TRUSTED_REASON
+]);
+const STRICT_VERIFY_ENV = "XOONYA_STRICT_VERIFY";
+
+// ---------------------------------------------------------------------------
+// Primitives and canonicalization
+// ---------------------------------------------------------------------------
+
+function sha256Hex(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+function hash160Hex(buf) {
+  const sha = crypto.createHash("sha256").update(buf).digest();
+  return crypto.createHash("ripemd160").update(sha).digest("hex");
+}
+
+function assertHex(hex, expectedLen, label) {
+  const normalized = String(hex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(normalized) || normalized.length !== expectedLen) {
+    throw new Error(`${label} must be ${expectedLen / 2} byte hex`);
+  }
+  return normalized;
+}
+
+function assertVariableHex(hex, label) {
+  const normalized = String(hex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(normalized) || normalized.length === 0 || normalized.length % 2 !== 0) {
+    throw new Error(`${label} must be non-empty byte-aligned hex`);
+  }
+  return normalized;
+}
+
+// Deterministic JSON: arrays in order, object keys sorted, JSON.stringify scalars.
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalize(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function canonicalJsonSha256Hex(value) {
+  return sha256Hex(Buffer.from(canonicalize(value), "utf8"));
+}
+
+function base64urlDecode(value, label) {
+  const normalized = normalizeString(value);
+  if (!/^[A-Za-z0-9_-]+$/.test(normalized)) {
+    throw new Error(`${label} must be base64url`);
+  }
+  const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+  return Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+
+function readUInt64String(buf) {
+  return buf.readBigUInt64BE(0).toString();
+}
+
+function normalizeString(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function normalizeStringArray(values, label) {
+  if (values == null) return undefined;
+  if (!Array.isArray(values)) {
+    throw new Error(`${label} must be an array`);
+  }
+  const normalized = values
+    .map((value) => normalizeString(value))
+    .filter(Boolean);
+  return normalized.length ? normalized : undefined;
+}
+
+function normalizePlainObject(value, label) {
+  if (value == null) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// Canonical event bundle
+// ---------------------------------------------------------------------------
+
+function canonicalizeEvent(event) {
+  if (!event || typeof event !== "object" || Array.isArray(event)) {
+    throw new Error("event must be an object");
+  }
+  const normalized = {
+    version: normalizeString(event.version || CANONICAL_EVENT_BUNDLE_VERSION),
+    domain_id: normalizeString(event.domain_id),
+    sequence: normalizeString(event.sequence),
+    actor_id: normalizeString(event.actor_id),
+    adapter_source: normalizeString(event.adapter_source),
+    event_type: normalizeString(event.event_type),
+    event_hash: normalizeString(event.event_hash).toLowerCase()
+  };
+  Object.entries(normalized).forEach(([key, value]) => {
+    if (!value) {
+      throw new Error(`event.${key} required`);
+    }
+  });
+  if (normalized.version !== CANONICAL_EVENT_BUNDLE_VERSION) {
+    throw new Error(`event.version must be ${CANONICAL_EVENT_BUNDLE_VERSION}`);
+  }
+  assertHex(normalized.event_hash, 64, "event.event_hash");
+
+  const timestampNs = normalizeString(event.timestamp_ns);
+  if (timestampNs) {
+    normalized.timestamp_ns = timestampNs;
+  }
+
+  const parentRefs = normalizeStringArray(event.parent_refs, "event.parent_refs");
+  if (parentRefs) {
+    normalized.parent_refs = parentRefs;
+  }
+
+  const capabilityRefs = normalizeStringArray(event.capability_refs, "event.capability_refs");
+  if (capabilityRefs) {
+    normalized.capability_refs = capabilityRefs;
+  }
+
+  const attestationRef = normalizeString(event.attestation_ref);
+  if (attestationRef) {
+    normalized.attestation_ref = attestationRef;
+  }
+
+  const semanticSlots = normalizePlainObject(event.semantic_slots, "event.semantic_slots");
+  if (semanticSlots) {
+    normalized.semantic_slots = semanticSlots;
+  }
+
+  return normalized;
+}
+
+function hashEvent(event) {
+  return canonicalJsonSha256Hex(canonicalizeEvent(event));
+}
+
+function buildCanonicalReceiptSigningMaterial(receipt) {
+  return {
+    agent_identity: receipt.agent_identity,
+    domain_id: receipt.domain_id,
+    event_commitment: receipt.event_commitment,
+    receipt_id: receipt.receipt_id,
+    sequence: receipt.sequence,
+    version: receipt.version
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registries
+// ---------------------------------------------------------------------------
+
+function listProofVerificationMethods() {
+  return Object.values(PROOF_VERIFICATION_METHODS).map((method) => ({ ...method }));
+}
+
+function getProofVerificationMethod(methodId) {
+  const normalized = normalizeString(methodId);
+  const method = PROOF_VERIFICATION_METHODS[normalized];
+  return method ? { ...method } : null;
+}
+
+function listNativeSignatureSuites() {
+  return Object.values(NATIVE_SIGNATURE_SUITES).map((suite) => ({ ...suite }));
+}
+
+function getNativeSignatureSuite(suiteId) {
+  const normalized = normalizeString(suiteId);
+  const suite = NATIVE_SIGNATURE_SUITES[normalized];
+  return suite ? { ...suite } : null;
+}
+
+function listImplementedClassicalNativeSignatureSuites() {
+  return listNativeSignatureSuites().filter((suite) => suite.maturity === "implemented" && !suite.id.startsWith("ml-dsa-") && !suite.id.startsWith("slh-dsa-"));
+}
+
+function listImplementedPqNativeSignatureSuites() {
+  return listNativeSignatureSuites().filter((suite) => suite.maturity === "implemented" && (suite.id.startsWith("ml-dsa-") || suite.id.startsWith("slh-dsa-")));
+}
+
+function buildNativeHybridSuiteId(classicalSuiteId, pqSuiteId) {
+  const classicalSuite = getNativeSignatureSuite(classicalSuiteId);
+  if (!classicalSuite || classicalSuite.maturity !== "implemented") {
+    throw new Error("native hybrid classical signature suite not implemented");
+  }
+  if (classicalSuite.id.startsWith("ml-dsa-") || classicalSuite.id.startsWith("slh-dsa-")) {
+    throw new Error("native hybrid classical signature suite must be classical");
+  }
+  const pqSuite = getNativeSignatureSuite(pqSuiteId);
+  if (!pqSuite || pqSuite.maturity !== "implemented") {
+    throw new Error("native hybrid pq signature suite not implemented");
+  }
+  if (!pqSuite.id.startsWith("ml-dsa-") && !pqSuite.id.startsWith("slh-dsa-")) {
+    throw new Error("native hybrid pq signature suite must be pq");
+  }
+  return `${classicalSuite.id}+${pqSuite.id}`;
+}
+
+function parseNativeHybridSuite(hybridSuiteId) {
+  const normalized = normalizeString(hybridSuiteId);
+  const [classicalSuiteId, pqSuiteId, extra] = normalized.split("+");
+  if (!classicalSuiteId || !pqSuiteId || extra) {
+    throw new Error("native hybrid signature suite unsupported");
+  }
+  return {
+    id: buildNativeHybridSuiteId(classicalSuiteId, pqSuiteId),
+    classical_suite: getNativeSignatureSuite(classicalSuiteId),
+    pq_suite: getNativeSignatureSuite(pqSuiteId)
+  };
+}
+
+function listImplementedNativeHybridSuites() {
+  const suites = [];
+  for (const classicalSuite of listImplementedClassicalNativeSignatureSuites()) {
+    for (const pqSuite of listImplementedPqNativeSignatureSuites()) {
+      suites.push({
+        id: buildNativeHybridSuiteId(classicalSuite.id, pqSuite.id),
+        classical_suite: classicalSuite.id,
+        pq_suite: pqSuite.id,
+        posture: "dual_signature_verified"
+      });
+    }
+  }
+  return suites;
+}
+
+function listxoonyaNativeIdentityTypes() {
+  return Object.values(XOONYA_NATIVE_IDENTITY_TYPES).map((entry) => ({ ...entry }));
+}
+
+function getxoonyaNativeIdentityType(prefixHex) {
+  const normalized = normalizeString(prefixHex).toLowerCase();
+  const entry = XOONYA_NATIVE_IDENTITY_TYPES[normalized];
+  return entry ? { ...entry } : null;
+}
+
+function isExternalAssertionMethod(algorithm) {
+  return EXTERNAL_PROOF_IMPORT_METHODS.includes(algorithm);
+}
+
+// ---------------------------------------------------------------------------
+// Native proof material (recomputed by the verifier, never signed here)
+// ---------------------------------------------------------------------------
+
+function expectedNativeDigestSignature(receipt, canonicalEvent) {
+  const material = {
+    method: XOONYA_NATIVE_SHA256_METHOD,
+    receipt_signing_material: buildCanonicalReceiptSigningMaterial(receipt),
+    event_commitment: hashEvent(canonicalEvent)
+  };
+  return `${XOONYA_NATIVE_SHA256_METHOD}:${sha256Hex(Buffer.from(canonicalize(material), "utf8"))}`;
+}
+
+function normalizePublicKeyPem(value) {
+  const pem = String(value || "").replace(/\r\n/g, "\n").trim();
+  if (!pem.includes("BEGIN PUBLIC KEY")) {
+    throw new Error("native public key must be SPKI PEM");
+  }
+  return `${pem}\n`;
+}
+
+function nativePublicKeyRefFromPem(publicKeyPem, signatureSuite = "ed25519") {
+  const suite = getNativeSignatureSuite(signatureSuite);
+  if (!suite) {
+    throw new Error("native signature suite unsupported");
+  }
+  if (suite.maturity !== "implemented") {
+    throw new Error("native signature suite not implemented");
+  }
+  const publicKey = crypto.createPublicKey(normalizePublicKeyPem(publicKeyPem));
+  const der = publicKey.export({ type: "spki", format: "der" });
+  return `${suite.id}-spki-sha256:${sha256Hex(der)}`;
+}
+
+function nativeHybridPublicKeyRefFromPems(classicalPublicKeyPem, pqPublicKeyPem, hybridSuiteId) {
+  parseNativeHybridSuite(hybridSuiteId);
+  const classicalDer = crypto.createPublicKey(normalizePublicKeyPem(classicalPublicKeyPem)).export({ type: "spki", format: "der" });
+  const pqDer = crypto.createPublicKey(normalizePublicKeyPem(pqPublicKeyPem)).export({ type: "spki", format: "der" });
+  return `${hybridSuiteId}-hybrid-spki-sha256:${sha256Hex(Buffer.concat([classicalDer, pqDer]))}`;
+}
+
+function nativeSigningHashForSuite(suite) {
+  return suite && suite.signing_hash ? suite.signing_hash : null;
+}
+
+function assertNativeKeyMatchesSuite(keyObject, suite, label) {
+  if (suite && suite.key_type && keyObject.asymmetricKeyType !== suite.key_type) {
+    throw new Error(`${label} key type must be ${suite.key_type}`);
+  }
+  if (suite && suite.curve) {
+    const details = keyObject.asymmetricKeyDetails || {};
+    if (details.namedCurve !== suite.curve) {
+      throw new Error(`${label} curve must be ${suite.curve}`);
+    }
+  }
+}
+
+function buildNativeSignedProofMaterial(receipt, canonicalEvent, proofDescriptor) {
+  return {
+    identity_ref: proofDescriptor.identity_ref,
+    method: XOONYA_NATIVE_SIGNED_METHOD,
+    public_key_ref: proofDescriptor.public_key_ref,
+    receipt_signing_material: buildCanonicalReceiptSigningMaterial(receipt),
+    event_commitment: hashEvent(canonicalEvent),
+    signature_suite: proofDescriptor.signature_suite,
+    standard_version: XOONYA_NATIVE_PROOF_FORMAT_VERSION
+  };
+}
+
+function buildNativeHybridProofMaterial(receipt, canonicalEvent, proofDescriptor) {
+  return {
+    identity_ref: proofDescriptor.identity_ref,
+    method: XOONYA_NATIVE_HYBRID_METHOD,
+    hybrid_suite: proofDescriptor.hybrid_suite,
+    hybrid_public_key_ref: proofDescriptor.hybrid_public_key_ref,
+    classical_public_key_ref: proofDescriptor.classical_public_key_ref,
+    pq_public_key_ref: proofDescriptor.pq_public_key_ref,
+    receipt_signing_material: buildCanonicalReceiptSigningMaterial(receipt),
+    event_commitment: hashEvent(canonicalEvent),
+    standard_version: XOONYA_NATIVE_PROOF_FORMAT_VERSION
+  };
+}
+
+// Runtime capability probe: can this Node build verify the classical and PQ
+// halves of a hybrid suite? Uses a throwaway key pair; nothing is persisted.
+const NATIVE_HYBRID_RUNTIME_SUPPORT_CACHE = new Map();
+
+function runtimeSupportsNativeHybridSuite(hybridSuiteId) {
+  const cacheKey = normalizeString(hybridSuiteId);
+  if (NATIVE_HYBRID_RUNTIME_SUPPORT_CACHE.has(cacheKey)) {
+    return NATIVE_HYBRID_RUNTIME_SUPPORT_CACHE.get(cacheKey);
+  }
+  const supported = probeNativeHybridRuntimeSupport(cacheKey);
+  NATIVE_HYBRID_RUNTIME_SUPPORT_CACHE.set(cacheKey, supported);
+  return supported;
+}
+
+function probeNativeHybridRuntimeSupport(hybridSuiteId) {
+  try {
+    const hybridSuite = parseNativeHybridSuite(hybridSuiteId);
+    const classicalPair = hybridSuite.classical_suite.id === "secp256k1"
+      ? crypto.generateKeyPairSync("ec", { namedCurve: "secp256k1" })
+      : hybridSuite.classical_suite.id === "p256"
+        ? crypto.generateKeyPairSync("ec", { namedCurve: "P-256" })
+        : crypto.generateKeyPairSync(hybridSuite.classical_suite.key_type);
+    const pqPair = crypto.generateKeyPairSync(hybridSuite.pq_suite.key_type);
+    const probe = Buffer.from(`xoonya-hybrid-runtime-probe:${hybridSuiteId}`, "utf8");
+    const classicalSignature = crypto.sign(nativeSigningHashForSuite(hybridSuite.classical_suite), probe, classicalPair.privateKey);
+    const pqSignature = crypto.sign(nativeSigningHashForSuite(hybridSuite.pq_suite), probe, pqPair.privateKey);
+    return (
+      crypto.verify(nativeSigningHashForSuite(hybridSuite.classical_suite), probe, classicalPair.publicKey, classicalSignature) &&
+      crypto.verify(nativeSigningHashForSuite(hybridSuite.pq_suite), probe, pqPair.publicKey, pqSignature)
+    );
+  } catch (_error) {
+    return false;
+  }
+}
+
+function normalizeNativeAnchorRefs(anchorRefs, label = "native anchors") {
+  if (!Array.isArray(anchorRefs) || anchorRefs.length === 0) {
+    throw new Error(`${label} must be a non-empty array`);
+  }
+  if (anchorRefs.length > 32) {
+    throw new Error(`${label} must contain at most 32 entries`);
+  }
+  const normalized = anchorRefs.map((anchor, index) => {
+    if (!anchor || typeof anchor !== "object" || Array.isArray(anchor)) {
+      throw new Error(`${label}[${index}] must be an object`);
+    }
+    const entry = {
+      anchor_id: normalizeString(anchor.anchor_id || anchor.id),
+      anchor_kind: normalizeString(anchor.anchor_kind || anchor.kind),
+      anchor_ref: normalizeString(anchor.anchor_ref || anchor.ref),
+      anchor_hash_sha256: normalizeString(anchor.anchor_hash_sha256 || anchor.hash_sha256 || anchor.anchor_hash).toLowerCase()
+    };
+    if (!entry.anchor_id) throw new Error(`${label}[${index}].anchor_id required`);
+    if (!entry.anchor_kind) throw new Error(`${label}[${index}].anchor_kind required`);
+    if (!entry.anchor_ref) throw new Error(`${label}[${index}].anchor_ref required`);
+    entry.anchor_hash_sha256 = assertHex(entry.anchor_hash_sha256, 64, `${label}[${index}].anchor_hash_sha256`);
+
+    const network = normalizeString(anchor.network);
+    if (network) entry.network = network;
+    const finalityState = normalizeString(anchor.finality_state);
+    if (finalityState) entry.finality_state = finalityState;
+    const observedAtIso = normalizeString(anchor.observed_at_iso);
+    if (observedAtIso) entry.observed_at_iso = observedAtIso;
+    const providerRef = normalizeString(anchor.provider_ref);
+    if (providerRef) entry.provider_ref = providerRef;
+    const inclusionProofRef = normalizeString(anchor.inclusion_proof_ref);
+    if (inclusionProofRef) entry.inclusion_proof_ref = inclusionProofRef;
+    return entry;
+  });
+  return normalized.sort((a, b) => canonicalize(a).localeCompare(canonicalize(b)));
+}
+
+function buildNativeAnchorBindingMaterial(receipt, canonicalEvent, anchorRefs) {
+  const normalizedAnchors = normalizeNativeAnchorRefs(anchorRefs);
+  return {
+    anchor_refs: normalizedAnchors,
+    base_method: XOONYA_NATIVE_SHA256_METHOD,
+    event_commitment: hashEvent(canonicalEvent),
+    method: XOONYA_NATIVE_ANCHORED_METHOD,
+    receipt_signing_material: buildCanonicalReceiptSigningMaterial(receipt),
+    standard_version: XOONYA_NATIVE_PROOF_FORMAT_VERSION
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Verification options, trust roots, verification classes
+// ---------------------------------------------------------------------------
+
+function strictVerifyEnabledByEnvironment() {
+  const raw = normalizeString(process.env[STRICT_VERIFY_ENV]).toLowerCase();
+  return raw === "1" || raw === "true";
+}
+
+function resolveProofVerificationOptions(options) {
+  const source = options && typeof options === "object" && !Array.isArray(options) ? options : {};
+  const trustedPublicKeyRefs = source.trusted_public_key_refs &&
+    typeof source.trusted_public_key_refs === "object" &&
+    !Array.isArray(source.trusted_public_key_refs)
+    ? source.trusted_public_key_refs
+    : null;
+  const expectedPublicKeyRef = normalizeString(source.expected_public_key_ref);
+  const expectedClassicalPublicKeyRef = normalizeString(source.expected_classical_public_key_ref);
+  const expectedPqPublicKeyRef = normalizeString(source.expected_pq_public_key_ref);
+  const expectedHybridPublicKeyRef = normalizeString(source.expected_hybrid_public_key_ref);
+  return {
+    __resolved_verification_options: true,
+    strict: source.strict === true || strictVerifyEnabledByEnvironment(),
+    trust_root_applied: Boolean(
+      trustedPublicKeyRefs ||
+      expectedPublicKeyRef ||
+      expectedClassicalPublicKeyRef ||
+      expectedPqPublicKeyRef ||
+      expectedHybridPublicKeyRef
+    ),
+    expected_public_key_ref: expectedPublicKeyRef,
+    expected_classical_public_key_ref: expectedClassicalPublicKeyRef,
+    expected_pq_public_key_ref: expectedPqPublicKeyRef,
+    expected_hybrid_public_key_ref: expectedHybridPublicKeyRef,
+    trusted_public_key_refs: trustedPublicKeyRefs
+  };
+}
+
+function normalizeTrustedPublicKeyRefList(value) {
+  if (value == null) return [];
+  const list = Array.isArray(value) ? value : [value];
+  return list.map((entry) => normalizeString(entry)).filter(Boolean);
+}
+
+function lookupTrustedPublicKeyEntry(trustedPublicKeyRefs, identityRef, agentIdentity) {
+  if (!trustedPublicKeyRefs) return undefined;
+  for (const candidate of [normalizeString(identityRef), normalizeString(agentIdentity)]) {
+    if (candidate && Object.prototype.hasOwnProperty.call(trustedPublicKeyRefs, candidate)) {
+      return trustedPublicKeyRefs[candidate];
+    }
+  }
+  return undefined;
+}
+
+function trustedPublicKeyRefsForLane(entry, lane) {
+  if (entry == null) return { declared: false, refs: [] };
+  if (typeof entry === "string" || Array.isArray(entry)) {
+    return lane === "classical"
+      ? { declared: true, refs: normalizeTrustedPublicKeyRefList(entry) }
+      : { declared: false, refs: [] };
+  }
+  if (typeof entry !== "object") return { declared: false, refs: [] };
+  const laneValue = lane === "classical"
+    ? (entry.classical != null ? entry.classical : (entry.classical_public_key_ref != null ? entry.classical_public_key_ref : entry.public_key_ref))
+    : lane === "pq"
+      ? (entry.pq != null ? entry.pq : entry.pq_public_key_ref)
+      : (entry.hybrid != null ? entry.hybrid : entry.hybrid_public_key_ref);
+  if (laneValue == null) return { declared: false, refs: [] };
+  return { declared: true, refs: normalizeTrustedPublicKeyRefList(laneValue) };
+}
+
+function nativeSignedPublicKeyTrusted(verification, publicKeyRef, identityRef, agentIdentity) {
+  if (!verification || !verification.trust_root_applied) return true;
+  let constrained = false;
+  if (verification.expected_public_key_ref) {
+    constrained = true;
+    if (publicKeyRef !== verification.expected_public_key_ref) return false;
+  }
+  if (verification.expected_classical_public_key_ref) {
+    constrained = true;
+    if (publicKeyRef !== verification.expected_classical_public_key_ref) return false;
+  }
+  if (verification.trusted_public_key_refs) {
+    constrained = true;
+    const entry = lookupTrustedPublicKeyEntry(verification.trusted_public_key_refs, identityRef, agentIdentity);
+    const lane = trustedPublicKeyRefsForLane(entry, "classical");
+    if (!lane.declared || !lane.refs.includes(publicKeyRef)) return false;
+  }
+  return constrained;
+}
+
+function nativeHybridPublicKeyTrusted(verification, refs, identityRef, agentIdentity) {
+  if (!verification || !verification.trust_root_applied) return true;
+  let constrained = false;
+  if (verification.expected_public_key_ref) {
+    constrained = true;
+    if (refs.classical !== verification.expected_public_key_ref && refs.hybrid !== verification.expected_public_key_ref) return false;
+  }
+  if (verification.expected_classical_public_key_ref) {
+    constrained = true;
+    if (refs.classical !== verification.expected_classical_public_key_ref) return false;
+  }
+  if (verification.expected_pq_public_key_ref) {
+    constrained = true;
+    if (refs.pq !== verification.expected_pq_public_key_ref) return false;
+  }
+  if (verification.expected_hybrid_public_key_ref) {
+    constrained = true;
+    if (refs.hybrid !== verification.expected_hybrid_public_key_ref) return false;
+  }
+  if (verification.trusted_public_key_refs) {
+    const entry = lookupTrustedPublicKeyEntry(verification.trusted_public_key_refs, identityRef, agentIdentity);
+    const classicalLane = trustedPublicKeyRefsForLane(entry, "classical");
+    const pqLane = trustedPublicKeyRefsForLane(entry, "pq");
+    const hybridLane = trustedPublicKeyRefsForLane(entry, "hybrid");
+    if (!classicalLane.declared && !pqLane.declared && !hybridLane.declared) return false;
+    if (classicalLane.declared && !classicalLane.refs.includes(refs.classical) && !classicalLane.refs.includes(refs.hybrid)) return false;
+    if (pqLane.declared && !pqLane.refs.includes(refs.pq)) return false;
+    if (hybridLane.declared && !hybridLane.refs.includes(refs.hybrid)) return false;
+    constrained = true;
+  }
+  return constrained;
+}
+
+function verificationClassForMethod(algorithm) {
+  const normalized = normalizeString(algorithm);
+  for (const entry of Object.values(PROOF_VERIFICATION_CLASSES)) {
+    if (entry.methods.includes(normalized)) return entry.id;
+  }
+  return null;
+}
+
+function listProofVerificationClasses() {
+  return Object.values(PROOF_VERIFICATION_CLASSES).map((entry) => ({ ...entry, methods: entry.methods.slice() }));
+}
+
+function finalizeProofMethodVerification(result, algorithm, verification) {
+  const verificationClass = verificationClassForMethod(algorithm);
+  const classEntry = verificationClass ? PROOF_VERIFICATION_CLASSES[verificationClass] : null;
+  const decorated = {
+    ...result,
+    verification_class: verificationClass,
+    cryptographically_verified: result.valid === true && Boolean(classEntry && classEntry.cryptographically_verified),
+    strict: verification.strict === true,
+    trust_root_applied: verification.trust_root_applied === true
+  };
+  if (decorated.valid === true && decorated.strict && classEntry && !classEntry.strict_mode_accepted) {
+    return {
+      ...decorated,
+      valid: false,
+      reason: verificationClass === VERIFICATION_CLASS_STRUCTURAL
+        ? STRICT_EXTERNAL_VERIFICATION_REASON
+        : STRICT_DIGEST_ONLY_REASON,
+      cryptographically_verified: false
+    };
+  }
+  return decorated;
+}
+
+// ---------------------------------------------------------------------------
+// Native method verifiers
+// ---------------------------------------------------------------------------
+
+function verifyNativeSignedReceiptProof(receipt, ceb, verification = null) {
+  try {
+    const proof = receipt.native_proof;
+    if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
+      return { valid: false, reason: "native_proof_missing" };
+    }
+    if (normalizeString(proof.method) !== XOONYA_NATIVE_SIGNED_METHOD) {
+      return { valid: false, reason: "native_proof_method_mismatch" };
+    }
+    const signatureSuite = normalizeString(proof.signature_suite);
+    const suite = getNativeSignatureSuite(signatureSuite);
+    if (!suite) {
+      return { valid: false, reason: "native_signature_suite_unsupported" };
+    }
+    if (suite.maturity !== "implemented") {
+      return { valid: false, reason: "native_signature_suite_not_implemented" };
+    }
+    const identityRef = normalizeString(proof.identity_ref);
+    if (!identityRef) {
+      return { valid: false, reason: "native_identity_ref_missing" };
+    }
+    const publicKeyMaterial = proof.public_key_material;
+    if (!publicKeyMaterial || typeof publicKeyMaterial !== "object" || Array.isArray(publicKeyMaterial)) {
+      return { valid: false, reason: "native_public_key_material_missing" };
+    }
+    if (normalizeString(publicKeyMaterial.format) !== suite.public_key_format) {
+      return { valid: false, reason: "native_public_key_format_mismatch" };
+    }
+    const publicKeyPem = normalizePublicKeyPem(publicKeyMaterial.value);
+    const publicKey = crypto.createPublicKey(publicKeyPem);
+    assertNativeKeyMatchesSuite(publicKey, suite, "native public key");
+    const expectedPublicKeyRef = nativePublicKeyRefFromPem(publicKeyPem, suite.id);
+    if (normalizeString(proof.public_key_ref) !== expectedPublicKeyRef) {
+      return { valid: false, reason: "native_public_key_ref_mismatch" };
+    }
+    const proofMaterial = proof.proof_material;
+    if (!proofMaterial || typeof proofMaterial !== "object" || Array.isArray(proofMaterial)) {
+      return { valid: false, reason: "native_proof_material_missing" };
+    }
+    const signature = normalizeString(proofMaterial.signature);
+    if (!signature) {
+      return { valid: false, reason: "native_signature_missing" };
+    }
+    const expectedCompactSignature = `${XOONYA_NATIVE_SIGNED_METHOD}:${suite.id}:${signature}`;
+    if (normalizeString(receipt.signature) !== expectedCompactSignature) {
+      return { valid: false, reason: "signature_native_signed_mismatch" };
+    }
+    const signingMaterial = buildNativeSignedProofMaterial(receipt, ceb, {
+      identity_ref: identityRef,
+      public_key_ref: expectedPublicKeyRef,
+      signature_suite: suite.id
+    });
+    const signingBytes = Buffer.from(canonicalize(signingMaterial), "utf8");
+    const expectedSigningHash = sha256Hex(signingBytes);
+    if (normalizeString(proofMaterial.signing_material_sha256).toLowerCase() !== expectedSigningHash) {
+      return { valid: false, reason: "native_signing_material_hash_mismatch" };
+    }
+    const signatureBytes = base64urlDecode(signature, "native signature");
+    const verified = crypto.verify(nativeSigningHashForSuite(suite), signingBytes, publicKey, signatureBytes);
+    if (!verified) {
+      return { valid: false, reason: "native_signature_invalid" };
+    }
+    if (!nativeSignedPublicKeyTrusted(verification, expectedPublicKeyRef, identityRef, receipt.agent_identity)) {
+      return { valid: false, reason: NATIVE_PUBLIC_KEY_NOT_TRUSTED_REASON, public_key_ref: expectedPublicKeyRef };
+    }
+    return {
+      valid: true,
+      verification_state: "verified_native_signature",
+      signature_suite: suite.id,
+      public_key_ref: expectedPublicKeyRef
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+function verifyNativeHybridReceiptProof(receipt, ceb, verification = null) {
+  try {
+    const proof = receipt.native_proof;
+    if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
+      return { valid: false, reason: "native_proof_missing" };
+    }
+    if (normalizeString(proof.method) !== XOONYA_NATIVE_HYBRID_METHOD) {
+      return { valid: false, reason: "native_proof_method_mismatch" };
+    }
+    const hybridSuite = parseNativeHybridSuite(proof.hybrid_suite);
+    if (!runtimeSupportsNativeHybridSuite(hybridSuite.id)) {
+      return { valid: false, reason: "native_hybrid_runtime_validator_unavailable" };
+    }
+    const identityRef = normalizeString(proof.identity_ref);
+    if (!identityRef) {
+      return { valid: false, reason: "native_identity_ref_missing" };
+    }
+    const classicalPublicKeyMaterial = proof.classical_public_key_material;
+    const pqPublicKeyMaterial = proof.pq_public_key_material;
+    if (!classicalPublicKeyMaterial || typeof classicalPublicKeyMaterial !== "object" || Array.isArray(classicalPublicKeyMaterial)) {
+      return { valid: false, reason: "native_hybrid_classical_public_key_material_missing" };
+    }
+    if (!pqPublicKeyMaterial || typeof pqPublicKeyMaterial !== "object" || Array.isArray(pqPublicKeyMaterial)) {
+      return { valid: false, reason: "native_hybrid_pq_public_key_material_missing" };
+    }
+    if (normalizeString(classicalPublicKeyMaterial.format) !== hybridSuite.classical_suite.public_key_format) {
+      return { valid: false, reason: "native_hybrid_classical_public_key_format_mismatch" };
+    }
+    if (normalizeString(pqPublicKeyMaterial.format) !== hybridSuite.pq_suite.public_key_format) {
+      return { valid: false, reason: "native_hybrid_pq_public_key_format_mismatch" };
+    }
+    const classicalPublicKeyPem = normalizePublicKeyPem(classicalPublicKeyMaterial.value);
+    const pqPublicKeyPem = normalizePublicKeyPem(pqPublicKeyMaterial.value);
+    const classicalPublicKey = crypto.createPublicKey(classicalPublicKeyPem);
+    const pqPublicKey = crypto.createPublicKey(pqPublicKeyPem);
+    assertNativeKeyMatchesSuite(classicalPublicKey, hybridSuite.classical_suite, "native hybrid classical public key");
+    assertNativeKeyMatchesSuite(pqPublicKey, hybridSuite.pq_suite, "native hybrid pq public key");
+    const expectedClassicalPublicKeyRef = nativePublicKeyRefFromPem(classicalPublicKeyPem, hybridSuite.classical_suite.id);
+    const expectedPqPublicKeyRef = nativePublicKeyRefFromPem(pqPublicKeyPem, hybridSuite.pq_suite.id);
+    const expectedHybridPublicKeyRef = nativeHybridPublicKeyRefFromPems(classicalPublicKeyPem, pqPublicKeyPem, hybridSuite.id);
+    if (normalizeString(proof.classical_public_key_ref) !== expectedClassicalPublicKeyRef) {
+      return { valid: false, reason: "native_hybrid_classical_public_key_ref_mismatch" };
+    }
+    if (normalizeString(proof.pq_public_key_ref) !== expectedPqPublicKeyRef) {
+      return { valid: false, reason: "native_hybrid_pq_public_key_ref_mismatch" };
+    }
+    if (normalizeString(proof.hybrid_public_key_ref) !== expectedHybridPublicKeyRef) {
+      return { valid: false, reason: "native_hybrid_public_key_ref_mismatch" };
+    }
+    const proofMaterial = proof.proof_material;
+    if (!proofMaterial || typeof proofMaterial !== "object" || Array.isArray(proofMaterial)) {
+      return { valid: false, reason: "native_proof_material_missing" };
+    }
+    const classicalSignature = normalizeString(proofMaterial.classical_signature);
+    const pqSignature = normalizeString(proofMaterial.pq_signature);
+    if (!classicalSignature) {
+      return { valid: false, reason: "native_hybrid_classical_signature_missing" };
+    }
+    if (!pqSignature) {
+      return { valid: false, reason: "native_hybrid_pq_signature_missing" };
+    }
+    const expectedCompactSignature = `${XOONYA_NATIVE_HYBRID_METHOD}:${hybridSuite.id}:${classicalSignature}.${pqSignature}`;
+    if (normalizeString(receipt.signature) !== expectedCompactSignature) {
+      return { valid: false, reason: "signature_native_hybrid_mismatch" };
+    }
+    const signingMaterial = buildNativeHybridProofMaterial(receipt, ceb, {
+      identity_ref: identityRef,
+      hybrid_suite: hybridSuite.id,
+      hybrid_public_key_ref: expectedHybridPublicKeyRef,
+      classical_public_key_ref: expectedClassicalPublicKeyRef,
+      pq_public_key_ref: expectedPqPublicKeyRef
+    });
+    const signingBytes = Buffer.from(canonicalize(signingMaterial), "utf8");
+    const expectedSigningHash = sha256Hex(signingBytes);
+    if (normalizeString(proofMaterial.signing_material_sha256).toLowerCase() !== expectedSigningHash) {
+      return { valid: false, reason: "native_hybrid_signing_material_hash_mismatch" };
+    }
+    const classicalSignatureBytes = base64urlDecode(classicalSignature, "native hybrid classical signature");
+    const pqSignatureBytes = base64urlDecode(pqSignature, "native hybrid pq signature");
+    if (!crypto.verify(nativeSigningHashForSuite(hybridSuite.classical_suite), signingBytes, classicalPublicKey, classicalSignatureBytes)) {
+      return { valid: false, reason: "native_hybrid_classical_signature_invalid" };
+    }
+    if (!crypto.verify(nativeSigningHashForSuite(hybridSuite.pq_suite), signingBytes, pqPublicKey, pqSignatureBytes)) {
+      return { valid: false, reason: "native_hybrid_pq_signature_invalid" };
+    }
+    const publicKeyRefs = {
+      classical: expectedClassicalPublicKeyRef,
+      pq: expectedPqPublicKeyRef,
+      hybrid: expectedHybridPublicKeyRef
+    };
+    if (!nativeHybridPublicKeyTrusted(verification, publicKeyRefs, identityRef, receipt.agent_identity)) {
+      return {
+        valid: false,
+        reason: NATIVE_HYBRID_PUBLIC_KEY_NOT_TRUSTED_REASON,
+        public_key_ref: expectedHybridPublicKeyRef,
+        classical_public_key_ref: expectedClassicalPublicKeyRef,
+        pq_public_key_ref: expectedPqPublicKeyRef
+      };
+    }
+    return {
+      valid: true,
+      verification_state: "verified_native_hybrid_signature",
+      signature_suite: hybridSuite.id,
+      public_key_ref: expectedHybridPublicKeyRef,
+      classical_public_key_ref: expectedClassicalPublicKeyRef,
+      pq_public_key_ref: expectedPqPublicKeyRef
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+function verifyNativeAnchoredReceiptProof(receipt, ceb, bundle) {
+  try {
+    const proof = receipt.native_proof;
+    if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
+      return { valid: false, reason: "native_proof_missing" };
+    }
+    if (normalizeString(proof.method) !== XOONYA_NATIVE_ANCHORED_METHOD) {
+      return { valid: false, reason: "native_proof_method_mismatch" };
+    }
+    if (normalizeString(proof.base_method) !== XOONYA_NATIVE_SHA256_METHOD) {
+      return { valid: false, reason: "native_anchor_base_method_unsupported" };
+    }
+    if (!bundle || !Array.isArray(bundle.anchors)) {
+      return { valid: false, reason: "native_anchor_bundle_missing" };
+    }
+    const proofAnchors = normalizeNativeAnchorRefs(proof.anchor_refs);
+    const bundleAnchors = normalizeNativeAnchorRefs(bundle.anchors);
+    if (canonicalize(proofAnchors) !== canonicalize(bundleAnchors)) {
+      return { valid: false, reason: "native_anchor_bundle_mismatch" };
+    }
+    const proofMaterial = proof.proof_material;
+    if (!proofMaterial || typeof proofMaterial !== "object" || Array.isArray(proofMaterial)) {
+      return { valid: false, reason: "native_anchor_proof_material_missing" };
+    }
+    const expectedAnchorRoot = canonicalJsonSha256Hex(proofAnchors);
+    if (normalizeString(proofMaterial.anchor_root_sha256).toLowerCase() !== expectedAnchorRoot) {
+      return { valid: false, reason: "native_anchor_root_mismatch" };
+    }
+    const bindingMaterial = buildNativeAnchorBindingMaterial(receipt, ceb, proofAnchors);
+    const bindingHash = sha256Hex(Buffer.from(canonicalize(bindingMaterial), "utf8"));
+    if (normalizeString(proofMaterial.binding_material_sha256).toLowerCase() !== bindingHash) {
+      return { valid: false, reason: "native_anchor_binding_hash_mismatch" };
+    }
+    if (normalizeString(receipt.signature) !== `${XOONYA_NATIVE_ANCHORED_METHOD}:${bindingHash}`) {
+      return { valid: false, reason: "signature_native_anchored_mismatch" };
+    }
+    return {
+      valid: true,
+      verification_state: "verified_native_anchor_binding",
+      anchor_count: proofAnchors.length,
+      anchor_root_sha256: expectedAnchorRoot
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Receipt method dispatch and proof bundle verification
+// ---------------------------------------------------------------------------
+
+function verifyReceiptProofMethod(receipt, ceb, bundle, options = {}) {
+  const verification = options && options.__resolved_verification_options === true
+    ? options
+    : resolveProofVerificationOptions(options);
+  const algorithm = normalizeString(receipt.algorithm);
+  return finalizeProofMethodVerification(
+    verifyReceiptProofMethodInner(receipt, ceb, bundle, algorithm, verification),
+    algorithm,
+    verification
+  );
+}
+
+function verifyReceiptProofMethodInner(receipt, ceb, bundle, algorithm, verification) {
+  if (!algorithm) {
+    return { valid: false, reason: "verification_method_missing" };
+  }
+  if (algorithm === VERIFICATION_METHOD_NONE) {
+    return { valid: false, reason: "verification_method_none" };
+  }
+  if (algorithm === XOONYA_NATIVE_HYBRID_METHOD) {
+    const hybridVerification = verifyNativeHybridReceiptProof(receipt, ceb, verification);
+    if (!hybridVerification.valid) {
+      return { valid: false, reason: hybridVerification.reason };
+    }
+    return {
+      valid: true,
+      method: { ...NATIVE_HYBRID_METHOD_DESCRIPTOR },
+      verification_state: hybridVerification.verification_state,
+      signature_suite: hybridVerification.signature_suite,
+      public_key_ref: hybridVerification.public_key_ref,
+      classical_public_key_ref: hybridVerification.classical_public_key_ref,
+      pq_public_key_ref: hybridVerification.pq_public_key_ref
+    };
+  }
+
+  const method = PROOF_VERIFICATION_METHODS[algorithm];
+  if (!method) {
+    return { valid: false, reason: "verification_method_unsupported" };
+  }
+
+  const legacyReceipt = receipt.compatibility && receipt.compatibility.legacy_receipt;
+  if (legacyReceipt && algorithm !== LEGACY_OPRETURN_METHOD) {
+    return { valid: false, reason: "legacy_receipt_method_mismatch" };
+  }
+
+  if (algorithm === LEGACY_OPRETURN_METHOD) {
+    if (!legacyReceipt) {
+      return { valid: false, reason: "legacy_receipt_missing" };
+    }
+    const legacyVerification = verifyReceipt(
+      legacyReceipt.opreturn_hex,
+      Buffer.from(canonicalize(ceb), "utf8")
+    );
+    if (!legacyVerification.valid) {
+      return { valid: false, reason: `legacy_receipt_${legacyVerification.reason}` };
+    }
+    if (normalizeString(legacyReceipt.agent_id).toLowerCase() !== normalizeString(legacyVerification.agent_id).toLowerCase()) {
+      return { valid: false, reason: "legacy_agent_id_mismatch" };
+    }
+    if (normalizeString(receipt.signature).toLowerCase() !== normalizeString(legacyReceipt.opreturn_hex).toLowerCase()) {
+      return { valid: false, reason: "signature_legacy_mismatch" };
+    }
+    return {
+      valid: true,
+      method,
+      verification_state: "verified_legacy_opreturn"
+    };
+  }
+
+  if (algorithm === XOONYA_NATIVE_SHA256_METHOD) {
+    const expectedSignature = expectedNativeDigestSignature(receipt, ceb);
+    if (normalizeString(receipt.signature) !== expectedSignature) {
+      return { valid: false, reason: "signature_native_mismatch" };
+    }
+    return {
+      valid: true,
+      method,
+      verification_state: "verified_native_digest"
+    };
+  }
+
+  if (algorithm === XOONYA_NATIVE_SIGNED_METHOD) {
+    const signedVerification = verifyNativeSignedReceiptProof(receipt, ceb, verification);
+    if (!signedVerification.valid) {
+      return { valid: false, reason: signedVerification.reason };
+    }
+    return {
+      valid: true,
+      method,
+      verification_state: signedVerification.verification_state,
+      signature_suite: signedVerification.signature_suite,
+      public_key_ref: signedVerification.public_key_ref
+    };
+  }
+
+  if (algorithm === XOONYA_NATIVE_ANCHORED_METHOD) {
+    const anchoredVerification = verifyNativeAnchoredReceiptProof(receipt, ceb, bundle);
+    if (!anchoredVerification.valid) {
+      return { valid: false, reason: anchoredVerification.reason };
+    }
+    return {
+      valid: true,
+      method,
+      verification_state: anchoredVerification.verification_state,
+      anchor_count: anchoredVerification.anchor_count,
+      anchor_root_sha256: anchoredVerification.anchor_root_sha256
+    };
+  }
+
+  if (isExternalAssertionMethod(algorithm)) {
+    const signature = normalizeString(receipt.signature);
+    if (
+      signature.startsWith(`${XOONYA_NATIVE_SHA256_METHOD}:`) ||
+      signature.startsWith(`${XOONYA_NATIVE_SIGNED_METHOD}:`) ||
+      signature.startsWith(`${XOONYA_NATIVE_ANCHORED_METHOD}:`) ||
+      signature.startsWith(`${XOONYA_NATIVE_HYBRID_METHOD}:`)
+    ) {
+      return { valid: false, reason: "signature_method_mismatch" };
+    }
+    return {
+      valid: true,
+      method,
+      verification_state: algorithm === DETACHED_ASSERTION_METHOD
+        ? "accepted_detached_assertion"
+        : "accepted_external_proof_envelope"
+    };
+  }
+
+  return { valid: false, reason: "verification_method_unsupported" };
+}
+
+function verifyProofBundle(bundle, options = {}) {
+  const verification = resolveProofVerificationOptions(options);
+  const result = verifyProofBundleInner(bundle, verification);
+  const algorithm = bundle && bundle.receipt && typeof bundle.receipt === "object" && !Array.isArray(bundle.receipt)
+    ? bundle.receipt.algorithm
+    : null;
+  return {
+    ...result,
+    cryptographically_verified: result.cryptographically_verified === true,
+    verification_class: result.verification_class !== undefined ? result.verification_class : verificationClassForMethod(algorithm),
+    strict: verification.strict,
+    trust_root_applied: verification.trust_root_applied
+  };
+}
+
+function verifyProofBundleInner(bundle, verification) {
+  try {
+    if (!bundle || typeof bundle !== "object" || Array.isArray(bundle)) {
+      return { valid: false, reason: "bundle_not_object" };
+    }
+    if (normalizeString(bundle.version) !== PROOF_BUNDLE_VERSION) {
+      return { valid: false, reason: "bad_bundle_version" };
+    }
+    const ceb = canonicalizeEvent(bundle.ceb);
+    const receipt = bundle.receipt;
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+      return { valid: false, reason: "receipt_not_object" };
+    }
+    if (normalizeString(receipt.version) !== CANONICAL_RECEIPT_VERSION) {
+      return { valid: false, reason: "bad_receipt_version" };
+    }
+    if (normalizeString(receipt.domain_id) !== ceb.domain_id) {
+      return { valid: false, reason: "receipt_domain_mismatch" };
+    }
+    if (normalizeString(receipt.sequence) !== ceb.sequence) {
+      return { valid: false, reason: "receipt_sequence_mismatch" };
+    }
+    const expectedCommitment = hashEvent(ceb);
+    if (normalizeString(receipt.event_commitment).toLowerCase() !== expectedCommitment) {
+      return { valid: false, reason: "event_commitment_mismatch" };
+    }
+    const expectedReceiptId = sha256Hex(Buffer.from(
+      canonicalize({
+        agent_identity: normalizeString(receipt.agent_identity),
+        domain_id: ceb.domain_id,
+        event_commitment: expectedCommitment,
+        sequence: ceb.sequence,
+        version: CANONICAL_RECEIPT_VERSION
+      }),
+      "utf8"
+    ));
+    if (normalizeString(receipt.receipt_id).toLowerCase() !== expectedReceiptId) {
+      return { valid: false, reason: "receipt_id_mismatch" };
+    }
+    if (!normalizeString(receipt.agent_identity)) {
+      return { valid: false, reason: "agent_identity_missing" };
+    }
+    if (!normalizeString(receipt.signature)) {
+      return { valid: false, reason: "signature_missing" };
+    }
+
+    const methodVerification = verifyReceiptProofMethod(receipt, ceb, bundle, verification);
+    if (!methodVerification.valid) {
+      return {
+        valid: false,
+        reason: methodVerification.reason,
+        verification_class: methodVerification.verification_class,
+        cryptographically_verified: false
+      };
+    }
+
+    return {
+      valid: true,
+      reason: null,
+      version: PROOF_BUNDLE_VERSION,
+      event_commitment: expectedCommitment,
+      receipt_id: expectedReceiptId,
+      verification_method: methodVerification.method.id,
+      verification_method_family: methodVerification.method.family,
+      verification_state: methodVerification.verification_state,
+      ...(methodVerification.anchor_count != null ? { anchor_count: methodVerification.anchor_count } : {}),
+      ...(methodVerification.anchor_root_sha256 ? { anchor_root_sha256: methodVerification.anchor_root_sha256 } : {}),
+      ...(methodVerification.signature_suite ? { signature_suite: methodVerification.signature_suite } : {}),
+      ...(methodVerification.public_key_ref ? { public_key_ref: methodVerification.public_key_ref } : {}),
+      ...(methodVerification.classical_public_key_ref ? { classical_public_key_ref: methodVerification.classical_public_key_ref } : {}),
+      ...(methodVerification.pq_public_key_ref ? { pq_public_key_ref: methodVerification.pq_public_key_ref } : {}),
+      verification_class: methodVerification.verification_class,
+      cryptographically_verified: methodVerification.cryptographically_verified === true
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+// Verify a receipt plus the canonical event it commits to, without a bundle
+// wrapper. `anchors` is required for the anchored method.
+function verifyNativeProof(input, options = {}) {
+  const source = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const anchors = Array.isArray(source.anchors) ? source.anchors : undefined;
+  return verifyProofBundle({
+    version: PROOF_BUNDLE_VERSION,
+    ceb: source.ceb || source.event,
+    receipt: source.receipt,
+    anchors
+  }, options);
+}
+
+// ---------------------------------------------------------------------------
+// Compatibility OP_RETURN receipts (PRFT) and proof envelopes
+// ---------------------------------------------------------------------------
+
+function parseReceipt(opreturnHex) {
+  const hex = String(opreturnHex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(hex)) {
+    throw new Error("opreturnHex must be hex");
+  }
+  if (hex.length !== 116 && hex.length !== 140) {
+    throw new Error("opreturnHex must be a supported v1 or v2 receipt");
+  }
+  const magic = hex.slice(0, 8);
+  const version = hex.slice(8, 10);
+  const recordType = hex.slice(10, 12);
+  const agentId = hex.slice(12, 52);
+  const payloadHash = hex.slice(52, 116);
+  if (magic !== MAGIC_HEX) {
+    throw new Error("opreturnHex has bad receipt magic");
+  }
+  if (!VALID_TYPES.has(recordType)) {
+    throw new Error("opreturnHex has unsupported record type");
+  }
+  if (version === VERSION_V1_HEX && hex.length === 116) {
+    return {
+      spec_version: "v1",
+      record_type_hex: recordType,
+      agent_id: agentId,
+      payload_hash_sha256: payloadHash,
+      receipt_hash_sha256: sha256Hex(Buffer.from(hex, "hex")),
+      opreturn_hex: hex
+    };
+  }
+  if (version === VERSION_V2_HEX && hex.length === 140) {
+    return {
+      spec_version: "v2",
+      record_type_hex: recordType,
+      agent_id: agentId,
+      payload_hash_sha256: payloadHash,
+      context_hash12: hex.slice(116, 140),
+      receipt_hash_sha256: sha256Hex(Buffer.from(hex, "hex")),
+      opreturn_hex: hex
+    };
+  }
+  throw new Error("opreturnHex/version length mismatch");
+}
+
+function verifyReceipt(opreturnHex, payloadBytes) {
+  const hex = String(opreturnHex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(hex)) {
+    return { valid: false, reason: "non_hex", spec_version: "v1", compliance_hash: null };
+  }
+  if (hex.length !== 116) {
+    return { valid: false, reason: "invalid_length", spec_version: "v1", compliance_hash: null };
+  }
+  const magic = hex.slice(0, 8);
+  const version = hex.slice(8, 10);
+  const type = hex.slice(10, 12);
+  const agentId = hex.slice(12, 52);
+  const payloadHash = hex.slice(52, 116);
+  if (magic !== MAGIC_HEX) return { valid: false, reason: "bad_magic", spec_version: "v1", compliance_hash: null };
+  if (version !== VERSION_V1_HEX) return { valid: false, reason: "bad_version", spec_version: "v1", compliance_hash: null };
+  if (!VALID_TYPES.has(type)) return { valid: false, reason: "bad_type", spec_version: "v1", compliance_hash: null };
+  const expectedPayload = payloadBytes && payloadBytes.length
+    ? sha256Hex(Buffer.from(payloadBytes))
+    : ZERO_HASH32;
+  if (expectedPayload !== payloadHash) {
+    return { valid: false, reason: "payload_mismatch", spec_version: "v1", compliance_hash: null };
+  }
+  return {
+    valid: true,
+    reason: null,
+    spec_version: "v1",
+    compliance_hash: sha256Hex(Buffer.from(hex, "hex")),
+    agent_id: agentId
+  };
+}
+
+function verifyReceiptV2(opreturnHex, payloadBytes) {
+  const hex = String(opreturnHex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(hex)) {
+    return { valid: false, reason: "non_hex", spec_version: "v2", compliance_hash: null };
+  }
+  if (hex.length !== 140) {
+    return { valid: false, reason: "invalid_length", spec_version: "v2", compliance_hash: null };
+  }
+  const magic = hex.slice(0, 8);
+  const version = hex.slice(8, 10);
+  const type = hex.slice(10, 12);
+  const agentId = hex.slice(12, 52);
+  const payloadHash = hex.slice(52, 116);
+  const contextHash12 = hex.slice(116, 140);
+  if (magic !== MAGIC_HEX) return { valid: false, reason: "bad_magic", spec_version: "v2", compliance_hash: null };
+  if (version !== VERSION_V2_HEX) return { valid: false, reason: "bad_version", spec_version: "v2", compliance_hash: null };
+  if (!VALID_TYPES.has(type)) return { valid: false, reason: "bad_type", spec_version: "v2", compliance_hash: null };
+  if (contextHash12 === ZERO_CONTEXT12) return { valid: false, reason: "context_zero_forbidden", spec_version: "v2", compliance_hash: null };
+  const expectedPayload = payloadBytes && payloadBytes.length
+    ? sha256Hex(Buffer.from(payloadBytes))
+    : ZERO_HASH32;
+  if (expectedPayload !== payloadHash) {
+    return { valid: false, reason: "payload_mismatch", spec_version: "v2", compliance_hash: null };
+  }
+  return {
+    valid: true,
+    reason: null,
+    spec_version: "v2",
+    compliance_hash: sha256Hex(Buffer.from(hex, "hex")),
+    agent_id: agentId,
+    context_hash12: contextHash12
+  };
+}
+
+function normalizeProofEntry(proof, index) {
+  if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
+    throw new Error(`proofs[${index}] must be an object`);
+  }
+  const normalized = {
+    proof_id: String(proof.proof_id || "").trim(),
+    proof_type: String(proof.proof_type || "").trim(),
+    role: String(proof.role || "").trim(),
+    media_type: String(proof.media_type || "").trim(),
+    proof_hash_sha256: assertHex(proof.proof_hash_sha256, 64, `proofs[${index}].proof_hash_sha256`),
+    locator: String(proof.locator || "").trim()
+  };
+  if (!normalized.proof_id) throw new Error(`proofs[${index}].proof_id required`);
+  if (!normalized.proof_type) throw new Error(`proofs[${index}].proof_type required`);
+  if (!normalized.role) throw new Error(`proofs[${index}].role required`);
+  if (!normalized.media_type) throw new Error(`proofs[${index}].media_type required`);
+  if (!normalized.locator) throw new Error(`proofs[${index}].locator required`);
+  return normalized;
+}
+
+function makeProofEnvelopeBindingMaterial(receiptRef, proofs) {
+  return {
+    envelope_version: PROOF_ENVELOPE_VERSION,
+    payload_hash_sha256: receiptRef.payload_hash_sha256,
+    proofs: proofs.map((proof) => ({
+      locator: proof.locator,
+      media_type: proof.media_type,
+      proof_hash_sha256: proof.proof_hash_sha256,
+      proof_id: proof.proof_id,
+      proof_type: proof.proof_type,
+      role: proof.role
+    })),
+    receipt_hash_sha256: receiptRef.receipt_hash_sha256
+  };
+}
+
+function verifyProofEnvelopeV1(envelope) {
+  try {
+    if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+      return { valid: false, reason: "envelope_not_object" };
+    }
+    if (envelope.envelope_version !== PROOF_ENVELOPE_VERSION) {
+      return { valid: false, reason: "bad_envelope_version" };
+    }
+    const receiptRef = parseReceipt(envelope.receipt_ref && envelope.receipt_ref.opreturn_hex);
+    if (String((envelope.receipt_ref && envelope.receipt_ref.spec_version) || "") !== receiptRef.spec_version) {
+      return { valid: false, reason: "receipt_spec_version_mismatch" };
+    }
+    if (String((envelope.receipt_ref && envelope.receipt_ref.receipt_hash_sha256) || "").toLowerCase() !== receiptRef.receipt_hash_sha256) {
+      return { valid: false, reason: "receipt_hash_mismatch" };
+    }
+    if (String((envelope.receipt_ref && envelope.receipt_ref.payload_hash_sha256) || "").toLowerCase() !== receiptRef.payload_hash_sha256) {
+      return { valid: false, reason: "payload_hash_mismatch" };
+    }
+    const proofs = Array.isArray(envelope.proofs) ? envelope.proofs.map(normalizeProofEntry) : [];
+    if (proofs.length === 0) return { valid: false, reason: "proofs_empty" };
+    const proofIds = new Set();
+    for (const proof of proofs) {
+      if (proofIds.has(proof.proof_id)) return { valid: false, reason: "proof_duplicate_id" };
+      proofIds.add(proof.proof_id);
+    }
+    const expectedBindingHash = canonicalJsonSha256Hex(makeProofEnvelopeBindingMaterial(receiptRef, proofs));
+    if (String(envelope.binding_hash_sha256 || "").toLowerCase() !== expectedBindingHash) {
+      return { valid: false, reason: "binding_hash_mismatch" };
+    }
+    return {
+      valid: true,
+      reason: null,
+      envelope_version: PROOF_ENVELOPE_VERSION,
+      binding_hash_sha256: expectedBindingHash
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// XNYA native atoms
+// ---------------------------------------------------------------------------
+
+function atomValidationError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function normalizexoonyaNativeIdentityMaterial(identityMaterialHex) {
+  const materialHex = assertVariableHex(identityMaterialHex, "identityMaterialHex");
+  const typePrefix = materialHex.slice(0, 2);
+  if (!XOONYA_NATIVE_IDENTITY_TYPES[typePrefix]) {
+    throw atomValidationError(
+      XNYA_NATIVE_ATOM_ERROR_CODES.IDENTITY_UNSUPPORTED_TYPE_PREFIX,
+      "identityMaterialHex has unsupported identity type prefix"
+    );
+  }
+  if (materialHex.length === 2) {
+    throw atomValidationError(
+      XNYA_NATIVE_ATOM_ERROR_CODES.IDENTITY_MISSING_RAW_BYTES,
+      "identityMaterialHex must include raw identity bytes"
+    );
+  }
+  return materialHex;
+}
+
+function hashxoonyaNativePayload(payloadBytes, domainSeparator) {
+  if (!payloadBytes || payloadBytes.length === 0) {
+    return ZERO_HASH32;
+  }
+  const digest = sha256Hex(Buffer.concat([
+    Buffer.from(domainSeparator, "utf8"),
+    Buffer.from(payloadBytes)
+  ]));
+  if (digest === ZERO_HASH32) {
+    throw new Error("payload hash cannot equal the absent-payload sentinel");
+  }
+  return digest;
+}
+
+function parsexoonyaNativeAtom(atomHex) {
+  const hex = String(atomHex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(hex)) {
+    throw atomValidationError(XNYA_NATIVE_ATOM_ERROR_CODES.ATOM_HEX_NOT_HEX, "atomHex must be hex");
+  }
+  if (hex.length !== 116 && hex.length !== 140) {
+    throw atomValidationError(
+      XNYA_NATIVE_ATOM_ERROR_CODES.ATOM_UNSUPPORTED_LENGTH,
+      "atomHex must be a supported xoonya native atom"
+    );
+  }
+  const magic = hex.slice(0, 8);
+  const version = hex.slice(8, 10);
+  const recordType = hex.slice(10, 12);
+  if (magic !== XOONYA_NATIVE_ATOM_MAGIC_HEX.toLowerCase()) {
+    throw atomValidationError(
+      XNYA_NATIVE_ATOM_ERROR_CODES.ATOM_BAD_MAGIC,
+      "atomHex has bad xoonya native atom magic"
+    );
+  }
+  if (!VALID_TYPES.has(recordType)) {
+    throw atomValidationError(
+      XNYA_NATIVE_ATOM_ERROR_CODES.ATOM_UNSUPPORTED_RECORD_TYPE,
+      "atomHex has unsupported record type"
+    );
+  }
+  if (version === VERSION_V1_HEX && hex.length === 116) {
+    const agentId = hex.slice(12, 52);
+    const payloadHash = hex.slice(52, 116);
+    return {
+      atom_version: XOONYA_NATIVE_ATOM_V1,
+      spec_version: "v1",
+      byte_length: 58,
+      record_type_hex: recordType,
+      agent_id: agentId,
+      payload_hash_sha256: payloadHash,
+      atom_hash_sha256: sha256Hex(Buffer.from(hex, "hex")),
+      atom_hex: hex
+    };
+  }
+  if (version === VERSION_V2_HEX && hex.length === 140) {
+    const agentId = hex.slice(12, 76);
+    const payloadHash = hex.slice(76, 140);
+    return {
+      atom_version: XOONYA_NATIVE_ATOM_V2,
+      spec_version: "v2",
+      byte_length: 70,
+      record_type_hex: recordType,
+      agent_id: agentId,
+      payload_hash_sha256: payloadHash,
+      atom_hash_sha256: sha256Hex(Buffer.from(hex, "hex")),
+      atom_hex: hex
+    };
+  }
+  throw atomValidationError(
+    XNYA_NATIVE_ATOM_ERROR_CODES.ATOM_VERSION_LENGTH_MISMATCH,
+    "atomHex/version length mismatch"
+  );
+}
+
+function verifyxoonyaNativeAtom(atomHex, options = {}) {
+  try {
+    const parsed = parsexoonyaNativeAtom(atomHex);
+    const hasIdentityMaterial = options.identity_material_hex != null;
+    if (hasIdentityMaterial) {
+      const materialHex = normalizexoonyaNativeIdentityMaterial(options.identity_material_hex);
+      const expectedAgentId = parsed.spec_version === "v1"
+        ? hash160Hex(Buffer.concat([Buffer.from(XNYA_DS_AGENT_V1, "utf8"), Buffer.from(materialHex, "hex")]))
+        : sha256Hex(Buffer.concat([Buffer.from(XNYA_DS_AGENT_V2, "utf8"), Buffer.from(materialHex, "hex")]));
+      if (parsed.agent_id !== expectedAgentId) {
+        return {
+          valid: false,
+          reason: "agent_id_mismatch",
+          error_code: XNYA_NATIVE_ATOM_ERROR_CODES.AGENT_ID_MISMATCH,
+          ...parsed
+        };
+      }
+    }
+
+    const hasPayload = options.payload_bytes != null;
+    if (hasPayload) {
+      const payloadHash = parsed.spec_version === "v1"
+        ? hashxoonyaNativePayload(options.payload_bytes, XNYA_DS_PAYLOAD_V1)
+        : hashxoonyaNativePayload(options.payload_bytes, XNYA_DS_PAYLOAD_V2);
+      if (payloadHash !== parsed.payload_hash_sha256) {
+        return {
+          valid: false,
+          reason: "payload_hash_mismatch",
+          error_code: XNYA_NATIVE_ATOM_ERROR_CODES.PAYLOAD_HASH_MISMATCH,
+          ...parsed
+        };
+      }
+    } else if (parsed.payload_hash_sha256 === ZERO_HASH32) {
+      return { valid: true, reason: null, error_code: null, payload_state: "absent", ...parsed };
+    }
+
+    return {
+      valid: true,
+      reason: null,
+      error_code: null,
+      payload_state: parsed.payload_hash_sha256 === ZERO_HASH32 ? "absent" : "committed",
+      ...parsed
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message, error_code: error.code || "native_atom_validation_error" };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// XNYP payload profile (parse/verify) and XNYA line-rate frame
+// ---------------------------------------------------------------------------
+
+const XNYA_PAYLOAD_FIELD_TYPES = Object.freeze({
+  bytes32: Object.freeze({ id: 1, fixed_length: 32 }),
+  bytes20: Object.freeze({ id: 2, fixed_length: 20 }),
+  uint64: Object.freeze({ id: 3, fixed_length: 8 }),
+  utf8: Object.freeze({ id: 4, max_length: 1024 }),
+  bool: Object.freeze({ id: 5, fixed_length: 1 })
+});
+const XNYA_PAYLOAD_FIELD_TYPE_BY_ID = Object.freeze(
+  Object.fromEntries(Object.entries(XNYA_PAYLOAD_FIELD_TYPES).map(([name, spec]) => [spec.id, { name, ...spec }]))
+);
+
+function parsexoonyaNativePayloadProfileV1(canonicalBytesHex) {
+  const hex = assertVariableHex(canonicalBytesHex, "payload profile canonical bytes");
+  const buf = Buffer.from(hex, "hex");
+  if (buf.length < 38) {
+    throw new Error("payload profile bytes too short");
+  }
+  if (buf.subarray(0, 4).toString("ascii") !== "XNYP") {
+    throw new Error("payload profile magic mismatch");
+  }
+  if (buf[4] !== 1) {
+    throw new Error("payload profile version unsupported");
+  }
+  const schemaHash = buf.subarray(5, 37).toString("hex");
+  const fieldCount = buf[37];
+  if (fieldCount === 0 || fieldCount > 64) {
+    throw new Error("payload profile field count unsupported");
+  }
+  let offset = 38;
+  const fields = [];
+  const seen = new Set();
+  for (let i = 0; i < fieldCount; i += 1) {
+    if (offset + 5 > buf.length) {
+      throw new Error("payload profile truncated field header");
+    }
+    const fieldId = buf.readUInt16BE(offset);
+    const fieldTypeId = buf[offset + 2];
+    const length = buf.readUInt16BE(offset + 3);
+    offset += 5;
+    if (offset + length > buf.length) {
+      throw new Error("payload profile truncated field value");
+    }
+    const typeSpec = XNYA_PAYLOAD_FIELD_TYPE_BY_ID[fieldTypeId];
+    if (!typeSpec) {
+      throw new Error("payload profile field type unsupported");
+    }
+    const value = buf.subarray(offset, offset + length);
+    offset += length;
+    if (typeSpec.fixed_length && value.length !== typeSpec.fixed_length) {
+      throw new Error("payload profile fixed field length mismatch");
+    }
+    if (typeSpec.max_length && (value.length === 0 || value.length > typeSpec.max_length)) {
+      throw new Error("payload profile variable field length mismatch");
+    }
+    if (typeSpec.name === "bool" && value[0] !== 0 && value[0] !== 1) {
+      throw new Error("payload profile bool value invalid");
+    }
+    const key = `${fieldId}:${fieldTypeId}`;
+    if (seen.has(key)) {
+      throw new Error("payload profile duplicate field id/type");
+    }
+    seen.add(key);
+    fields.push({
+      field_id: fieldId,
+      field_type: typeSpec.name,
+      field_type_id: fieldTypeId,
+      value_hex: value.toString("hex"),
+      ...(typeSpec.name === "uint64" ? { value: readUInt64String(value) } : {}),
+      ...(typeSpec.name === "bool" ? { value: value[0] === 1 } : {})
+    });
+  }
+  if (offset !== buf.length) {
+    throw new Error("payload profile trailing bytes");
+  }
+  const sorted = fields.slice().sort((a, b) => a.field_id - b.field_id || a.field_type_id - b.field_type_id);
+  if (canonicalize(fields) !== canonicalize(sorted)) {
+    throw new Error("payload profile fields not canonical order");
+  }
+  return {
+    profile: XOONYA_NATIVE_PAYLOAD_PROFILE_V1,
+    version: 1,
+    schema_hash_sha256: schemaHash,
+    field_count: fieldCount,
+    fields,
+    canonical_bytes_hex: hex,
+    payload_hash_sha256: sha256Hex(Buffer.concat([
+      Buffer.from(XNYA_DS_PAYLOAD_PROFILE_V1, "utf8"),
+      buf
+    ]))
+  };
+}
+
+function verifyxoonyaNativePayloadProfileV1(canonicalBytesHex, options = {}) {
+  try {
+    const parsed = parsexoonyaNativePayloadProfileV1(canonicalBytesHex);
+    const expectedHash = normalizeString(options.payload_hash_sha256 || options.expected_payload_hash_sha256).toLowerCase();
+    if (expectedHash && expectedHash !== parsed.payload_hash_sha256) {
+      return { valid: false, reason: "payload_profile_hash_mismatch", parsed };
+    }
+    const schemaRef = normalizeString(options.schema_ref || options.schemaRef);
+    if (schemaRef) {
+      const expectedSchemaHash = sha256Hex(Buffer.from(`xoonya:payload-schema:v1:${schemaRef}`, "utf8"));
+      if (expectedSchemaHash !== parsed.schema_hash_sha256) {
+        return { valid: false, reason: "payload_profile_schema_mismatch", parsed };
+      }
+    }
+    const allowedFieldIds = Array.isArray(options.allowed_field_ids)
+      ? options.allowed_field_ids.map((entry) => Number(entry))
+      : null;
+    if (allowedFieldIds) {
+      const allowed = new Set(allowedFieldIds);
+      if (parsed.fields.some((field) => !allowed.has(field.field_id))) {
+        return { valid: false, reason: "payload_profile_unknown_field", parsed };
+      }
+    }
+    return { valid: true, parsed };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+function lineRateFrameChecksum(atomBytes) {
+  return sha256Hex(Buffer.concat([
+    Buffer.from(XNYA_DS_LINE_RATE_FRAME_V1, "utf8"),
+    atomBytes
+  ])).slice(0, 4);
+}
+
+function parsexoonyaNativeLineRateFrameV1(frameHex) {
+  const hex = assertVariableHex(frameHex, "line-rate frame");
+  const byteLength = hex.length / 2;
+  if (![60, 72].includes(byteLength)) {
+    throw new Error("line-rate frame unsupported length");
+  }
+  const atomHex = hex.slice(0, -4);
+  const checksumHex = hex.slice(-4);
+  const parsedAtom = parsexoonyaNativeAtom(atomHex);
+  const expectedChecksum = lineRateFrameChecksum(Buffer.from(parsedAtom.atom_hex, "hex"));
+  return {
+    profile: XOONYA_NATIVE_LINE_RATE_FRAME_V1,
+    frame_hex: hex,
+    atom_hex: parsedAtom.atom_hex,
+    atom_version: parsedAtom.atom_version,
+    atom_byte_length: parsedAtom.byte_length,
+    frame_byte_length: byteLength,
+    checksum_hex: checksumHex,
+    expected_checksum_hex: expectedChecksum,
+    checksum_valid: checksumHex === expectedChecksum
+  };
+}
+
+function verifyxoonyaNativeLineRateFrameV1(frameHex, options = {}) {
+  try {
+    const parsedFrame = parsexoonyaNativeLineRateFrameV1(frameHex);
+    if (!parsedFrame.checksum_valid) {
+      return { valid: false, reason: "line_rate_frame_checksum_mismatch", parsed_frame: parsedFrame };
+    }
+    const atomVerification = verifyxoonyaNativeAtom(parsedFrame.atom_hex, options);
+    if (!atomVerification.valid) {
+      return { valid: false, reason: `line_rate_frame_atom_${atomVerification.reason}`, parsed_frame: parsedFrame, atom_verification: atomVerification };
+    }
+    return {
+      valid: true,
+      parsed_frame: parsedFrame,
+      atom_verification: atomVerification
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+module.exports = {
+  // constants
+  CANONICAL_EVENT_BUNDLE_VERSION,
+  CANONICAL_RECEIPT_VERSION,
+  PROOF_BUNDLE_VERSION,
+  XOONYA_NATIVE_PROOF_FORMAT_VERSION,
+  XOONYA_NATIVE_SHA256_METHOD,
+  XOONYA_NATIVE_SIGNED_METHOD,
+  XOONYA_NATIVE_ANCHORED_METHOD,
+  XOONYA_NATIVE_HYBRID_METHOD,
+  XNYA_NATIVE_ATOM_ERROR_CODES,
+  PROOF_VERIFICATION_STRICT_REJECTION_CODES,
+  PROOF_VERIFICATION_TRUST_ROOT_REJECTION_CODES,
+  // canonicalization
+  canonicalize,
+  canonicalJsonSha256Hex,
+  canonicalizeEvent,
+  hashEvent,
+  // registries
+  listProofVerificationMethods,
+  getProofVerificationMethod,
+  listProofVerificationClasses,
+  listNativeSignatureSuites,
+  getNativeSignatureSuite,
+  listImplementedNativeHybridSuites,
+  listxoonyaNativeIdentityTypes,
+  getxoonyaNativeIdentityType,
+  runtimeSupportsNativeHybridSuite,
+  nativePublicKeyRefFromPem,
+  nativeHybridPublicKeyRefFromPems,
+  // proof bundle verification
+  verifyProofBundle,
+  verifyNativeBundle: verifyProofBundle,
+  verifyNativeProof,
+  verifyReceiptProofMethod,
+  // compatibility receipts and envelopes
+  parseReceipt,
+  verifyReceipt,
+  verifyReceiptV2,
+  verifyProofEnvelopeV1,
+  // XNYA atoms, payload profiles, line-rate frames
+  parsexoonyaNativeAtom,
+  verifyxoonyaNativeAtom,
+  parsexoonyaNativePayloadProfileV1,
+  verifyxoonyaNativePayloadProfileV1,
+  parsexoonyaNativeLineRateFrameV1,
+  verifyxoonyaNativeLineRateFrameV1
+};