xoonya 3.0.1 → 3.1.1

package/.env.example

@@ -1,2 +1,10 @@
 XOONYA_HOST=127.0.0.1
 XOONYA_PORT=4310
+# Set to 1 to make every proof-bundle verification strict: only cryptographically verified
+# (native signed / native hybrid) results are valid; digest and structural results are rejected.
+# XOONYA_STRICT_VERIFY=1
+# Whether POST /v1/receipts/emit, /v1/proof-bundles/build, and the proof-center run routes may
+# receive private key material (private_key_pem, classical_private_key_pem, pq_private_key_pem).
+# Unset = accepted locally, rejected when RENDER is set. Set to false on any shared deployment
+# and sign locally with the xoonya SDK or CLI instead.
+# XOONYA_ACCEPT_PRIVATE_KEY_MATERIAL=false

package/README.md

@@ -14,6 +14,29 @@ This repo is the proof-side half of the final two-repo public stack. It focuses
 
 The 10-phase public program is now complete. `xoonya` is in terminal closeout posture rather than active milestone build posture.
 
+## Public Discovery
+
+The broader stack now has a canonical human front door and a canonical machine doorway:
+
+- https://www.naxytra.com/agents
+- https://www.naxytra.com/v1/agent-discovery-index
+- https://www.naxytra.com/v1/agent-discovery-index/summary
+- https://www.naxytra.com/.well-known/agent.json
+
+Use the human page when you want the shortest adoption landing page, and use the machine endpoints when a registry, crawler, or agent needs a stable public discovery surface.
+
+The shared control-plane contract documents are:
+
+- [OPERATIONAL_RECEIPT_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/OPERATIONAL_RECEIPT_CONTRACT.md)
+- [MACHINE_IDENTITY_REGISTRY_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/MACHINE_IDENTITY_REGISTRY_CONTRACT.md)
+- [CRYPTO_AGILITY_MATRIX.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/CRYPTO_AGILITY_MATRIX.md)
+- [AUTHORITY_BINDING_LIFECYCLE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/AUTHORITY_BINDING_LIFECYCLE_CONTRACT.md)
+- [PUBLIC_SURFACE_POLICY_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/PUBLIC_SURFACE_POLICY_CONTRACT.md)
+- [OFFLINE_VERIFIABILITY_AND_RECOVERY_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/OFFLINE_VERIFIABILITY_AND_RECOVERY_CONTRACT.md)
+- [ADAPTER_CERTIFICATION_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/ADAPTER_CERTIFICATION_CONTRACT.md)
+- [TRUST_PORTABILITY_BOUNDARY_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/TRUST_PORTABILITY_BOUNDARY_CONTRACT.md)
+- [SIGNED_AUDIT_PROVENANCE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/SIGNED_AUDIT_PROVENANCE_CONTRACT.md)
+
 ## Public Boundary
 
 The public adoption story is intentionally narrow:
@@ -46,6 +69,7 @@ The shortest public proof loop is:
 The frozen proof-side fact model for `3.0.0` closeout is documented in:
 
 - [XOONYA_PROOF_TRUTH_MODEL.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xoonya/XOONYA_PROOF_TRUTH_MODEL.md)
+- [OPERATIONAL_RECEIPT_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/architecture/OPERATIONAL_RECEIPT_CONTRACT.md)
 
 Machine-readable proof-truth surfaces:
 
@@ -97,6 +121,9 @@ If you want the broadest machine-readable census for these already-core proof la
 - `GET /v1/artifact-distribution`
 - `GET /v1/shared-signals`
 - `GET /v1/feature-control`
+- `GET /v1/adapter-certification`
+- `GET /v1/trust-portability-boundary`
+- `GET /v1/signed-audit-provenance`
 
 ## One-Line After Install
 
@@ -116,6 +143,54 @@ If you want the shortest machine-readable discovery path, inspect:
 - `GET /v1/proof-bridge`
 - `GET /v1/telemetry`
 - `GET /v1/provenance`
