xoonya 2.4.0 → 2.6.0

package/README.md

@@ -1,6 +1,6 @@
 # xoonya
 
-`xoonya` is the proof foundation for machine actions.
+`xoonya` is the proof and review foundation for machine actions.
 
 It exists to make machine evidence:
 
@@ -14,6 +14,63 @@ 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 Boundary
+
+The public adoption story is intentionally narrow:
+
+- receive a handoff or event bundle
+- review it
+- verify it
+- emit a durable proof bundle
+
+`xoonya` should expose proof, review, and continuity. It should not force outside builders to learn runtime treasury or operator internals just to use the proof layer correctly.
+
+## Universal Proof Shape
+
+`xoonya` is intended to be usable from:
+
+- CLI and terminal
+- direct API calls
+- chat and agent environments that can submit handoff bundles
+- hosted or embedded review flows
+- partner systems that need deterministic proof verification
+
+The shortest public proof loop is:
+
+- receive a handoff or event bundle
+- review it
+- verify it
+- emit a durable proof bundle
+- preserve governance and continuity context when needed
+
+The current proof breadth already includes:
+
+- canonical events, receipts, and proof bundles
+- result-package handoff review and run paths
+- bridge and compatibility review surfaces
+- governance, dispute, and signoff support
+- proof-side continuity for economic consequence carry
+- proof-adjacent integration registration and review
+
+## One-Line After Install
+
+If you only run two commands after install, use:
+
+- `xoonya start-here`
+- `xoonya first-run`
+- `xoonya first-run --verify-native --pretty`
+- `xoonya release --summary`
+- `xoonya conformance`
+
+If you want the shortest machine-readable discovery path, inspect:
+
+- `GET /v1/providers`
+- `GET /v1/frameworks`
+- `GET /v1/integration-matrix`
+- `GET /v1/proof-bridge`
+- `GET /v1/telemetry`
+- `GET /v1/provenance`
+
 ## Start Here
 
 If you are new to the proof-side package, use this order:
@@ -23,13 +80,10 @@ If you are new to the proof-side package, use this order:
 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 evaluating the post-program operating posture, read:
+If you are reading the GitHub repo and want deeper product context beyond the npm starter path, continue with:
 
-- [PROGRAM_STATUS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/PROGRAM_STATUS.md)
-- [OPERATOR_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/OPERATOR_START_HERE.md)
-- [OPERATIONS_RUNBOOK.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/OPERATIONS_RUNBOOK.md)
-- [PROGRAM_COMPLETE_RELEASE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/PROGRAM_COMPLETE_RELEASE.md)
 - [WHY_XYTARA_XOONYA.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/WHY_XYTARA_XOONYA.md)
+- [PARTNER_READY_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/PARTNER_READY_PATH.md)
 
 If you want one concrete cross-repo adoption story, start with:
 
@@ -172,6 +226,45 @@ That means the center of gravity is now:
 - `emitReceipt(...)`
 - `buildProofBundle(...)`
 - `verifyProofBundle(...)`
