docs: add v5 theorem scaffold, threat model, and benchmark plan

.gitignore

@@ -19,4 +19,7 @@ __MACOSX/
 ._*
 *.egg-info/
 .pytest_cache/
+
+# Rust build artifacts
 rust/tritrpc_v1/target/
+go/tritrpcv1/vendor/

docs/policy_evidence_aux_profile.md

@@ -0,0 +1,95 @@
+# TritRPC policy/evidence AUX profile (draft profile)
+
+This document defines a **draft carriage profile** for policy and evidence references in
+TritRPC AUX.
+
+It does **not** redefine the stable TritRPC v1 envelope. Instead, it defines how a policy /
+evidence bundle is serialized into the existing AUX byte field.
+
+## Scope
+
+The stable Go/Rust ports currently treat AUX as an **opaque byte slice**, and current
+published fixture vectors omit AUX entirely. This profile is therefore the **next-step
+integration contract** for carrying policy/evidence references without requiring a stable port
+wire-format change.
+
+## Profile identifier
+
+Top-level profile string:
+
+- `tritrpc.policy_evidence_aux.v1`
+
+## Serialization
+
+The AUX bundle is encoded as:
+
+1. A top-level JSON object.
+2. Canonicalized to UTF-8 bytes using **RFC 8785 (JCS)**.
+3. Inserted directly into the existing TritRPC AUX field as opaque bytes.
+
+Because the existing AEAD AAD definition covers the envelope bytes before the final tag field,
+AUX bytes are already authenticated when AEAD is enabled.
+
+## Top-level object
+
+Required fields:
+
+- `profile`: profile identifier string.
+- `grant_ref`: URI-like reference to a grant.
+- `policy_decision_ref`: URI-like reference to a policy decision.
+- `runtime_evidence_refs`: structured evidence references.
+
+Optional fields:
+
+- `attestation_bundle_ref`: URI-like reference to a runtime attestation bundle.
+- `policy_hash`: stable policy hash (`sha256:...`) associated with the decision.
+- `notes`: array of human-readable notes.
+
+## Runtime evidence refs
+
+`runtime_evidence_refs` MAY contain:
+
+- `event_ir_ref`
+- `event_ir_hash`
+- `semantic_proof_ref`
+- `semantic_proof_hash`
+- `hdt_decision_ref`
+- `hdt_decision_hash`
+- `attestation_bundle_ref`
+- `attestation_bundle_hash`
+
+Hash fields are expected to use the `sha256:<64 lowercase hex chars>` form used elsewhere in the
+identity/governance stack.
+
+## Signed bytes / receipt-grade hashing
+
+For any receipt-grade or replay-grade use of the AUX JSON object itself:
+
+- parse JSON per RFC 8259,
+- canonicalize with JCS,
+- hash the UTF-8 canonical bytes using the current repository receipt/content-hash rule.
+
+At the time of writing, the repository copy of the full spec states that receipt/content
+hashing for JSON is **JCS + BLAKE3-256**.
+
+## Non-goals
+
+This profile does **not**:
+
+- define semantic policy meaning,
+- replace grant / decision / attestation schemas,
+- require ports to parse structured AUX today,
+- redefine the AEAD lane or frame layout.
+
+## Migration posture
+
+Near-term:
+
+- ports remain AUX-opaque,
+- integrations generate and validate the JSON bundle out-of-band,
+- fixture/examples establish stable carriage bytes for future port decoding.
+
+Later:
+
+- ports may add structured AUX decoding for this profile,
+- fixture vectors may add positive / negative AUX-bearing frames.

docs/vnext/reports/_connector_write_probe.txt

@@ -0,0 +1 @@
+probe

docs/vnext/reports/tritrpc_v5_benchmark_and_ablation_plan.md

