Harden TritRPC v1 parity: canonical IDs, decoders, repack checks, and CI/verify tooling

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install Python deps
+        run: python -m pip install --upgrade pip cryptography
+      - name: Verify
+        run: make verify

Makefile

@@ -0,0 +1,20 @@
+.PHONY: verify fmt rust-fmt go-fmt rust-test go-test fixtures
+
+verify: fmt rust-test go-test fixtures
+
+fmt: rust-fmt go-fmt
+
+rust-fmt:
+	cd rust/tritrpc_v1 && cargo fmt --check
+
+go-fmt:
+	cd go/tritrpcv1 && test -z "$$(gofmt -l .)"
+
+rust-test:
+	cd rust/tritrpc_v1 && cargo test
+
+go-test:
+	cd go/tritrpcv1 && go test
+
+fixtures:
+	python tools/verify_fixtures_strict.py

README.md

@@ -15,6 +15,7 @@ byte-transport, along with authenticated envelope framing. The focus of this rep
 - **Theory & conceptual model:** `docs/THEORY.md`
 - **Full specification:** `spec/README-full-spec.md`
 - **Reference implementation:** `reference/tritrpc_v1.py`
+- **Integration readiness checklist:** `docs/integration_readiness_checklist.md`
 - **Fixtures (canonical vectors):** `fixtures/`
 - **Rust port:** `rust/`
 - **Go port:** `go/`
@@ -43,8 +44,7 @@ TritRPC v1 is built on these conceptual layers:
 - **Path-A** payloads are encoded with Avro Binary Encoding (used by the reference
   implementation and most fixtures).
 - **Path-B** payloads are ternary-native (toy subset fixtures demonstrate this).
-- **AEAD integrity** uses XChaCha20-Poly1305 (or a deterministic MAC fallback) with
-  24-byte nonces for authenticated frames.
+- **AEAD integrity** uses XChaCha20-Poly1305 with 24-byte nonces for authenticated frames.
 
 For complete detail, read `docs/THEORY.md` and the full spec.
 
@@ -68,8 +68,8 @@ A more detailed guide lives in `docs/REPOSITORY_GUIDE.md`. At a glance:
 
 ### Fixture verification
 
-- Rust: `cargo test -p tritrpc_v1` validates AEAD tags using `.nonces` and checks Avro
-  payload bytes for key frames.
+- Rust: `cargo test -p tritrpc_v1` validates AEAD tags, schema/context IDs, and full-frame
+  repack determinism using `.nonces`.
 - Go: `cd go/tritrpcv1 && go test` performs the same validations.
 
 ### CLI tools
@@ -105,8 +105,8 @@ See `fixtures/vectors_hex_pathB.txt` (+ `.nonces`). These use ternary-native enc
 
 ## CI
 
-A GitHub Actions workflow is included in `.github/workflows/ci.yml` to run `cargo test`
-and `go test` on push/PR.
+A GitHub Actions workflow runs `make verify` (format checks + tests + fixture verification)
+on push/PR.
 
 ## Release workflow
 
@@ -116,8 +116,8 @@ and `go test` on push/PR.
 
 ## Repack check
 
-CI job `repack-check` rebuilds a canonical AddVertex_a frame with Rust and Go CLIs and
-compares it against the fixtures.
+Repack determinism is verified in the fixture tests by re-encoding envelopes and comparing
+full-frame bytes to fixture vectors.
 
 ## Pre-commit hook (strict AEAD verification)
 

docs/REPOSITORY_GUIDE.md

@@ -8,6 +8,7 @@ folder. It complements the top-level README by giving concrete navigation hints.
 - `README.md`: Project summary, build instructions, and high-level navigation.
 - `docs/`: Conceptual and procedural documentation.
   - `THEORY.md`: Theory and conceptual model for TritRPC v1.
+  - `integration_readiness_checklist.md`: Pre-integration verification checklist.
   - `REPOSITORY_GUIDE.md`: This file.
 - `spec/`: Specification material.
   - `README-full-spec.md`: The full spec text (repo copy).

docs/THEORY.md

@@ -71,34 +71,27 @@ changes.
 
 The protocol authenticates frames using an **AEAD lane**:
 
-- The preferred suite in the reference implementation is **XChaCha20-Poly1305**.
-- Some fixtures allow a deterministic MAC fallback when AEAD primitives are not available.
-- The AEAD tag is computed over the envelope's AAD (associated data) and the payload, using
-  a 24-byte nonce. This makes integrity checks deterministic and replay-resistant.
+- The suite used across fixtures and ports is **XChaCha20-Poly1305**.
+- The AEAD tag is computed with **empty plaintext** and **AAD equal to the envelope bytes
+  before the final tag field**, using a 24-byte nonce. This includes payload and AUX data.
+- Deterministic MAC fallback support exists only in the Python reference and is
+  **non-normative for Go/Rust**; fixtures are generated with XChaCha20-Poly1305.
 
 A strict verification mode is used by fixtures and tooling to ensure tags remain correct if
 any portion of the envelope or payload changes.
 
 ## 7. Streaming and rolling nonces
 
-For streaming sequences of frames, TritRPC uses **rolling nonces**:
-
-- A base nonce is derived or agreed upon.
-- Each subsequent frame increments or derives the next nonce in a deterministic way.
-- This keeps AEAD authentication safe across a stream while retaining deterministic test
-  fixtures.
+Rolling nonces are described in early sketches, but **Go/Rust ports and fixtures use
+explicit per-frame nonces** stored in `fixtures/*.nonces`. Rolling nonce derivation is not
+implemented in those ports.
 
 ## 8. AUX structures
 
