xoonya 1.25.0 → 1.27.0

package/COMPATIBILITY_NOTE.md

@@ -0,0 +1,27 @@
+# xoonya Compatibility Note
+
+`xoonya` is a first public contract built from private lineage.
+
+That means the current public center of gravity is:
+
+- `Canonical Event Bundle`
+- `Receipt`
+- `Proof Bundle`
+
+Older compact receipt and profile helpers remain available because they are useful support breadth, not because the public contract is required to center on them.
+
+Current retained compatibility helpers include:
+
+- `createReceipt(...)`
+- `verifyReceipt(...)`
+- `createReceiptV2(...)`
+- `verifyReceiptV2(...)`
+- `createProofEnvelopeV1(...)`
+- `verifyProofEnvelopeV1(...)`
+- profile verification helpers
+
+Public guidance:
+
+- use the canonical event and proof-bundle flow first
+- treat retained compact helpers as compatibility/support utilities
+- do not model new integrations as if the older helper lineage were the only public proof contract

package/CROSS_RUNTIME_POSTURE.md

@@ -0,0 +1,47 @@
+# xoonya Cross-Runtime Posture
+
+`xoonya` is intended to be reproducible across runtimes.
+
+The current reference implementation is Node.js, but the proof contract is designed so that:
+
+- canonical event normalization is explicit
+- hashing is deterministic
+- receipt derivation is deterministic
+- proof-bundle verification is deterministic
+
+## Current reference runtime
+
+- Node.js `>=18`
+
+## What is already explicit
+
+- canonical object ordering is defined by the proof implementation
+- event commitment is derived from canonical serialized event content
+- receipt IDs are derived from canonical receipt-signing material
+- proof-bundle verification checks deterministic structural invariants
+
+## Current publication artifacts
+
+- `vectors/conformance-vectors.json`
+- `vectors/adversarial-vectors.json`
+
+These vectors are intended to be reusable by future implementations in other runtimes.
+
+## Current limitation
+
+This repo does not yet ship a second-language reference implementation.
+
+So the current cross-runtime posture is:
+
+- contract and vectors are published
+- Node.js reference behavior is enforced
+- additional runtime implementations can now target the same vector sets
+
+## Final release expectation
+
+Before calling the proof product fully closed, future implementations should be able to replay the published vectors and reach the same outcomes for:
+
+- canonical event commitments
+- receipt IDs
+- proof-bundle verification
+- adversarial rejection reasons where contractually stable

package/FINAL_CONTRACT.md

