xoonya 3.0.1 → 3.1.0

package/XOONYA_FOLLOWTHROUGH_TRUTH_MODEL.md

@@ -1,63 +1,63 @@
-# xoonya Followthrough Truth Model
-
-`xoonya` cannot reach a truthful `3.0.0` if its followthrough story is left as scattered bridge, governance, trust-portability, and verification endpoints.
-
-For the public launch line, it needs one frozen answer to:
-
-- what proof-side followthrough is publicly claimable
-- what trust portability is real and bounded
-- what bridge carry is real and bounded
-- what governance and dispute posture is real and bounded
-- what must remain outside the public `xoonya` claim boundary
-
-## Core Rule
-
-All public followthrough claims must stay inside one bounded proof-side truth:
-
-`verify -> carry -> review -> govern -> preserve continuity`
-
-`xoonya` may expose many helper routes.
-It may not imply unbounded scope.
-
-## Covered Followthrough Families
-
-The frozen `3.0.0` followthrough truth model covers:
-
-- verification services
-- trust portability
-- bridge followthrough
-- governance followthrough
-
-## What This Model Allows Us To Claim
-
-We can publicly claim:
-
-- proof bundles, receipts, and handoffs can be verified and replayed through real public surfaces
-- trust can remain portable across the listed identity, delegation, delivery, and settlement-linked review lanes
-- bridge carry can preserve operator and compatibility review without becoming the runtime owner
-- governance can preserve disputes, signoff, interpretation, and handoff continuity without pretending to be universal legal truth
-
-## What This Model Does Not Allow Us To Claim
-
-We do not publicly claim:
-
-- unbounded runtime execution truth
-- universal external chain truth
-- universal custody truth
-- universal identity truth
-- universal legal or regulatory judgment truth
-
-## Machine-Readable Surfaces
-
-- `GET /v1/followthrough-truth`
-- `GET /v1/followthrough-truth/summary`
-- `GET /v1/followthrough-truth/:profile_id`
-
-## Launch Standard
-
-For `3.0.0`, this model is considered real only if:
-
-- each listed profile has callable first-party surfaces
-- each listed profile stays attached to proof truth and proof review
-- each listed profile has an explicit claim boundary
-- no launch copy overstates `xoonya` beyond these frozen followthrough profiles
+# xoonya Followthrough Truth Model
+
+`xoonya` cannot reach a truthful `3.0.0` if its followthrough story is left as scattered bridge, governance, trust-portability, and verification endpoints.
+
+For the public launch line, it needs one frozen answer to:
+
+- what proof-side followthrough is publicly claimable
+- what trust portability is real and bounded
+- what bridge carry is real and bounded
+- what governance and dispute posture is real and bounded
+- what must remain outside the public `xoonya` claim boundary
+
+## Core Rule
+
+All public followthrough claims must stay inside one bounded proof-side truth:
+
+`verify -> carry -> review -> govern -> preserve continuity`
+
+`xoonya` may expose many helper routes.
+It may not imply unbounded scope.
+
+## Covered Followthrough Families
+
+The frozen `3.0.0` followthrough truth model covers:
+
+- verification services
+- trust portability
+- bridge followthrough
+- governance followthrough
+
+## What This Model Allows Us To Claim
+
+We can publicly claim:
+
+- proof bundles, receipts, and handoffs can be verified and replayed through real public surfaces
+- trust can remain portable across the listed identity, delegation, delivery, and settlement-linked review lanes
+- bridge carry can preserve operator and compatibility review without becoming the runtime owner
+- governance can preserve disputes, signoff, interpretation, and handoff continuity without pretending to be universal legal truth
+
+## What This Model Does Not Allow Us To Claim
+
+We do not publicly claim:
+
+- unbounded runtime execution truth
+- universal external chain truth
+- universal custody truth
+- universal identity truth
+- universal legal or regulatory judgment truth
+
+## Machine-Readable Surfaces
+
+- `GET /v1/followthrough-truth`
+- `GET /v1/followthrough-truth/summary`
+- `GET /v1/followthrough-truth/:profile_id`
+
+## Launch Standard
+
+For `3.0.0`, this model is considered real only if:
+
+- each listed profile has callable first-party surfaces
+- each listed profile stays attached to proof truth and proof review
+- each listed profile has an explicit claim boundary
+- no launch copy overstates `xoonya` beyond these frozen followthrough profiles

package/XOONYA_NATIVE_ATOM_SPEC.md