@@ -0,0 +1,61 @@
+# TRiTRPC v5 benchmark and ablation plan
+
+## Purpose
+
+This document turns the white-paper benchmark into a reproducible next-pass experiment plan. It separates serializer comparison from framed transport comparison and identifies the ablations needed to answer the strongest red-team questions.
+
+## Benchmark families
+
+### A. Five-event hot-path family
+
+- `PAIR.OPEN`
+- `PAIR.HERALD`
+- `TELEPORT.BSM3`
+- `FRAME.DEFER`
+- `WITNESS.REPORT`
+
+### B. Route-reuse sweep
+
+Vary:
+- route-handle reuse ratio
+- inline route vs handle route
+- handle lifetime and invalidation frequency
+
+### C. Stream-inheritance sweep
+
+Vary:
+- number of `STREAM_DATA` frames per `STREAM_OPEN`
+- per-frame semantic override rate
+- beacon-carried vs inherited defaults
+
+### D. Payload-shape sweep
+
+Vary:
+- opaque byte payload size
+- percentage of ternary / low-cardinality fields
+- percentage of repeated semantic coordinates
+
+## Required ablations
+
+1. **Control-word ablation**
+2. **Route-handle ablation**
+3. **Stream-inheritance ablation**
+4. **Ternary-payload ablation**
+5. **Authentication-placement ablation**
+
+## Fairness rules
+
+- Publish the exact competitor schemas and encoder code.
+- Label payload-only comparisons as serializer comparisons.
+- Label full-frame comparisons as framed-transport comparisons.
+- Treat gRPC numbers as lower bounds unless full HTTP/2 framing, headers, and trailers are modeled.
+- Keep Path-H claims narrow: strongest on route-repetitive, low-cardinality control workloads; weak on large opaque blobs.
+
+## Outputs required
+
+- machine-readable CSV of every run
+- plots by payload size
+- plots by route-reuse rate
+- plots by stream length
+- plots by ternary-field share
+- written interpretation of where the advantage appears and disappears

docs/vnext/reports/tritrpc_v5_claims_ledger.md

@@ -0,0 +1,31 @@
+# TRiTRPC v5 claims ledger
+
+| Claim | Status | Evidence source | Overclaim risk |
+| --- | --- | --- | --- |
+| Stable TritRPC v1 exists in the live public repo | Repository fact | README repository status | Low |
+| Experimental TriTRPC vNext exists as a public design pack | Repository fact | README and `docs/vnext/README.md` | Low |
+| Stable v1 guarantees canonical encoding, parity, strict verification, and traceable theory | Repository fact | README guarantees section | Low |
+| Current stable surface uses Path-A Avro, Path-B toy subset, and XChaCha20-Poly1305 authenticated framing | Repository fact | README plus theory/spec | Low |
+| Go/Rust ports use explicit per-frame nonces from fixtures | Repository fact | theory/spec | Low |
+| SECURITY.md is currently placeholder-grade in the live repo | Repository fact | SECURITY.md | Low |
+| CI currently runs one `make verify` workflow on push/PR | Repository fact | README and CI workflow | Low |
+| Protobuf serialization is not canonical | External fact | protobuf serialization-not-canonical guidance | Low |
+| Deterministic protobuf serialization is still not canonical | External fact | protobuf serialization-not-canonical guidance | Low |
+| gRPC is built on HTTP/2 streams and framing | External fact | gRPC HTTP/2 documentation | Low |
+| Go FIPS claims are bounded to module version and operating environment | External fact | Go FIPS documentation | Low |
+| IBM Statevector supports non-power-of-two subsystem dimensions | External fact | IBM Qiskit Statevector documentation | Low |
+| Path-H payloads average 16.4 bytes on the five-event benchmark | Modeled benchmark result | paper benchmark harness | Medium |
+| Protocol Buffers payloads average 25.4 bytes on the five-event benchmark | Modeled benchmark result | paper benchmark harness | Medium |
+| Thrift compact payloads average 25.6 bytes on the five-event benchmark | Modeled benchmark result | paper benchmark harness | Medium |
+| Thrift binary payloads average 61.4 bytes on the five-event benchmark | Modeled benchmark result | paper benchmark harness | Medium |
+| Current TriTRPC-style full frames average about 151 bytes on the five-event benchmark | Modeled benchmark result | paper benchmark harness | Medium |
+| Path-H-style full frames average about 39.4 bytes on the five-event benchmark | Modeled benchmark result | paper benchmark harness | Medium |
+| vNext measured hot unary frame is 52 bytes in the current design pack | Measured design-pack fact | `docs/vnext/PERFORMANCE_AND_TESTING.md` | Low |
+| vNext measured stream DATA frame is 35 bytes in the current design pack | Measured design-pack fact | `docs/vnext/PERFORMANCE_AND_TESTING.md` | Low |
+| vNext braid coordinate is 1 byte in the current design pack | Measured design-pack fact | `docs/vnext/PERFORMANCE_AND_TESTING.md` | Low |
+| vNext large opaque payload advantage mostly disappears | Measured design-pack fact | `docs/vnext/PERFORMANCE_AND_TESTING.md` | Low |
+| Inherited defaults beat per-frame semantic carriage after 2 data frames | Measured design-pack fact | performance note plus cadence docs | Low |
+| A separate beacon beats per-frame semantic carriage after 13 data frames | Measured design-pack fact | performance note plus cadence docs | Low |
+| TriTRPC is structurally advantaged on authenticated hot-path control transport | Future theorem / proposal | vNext docs plus paper argument | Medium |
+| Braided beaconing is an independently developed privacy-shaping design | Future theorem / authorship framing | project authorship decision | Medium |
+| Path-H is the classical sidecar around future qutrit-aware systems | Future extension | paper hybrid design | Medium |