+- `listProofVerificationMethods(...)`
+- `getProofVerificationMethod(...)`
+
+### Verification Methods
+
+`xoonya` keeps proof verification method-agnostic. The proof bundle verifier uses a small method registry instead of treating every non-empty signature as equally verified.
+
+Current built-in methods:
+
+- `legacy-opreturn-v1` verifies the compatibility OP_RETURN receipt path.
+- `detached-assertion-v1` accepts an explicit detached assertion after canonical receipt checks; cryptographic verification is expected to happen outside this helper.
+- `xoonya-native-sha256-v1` verifies Xoonya's native deterministic digest format.
+- `xoonya-native-signed-v1` verifies Xoonya's native signed proof envelope with Ed25519, secp256k1, and P-256 implemented through the explicit suite registry. Other suites stay registry-only until validators exist.
+- `xoonya-native-anchored-v1` verifies Xoonya's native anchor-binding proof envelope for chain, batch, finality, content-hash, or external attestation refs. It verifies the binding, not the external provider or chain truth itself.
+- `jwt-assertion-v1` accepts compact JWT assertion envelopes after canonical receipt checks; JWT signature, issuer, and audience verification remain external to this helper.
+- `did-vc-v1` accepts DID/VC proof envelopes after canonical receipt checks; DID resolution and VC proof validation remain external to this helper.
+- `sd-jwt-vc-v1` accepts SD-JWT VC disclosure envelopes after canonical receipt checks; issuer, holder binding, and disclosure verification remain external to this helper.
+- `signed-envelope-v1` accepts generic signed envelopes after canonical receipt checks; envelope-specific signature verification remains external to this helper.
+- `partner-proof-envelope-v1` accepts partner-specific proof envelopes after canonical receipt checks; partner verifier policy remains external to this helper.
+
+`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.
+
+### 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.
+
+The native standard is Xoonya's own fixed-size hot-path commitment atom, cold-path proof envelope, semantic-free core bytes, and deterministic validation. The current implemented native methods are `xoonya-native-sha256-v1`, `xoonya-native-signed-v1`, and `xoonya-native-anchored-v1`. The signed native method verifies Ed25519, secp256k1, and P-256 today and keeps PQ/hybrid suites in the registry until their validators are implemented, so the standard stays agnostic without overclaiming. The anchored native method binds receipts to declared anchor/finality/attestation refs without claiming the external system has been independently verified by Xoonya.
+
+The atom ladder is treated as native Xoonya design, not a runtime dependency: `xoonya-native-atom/v1` is the 58-byte classical commitment atom, `xoonya-native-atom/v2` is the 70-byte PQ-horizon identity commitment candidate, and `xoonya-native-atom/v3-contingency` stays reserved for a future digest-family shift only if the underlying hash assumptions materially change.
+
+The canonical Xoonya Native atom magic is `XNYA`. No other magic value is part of the Xoonya Native atom standard. The formal atom spec ships inside the `xoonya` package first; a separate standards repo can be extracted later if external governance needs it.
+
+XNYA atom conformance now includes stable machine-readable reject codes and adversarial vectors. Passing only the happy-path vectors is not enough to claim Xoonya Native compatibility.
+
+The native payload profile is now explicit: `xoonya-native-payload-profile/v1` uses the binary `XNYP` magic and typed fields with deterministic ordering, fixed-width integer encoding, unknown-field policy checks, and no floats or loose JSON semantics. The optional `xoonya-native-line-rate-frame/v1` wraps an existing 58-byte or 70-byte `XNYA` atom with a 2-byte checksum for transport fast rejection; it does not change the atom and does not claim signature, encryption, custody, settlement, or external finality truth.
+
+See [XOONYA_NATIVE_PROOF_FORMAT.md](./XOONYA_NATIVE_PROOF_FORMAT.md).
+See [XOONYA_NATIVE_ATOM_SPEC.md](./XOONYA_NATIVE_ATOM_SPEC.md).
+See [XOONYA_NATIVE_STANDARD_GOVERNANCE.md](./XOONYA_NATIVE_STANDARD_GOVERNANCE.md).
 
 ## Compatibility Surface
 
@@ -183,6 +276,9 @@ Legacy compact receipt and profile helpers are still available during alignment:
 - `verifyReceiptV2(...)`
 - `createProofEnvelopeV1(...)`
 - `verifyProofEnvelopeV1(...)`
+- `createXoonyaNativeAtomV1(...)`
+- `createXoonyaNativeAtomV2(...)`
+- `verifyXoonyaNativeAtom(...)`
 - `createEconomicReceiptProfileV1(...)`
 - `verifyEconomicReceiptProfileV1(...)`
 - `createRegistryProfileV1(...)`
@@ -238,6 +334,23 @@ Primary proof-model routes:
 - `GET /health`
 - `GET /v1/proof-center`
 - `GET /v1/proof-center/summary`
+- `GET /v1/proof-center/native-standard`
+- `GET /v1/proof-center/native-standard/summary`
+- `GET /v1/proof-center/native-atom-spec`
+- `GET /v1/proof-center/native-atom-spec/summary`
+- `GET /v1/proof-center/native-atom-conformance`
+- `GET /v1/proof-center/native-atom-conformance/summary`
+- `GET /v1/proof-center/native-anchor-profile`
+- `GET /v1/proof-center/native-anchor-profile/summary`
+- `GET /v1/proof-center/native-payload-profile`
+- `GET /v1/proof-center/native-payload-profile/summary`
+- `GET /v1/proof-center/native-line-rate-frame`
+- `GET /v1/proof-center/native-line-rate-frame/summary`
+- `GET /v1/proof-center/import-adapter`
+- `GET /v1/proof-center/import-adapter/summary`
+- `POST /v1/proof-center/import-adapter/review`
+- `POST /v1/proof-center/import-adapter/review/summary`
+- `POST /v1/proof-center/import-adapter/run`
 - `GET /v1/proof-center/default-loops`
 - `GET /v1/proof-center/default-loops/summary`
 - `GET /v1/proof-center/default-loop`
@@ -460,6 +573,7 @@ Preserved compatibility routes:
 Local verification commands:
 
 - `npm run verify:package`
+- `npm run verify:conformance`
 - `npm run verify:vectors`
 - `npm run verify:examples`
 - `npm run verify:service`
@@ -473,11 +587,21 @@ The current verification covers:
 - package export presence
 - deterministic event hashing
 - proof-bundle tamper detection
+- public conformance CLI execution through `xoonya conformance --json`
 - published conformance vectors
 - published adversarial vectors
 - package quickstart flow
 - service routes for both the primary proof model and the legacy compatibility layer
 
+Public conformance command:
+
+```bash
+xoonya conformance
+xoonya conformance --json
+```
+
+The conformance command verifies the published vector files shipped in the package. The positive set covers `legacy-opreturn-v1`, `detached-assertion-v1`, `xoonya-native-sha256-v1`, `xoonya-native-signed-v1`, `xoonya-native-anchored-v1`, `jwt-assertion-v1`, `did-vc-v1`, `sd-jwt-vc-v1`, `signed-envelope-v1`, and `partner-proof-envelope-v1`. The adversarial set covers bad event versions, missing signatures, mismatched commitments, unsupported methods, ambiguous `none`, replayed receipt context, native digest tampering, native signed proof tampering, native anchored proof tampering, native-to-detached downgrade attempts, and receipt-id mismatches.
+
 Published proof hardening artifacts:
 
 - [conformance-vectors.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/vectors/conformance-vectors.json)
@@ -497,8 +621,12 @@ Published proof hardening artifacts:
 `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