@@ -1,184 +1,184 @@
-# xoonya Native Atom Specification
-
-Status: formal spec pack active
-
-Spec version: `xoonya-native-atom-spec/v1`
-
-## Decision
-
-The canonical xoonya Native atom magic is `XNYA`.
-
-No other magic value is part of the xoonya Native atom standard. Implementations that use a different discriminator are separate formats and must not claim xoonya Native atom compatibility.
-
-`XNYA` is four bytes, not three, because a fixed 4-byte ASCII discriminator is easier to index, validate, debug, and defend than a shorter clever header.
-
-## Repository Strategy
-
-The native atom spec ships inside the `xoonya` package first.
-
-This is intentional:
-
-- there is one public website and one xoonya package surface today
-- the verifier implementation and conformance vectors live beside the spec
-- builders should not need another repo to understand the native proof path
-
-A separate standards repo can be created later if external adoption, independent governance, or standards-body work needs it. Until then, separate extraction would add coordination overhead before the standard has enough external pressure to justify it.
-
-## Atom Purpose
-
-The xoonya Native atom is a fixed-size commitment record.
-
-It answers:
-
-> Which typed machine identity committed to which payload hash under which frozen xoonya Native version line?
-
-It does not contain:
-
-- signatures
-- timestamps
-- prices
-- balances
-- settlement references
-- custody references
-- chain identifiers
-- runtime metadata
-- policy decisions
-- governance outcomes
-
-Those belong in canonical payloads, proof envelopes, profiles, and runtime consumers.
-
-## Version 1
-
-Atom version: `xoonya-native-atom/v1`
-
-Fixed size: `58` bytes
-
-Purpose: classical minimal identity and payload commitment.
-
-Layout:
-
-```text
-MAGIC(4) | VERSION(1) | TYPE(1) | AGENT_ID(20) | PAYLOAD_HASH(32)
-```
-
-Fields:
-
-| Field | Size | Rule |
-| --- | ---: | --- |
-| `MAGIC` | 4 | ASCII `XNYA` |
-| `VERSION` | 1 | `0x01` |
-| `TYPE` | 1 | `0x01`, `0x02`, or `0x03` |
-| `AGENT_ID` | 20 | `HASH160("xoonya:agent:v1:" || identity_material)` |
-| `PAYLOAD_HASH` | 32 | `SHA256("xoonya:payload:v1:" || payload_bytes)` or all-zero sentinel when absent |
-
-## Version 2
-
-Atom version: `xoonya-native-atom/v2`
-
-Fixed size: `70` bytes
-
-Purpose: PQ-horizon identity commitment with 32-byte agent digest.
-
-Layout:
-
-```text
-MAGIC(4) | VERSION(1) | TYPE(1) | AGENT_ID(32) | PAYLOAD_HASH(32)
-```
-
-Fields:
-
-| Field | Size | Rule |
-| --- | ---: | --- |
-| `MAGIC` | 4 | ASCII `XNYA` |
-| `VERSION` | 1 | `0x02` |
-| `TYPE` | 1 | `0x01`, `0x02`, or `0x03` |
-| `AGENT_ID` | 32 | `SHA256("xoonya:agent:v2:" || identity_material)` |
-| `PAYLOAD_HASH` | 32 | `SHA256("xoonya:payload:v2:" || payload_bytes)` or all-zero sentinel when absent |
-
-## Record Types
-
-| Code | Name | Meaning |
-| --- | --- | --- |
-| `0x01` | register | registration or first commitment |
-| `0x02` | update | update or lifecycle continuation |
-| `0x03` | revoke | revoke or lifecycle close |
-
-The atom does not define lifecycle policy. Profiles define evidence semantics above the atom.
-
-## Identity Material
-
-`identity_material = type_prefix || raw_identity_bytes`
-
-Initial type registry:
-
-| Prefix | ID | Canonical Material |
-| --- | --- | --- |
-| `0x01` | `secp256k1-public-key` | compressed SEC1 public key |
-| `0x02` | `device-identifier` | raw device identifier bytes |
-| `0x03` | `did-string` | UTF-8 DID string, no BOM, no normalization |
-| `0x04` | `opaque-agent-key` | opaque agent key bytes |
-| `0x05` | `dilithium-public-key` | suite-defined PQ public key bytes |
-| `0x06` | `falcon-public-key` | suite-defined PQ public key bytes |
-| `0x07` | `sphincs-plus-public-key` | suite-defined PQ public key bytes |
-
-Implementations must not lowercase, normalize, trim, parse, or reinterpret `raw_identity_bytes` after canonicalization by the type-specific producer.
-
-## Payload Sentinel Rule
-
-If there is no payload, `PAYLOAD_HASH` is exactly 32 zero bytes.
-
-If payload bytes are present, implementations must compute the domain-separated payload hash and must not accept a present payload as the all-zero sentinel.
-
-## Validation Rules
-
-Validators must reject:
-
-- non-hex display input
-- byte length other than 58 or 70
-- bad magic
-- version/length mismatch
-- unsupported type
-- unsupported identity type prefix when identity material is supplied
-- agent ID mismatch when identity material is supplied
-- payload hash mismatch when payload bytes are supplied
-- ambiguous all-zero payload hash for a present payload
-
-Validation must be deterministic: the same bytes produce the same accept/reject reason.
-
-## Deterministic Error Codes
-
-Validators should return stable machine-readable error codes alongside any human-readable reason.
-
-Current reject codes:
-
-| Code | Meaning |
-| --- | --- |
-| `atom_hex_not_hex` | Input is not hex display form. |
-| `atom_unsupported_length` | Byte length is not a supported XNYA atom length. |
-| `atom_bad_magic` | Magic is not `XNYA`. |
-| `atom_unsupported_record_type` | Record type is not `0x01`, `0x02`, or `0x03`. |
-| `atom_version_length_mismatch` | Version byte and atom length do not match. |
-| `identity_unsupported_type_prefix` | Supplied identity material uses an unregistered prefix. |
-| `identity_missing_raw_bytes` | Supplied identity material contains only the type prefix. |
-| `agent_id_mismatch` | Supplied identity material does not derive the atom agent id. |
-| `payload_hash_mismatch` | Supplied payload bytes do not derive the atom payload hash. |
-
-Error-code stability matters because third-party validators and agents should be able to compare failures without parsing prose.
-
-## Version Freeze Rule
-
-Once a version line is published:
-
-- field order must not change
-- field sizes must not change
-- hash derivation must not change
-- validation semantics must not change
-- reserved behavior must not be silently introduced
-
-Any breaking change requires a new version line.
-
-## V3 Contingency
-
-`xoonya-native-atom/v3-contingency` is not an implementation target.
-
-It is reserved for a material digest-family shift, such as a practical break in SHA-256 assumptions. If it is ever needed, it should remain fixed length, deterministic, and semantic-free.
+# xoonya Native Atom Specification
+
+Status: formal spec pack active
+
+Spec version: `xoonya-native-atom-spec/v1`
+
+## Decision
+
+The canonical xoonya Native atom magic is `XNYA`.
+
+No other magic value is part of the xoonya Native atom standard. Implementations that use a different discriminator are separate formats and must not claim xoonya Native atom compatibility.
+
+`XNYA` is four bytes, not three, because a fixed 4-byte ASCII discriminator is easier to index, validate, debug, and defend than a shorter clever header.
+
+## Repository Strategy
+
+The native atom spec ships inside the `xoonya` package first.
+
+This is intentional:
+
+- there is one public website and one xoonya package surface today
+- the verifier implementation and conformance vectors live beside the spec
+- builders should not need another repo to understand the native proof path
+
+A separate standards repo can be created later if external adoption, independent governance, or standards-body work needs it. Until then, separate extraction would add coordination overhead before the standard has enough external pressure to justify it.
+
+## Atom Purpose
+
+The xoonya Native atom is a fixed-size commitment record.
+
+It answers:
+
+> Which typed machine identity committed to which payload hash under which frozen xoonya Native version line?
+
+It does not contain:
+
+- signatures
+- timestamps
+- prices
+- balances
+- settlement references
+- custody references
+- chain identifiers
+- runtime metadata
+- policy decisions
+- governance outcomes
+
+Those belong in canonical payloads, proof envelopes, profiles, and runtime consumers.
+
+## Version 1
+
+Atom version: `xoonya-native-atom/v1`
+
+Fixed size: `58` bytes
+
+Purpose: classical minimal identity and payload commitment.
+
+Layout:
+
+```text
+MAGIC(4) | VERSION(1) | TYPE(1) | AGENT_ID(20) | PAYLOAD_HASH(32)
+```
+
+Fields:
+
+| Field | Size | Rule |
+| --- | ---: | --- |
+| `MAGIC` | 4 | ASCII `XNYA` |
+| `VERSION` | 1 | `0x01` |
+| `TYPE` | 1 | `0x01`, `0x02`, or `0x03` |
+| `AGENT_ID` | 20 | `HASH160("xoonya:agent:v1:" || identity_material)` |
+| `PAYLOAD_HASH` | 32 | `SHA256("xoonya:payload:v1:" || payload_bytes)` or all-zero sentinel when absent |
+
+## Version 2
+
+Atom version: `xoonya-native-atom/v2`
+
+Fixed size: `70` bytes
+
+Purpose: PQ-horizon identity commitment with 32-byte agent digest.
+
+Layout:
+
+```text
+MAGIC(4) | VERSION(1) | TYPE(1) | AGENT_ID(32) | PAYLOAD_HASH(32)
+```
+
+Fields:
+
+| Field | Size | Rule |
+| --- | ---: | --- |
+| `MAGIC` | 4 | ASCII `XNYA` |
+| `VERSION` | 1 | `0x02` |
+| `TYPE` | 1 | `0x01`, `0x02`, or `0x03` |
+| `AGENT_ID` | 32 | `SHA256("xoonya:agent:v2:" || identity_material)` |
+| `PAYLOAD_HASH` | 32 | `SHA256("xoonya:payload:v2:" || payload_bytes)` or all-zero sentinel when absent |
+
+## Record Types
+
+| Code | Name | Meaning |
+| --- | --- | --- |
+| `0x01` | register | registration or first commitment |
+| `0x02` | update | update or lifecycle continuation |
+| `0x03` | revoke | revoke or lifecycle close |
+
+The atom does not define lifecycle policy. Profiles define evidence semantics above the atom.
+
+## Identity Material
+
+`identity_material = type_prefix || raw_identity_bytes`
+
+Initial type registry:
+
+| Prefix | ID | Canonical Material |
+| --- | --- | --- |
+| `0x01` | `secp256k1-public-key` | compressed SEC1 public key |
+| `0x02` | `device-identifier` | raw device identifier bytes |
+| `0x03` | `did-string` | UTF-8 DID string, no BOM, no normalization |
+| `0x04` | `opaque-agent-key` | opaque agent key bytes |
+| `0x05` | `dilithium-public-key` | suite-defined PQ public key bytes |
+| `0x06` | `falcon-public-key` | suite-defined PQ public key bytes |
+| `0x07` | `sphincs-plus-public-key` | suite-defined PQ public key bytes |
+
+Implementations must not lowercase, normalize, trim, parse, or reinterpret `raw_identity_bytes` after canonicalization by the type-specific producer.
+
+## Payload Sentinel Rule
+
+If there is no payload, `PAYLOAD_HASH` is exactly 32 zero bytes.
+
+If payload bytes are present, implementations must compute the domain-separated payload hash and must not accept a present payload as the all-zero sentinel.
+
+## Validation Rules
+
+Validators must reject:
+
+- non-hex display input
+- byte length other than 58 or 70
+- bad magic
+- version/length mismatch
+- unsupported type
+- unsupported identity type prefix when identity material is supplied
+- agent ID mismatch when identity material is supplied
+- payload hash mismatch when payload bytes are supplied
+- ambiguous all-zero payload hash for a present payload
+
+Validation must be deterministic: the same bytes produce the same accept/reject reason.
+
+## Deterministic Error Codes
+
+Validators should return stable machine-readable error codes alongside any human-readable reason.
+
+Current reject codes:
+
+| Code | Meaning |
+| --- | --- |
+| `atom_hex_not_hex` | Input is not hex display form. |
+| `atom_unsupported_length` | Byte length is not a supported XNYA atom length. |
+| `atom_bad_magic` | Magic is not `XNYA`. |
+| `atom_unsupported_record_type` | Record type is not `0x01`, `0x02`, or `0x03`. |
+| `atom_version_length_mismatch` | Version byte and atom length do not match. |
+| `identity_unsupported_type_prefix` | Supplied identity material uses an unregistered prefix. |
+| `identity_missing_raw_bytes` | Supplied identity material contains only the type prefix. |
+| `agent_id_mismatch` | Supplied identity material does not derive the atom agent id. |
+| `payload_hash_mismatch` | Supplied payload bytes do not derive the atom payload hash. |
+
+Error-code stability matters because third-party validators and agents should be able to compare failures without parsing prose.
+
+## Version Freeze Rule
+
+Once a version line is published:
+
+- field order must not change
+- field sizes must not change
+- hash derivation must not change
+- validation semantics must not change
+- reserved behavior must not be silently introduced
+
+Any breaking change requires a new version line.
+
+## V3 Contingency
+
+`xoonya-native-atom/v3-contingency` is not an implementation target.
+
+It is reserved for a material digest-family shift, such as a practical break in SHA-256 assumptions. If it is ever needed, it should remain fixed length, deterministic, and semantic-free.