+- `GET /v1/adapter-certification`
+- `GET /v1/trust-portability-boundary`
+- `GET /v1/signed-audit-provenance`
+
+If you are working on shared evidence, inspect the operational receipt contract pack:
+
+- `buildOperationalReceiptContractPack()`
+- `summarizeOperationalReceiptContractPack()`
+
+If you are working on machine identity, inspect the registry contract pack:
+
+- `buildMachineIdentityRegistryContractPack()`
+- `summarizeMachineIdentityRegistryContractPack()`
+
+If you are working on crypto agility, inspect the matrix pack:
+
+- `buildCryptoAgilityMatrixPack()`
+- `summarizeCryptoAgilityMatrixPack()`
+
+If you are working on binding lifecycle, inspect the lifecycle pack:
+
+- `buildAuthorityBindingLifecycleContractPack()`
+- `summarizeAuthorityBindingLifecycleContractPack()`
+
+If you are working on public route policy, inspect the surface policy pack:
+
+- `buildPublicSurfacePolicyContractPack()`
+- `summarizePublicSurfacePolicyContractPack()`
+
+If you are working on offline recovery, inspect the recovery pack:
+
+- `buildOfflineVerifiabilityRecoveryContractPack()`
+- `summarizeOfflineVerifiabilityRecoveryContractPack()`
+
+If you are working on adapter certification, inspect the certification pack:
+
+- `buildAdapterCertificationContractPack()`
+- `summarizeAdapterCertificationContractPack()`
+
+If you are working on trust portability boundaries, inspect the boundary pack:
+
+- `buildTrustPortabilityBoundaryContractPack()`
+- `summarizeTrustPortabilityBoundaryContractPack()`
+
+If you are working on signed audit and provenance, inspect the audit/provenance pack:
+
+- `buildSignedAuditProvenanceContractPack()`
+- `summarizeSignedAuditProvenanceContractPack()`
 
 ## Start Here
 
@@ -302,6 +377,8 @@ Current built-in methods:
 
 `algorithm: "none"` is not a registered verification method and does not verify. External proof methods are first-class registry entries, but xoonya does not pretend to replace their own cryptographic verifier stacks. The proof core checks the canonical receipt, method registration, and method boundary; issuer-specific validation stays with the relevant JWT, DID/VC, SD-JWT VC, signed-envelope, or partner verifier.
 
+Every verify result now says which of these happened through `verification_class` and `cryptographically_verified` (see "Verification Classes" below). Native signed and hybrid proofs bind `public_key_ref` to the key carried in the proof, not to the identity string; pass `trusted_public_key_refs` or `expected_public_key_ref` to bind an identity to its keys, and `strict: true` to refuse anything that was not cryptographically verified.
+
 ### xoonya Native Proof Format
 
 xoonya Native is the optional native proof/result/attestation format direction for machine proof. It is not a replacement for JWT, OAuth, OIDC, DID/VC, or SD-JWT VC. Those remain interoperability lanes.
@@ -390,6 +467,14 @@ Environment example:
 
 - [`.env.example`](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xoonya/.env.example)
 
+Service environment variables:
+
+- `XOONYA_HOST`, `XOONYA_PORT` (or `PORT`): bind address and port.
+- `XOONYA_STRICT_VERIFY=1`: make every proof-bundle verification strict (only `cryptographic` results are `valid`).
+- `XOONYA_ACCEPT_PRIVATE_KEY_MATERIAL`: `true` or `false`. When `false`, or when it is unset and `RENDER` is set (hosted deployments), `POST /v1/receipts/emit`, `POST /v1/proof-bundles/build`, and the proof-center run routes reject any body containing a field matching `/private_key/i` with `400 private_key_material_not_accepted`. Sign locally with the SDK (`emitReceipt`, `buildProofBundle`) or the `xoonya` CLI and submit the signed receipt or bundle instead. Local runs without `RENDER` keep accepting private key material so the existing verifiers pass.
+
+Request bodies are capped at 1 MiB by byte count (a larger declared `content-length` is rejected before the body is read). `OPTIONS` returns `204` with an `allow` header, `HEAD` mirrors `GET` without a body, malformed percent-encoding in a path returns `400 invalid_path_encoding`, and unexpected handler failures return a generic `500 internal_error` with the stack logged server-side only.
+
 ## Service Routes
 
 Primary proof-model routes:
@@ -645,6 +730,7 @@ Local verification commands:
 - `npm run verify:examples`
 - `npm run verify:service`
 - `npm run verify:tooling`
+- `npm run verify:forgery-resistance`
 - `npm run verify:all`
 
 The current verification covers:
@@ -659,6 +745,26 @@ The current verification covers:
 - published adversarial vectors
 - package quickstart flow
 - service routes for both the primary proof model and the legacy compatibility layer
+- forgery resistance: key substitution with and without a trust root, strict-mode rejection of digest and structural results, hybrid PQ tampering and wrong-pin rejection, and result determinism
+
+### Verification Classes
+
+`verifyProofBundle(bundle, options)` and `POST /v1/proof-bundles/verify` (`{ "bundle": ..., "options": ... }`) return `verification_class`, `cryptographically_verified`, `strict`, and `trust_root_applied` next to `valid`:
+
+| `verification_class` | Methods | `cryptographically_verified` | Strict mode |
+| --- | --- | --- | --- |
+| `cryptographic` | `xoonya-native-signed-v1`, `xoonya-native-hybrid-v1` | `true` when valid | accepted |
+| `digest` | `xoonya-native-sha256-v1`, `legacy-opreturn-v1` | `false` | rejected: `digest_only_not_cryptographically_verified` |
+| `anchored_binding` | `xoonya-native-anchored-v1` | `false` | rejected: `digest_only_not_cryptographically_verified` |
+| `structural` | `detached-assertion-v1`, `jwt-assertion-v1`, `did-vc-v1`, `sd-jwt-vc-v1`, `signed-envelope-v1`, `partner-proof-envelope-v1` | `false` | rejected: `external_verification_required` |
+
+Default `valid` semantics are unchanged. Options:
+
+- `strict: true` (or env `XOONYA_STRICT_VERIFY=1`): only `cryptographic` results are `valid`.
+- `expected_public_key_ref`, `expected_classical_public_key_ref`, `expected_pq_public_key_ref`, `expected_hybrid_public_key_ref`: pin the exact key refs a native proof must carry.
+- `trusted_public_key_refs`: `{ "<identity_ref>": "<ref>" | ["<ref>", ...] | { "classical": ..., "pq": ..., "hybrid": ... } }`. Native signed proofs fail with `native_public_key_not_trusted` and native hybrid proofs with `native_hybrid_public_key_not_trusted` when the signing key is not pinned for that identity. Any trust-root option sets `trust_root_applied: true` and fails closed for identities that are not listed.
+
+Without a trust root, a native signed proof only proves that the carried key signed the receipt; `identity_ref` and `agent_identity` are not bound to that key by xoonya. `npm run verify:forgery-resistance` pins this behavior.
 
 Public conformance command:
 
@@ -730,4 +836,4 @@ The proof-side readiness layer now also makes promotion posture explicit without
 - production-default-ready means certification, maturity, bundled posture, and selection posture all line up
 - blockers are returned as data instead of being left implicit
 - promotion workflow summaries now show the next proof-side transition and the current recommendation without introducing approval state
-
+

package/RELEASE_NOTES.md

@@ -1,15 +1,18 @@
-`xoonya` 3.0.1 is the synchronized stability patch for the live proof, verification, continuity, governance, replay, and public first-contact line.
+## 3.1.1
 
-This release keeps the public proof line synchronized after the major cut by preserving the same frozen proof truth models, widened finish-line scope, and naxytra public contract, proof, release, and gate surfaces while tightening the installable package experience for outside agents and builders.
+`xoonya` 3.1.1 is the verification-honesty and service-hardening patch on the synchronized control-plane and evidence-line release for the live proof, verification, continuity, governance, replay, and public first-contact line.
+
+This release keeps every frozen proof truth model, public contract, proof, release, and gate surface intact while making verify results say exactly what was checked, letting verifiers pin identities to keys, and hardening the HTTP service against oversized bodies, malformed paths, leaked error details, and private key material submitted over the wire.
 
 Highlights:
 