docs/vnext/reports/tritrpc_v5_profile_matrix.md

@@ -0,0 +1,9 @@
+# TRiTRPC v5 profile matrix
+
+| Profile | Intended use | Status | Crypto / integrity story | Canonicality story | Guarantees | Non-goals |
+| --- | --- | --- | --- | --- | --- | --- |
+| `compat-v1` | Stable fixture-defined interoperability | Live stable surface | Current repository-authenticated framing as published | Direct frame canonicality under stable v1 rules | canonical fixtures, cross-language parity, strict verification | not optimized hot-path framing |
+| `hot-v1.1` | Compact authenticated control transport | Proposed / experimental | bounded authenticated hot frame | wire-canonical relative to fixed profile, registry snapshot, handle dictionary, and epoch | compact control words, route handles, hot-path reuse | not a universal serializer theorem |
+| `path-h-research` | Simulator-first hybrid qutrit-aware control sidecar | Proposed / experimental | research profile, not normative for stable ports | same contextual canonicality model as hot-v1.1 | compact hybrid events, qutrit-aware correction semantics | not the physical quantum wire |
+| `beaconed-vnext` | Cadence-shaped multi-stream control with inherited semantics | Proposed / experimental | profile-specific authenticated beacon/control framing | canonical relative to epoch, registry snapshot, inherited context | pooled cadence, rotating handles, semantic inheritance | not a formal anonymity proof |
+| `fips-v1` | Bounded future compliance profile | Proposal only | must be tied to explicit provider/module/OE claim | canonicality preserved only within that bounded profile | auditable bounded claim surface | no implied broad compliance claim from cipher names alone |

docs/vnext/reports/tritrpc_v5_protocol_threat_table.md

@@ -0,0 +1,14 @@
+# TRiTRPC v5 protocol threat table
+
+| Threat | Preconditions | Effect | Detection | Mitigation | Residual risk |
+| --- | --- | --- | --- | --- | --- |
+| Replay of authenticated frame | Adversary records valid frame and replays within acceptance window | Duplicate or stale action | nonce/sequence checks, epoch checks, duplicate receipt detection | strict nonce discipline, replay cache, bounded epochs | cache exhaustion or desync under heavy load |
+| Stale beacon replay | Receiver accepts old beacon context or old handle dictionary | Wrong semantic inheritance, misrouted context | epoch mismatch, dictionary version mismatch | beacon expiry, hard epoch bounds, stale-cache rejection | liveness hit if clocks or caches drift |
+| Handle poisoning | Compromised resolver or bad update maps handle to wrong route/context | Semantic confusion or misdelivery | signed/hashed registry snapshots, dictionary checksum mismatch | pinned registry snapshots, epoch-scoped handles, explicit tombstones | operational complexity of rotation and rollback |
+| Epoch desynchronization | Peers disagree on active epoch or cadence window | beacon inheritance failure, false stale rejection | clock drift alarms, epoch-gap counters | explicit epoch negotiation, grace windows, time-service hardening | transient drops near boundaries |
+| Profile downgrade | Peer or intermediary forces lower-assurance profile | weakened verification or policy bypass | negotiated-profile mismatch, policy logs | profile pinning, downgrade refusal, explicit policy matrix | coordination cost across mixed deployments |
+| Tombstone reuse | Expired or retired handle is mistakenly reintroduced | stale semantics or linkability | tombstone table, audit-chain mismatch | monotonic generations, never-reuse window, signed registry state | storage overhead for retired IDs |
+| Nonce misuse | Duplicate or malformed nonces in authenticated lane | integrity failure or catastrophic misuse depending on suite | strict verifier, fixture checks, runtime duplicate detection | deterministic nonce sourcing, explicit per-frame nonce files in v1, bounded profile rules | human error in manual tooling |
+| Registry divergence | Different nodes load different route/semantic registries | canonicality mismatch, verification drift | registry hash mismatch, capability exchange | registry snapshot pinning, explicit hash in beacons/handshakes | rollout friction |
+| Stale inherited defaults | Stream or beacon inheritance continues past safe semantic scope | wrong semantics attached to data frames | explicit override markers, stream/bundle audit | strict default lifetime, typed semantic deltas, inherited-context expiry | complexity in long-lived streams |
+| Cross-profile confusion | v1 fixtures, vNext hot frames, and hybrid Path-H material are mixed incorrectly | invalid comparisons, false assurances, wrong tooling path | profile tagging, fixture-path discipline | separate profile namespaces, separate CI lanes | documentation drift if not curated |