+- attestation and evidence reference adapters
+- anchor reference adapters
 - profile verification helpers
+- compatibility-oriented proof integrations
+
+This integration toolkit is broader than the proof verification method registry. Verification methods describe how a receipt or proof envelope is admitted at the proof boundary; integrations describe additive proof-side helpers, references, profiles, and staged third-party support that can be reviewed without changing the proof kernel.
 
 The package now includes:
 

package/RELEASE_NOTES.md

@@ -1,31 +1,40 @@
-# xoonya 2.4.0 Release Notes
+# xoonya 2.6.0 Release Notes
 
-`xoonya` 2.4.0 is the proof-role freeze and transition-clarity line.
+`xoonya` 2.6.0 is the expansion release line for Xoonya Native standard hardening, external proof import, native signed and anchored verification, and strict XNYA payload/frame profile work.
 
 Highlights:
 
-- direct one-line proof-side review with `xoonya-review`
-- trust intelligence for proof readiness, bridge confidence, and recommended review motion
-- review intelligence for governance burden, dispute risk, and dependency posture
-- governance intelligence for escalation, signoff, and handoff continuity
-- bridge intelligence for compatibility strength and bridge coverage posture
-- explicit proof-role freeze, operator bundle, policy pack, and package surfaces
-- explicit role-transition package recording long-term coordination-shell direction
-- explicit capability-registry-home package recording `xytara` as current home and `xoonya` as the later canonical target
-- canonical event, receipt, and proof-bundle model with stable runtime-to-proof followthrough
-- partner-ready onboarding, launch docs, and public example paths remain in place
+- umbrella CLI entrypoint with `xoonya start-here`, plus `xoonya review` and `xoonya release`
+- `xoonya-native-signed-v1` verification with Ed25519, secp256k1, and P-256 through the explicit signature-suite registry
+- `xoonya-native-anchored-v1` anchor binding for chain, finality, batch, content-hash, and external attestation refs without claiming external provider truth
+- `xoonya-native-payload-profile/v1` with `XNYP` binary payload canonicalization, typed fields, fixed-width integers, canonical ordering, and unknown-field policy checks
+- `xoonya-native-line-rate-frame/v1` as an optional 60/72-byte transport fast-reject wrapper around existing `XNYA` atoms
+- native payload profile vectors and line-rate frame vectors
+- external proof import adapter for JWT, DID/VC, SD-JWT VC, detached assertions, signed envelopes, and partner proof envelopes
+- native hybrid/PQ readiness and standardization packs that keep `xoonya-native-hybrid-v1` design-gated until validators and vectors are real
+- first-class public contract lanes for `OpenAPI`, `AsyncAPI`, and `CloudEvents`
+- first-class provider, framework, and integration-matrix discovery surfaces for the proof side
+- surfaced proof breadth across `proof-bridge`, `external-proof-import`, `result-package-trust`, major rails, treasury, and registry-backed integrations
+- surfaced observability, provenance, artifact-distribution, shared-signals, and feature-control lanes for proof operations and trust
+- explicit proof-role freeze, role-transition, and capability-registry-home posture remain in place
+- canonical event, receipt, and proof-bundle model remain the proof center while external compatibility stays adapter-friendly
+- clearer install-and-use posture for reviewers, operators, outside builders, and proof-carry integrations
 
 Recommended first checks:
 
 1. `npm install xoonya`