-- keeps `/v1/proof-truth` and `/v1/proof-truth/summary` as the named proof object boundary
-- keeps `/v1/default-path` and `/v1/default-path/summary` as the named proof-side multi-surface entry boundary
-- keeps `/v1/followthrough-truth` and `/v1/followthrough-truth/summary` as the named bridge, governance, portability, and verification claim boundary
-- keeps verification services, trust-portability surfaces, governance/dispute visibility, and reference-implementation posture aligned with the same synchronized public release line
-- promotes bounded native hybrid live verification for registered runtime-supported vector-covered suites instead of leaving PQ/hybrid as a design-only posture
-- preserves XNYA-compatible conformance, native reference implementation boundaries, external proof import boundaries, deterministic replay posture, and proof-side governance as one discoverable proof stack inside the final major line
+- adds `verification_class` (`cryptographic`, `digest`, `anchored_binding`, `structural`), `cryptographically_verified`, `strict`, and `trust_root_applied` to every `verifyProofBundle` and `POST /v1/proof-bundles/verify` result without changing default `valid` semantics
+- adds strict verification (`options.strict`, `XOONYA_STRICT_VERIFY=1`) with the deterministic rejection codes `digest_only_not_cryptographically_verified` and `external_verification_required`
+- adds verifier-supplied trust roots (`trusted_public_key_refs`, `expected_public_key_ref`, `expected_pq_public_key_ref`, and related lane pins) with the deterministic rejection codes `native_public_key_not_trusted` and `native_hybrid_public_key_not_trusted`, and documents that native `public_key_ref` is self-bound to the carried key while identity binding requires a trust root
+- caches the native hybrid runtime-support probe per suite pair so sign and verify no longer regenerate classical and PQ key pairs on every call
+- hardens `server.js`: byte-counted 1 MiB body limit with a `content-length` precheck, `OPTIONS` and `HEAD` handling, `400 invalid_path_encoding` for malformed percent-encoding, generic `500 internal_error` with server-side stack logging, request and header timeouts, `x-content-type-options: nosniff`, `cache-control: no-store` on non-GET responses, and `uncaughtException` / `unhandledRejection` handlers
+- adds `XOONYA_ACCEPT_PRIVATE_KEY_MATERIAL`; when `false`, or unset on Render, emit, build, and proof-center run routes reject bodies carrying `/private_key/i` fields with `400 private_key_material_not_accepted` and point to local SDK/CLI signing
+- adds `npm run verify:forgery-resistance` (key substitution with and without a trust root, strict-mode rejection of digest and structural results, hybrid PQ tampering and wrong-pin rejection, result determinism) to `verify:all`, plus strict-mode, hardening, and private-key-policy checks in `verify:service`
+- marks the `dilithium`, `falcon`, and `sphincs-plus` registry entries as `deprecated_placeholder` aliases pointing at the implemented `ml-dsa-65` and `slh-dsa-sha2-128f` suites, and labels native identity prefixes `05`-`07` as legacy placeholders
 - keeps `RELEASE_NOTES.md` scoped to the current release so npm and GitHub release notes stay clean
 - keeps the canonical `https://naxytra.com/xoonya` public product URL and single naxytra website positioning intact
-- verifies the release candidate, full package verifier, umbrella pre-deploy gates, and clean-consumer release smoke before the synchronized stability patch

package/SERVICE_CONTRACT.md

@@ -50,6 +50,15 @@ Primary proof-model routes:
 - `GET /v1/shared-signals/summary`
 - `GET /v1/feature-control`
 - `GET /v1/feature-control/summary`
+- `GET /v1/adapter-certification`
+- `GET /v1/adapter-certification/summary`
+- `GET /v1/adapter-certification/:front_id`
+- `GET /v1/trust-portability-boundary`
+- `GET /v1/trust-portability-boundary/summary`
+- `GET /v1/trust-portability-boundary/:axis_id`
+- `GET /v1/signed-audit-provenance`
+- `GET /v1/signed-audit-provenance/summary`
+- `GET /v1/signed-audit-provenance/:surface_id`
 - `GET /v1/integrations`
 - `GET /v1/integrations/summary`
 - `GET /v1/integrations/snapshot`