docs/vnext/reports/tritrpc_v5_repo_implementation_package.md

@@ -0,0 +1,51 @@
+# TRiTRPC v5 repository implementation package
+
+## Goal
+
+Map the white-paper claims to concrete repository work so the paper and the repo evolve together.
+
+## Immediate documentation updates
+
+- Update `README.md` to state the narrowest strongest public claim and link to the white paper, threat table, profile matrix, and claims ledger.
+- Replace placeholder `SECURITY.md` with a real policy that distinguishes stable v1 from best-effort vNext and avoids vague compliance claims.
+- Update `docs/vnext/README.md` and `docs/vnext/WHAT_IS_TRITRPC_VNEXT.md` so the public theorem is explicit and bounded.
+
+## White-paper and evidence files to add
+
+- `docs/vnext/whitepaper/TRiRPC_WHITE_PAPER_V5.md`
+- `docs/vnext/reports/tritrpc_v5_claims_ledger.csv`
+- `docs/vnext/reports/tritrpc_v5_protocol_threat_table.md`
+- `docs/vnext/reports/tritrpc_v5_profile_matrix.md`
+- `docs/vnext/reports/tritrpc_v5_benchmark_and_ablation_plan.md`
+
+## Benchmarks and regenerated evidence
+
+- Publish competitor schemas and encoder code for the five-event benchmark.
+- Add ablation outputs showing the effect of compact control words, route handles, stream inheritance, and ternary payload packing.
+- Regenerate machine-readable benchmark CSVs and plots.
+- Extend cadence testing to native runtime, not only the experimental reference package.
+
+## Native runtime work implied by the paper
+
+- Port `Braid243` and `State243` into native Go and Rust.
+- Implement stream semantic inheritance and semantic tail behavior in the native runtime.
+- Add typed `BEACON_INTENT` semantic deltas instead of opaque payload bytes.
+- Add native golden fixtures for per-frame, inherited, and beaconed semantic regimes.
+
+## Security / assurance follow-through
+
+- Split protocol threat analysis from compliance profile documentation.
+- Add separate CI lanes or at minimum separate jobs for stable v1, experimental vNext framing, and future bounded compliance tests.
+- Keep any future FIPS/CNSA-style profile clearly tied to module/provider/OE language.
+
+## Hybrid / Path-H next proof point
+
+- Build one simulator-backed end-to-end control walkthrough:
+  `PAIR.OPEN -> PAIR.HERALD -> TELEPORT.BSM3 -> FRAME.DEFER/CORRECTION.APPLY -> WITNESS.REPORT`
+- Keep it explicitly labeled as a classical sidecar around quantum simulation rather than as the quantum wire itself.
+
+## Freeze points needed
+
+- freeze authoritative route/semantic registries when ready;
+- keep `topic23` and `cycle7` explicit about whether they are proposed or authoritative;
+- keep stable v1 fixtures fixed while vNext evolves beside them.

fixtures/policy_evidence_aux_examples.json