-2. `xoonya-release --candidate --summary`
+2. `xoonya start-here`
 3. `npm run verify:release-candidate`
 4. `node examples/partner_proof_walkthrough.js`
-5. inspect `/v1/role-freeze/package`
-6. inspect `/v1/role-transition`
-7. inspect `/v1/capability-registry-home`
-8. inspect `/v1/trust-intelligence` and `/v1/review-intelligence`
-9. inspect `/v1/proof-center/summary` on the deployed service
+5. inspect `/v1/proof-center/native-standard/summary`
+6. inspect `/v1/proof-center/native-payload-profile/summary`
+7. inspect `/v1/proof-center/native-line-rate-frame/summary`
+8. inspect `/v1/proof-center/import-adapter/summary`
+9. inspect `/v1/providers`, `/v1/frameworks`, `/v1/integration-matrix`, and `/v1/proof-bridge`
+10. inspect `/v1/telemetry`, `/v1/provenance`, `/v1/artifact-distribution`, `/v1/shared-signals`, and `/v1/feature-control`
+11. inspect `/v1/role-freeze/package`
+12. inspect `/v1/role-transition` and `/v1/capability-registry-home`
+13. inspect `/v1/proof-center/summary` on the deployed service
 
 Recommended first docs:
 

package/SERVICE_CONTRACT.md

@@ -7,8 +7,77 @@ This file freezes the public service contract for `xoonya`.
 Primary proof-model routes:
 
 - `GET /health`
+- `GET /openapi.json`
+- `GET /v1/openapi`
+- `GET /v1/openapi/summary`
+- `GET /asyncapi.json`
+- `GET /v1/asyncapi`
+- `GET /v1/asyncapi/summary`
+- `GET /cloudevents.json`
+- `GET /v1/cloudevents`
+- `GET /v1/cloudevents/summary`
+- `GET /v1/auth-profiles`
+- `GET /v1/auth-profiles/summary`
+- `GET /v1/identity-interop`
+- `GET /v1/identity-interop/summary`
+- `GET /v1/providers`
+- `GET /v1/providers/summary`
+- `GET /v1/frameworks`
+- `GET /v1/frameworks/summary`
+- `GET /v1/integration-matrix`
+- `GET /v1/integration-matrix/summary`
+- `GET /v1/major-rails`
+- `GET /v1/major-rails/summary`
+- `GET /v1/treasury`
+- `GET /v1/treasury/summary`
+- `GET /v1/erc8004`
+- `GET /v1/erc8004/summary`
+- `GET /v1/proof-bridge`
+- `GET /v1/proof-bridge/summary`
+- `GET /v1/external-proof-import`
+- `GET /v1/external-proof-import/summary`
+- `GET /v1/result-package-trust`
+- `GET /v1/result-package-trust/summary`
+- `GET /v1/event-systems`
+- `GET /v1/event-systems/summary`
+- `GET /v1/telemetry`
+- `GET /v1/telemetry/summary`
+- `GET /v1/provenance`
+- `GET /v1/provenance/summary`
+- `GET /v1/artifact-distribution`
+- `GET /v1/artifact-distribution/summary`
+- `GET /v1/shared-signals`
+- `GET /v1/shared-signals/summary`
+- `GET /v1/feature-control`
+- `GET /v1/feature-control/summary`
+- `GET /v1/integrations`
+- `GET /v1/integrations/summary`
+- `GET /v1/integrations/snapshot`
+- `GET /v1/integrations/promotion-readiness`
+- `GET /v1/integrations/promotion-workflow`
 - `GET /v1/proof-center`
 - `GET /v1/proof-center/summary`
+- `GET /v1/proof-center/native-standard`
+- `GET /v1/proof-center/native-standard/summary`
+- `GET /v1/proof-center/native-hybrid-readiness`
+- `GET /v1/proof-center/native-hybrid-readiness/summary`
+- `GET /v1/proof-center/native-standardization`
+- `GET /v1/proof-center/native-standardization/summary`
+- `GET /v1/proof-center/native-atom-spec`
+- `GET /v1/proof-center/native-atom-spec/summary`
+- `GET /v1/proof-center/native-atom-conformance`
+- `GET /v1/proof-center/native-atom-conformance/summary`
+- `GET /v1/proof-center/native-anchor-profile`
+- `GET /v1/proof-center/native-anchor-profile/summary`
+- `GET /v1/proof-center/native-payload-profile`
+- `GET /v1/proof-center/native-payload-profile/summary`
+- `GET /v1/proof-center/native-line-rate-frame`
+- `GET /v1/proof-center/native-line-rate-frame/summary`
+- `GET /v1/proof-center/import-adapter`
+- `GET /v1/proof-center/import-adapter/summary`
+- `POST /v1/proof-center/import-adapter/review`
+- `POST /v1/proof-center/import-adapter/review/summary`
+- `POST /v1/proof-center/import-adapter/run`
 - `GET /v1/proof-center/governance`
 - `GET /v1/proof-center/governance/summary`
 - `GET /v1/proof-center/bridge`