@@ -161,6 +170,9 @@ Interop note:
 - `GET /v1/artifact-distribution` exposes OCI-style artifact distribution posture for proof bundles, handoff bundles, snapshots, and release artifacts
 - `GET /v1/shared-signals` exposes OpenID Shared Signals and CAEP-aligned review, bridge, import, and trust event exchange posture
 - `GET /v1/feature-control` exposes OpenFeature/OFREP-aligned rollout and review portability posture around role freeze, bridge, trust, and release gates
+- `GET /v1/adapter-certification` exposes the front-specific adapter certification contract and its machine-readable compatibility states
+- `GET /v1/trust-portability-boundary` exposes the bounded trust portability contract for identity, delegation, delivery, and settlement-linked followthrough
+- `GET /v1/signed-audit-provenance` exposes the signed audit and provenance surface map for selected evidence-bearing proof and release lanes
 
 ## Final-Loop Verification
 

package/START_HERE.md

@@ -6,6 +6,12 @@ The phase program is now complete, so this file is the right starting point for
 
 The product-side implementation, proof posture, and bounded hybrid verification work for the widened `3.0.0` finish line are now complete. The remaining step is the synchronized public `3.0.0` release cut, publish, deploy, and verification sequence documented in [NAXYTRA_3_0_0_RELEASE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/docs/release/NAXYTRA_3_0_0_RELEASE_CONTRACT.md) and [PUBLISH_PLAN.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_naxytra/naxytra/xoonya/PUBLISH_PLAN.md).
 
+If you are arriving from the broader public discovery layer, the canonical entry points are:
+
+- https://www.naxytra.com/agents
+- https://www.naxytra.com/v1/agent-discovery-index
+- https://www.naxytra.com/.well-known/agent.json
+
 ## 1. Understand The Role
 
 `xoonya` is the proof-side half of the public stack.
@@ -100,6 +106,9 @@ For long-term product understanding, read:
 - `GET /v1/artifact-distribution`
 - `GET /v1/shared-signals`
 - `GET /v1/feature-control`
+- `GET /v1/adapter-certification`
+- `GET /v1/trust-portability-boundary`
+- `GET /v1/signed-audit-provenance`
 - `GET /v1/major-rails`
 - `GET /v1/treasury`
 - `GET /v1/erc8004`

package/XOONYA_NATIVE_PROOF_FORMAT.md

@@ -204,7 +204,9 @@ It is not the final signed native standard by itself.
 
 Implemented.
 
-This adds a native signature envelope with explicit identity and key binding. The format declares its signature suite instead of hardcoding one global algorithm.
+This adds a native signature envelope whose `public_key_ref` is self-bound to the public key material carried inside the proof (`public_key_ref == sha256(SPKI DER)` of that same key), and whose signature covers the receipt signing material, event commitment, `identity_ref`, and `public_key_ref`. The format declares its signature suite instead of hardcoding one global algorithm.
+
+The verifier checks key self-binding and the signature, not identity ownership. `identity_ref` and `agent_identity` are free strings: any key can sign a proof that claims any identity, and that proof self-verifies. Identity binding therefore requires a trust root supplied by the verifier (`trusted_public_key_refs` or `expected_public_key_ref`, see "Verification Classes, Strict Mode, And Trust Roots" below). Without a trust root the result is `cryptographically_verified: true` with `trust_root_applied: false`, which means "this key signed this receipt", not "this identity signed this receipt".
 
 Required signed-native fields:
 
@@ -220,14 +222,19 @@ Implemented suites:
 - `secp256k1`
 - `p256`
 
-Declared suite registry entries:
+Implemented PQ suites (usable only inside `xoonya-native-hybrid-v1`):
+
+- `ml-dsa-65` (FIPS 204)
+- `slh-dsa-sha2-128f` (FIPS 205)
 
-- `webauthn-cose`
-- `dilithium`
-- `falcon`
-- `sphincs-plus`
+Declared suite registry entries that never verify:
 
