xoonya 3.0.0 → 3.1.0

package/FINAL_CONTRACT.md

@@ -1,445 +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.
-
-That means:
-
-- prior proof formats are design history, not public obligations
-- useful earlier decisions may be preserved where they strengthen the final product
-- older 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 Earlier Proof Iterations
-
-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 implementation 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.
+# 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.
+
+That means:
+
+- prior proof formats are design history, not public obligations
+- useful earlier decisions may be preserved where they strengthen the final product
+- older 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 Earlier Proof Iterations
+
+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 implementation 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.