xoonya

xoonya is the proof foundation for machine actions.

It exists to make machine evidence:

• deterministic
• portable
• minimal
• verifiable
• replayable

This repo is the proof-side half of the final two-repo public stack. It focuses on canonical events, receipts, proof bundles, and verification. It does not own pricing, catalogs, workflow orchestration, payment rails, or settlement policy.

Start Here

If you are new to the proof-side package, use this order:

1. read START_HERE.md
2. run node examples/package_quickstart.js
3. run npm run verify:all
4. use FINAL_CONTRACT.md and SERVICE_CONTRACT.md as the durable public contract

If you are integrating from outside the stack, also read:

• CROSS_RUNTIME_POSTURE.md
• integrations/PROOF_INTEGRATION_PROCESS.md

Production Path

The intended production-facing proof path is now:

1. receive the transaction-side handoff or default path artifact from xytara
2. inspect the proof-side review posture
3. confirm carry and run posture
4. emit and verify the proof-native completion path

The rest of this README explains the broader route ladder, but the public starting posture should now be understandable from that one proof-side path.

The package and service now also expose a default proof center surface so the intended proof-native path is easy to inspect directly:

• canonical event bundle v1
• receipt v1
• proof bundle v1
• compact compatibility helpers preserved, but not treated as the public conceptual center
• proof remains settlement-agnostic and workflow-agnostic by default

The current 1.6.0 companion slice adds guided default proof loops on top of that proof center:

• default proof-loop catalog and detail routes
• a direct proof-loop run route for the canonical proof-native path
• package helpers that build, verify, and summarize the proof bundle boundary in one step

This keeps xoonya narrow while making the intended proof path easier to inspect alongside the newer guided transaction-loop work in xytara.

The current 1.7.0 companion slice adds a lightweight transaction proof-handoff surface:

• a transaction proof-handoff center that states the expected handoff contract
• a direct handoff run path that turns transaction-side proof handoff data into a proof-native bundle
• summary helpers that make the recommended proof follow-through explicit without widening proof scope

The current 1.8.0 companion slice extends that same proof-side carry to richer grouped interaction spine handoffs:

• an interaction-spine handoff center and summary surface
• a direct interaction-spine handoff run path for composed transaction spines
• proof-side summaries that preserve both pre-commit and committed-ref context without importing commerce logic

Proof Model

The primary proof model is layered:

1. Canonical Event Bundle
2. Receipt
3. Proof Bundle
4. optional domain-specific Profiles

That means the center of gravity is now:

• canonicalizeEvent(...)
• hashEvent(...)
• emitReceipt(...)
• buildProofBundle(...)
• verifyProofBundle(...)

Compatibility Surface

Legacy compact receipt and profile helpers are still available during alignment:

• createReceipt(...)
• verifyReceipt(...)
• createReceiptV2(...)
• verifyReceiptV2(...)
• createProofEnvelopeV1(...)
• verifyProofEnvelopeV1(...)
• createEconomicReceiptProfileV1(...)
• verifyEconomicReceiptProfileV1(...)
• createRegistryProfileV1(...)
• verifyRegistryProfileV1(...)

Those helpers remain verified so current receipt/profile consumers are not broken while the newer proof model becomes the primary public direction.

Package Quickstart

Run:

node examples/package_quickstart.js

The package quickstart demonstrates:

• proof integration discovery and certification posture
• staged proof-integration registration and snapshot export
• legacy compact receipt verification
• legacy proof-envelope verification
• canonical event creation
• canonical receipt emission
• proof bundle construction
• proof bundle verification
• transaction proof-handoff follow-through

Service Quickstart

Run:

npm start

Then in another shell:

curl -X POST http://127.0.0.1:4310/v1/events/hash ^
  -H "content-type: application/json" ^
  -d "{\"event\":{\"version\":\"canonical-event-bundle/v1\",\"domain_id\":\"demo\",\"sequence\":\"1\",\"actor_id\":\"agent-1\",\"adapter_source\":\"curl\",\"event_type\":\"demo.event\",\"event_hash\":\"abababababababababababababababababababababababababababababababab\"}}"

Environment example:

• .env.example

Service Routes

Primary proof-model routes:

• GET /health
• GET /v1/proof-center
• GET /v1/proof-center/summary
• GET /v1/proof-center/default-loops
• GET /v1/proof-center/default-loops/summary
• GET /v1/proof-center/default-loop
• POST /v1/proof-center/default-loops/run
• GET /v1/proof-center/transaction-handoff
• GET /v1/proof-center/transaction-handoff/summary
• POST /v1/proof-center/transaction-handoff/run
• GET /v1/proof-center/result-package-handoff
• GET /v1/proof-center/result-package-handoff/summary
• GET /v1/proof-center/governance
• GET /v1/proof-center/governance/summary
• GET /v1/proof-center/bridge
• GET /v1/proof-center/bridge/summary
• GET /v1/proof-center/bridge/profile-support
• POST /v1/proof-center/governance/interpretation-validate
• POST /v1/proof-center/governance/coordination
• POST /v1/proof-center/governance/dashboard
• POST /v1/proof-center/governance/operator-view
• POST /v1/proof-center/governance/admin-view
• POST /v1/proof-center/governance/dashboard-pack
• POST /v1/proof-center/governance/workflow-pack
• POST /v1/proof-center/governance/signoff-pack
• POST /v1/proof-center/governance/disputes/summary
• POST /v1/proof-center/governance/disputes/case-review
• POST /v1/proof-center/governance/disputes/action
• POST /v1/proof-center/governance/disputes/case-bundle
• POST /v1/proof-center/governance/disputes/resolution-pack
• POST /v1/proof-center/governance/console-pack
• POST /v1/proof-center/governance/handoff-bundle
• POST /v1/proof-center/governance/review-link
• POST /v1/proof-center/bridge/receipt-wrap
• POST /v1/proof-center/bridge/validator-verify
• POST /v1/proof-center/bridge/receipt-ledger-handoff
• POST /v1/proof-center/bridge/operator-review-pack
• POST /v1/proof-center/bridge/compatibility-pack
• POST /v1/proof-center/bridge/workflow-pack
• POST /v1/proof-center/bridge/admin-pack
• POST /v1/proof-center/result-package-handoff/review
• POST /v1/proof-center/result-package-handoff/review/summary
• POST /v1/proof-center/result-package-handoff/review/extension-readiness
• POST /v1/proof-center/result-package-handoff/review/extension-boundary
• POST /v1/proof-center/result-package-handoff/review/default-continuation
• POST /v1/proof-center/result-package-handoff/review/default-boundary
• POST /v1/proof-center/result-package-handoff/review/contract-summary
• POST /v1/proof-center/result-package-handoff/review/contract-boundary
• POST /v1/proof-center/result-package-handoff/review/contract-carry
• POST /v1/proof-center/result-package-handoff/review/bridge-summary
• POST /v1/proof-center/result-package-handoff/review/bridge-boundary
• POST /v1/proof-center/result-package-handoff/review/bridge-carry
• POST /v1/proof-center/result-package-handoff/review/bridge-run
• POST /v1/proof-center/result-package-handoff/review/handoff-continuity
• POST /v1/proof-center/result-package-handoff/review/handoff-intake
• POST /v1/proof-center/result-package-handoff/review/handoff-intake-boundary
• POST /v1/proof-center/result-package-handoff/review/handoff-intake-carry
• POST /v1/proof-center/result-package-handoff/review/handoff-package-intake
• POST /v1/proof-center/result-package-handoff/review/handoff-package-carry
• POST /v1/proof-center/result-package-handoff/review/handoff-package-run
• POST /v1/proof-center/result-package-handoff/review/execution-package
• POST /v1/proof-center/result-package-handoff/review/execution-package-carry
• POST /v1/proof-center/result-package-handoff/review/execution-package-run
• POST /v1/proof-center/result-package-handoff/review/execution-contract
• POST /v1/proof-center/result-package-handoff/review/execution-contract-carry
• POST /v1/proof-center/result-package-handoff/review/execution-contract-run
• POST /v1/proof-center/result-package-handoff/review/operating-contract
• POST /v1/proof-center/result-package-handoff/review/operating-contract-carry
• POST /v1/proof-center/result-package-handoff/review/operating-contract-run
• POST /v1/proof-center/result-package-handoff/review/operating-interface
• POST /v1/proof-center/result-package-handoff/review/operating-interface-carry
• POST /v1/proof-center/result-package-handoff/review/operating-interface-run
• POST /v1/proof-center/result-package-handoff/review/operating-integration
• POST /v1/proof-center/result-package-handoff/review/operating-integration-carry
• POST /v1/proof-center/result-package-handoff/review/operating-integration-run
• POST /v1/proof-center/result-package-handoff/review/operating-path
• POST /v1/proof-center/result-package-handoff/review/operating-path-carry
• POST /v1/proof-center/result-package-handoff/review/operating-path-run
• POST /v1/proof-center/result-package-handoff/review/complete-default-path
• POST /v1/proof-center/result-package-handoff/review/complete-default-path-carry
• POST /v1/proof-center/result-package-handoff/review/complete-default-path-run
• POST /v1/proof-center/result-package-handoff/review/handoff-run
• POST /v1/proof-center/result-package-handoff/run