-The atom commits to proof material; it does not validate these suites directly. Only suites with implemented validators should be described as verified.
+- `webauthn-cose` (`maturity: planned`)
+- `dilithium` (`status: deprecated_placeholder`, `deprecated_alias_of: ml-dsa-65`)
+- `falcon` (`status: deprecated_placeholder`, no registered successor yet)
+- `sphincs-plus` (`status: deprecated_placeholder`, `deprecated_alias_of: slh-dsa-sha2-128f`)
+
+The three `deprecated_placeholder` entries are legacy pre-standard names kept only so existing registry consumers keep resolving them; new material must use the ML-DSA/SLH-DSA identifiers. The atom commits to proof material; it does not validate these suites directly. Only suites with implemented validators should be described as verified.
 
 ### `xoonya-native-anchored-v1`
 
@@ -353,8 +360,44 @@ Current adversarial expectations include:
 - tampered PQ signature rejects as `native_hybrid_pq_signature_invalid`
 - key-binding mismatches reject as `native_hybrid_public_key_ref_mismatch`
 - downgrade attempts through external assertion methods reject as `signature_method_mismatch`
+- a valid dual signature from keys the verifier has not pinned for that `identity_ref` rejects as `native_hybrid_public_key_not_trusted` when a trust root is supplied
+
+This keeps the boundary honest: xoonya now verifies the hybrid lane where the runtime and vectors are real, and refuses to overclaim beyond that runtime-supported registry. The runtime-support probe for each suite pair runs once per process and is cached afterwards.
+
+## Verification Classes, Strict Mode, And Trust Roots
+
+Every result from `verifyProofBundle(bundle, options)` and `POST /v1/proof-bundles/verify` carries four extra fields:
+
+- `verification_class`: one of `cryptographic`, `digest`, `anchored_binding`, `structural`
+- `cryptographically_verified`: `true` only when a native signature was actually checked and the result is valid
+- `strict`: whether strict mode was active for that call
+- `trust_root_applied`: whether a verifier-supplied trust root constrained the accepted keys
+
+Classes by method:
+
+| Class | Methods | What was checked |
+| --- | --- | --- |
+| `cryptographic` | `xoonya-native-signed-v1`, `xoonya-native-hybrid-v1` | key self-binding plus a real classical and/or PQ signature over the signing material |
+| `digest` | `xoonya-native-sha256-v1`, `legacy-opreturn-v1` | an unkeyed deterministic digest; anyone can reproduce it, so it proves integrity and replayability, not authorship |
+| `anchored_binding` | `xoonya-native-anchored-v1` | an unkeyed digest binding to declared anchor refs; anchor truth and authorship stay external |
+| `structural` | `detached-assertion-v1`, `jwt-assertion-v1`, `did-vc-v1`, `sd-jwt-vc-v1`, `signed-envelope-v1`, `partner-proof-envelope-v1` | envelope shape, method registration, and canonical receipt binding only; the external signature must be verified by the external stack |
+
+`valid` keeps its historical meaning by default: a well-formed digest, anchored, or structural bundle is still `valid: true`, it just also says `cryptographically_verified: false`.
+
+Strict mode (`options.strict === true`, or `XOONYA_STRICT_VERIFY=1` in the environment) only accepts the `cryptographic` class. Deterministic rejection codes:
+
+- `digest_only_not_cryptographically_verified` for `digest` and `anchored_binding` results
+- `external_verification_required` for `structural` results
+
+Trust roots pin which keys may speak for an identity. Options:
+
+- `expected_public_key_ref`: the proof's `public_key_ref` (native signed) or classical/hybrid ref (native hybrid) must equal this value
+- `expected_classical_public_key_ref`, `expected_pq_public_key_ref`, `expected_hybrid_public_key_ref`: lane-specific pins for hybrid proofs
+- `trusted_public_key_refs`: object keyed by `identity_ref` (falling back to `agent_identity`). Values are a ref string, an array of ref strings, or `{ classical, pq, hybrid }` where each lane is a string or array. A string or array pins the classical lane; use the object form to pin the PQ lane of a hybrid proof.
+
+When any trust-root option is present, `trust_root_applied` is `true` and native verification fails closed: an identity missing from the map, a lane that cannot be satisfied by the proof (for example a PQ pin against a classical-only proof), or any ref outside the pinned set rejects with `native_public_key_not_trusted` (native signed) or `native_hybrid_public_key_not_trusted` (native hybrid). These checks run after the signature check, so a trust-root rejection always means "valid signature, untrusted key". Digest, anchored, and structural methods carry no key and are unaffected by trust roots; use strict mode to reject them.
 