@@ -73,6 +142,22 @@ Expected error shapes:
 
 Compatibility routes may return proof/profile-specific verification payloads, but the top-level shape should still remain predictable.
 
+Interop note:
+
+- `GET /v1/identity-interop` exposes how native proof, attestation, and bridge surfaces map to `JWT`, `DID/VC`, and `SD-JWT VC` interop lanes without replacing canonical proof truth inside `xoonya`
+- `GET /v1/major-rails` exposes the Solana and Antelope/Proton XPR/Metal proof family as one practical settlement-evidence lane
+- `GET /v1/treasury` exposes treasury destination/accounting evidence continuity while keeping DAI/USDC and Monero reserve doctrine clearly internal
+- `GET /v1/external-proof-import` exposes the result, receipt, and proof-bundle import family as one builder-trust lane
+- `GET /v1/result-package-trust` exposes the carried result-package trust continuity posture as a first-class proof-side lane
+- `GET /v1/providers` exposes the OpenAI Codex and Claude/MCP family as first-class provider-origin proof lanes
+- `GET /v1/frameworks` exposes LangGraph, LangChain, AutoGen, and Semantic Kernel as first-class framework followthrough lanes
+- `GET /v1/integration-matrix` exposes the canonical public view across providers, frameworks, proof lanes, and registry-backed proof integrations
+- `GET /v1/telemetry` exposes the OpenTelemetry-aligned proof observability posture across review, verification, bridge, and proof event signals
+- `GET /v1/provenance` exposes the SLSA-aligned provenance posture for proof artifacts, release trust, and bundle followthrough confidence
+- `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
+
 ## Final-Loop Verification
 
 The constitutional proof loop for `xoonya` is:
@@ -103,3 +188,4 @@ This loop is exercised through:
 - example verification
 - service verification
 - conformance/adversarial vector verification
+- public `xoonya conformance` and `xoonya conformance --json` commands

package/START_HERE.md

@@ -15,6 +15,18 @@ Its job is to let a caller:
 3. emit proof-native completion artifacts
 4. verify the final proof bundle
 
+For the full public quote -> execute -> prove path, start from:
+
+```text
+https://www.naxytra.com/v1/first-run-kit
+```
+
+Then run the local proof followthrough:
+
+```bash
+xoonya first-run --verify-native --pretty
+```
+
 ## 2. Run The Fastest Real Example
 
 Run:
@@ -52,6 +64,27 @@ For long-term product understanding, read:
 
 - [FINAL_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/FINAL_CONTRACT.md)
 - [SERVICE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/SERVICE_CONTRACT.md)
+- `GET /openapi.json`
+- `GET /asyncapi.json`
+- `GET /cloudevents.json`
+- `GET /v1/auth-profiles`
+- `GET /v1/identity-interop`
+- `GET /v1/providers`
+- `GET /v1/frameworks`
+- `GET /v1/integration-matrix`
+- `GET /v1/telemetry`
+- `GET /v1/provenance`
+- `GET /v1/artifact-distribution`
+- `GET /v1/shared-signals`
+- `GET /v1/feature-control`
+- `GET /v1/major-rails`
+- `GET /v1/treasury`
+- `GET /v1/erc8004`
+- `GET /v1/proof-bridge`
+- `GET /v1/external-proof-import`
+- `GET /v1/result-package-trust`
+- `GET /v1/event-systems`
+- `GET /v1/integrations`
 - [PROGRAM_STATUS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/PROGRAM_STATUS.md)
 - [OPERATOR_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/OPERATOR_START_HERE.md)
 - [OPERATIONS_RUNBOOK.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xoonya/OPERATIONS_RUNBOOK.md)
@@ -80,6 +113,12 @@ It is:
 
 receive handoff -> inspect review posture -> confirm run posture -> emit and verify proof
 
+If you want the shortest CLI-first read of the package after install, use:
+
+- `xoonya start-here`
+- `xoonya release --summary`
+- `xoonya review --help`
+
 ## 7. If You Are Operating The Closed Program
 
 Use:

package/XOONYA_NATIVE_ATOM_SPEC.md

@@ -0,0 +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.