-AUX structures are optional fields that can be inserted into an envelope for additional
-metadata. The reference implementation includes:
-
-- **Trace**: tracing and correlation metadata
-- **Sig**: placeholder for signature material
-- **PoE (Proof-of-Execution)**: a strict-initial placeholder for execution proofs
-
-These are designed to be extensible so that additional metadata can be added without breaking
-existing envelope parsing.
+AUX structures are optional byte fields that can be inserted into an envelope for additional
+metadata. The current fixtures do **not** include AUX data. The Python reference contains
+toy encoders for Trace/Sig/PoE, but Go/Rust treat AUX as an opaque byte slice and do not yet
+define structured decoding.
 
 ## 9. Hypergraph service model
 

docs/audit_tritrpc_v1_parity.md

@@ -0,0 +1,25 @@
+# TritRPC v1 Repo Health + Parity Audit
+
+Status: **Completed (post-fix)**. This report captures the protocol-relevant issues found
+and the corrective actions taken.
+
+## Findings (protocol-relevant)
+
+| ID | Severity | Issue | Evidence | Status |
+| --- | --- | --- | --- | --- |
+| A1 | **High** | Rust envelope builder previously used zeroed `schema_id`/`context_id`, diverging from fixtures. | `rust/tritrpc_v1/src/lib.rs` now defines canonical constants and uses them in the envelope builder (L125-L193). | **Fixed** |
+| A2 | **High** | Fixture verification did not assert full-frame byte equality or repack determinism. | Go fixture tests re-encode and compare full frames (`go/tritrpcv1/fixtures_test.go` L89-L102); Rust tests do the same (`rust/tritrpc_v1/tests/fixtures.rs` L81-L105). | **Fixed** |
+| A3 | **Medium** | Go/Rust lacked structured envelope decoders; tests used ad-hoc field splits only. | Envelope decoders exist in Go (`go/tritrpcv1/envelope_decode.go` L24-L143) and Rust (`rust/tritrpc_v1/src/lib.rs` L219-L341). | **Fixed** |
+| A4 | **Medium** | Path-A Avro subset had no decode/round-trip checks. | HGRequest/HGResponse decoders/encoders added in Go (`go/tritrpcv1/avrodec.go` L1-L321) and Rust (`rust/tritrpc_v1/src/lib.rs` L563-L844) with round-trip tests (`go/tritrpcv1/fixtures_test.go` L129-L153; `rust/tritrpc_v1/tests/fixtures.rs` L131-L147). | **Fixed** |
+| A5 | **Medium** | Spec/docs claimed MAC fallback, rolling nonces, and AUX structures were supported across ports. | Spec/docs now reflect current port behavior (`spec/README-full-spec.md` L7-L23; `docs/THEORY.md` L70-L94). | **Fixed** |
+| A6 | **Low** | README referenced CI/repack-check jobs that did not exist. | Added `Makefile` + CI workflow and updated README (`Makefile` L1-L20; `.github/workflows/ci.yml` L1-L27; `README.md` L106-L120). | **Fixed** |
+| A7 | **Low** | Tag comparisons used direct equality; constant-time compare was missing. | Constant-time comparisons now used in Go/Rust fixture checks (`go/tritrpcv1/fixtures_test.go` L117-L122; `rust/tritrpc_v1/tests/fixtures.rs` L123-L125). | **Fixed** |
+
+## Scope checklist coverage
+
+- **A) Cross-language envelope parity:** Schema/context constants aligned; AAD definition enforced.
+- **B) Strict fixture verification completeness:** Full-frame repack checks added and required.
+- **C) Decoder symmetry / round-trip reliability:** HGRequest/HGResponse decode → encode checks added for Path‑A fixtures.
+- **D) Spec alignment and missing normative text:** Spec/docs updated to match port behavior (no MAC fallback, explicit nonces, AUX opaque).
+- **E) Cryptography invariants:** Tag size + nonce size checked; constant-time tag comparison enforced in verification.
+- **F) Tooling / CI ergonomics:** Added `make verify` and CI workflow.

docs/integration_readiness_checklist.md

@@ -0,0 +1,50 @@
+# TritRPC v1 Integration Readiness Checklist
+
+This checklist documents the **minimum verification steps** required before integrating a
+policy/view (permissions + privacy) AUX bundle. It reflects the current behavior of the
+Go/Rust ports and fixtures.
+
+## ✅ Protocol invariants (must hold)
+
+- Schema/context IDs are canonical and match fixtures.
+- AEAD tags are computed with **empty plaintext** and **AAD = envelope bytes before the tag
+  field** (payload + AUX included).
+- Fixtures are the source of truth; repacking must reproduce **identical bytes**.
+- Nonces are deterministic and pulled from `fixtures/*.nonces`.
+
+## ✅ Local verification (single command)
+
+Run from repo root:
+
+```bash
+make verify
+```
+
+This runs:
+- Rust format check + tests
+- Go format check + tests
+- Fixture AEAD verification script
+
+## ✅ Per-language commands (if running manually)
+
+```bash
+cd rust/tritrpc_v1
+cargo fmt --check
+cargo test
+```
+
+```bash
+cd go/tritrpcv1
+gofmt -l .
+go test
+```
+
+```bash
+python tools/verify_fixtures_strict.py
+```
+
+## ✅ Readiness gates
+
+- All commands above must succeed on a clean checkout.
+- Fixture repack tests must pass (full-frame byte equality).
+- Envelope decode → encode stability holds for HGRequest/HGResponse Path-A payloads.