-This keeps the boundary honest: xoonya now verifies the hybrid lane where the runtime and vectors are real, and refuses to overclaim beyond that runtime-supported registry.
+The `scripts/verify_forgery_resistance.js` verifier (`npm run verify:forgery-resistance`) pins this behavior, including the documented key-substitution limitation without a trust root.
 
 ## Crypto And Identity Support Boundary
 
@@ -368,7 +411,7 @@ Cleanly supported above the atom:
 - DID and DIDComm identity references
 - JWT/JWS and signed envelope assertions
 - DID/VC and SD-JWT VC evidence references
-- Dilithium, Falcon, SPHINCS+, and future PQ signature public-key material
+- ML-DSA (FIPS 204), SLH-DSA (FIPS 205), and future PQ signature public-key material; the legacy `dilithium`, `falcon`, and `sphincs-plus` registry names are deprecated placeholders that never verify
 - HPKE, TLS, AES-GCM, or encrypted payload commitments
 - ZK proof, circuit, verifier-key, and public-input commitments
 

package/index.js

@@ -5,9 +5,18 @@ module.exports = {
   ...require("./integrations/registry"),
   ...require("./lib/verification_service_pack"),
   ...require("./lib/trust_portability_pack"),
-  ...require("./lib/proof_truth_contract"),
-  ...require("./lib/default_path_contract"),
-  ...require("./lib/followthrough_truth_contract"),
+...require("./lib/proof_truth_contract"),
+...require("./lib/operational_receipt_contract"),
+...require("./lib/machine_identity_registry_contract"),
+...require("./lib/crypto_agility_matrix"),
+...require("./lib/authority_binding_lifecycle_contract"),
+...require("./lib/public_surface_policy_contract"),
+...require("./lib/offline_verifiability_recovery_contract"),
+...require("./lib/adapter_certification_contract"),
+...require("./lib/trust_portability_boundary_contract"),
+...require("./lib/signed_audit_provenance_contract"),
+...require("./lib/default_path_contract"),
+...require("./lib/followthrough_truth_contract"),
   ...require("./lib/governance_disputes_summary"),
   ...require("./lib/release_pack"),
   ...require("./lib/release_manifest"),

package/lib/adapter_certification_contract.js

@@ -0,0 +1,90 @@
+"use strict";
+
+const packageJson = require("../package.json");
+
+function buildAdapterCertificationContractPack() {
+  return {
+    ok: true,
+    product: packageJson.name,
+    category: "naxytra-adapter-certification-contract",
+    pack_version: "naxytra-adapter-certification-contract-v1",
+    doctrine: "xoonya_certifies_adapter_compatibility_for_proof_and_review_surfaces_without_leaking_proof_core_semantics",
+    model_state: "core_now",
+    core_claim: "adapter certification is the machine-readable gate for manifest, capability, health, idempotency, failure, proof, and front-specific compatibility claims",
+    certification_states: [
+      { state: "pass", description: "the adapter satisfies the declared front contract without material constraints" },
+      { state: "pass_with_constraints", description: "the adapter is usable but only within declared constraints" },
+      { state: "needs_retest", description: "the adapter needs a fresh run against updated vectors or interface versions" },
+      { state: "blocked", description: "the adapter cannot be certified until a required dependency or vector exists" },
+      { state: "fail", description: "the adapter does not satisfy the declared front contract" }
+    ],
+    certification_fronts: [
+      { front_id: "protocol_front", required_tests: ["protocol negotiation", "surface discovery", "normalized request translation"], required_evidence: ["manifest", "protocol compatibility result", "failure mapping result"], claim_boundary: "only_claim_listed_protocol_front_compatibility" },
+      { front_id: "execution_front", required_tests: ["task dispatch", "idempotency", "execution result normalization"], required_evidence: ["manifest", "task vector results", "proof-compatible output facts"], claim_boundary: "only_claim_listed_execution_front_compatibility" },
+      { front_id: "payment_front", required_tests: ["quote to pay compatibility", "payment admission", "reversal or refund posture"], required_evidence: ["payment state result", "receipt compatibility result", "failure mapping result"], claim_boundary: "only_claim_listed_payment_front_compatibility" },
+      { front_id: "settlement_front", required_tests: ["settlement target translation", "finality reference capture", "batch or direct settlement posture"], required_evidence: ["settlement reference", "finality state", "reconciliation evidence"], claim_boundary: "only_claim_listed_settlement_front_compatibility" },
+      { front_id: "identity_trust_front", required_tests: ["identity schema compatibility", "registry linkage", "attestation or trust-state roundtrip"], required_evidence: ["identity record", "registry proof", "trust-state result"], claim_boundary: "only_claim_listed_identity_trust_front_compatibility" },
+      { front_id: "proof_front", required_tests: ["receipt compatibility", "proof import or export compatibility", "verification hook compatibility"], required_evidence: ["proof contract result", "receipt result", "verification evidence"], claim_boundary: "only_claim_listed_proof_front_compatibility" },
+      { front_id: "treasury_front", required_tests: ["destination routing", "balance model compatibility", "payout landing compatibility"], required_evidence: ["treasury route result", "account abstraction result", "operator review note"], claim_boundary: "only_claim_listed_treasury_front_compatibility" },
+      { front_id: "operator_front", required_tests: ["review surface visibility", "promotion posture", "reporting export compatibility"], required_evidence: ["review summary", "promotion readiness result", "operator export"], claim_boundary: "only_claim_listed_operator_front_compatibility" }
+    ],
+    harness_requirements: {
+      test_categories: [
+        "manifest_validity",
+        "interface_conformance",
+        "capability_declaration",
+        "health_reporting",
+        "failure_mapping",
+        "idempotency_behavior",
+        "proof_compatibility",
+        "front_specific_lifecycle_compatibility"
+      ],
+      required_result_fields: [
+        "certification_state",
+        "interface_version",
+        "tested_fronts",
+        "tested_capabilities",
+        "failed_cases",
+        "warnings",
+        "evidence_refs"
+      ]
+    },
+    linked_surfaces: {
+      proof_bridge_ref: "/v1/proof-bridge",
+      verification_services_ref: "/v1/proof-center/verification-services",
+      submission_bundle_review_ref: "/v1/proof-center/result-package-handoff/review/summary",
+      trust_portability_ref: "/v1/proof-center/trust-portability/summary",
+      integration_matrix_ref: "/v1/integration-matrix",
+      provenance_ref: "/v1/provenance"
+    },
+    claim_boundary: "claim_adapter_certification_as_front_specific_compatibility_and_review_gate_without_claiming_vendor_default_or_proof_core_truth"
+  };
+}
+
+function summarizeAdapterCertificationContractPack() {
+  const pack = buildAdapterCertificationContractPack();
+  return {
+    ok: true,
+    product: pack.product,
+    category: pack.category,
+    summary_version: "naxytra-adapter-certification-contract-summary-v1",
+    pack_version: pack.pack_version,
+    model_state: pack.model_state,
+    certification_state_count: pack.certification_states.length,
+    certification_front_count: pack.certification_fronts.length,
+    required_test_category_count: pack.harness_requirements.test_categories.length,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+function getAdapterCertificationFrontDetail(frontId) {
+  const normalized = String(frontId || "").trim().toLowerCase();
+  return (buildAdapterCertificationContractPack().certification_fronts || []).find((entry) => entry.front_id === normalized) || null;
+}
+
+module.exports = {
+  buildAdapterCertificationContractPack,
+  summarizeAdapterCertificationContractPack,
+  getAdapterCertificationFrontDetail
+};
+