@@ -0,0 +1,445 @@
+# xoonya Final Contract
+
+## Purpose
+
+`xoonya` is the neutral proof foundation for machine actions.
+
+It exists to make machine-action evidence:
+
+- deterministic
+- portable
+- minimal
+- verifiable
+- replayable
+- independent of payment rails, settlement systems, and workflow engines
+
+`xoonya` is not a commerce system, policy engine, or execution runtime.
+
+## Public Release Stance
+
+This product is being prepared as a first public release from private lineage.
+
+That means:
+
+- prior internal proof formats are design history, not public obligations
+- useful lineage may be preserved where it strengthens the final product
+- historical private helper shapes do not automatically become the public contract
+
+The public baseline should therefore be chosen for correctness, clarity, determinism, and extensibility, not for backward compatibility with prior private repos.
+
+## Product Boundary
+
+`xoonya` owns:
+
+- canonical event commitment rules
+- canonical hashing rules
+- receipt construction
+- proof bundle construction
+- receipt verification
+- proof bundle verification
+- conformance vectors
+- versioned proof schemas
+
+`xoonya` does not own:
+
+- pricing
+- balances
+- refunds
+- treasury logic
+- workflow semantics
+- task catalogs
+- execution orchestration
+- settlement orchestration
+- market rules
+- governance policy
+
+## Core Doctrine
+
+The proof model is layered.
+
+### Layer 1: Canonical Event Bundle
+
+This is the machine fact being committed.
+
+It is the canonical, deterministic representation of an externally consequential machine event.
+
+### Layer 2: Receipt
+
+This is the minimal commitment artifact.
+
+It proves that a specific identity committed to a specific canonical event commitment under a specific versioned receipt contract.
+
+### Layer 3: Proof Bundle
+
+This carries the richer proof context around the receipt:
+
+- anchors
+- attestation references
+- evidence references
+- batch inclusion material
+- metadata
+
+### Layer 4: Profiles
+
+Profiles are optional domain-specific overlays for things like:
+
+- economic handoff
+- registry lifecycle
+- compliance
+- industry-specific evidence rules
+
+Profiles must not mutate the base proof contract.
+
+## Non-Negotiable Invariants
+
+The following invariants must hold for all final versions.
+
+### 1. Deterministic canonicalization
+
+The same logical event must always produce the same canonical byte representation.
+
+No implementation may depend on:
+
+- locale
+- timezone
+- object insertion order
+- language-specific serializer behavior
+- non-canonical map ordering
+
+### 2. Deterministic hashing
+
+The same canonical event bytes must always yield the same commitment hash.
+
+Hashing must use explicit domain separation.
+
+### 3. Minimal receipt
+
+The receipt must stay small and stable.
+
+It must not absorb:
+
+- economics
+- payment semantics
+- execution transcript detail
+- attestation bodies
+- anchor proofs
+
+### 4. Optional anchoring
+
+Anchoring is optional.
+
+Proof validity must not depend on anchoring.
+
+Anchoring strengthens external assurance and chronology, but does not define whether the receipt is well-formed or verifiable.
+
+### 5. Single machine truth format
+
+There must be one machine-native proof contract.
+
+Human-readable renderings are views or encodings of the same proof objects, not separate proof protocols.
+
+### 6. Versioned stability
+
+Versions are explicit and strict.
+
+Older versions remain historically valid.
+
+New versions must not silently reinterpret older receipts.
+
+## Canonical Event Bundle v1
+
+The canonical event bundle is the fact layer.
+
+Its purpose is to represent an externally consequential machine event in a deterministic and portable way.
+
+### Required fields
+
+- `version`
+- `domain_id`
+- `sequence`
+- `actor_id`
+- `adapter_source`
+- `event_type`
+- `event_hash`
+
+### Optional fields
+
+- `timestamp_ns`
+- `parent_refs`
+- `capability_refs`
+- `attestation_ref`
+- `semantic_slots`
+
+### Rules
+
+- ordering is determined by explicit replay-safe fields, not by timestamps
+- timestamps may exist, but must not define event ordering
+- semantic slots are interpretation hints and must not change the event commitment semantics
+- attestation references are optional and external
+
+### Commitment rule
+
+The canonical event bundle commitment must be derived from the canonical serialized form of the full event bundle object, not from a hand-picked concatenation of selected fields.
+
+This is the preferred rule because it:
+
+- reduces hidden ambiguity
+- reduces implementation drift
+- makes conformance easier to test
+- makes schema evolution cleaner
+
+## Receipt v1
+
+The receipt is the minimal commitment artifact.
+
+### Purpose
+
+The receipt proves:
+
+- which proof contract version applies
+- which identity issued the commitment
+- which canonical event commitment is being committed
+- that the issuer signed or committed that event commitment
+
+### Required fields
+
+- `version`
+- `receipt_id`
+- `agent_identity`
+- `domain_id`
+- `sequence`
+- `event_commitment`
+- `signature`
+
+### Optional fields
+
+- `algorithm`
+
+### Rules
+
+- `receipt_id` must be deterministic or derivable in a stable way
+- `agent_identity` must be a stable identity reference, not a commerce-specific account handle
+- `event_commitment` must equal the canonical event bundle commitment
+- `signature` must verify against the exact commitment material defined by the contract
+
+### Explicit exclusions
+
+The receipt must not directly carry:
+
+- prices
+- balances
+- refunds
+- quote details
+- settlement details
+- anchor records
+- Merkle paths
+- attestation bodies
+- execution transcripts
+
+## Proof Bundle v1
+
+The proof bundle is the portable richer proof container.
+
+### Required fields
+
+- `ceb`
+- `receipt`
+
+### Optional fields
+
+- `anchors`
+- `attestations`
+- `evidence_refs`
+- `batch_refs`
+- `metadata`
+
+### Purpose
+
+The proof bundle is where richer proof and portability features live without bloating the receipt.
+
+This is the correct place for:
+
+- chain or ledger anchors
+- block references
+- batch roots
+- inclusion proofs
+- external evidence references
+- optional attestation references
+
+### Rules
+
+- the receipt remains valid without a proof bundle
+- the proof bundle must never alter the meaning of the receipt
+- all optional fields must be additive, not redefining
+
+## Attestation Relationship
+
+Attestation is separate from proof.
+
+`xoonya` may reference attestation material, commit to attestation hashes, and verify attestation-shaped adjuncts if needed, but attestation must remain conceptually separate from the receipt core.
+
+### Rule
+
+Attestation may be consumed.
+It must not become the receipt.
+
+## Profiles
+
+Profiles are optional structured overlays built on top of base proof primitives.
+
+Examples:
+
+- economic receipt profile
+- registry lifecycle profile
+- compliance profile
+
+### Profile rule
+
+Profiles may:
+
+- reference receipts
+- reference proof bundles
+- define domain-specific payload semantics
+- define domain-specific verification logic
+
+Profiles may not:
+
+- redefine base receipt meaning
+- redefine canonical event bundle meaning
+- create hidden alternate proof cores
+
+## Batching
+
+Batching is supported, but not part of the minimal receipt core.
+
+### Rule
+
+Multiple proof commitments may be compressed into a deterministic batch root.
+
+Batch-related material belongs in:
+
+- proof bundle
+- batch metadata
+- inclusion proofs
+- anchor references
+
+not in the base receipt itself.
+
+## Verification Contract
+
+Verification must produce deterministic outcomes.
+
+### Verification result fields
+
+- `ok`
+- `code`
+- `message`
+- optional `details`
+
+### Canonical failure classes
+
+- invalid schema
+- unsupported version
+- hash mismatch
+- signature mismatch
+- receipt mismatch
+- bundle mismatch
+- profile mismatch
+
+### Rule
+
+The same invalid input must fail the same way across conformant implementations.
+
+## Versioning Strategy
+
+### v1
+
+Freeze:
+
+- canonical event bundle v1
+- receipt v1
+- proof bundle v1
+- verification result contract v1
+
+### Future versions
+
+A new version is justified only when:
+
+- commitment semantics change
+- canonicalization semantics change
+- identity/signature semantics change in a breaking way
+- proof container semantics change in a breaking way
+
+New profiles do not require a new core proof version unless they change base semantics.
+
+## Conformance Requirements
+
+Any implementation claiming compatibility must pass:
+
+- canonicalization vectors
+- hashing vectors
+- receipt creation vectors
+- receipt verification vectors
+- proof bundle verification vectors
+- adversarial vectors
+
+### Adversarial vector classes
+
+- field ordering drift
+- null / absent field ambiguity
+- unicode normalization edge cases
+- timestamp representation drift
+- duplicate proof entries
+- wrong anchor references
+- wrong batch inclusion paths
+- signature mismatch
+- tampered metadata
+- version mismatch
+
+## Public API Direction
+
+The public API of `xoonya` should center on:
+
+- `canonicalizeEvent`
+- `hashEvent`
+- `emitReceipt`
+- `verifyReceipt`
+- `buildProofBundle`
+- `verifyProofBundle`
+
+Optional profile helpers may be added separately.
+
+## What Should Be Carried Forward From Older Proof Lineage
+
+Keep:
+
+- minimal commitment philosophy
+- strict domain separation
+- optional anchoring
+- proof envelope / bundle layering
+- additive profile concept
+- strong conformance vector discipline
+
+Do not freeze directly:
+
+- historical internal names
+- historical version labels
+- exact old byte-count decisions as sacred
+- old rail-shaped assumptions
+
+## Final Product Position
+
+`xoonya` should become:
+
+- the neutral machine truth layer
+- the portable proof layer
+- the deterministic evidence layer
+
+It should be usable:
+
+- independently of `xytara`
+- independently of any chain
+- independently of any specific payment rail
+- independently of any specific runtime
+
+That independence is the foundation of the whole stack.

package/README.md

@@ -12,6 +12,31 @@ It exists to make machine evidence:
 
 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](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/START_HERE.md)
+2. run `node examples/package_quickstart.js`
+3. run `npm run verify:all`
+4. use [FINAL_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/FINAL_CONTRACT.md) and [SERVICE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/SERVICE_CONTRACT.md) as the durable public contract
+
+If you are integrating from outside the stack, also read:
+
+- [CROSS_RUNTIME_POSTURE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/CROSS_RUNTIME_POSTURE.md)
+- [integrations/PROOF_INTEGRATION_PROCESS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/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
@@ -130,6 +155,34 @@ Primary proof-model routes:
 - `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`
@@ -187,6 +240,25 @@ It now also exposes a handoff-intake summary and handoff-intake-boundary summary
 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
@@ -258,6 +330,15 @@ The current `1.25.0` line starts turning that adapter-ready default path into a
 - 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](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/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`