The result-package review surface now also returns a durability summary so the preserved execution, economic, and proof-facing context is easier to inspect before proof-native execution. It also now exposes an extension-readiness summary so the stable post-review proof boundary is easier to treat as a reusable seam. It now also exposes a reusable-default continuation summary so that same stable post-review boundary is easier to reuse as a standard proof-side default path. It now also exposes a compact reusable-default boundary summary so the proof-side default seam can be treated as a stable public boundary, not just a recommended path. It now also exposes composition-contract summaries so the proof-side default seam can be treated more clearly as a stable public contract across review and run. It now also exposes compact contract-carry summaries so the stable proof-side contract context is easier to inspect directly without expanding proof scope. It now also exposes bridge summaries, bridge-boundary summaries, and bridge-carry summaries so the proof-side review seam is easier to treat as an adapter-ready bridge without widening proof scope. It now also exposes a bridge-run summary so that same proof-side bridge can be read directly as the final run posture instead of only as review-stage carry. It now also exposes a handoff-continuity summary so the proof-side bridge can be treated more clearly as a stable handoff contract into proof-native execution. It now also exposes a handoff-intake summary and handoff-intake-boundary summary so that same handoff contract can be consumed more directly as a stable proof-native intake surface for future adapters without widening proof scope. It now also exposes a handoff-intake-carry summary so the same proof-side intake surface can be reused more directly as compact consumable carry instead of only summary or boundary posture. It now also exposes a handoff-run summary so that same handoff contract can be read directly as the final proof-native run posture instead of only as continuity guidance.

The Wave B governance carry-over line adds a bounded governance center on the proof side:

• governance interpretation validation for receipt-ledger and result-package follow-through
• governance coordination emission for the next proof-side/operator handoff step
• governance dashboard, operator-view, admin-view, dashboard-pack, workflow-pack, and signoff-pack packaging
• dispute summary, case review, metadata-only dispute action, case-bundle export, and resolution-pack export
• console-pack, handoff-bundle, and explicit review-link surfaces for compact operator carry into the proof-side review/run ladder

This keeps governance review attached to the proof-side operating shape without widening xoonya into a runtime or economics system.

The Wave E bridge carry-over line adds a bounded bridge center on the proof side:

• receipt-wrap support for compact compatibility receipts when an outside bridge still needs that bounded surface
• validator-compatible verification and receipt inspection posture for bridge-side review
• receipt-ledger handoff packaging for compact proof-to-economics carry
• operator review packs, workflow packs, admin packs, and compatibility packs so bridge-facing support breadth is easy to inspect without changing the public proof center

This keeps the public story centered on xoonya while preserving the useful bridge, validator, and profile lineage as support surfaces instead of separate product identities.

The current 1.18.0 line starts turning that adapter-consumable handoff surface into a clearer adapter-usable handoff package:

• proof-side handoff-package intake summaries on top of the intake surface
• proof-side handoff-package carry for compact usable package carry
• proof-side handoff-package run summaries for direct default run posture
• clearer handoff-package ids across intake, carry, and proof-native run posture

This is intended to make the proof-side continuation path easier to use directly as a stable public handoff package instead of only a proof-native intake surface.

The current 1.19.0 line starts turning that adapter-usable handoff package into a clearer adapter-ready execution package:

• proof-side execution-package posture on top of the handoff-package path
• compact execution-package carry for direct execution-ready posture
• proof-side execution-package run posture for direct default proof-native run carry
• clearer execution-package ids across package review, carry, and proof-native run posture

This is intended to make the proof-side continuation path easier to execute against directly as a stable public package instead of only a package posture.

The current 1.20.0 line starts turning that adapter-ready execution package into a clearer adapter-operable execution contract:

• proof-side execution-contract posture on top of the execution-package path
• compact execution-contract carry for direct operable proof-side carry
• proof-side execution-contract run posture for direct default proof-native operation carry
• clearer execution-contract ids across review, carry, and proof-native run posture

This is intended to make the proof-side continuation path easier to operate against repeatedly as a stable public contract instead of only a package that is execution-ready by posture.

The current 1.21.0 line starts turning that adapter-operable execution contract into a clearer adapter-stable operating contract:

• proof-side operating-contract posture on top of the execution-contract path
• compact operating-contract carry for direct stable proof-side operating carry
• proof-side operating-contract run posture for direct default proof-native operating posture
• clearer operating-contract ids across review, carry, and proof-native run posture

This is intended to make the proof-side continuation path easier to depend on repeatedly as a durable public operating contract instead of only a contract that is operable in the moment.

The current 1.22.0 line starts turning that adapter-stable operating contract into a clearer adapter-reliable operating interface:

• proof-side operating-interface posture on top of the operating-contract path
• compact operating-interface carry for direct reliable proof-side interface carry
• proof-side operating-interface run posture for direct default proof-native reliable posture
• clearer operating-interface ids across review, carry, and proof-native run posture

This is intended to make the proof-side continuation path easier to rely on operationally as a durable public interface instead of only a stable operating contract shape.

The current 1.23.0 line starts turning that adapter-reliable operating interface into a clearer adapter-integrable operating path:

• proof-side operating-integration posture on top of the operating-interface path
• compact operating-integration carry for direct integrable proof-side path carry
• proof-side operating-integration run posture for direct default proof-native integration posture
• clearer operating-integration ids across review, carry, and proof-native run posture

This is intended to make the proof-side continuation path easier to plug into adapters directly as a durable public operating path instead of only a reliable interface shape.

The current 1.24.0 line starts turning that adapter-integrable operating path into a clearer adapter-ready default path:

• proof-side operating-path posture on top of the operating-integration path
• compact operating-path carry for direct default proof-side path carry
• proof-side operating-path run posture for direct default proof-native path posture
• clearer operating-path ids across review, carry, and proof-native run posture

This is intended to make the proof-side continuation path easier to use as the obvious first public adapter path instead of only a path that is integrable with a little extra coordination.

The current 1.25.0 line starts turning that adapter-ready default path into a clearer adapter-complete default path:

• proof-side complete-default-path posture on top of the operating-path path
• compact complete-default-path carry for direct complete proof-side path carry
• proof-side complete-default-path run posture for direct default proof-native complete path posture
• clearer complete-default-path ids across review, carry, and proof-native run posture

This is intended to make the proof-side continuation path easier to adopt as the complete public default path an outside builder can use without needing private interpretation.

The current 1.26.0 line finalizes that public shape into a cleaner production-ready package:

• a publishable START_HERE.md onboarding path
• clearer top-level README entry points for the default proof-side production flow
• publishable contract, compatibility, and terminology docs carried in the package tarball
• naming cleanup that keeps the public story anchored to xytara and xoonya

This is intended to make the public proof-side package feel like a finished production-facing product instead of a strong stack that still assumes milestone-history context.

• POST /v1/events/canonicalize
• POST /v1/events/hash
• POST /v1/receipts/emit
• POST /v1/proof-bundles/build
• POST /v1/proof-bundles/verify
• GET /v1/integrations
• GET /v1/integrations/summary
• GET /v1/integrations/snapshot
• GET /v1/integrations/promotion-readiness
• GET /v1/integrations/promotion-workflow

Preserved compatibility routes:

• POST /validate
• POST /v1/receipts/verify
• POST /v1/receipts/inspect
• POST /v1/proofs/verify
• POST /v1/profiles/economic/verify
• POST /v1/profiles/registry/verify

Verification

Local verification commands:

• npm run verify:package
• npm run verify:vectors
• npm run verify:examples
• npm run verify:service
• npm run verify:tooling
• npm run verify:all

The current verification covers:

• proof integration discovery metadata and filtering
• staged proof integration registration import and snapshot export
• package export presence
• deterministic event hashing
• proof-bundle tamper detection
• published conformance vectors
• published adversarial vectors
• package quickstart flow
• service routes for both the primary proof model and the legacy compatibility layer

Published proof hardening artifacts:

• conformance-vectors.json
• adversarial-vectors.json
• CROSS_RUNTIME_POSTURE.md

Control Files

• CROSS_RUNTIME_POSTURE.md
• FINAL_CONTRACT.md
• TERMINOLOGY.md
• SERVICE_CONTRACT.md
• COMPATIBILITY_NOTE.md

Proof Integration Toolkit

xoonya keeps its integration model narrower than xytara. The proof-side toolkit is for additive proof helpers only:

• identity-material providers
• proof-bundle reference adapters
• profile verification helpers

The package now includes:

• validateIntegrationRegistration(...)
• importRegisteredIntegration(...)
• exportIntegrationRegistrySnapshot(...)
• validateIntegrationRegistrySnapshot(...)
• summarizeIntegrationPromotionReadiness(...)
• summarizeIntegrationPromotionWorkflow(...)
• summarizeIntegrationPromotionWorkflowList(...)

Those helpers are intended to normalize proof-adjacent integrations without letting pricing, workflow, or settlement logic leak into the proof kernel.

For the lightweight external-builder path, use:

• PROOF_INTEGRATION_PROCESS.md

For lightweight local review flows, xoonya also includes a small repo-local proof-side CLI when working from a cloned xoonya repository:

node scripts/registry_cli.js validate-registration --example verifier
node scripts/registry_cli.js export-snapshot --registration_state staging_registered
node scripts/registry_cli.js promotion-readiness --integration partner.verifier.lattice_notary
node scripts/registry_cli.js promotion-workflow --integration partner.verifier.lattice_notary
node scripts/registry_cli.js promotion-workflow-summary --source third_party_example --registration_state staging_registered --bundled false

That tooling is intentionally narrow: validate proof-integration registration posture and export filtered proof registry snapshots.

The proof-side readiness layer now also makes promotion posture explicit without expanding xoonya into a control plane:

• review-ready means a proof integration is staged and inspectable
• default-eligible means it can participate in the proof-side default posture
• 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