@@ -0,0 +1,52 @@
+[
+  {
+    "name": "minimal-policy-evidence-aux",
+    "aux_object": {
+      "grant_ref": "grant://runtime/2026/04/04/g-001",
+      "policy_decision_ref": "decision://runtime/2026/04/04/pd-001",
+      "profile": "tritrpc.policy_evidence_aux.v1",
+      "runtime_evidence_refs": {
+        "event_ir_hash": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
+        "event_ir_ref": "eir://semantic/session-001",
+        "hdt_decision_hash": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
+        "hdt_decision_ref": "hdt://decision/session-001",
+        "semantic_proof_hash": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
+        "semantic_proof_ref": "proof://semantic/session-001"
+      }
+    },
+    "canonical_aux_json": "{\"grant_ref\":\"grant://runtime/2026/04/04/g-001\",\"policy_decision_ref\":\"decision://runtime/2026/04/04/pd-001\",\"profile\":\"tritrpc.policy_evidence_aux.v1\",\"runtime_evidence_refs\":{\"event_ir_hash\":\"sha256:1111111111111111111111111111111111111111111111111111111111111111\",\"event_ir_ref\":\"eir://semantic/session-001\",\"hdt_decision_hash\":\"sha256:2222222222222222222222222222222222222222222222222222222222222222\",\"hdt_decision_ref\":\"hdt://decision/session-001\",\"semantic_proof_hash\":\"sha256:3333333333333333333333333333333333333333333333333333333333333333\",\"semantic_proof_ref\":\"proof://semantic/session-001\"}}",
+    "notes": [
+      "Minimal carriage example.",
+      "Ports may still treat AUX as opaque bytes."
+    ]
+  },
+  {
+    "name": "full-policy-evidence-aux-with-attestation",
+    "aux_object": {
+      "attestation_bundle_ref": "attest://runtime/2026/04/04/ab-001",
+      "grant_ref": "grant://runtime/2026/04/04/g-002",
+      "notes": [
+        "Requires semantic proof and export readiness.",
+        "Bound to attested runtime."
+      ],
+      "policy_decision_ref": "decision://runtime/2026/04/04/pd-002",
+      "policy_hash": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
+      "profile": "tritrpc.policy_evidence_aux.v1",
+      "runtime_evidence_refs": {
+        "attestation_bundle_hash": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+        "attestation_bundle_ref": "attest://runtime/2026/04/04/ab-001",
+        "event_ir_hash": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
+        "event_ir_ref": "eir://semantic/session-002",
+        "hdt_decision_hash": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
+        "hdt_decision_ref": "hdt://decision/session-002",
+        "semantic_proof_hash": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
+        "semantic_proof_ref": "proof://semantic/session-002"
+      }
+    },
+    "canonical_aux_json": "{\"attestation_bundle_ref\":\"attest://runtime/2026/04/04/ab-001\",\"grant_ref\":\"grant://runtime/2026/04/04/g-002\",\"notes\":[\"Requires semantic proof and export readiness.\",\"Bound to attested runtime.\"],\"policy_decision_ref\":\"decision://runtime/2026/04/04/pd-002\",\"policy_hash\":\"sha256:4444444444444444444444444444444444444444444444444444444444444444\",\"profile\":\"tritrpc.policy_evidence_aux.v1\",\"runtime_evidence_refs\":{\"attestation_bundle_hash\":\"sha256:5555555555555555555555555555555555555555555555555555555555555555\",\"attestation_bundle_ref\":\"attest://runtime/2026/04/04/ab-001\",\"event_ir_hash\":\"sha256:6666666666666666666666666666666666666666666666666666666666666666\",\"event_ir_ref\":\"eir://semantic/session-002\",\"hdt_decision_hash\":\"sha256:7777777777777777777777777777777777777777777777777777777777777777\",\"hdt_decision_ref\":\"hdt://decision/session-002\",\"semantic_proof_hash\":\"sha256:8888888888888888888888888888888888888888888888888888888888888888\",\"semantic_proof_ref\":\"proof://semantic/session-002\"}}",
+    "notes": [
+      "Full carriage example with runtime attestation linkage.",
+      "Receipt-grade hashing of the AUX JSON itself follows the repo JCS+BLAKE3 rule."
+    ]
+  }
+]