Implement kaysentinel-hash (domain-separated BLAKE3 commitments, RC1 spec); update README and roadmap to reflect real progress

README.md

@@ -10,23 +10,42 @@ tags:
 
 A post-execution authorization framework for state-machine systems (e.g. Ethereum-class runtimes). Kaysentinel lifts execution traces into a canonical **Structural Sufficient Representation (SSR)** and evaluates policy purely over that quotient space, so authorization decisions are provably independent of *which* client (Geth, Reth, ...) produced the trace.
 
-> **Status:** conceptual specification + differential-test harness skeleton. There is not yet a working Geth/Reth extractor implementation — the theorems below describe the target invariants that any implementation must satisfy, they are not machine-checked proofs.
+> **Status:** formal specification, differential-test harness skeleton, and a working Rust reference implementation of the canonical event ABI, the builder pipeline (partition → reduce → lifecycle resolution → certificate assembly), and domain-separated cryptographic commitments. There is not yet a working Geth/Reth extractor, SSZ canonical encoding, or storage-trie derivation — see the roadmap below for exactly what's real vs. still open.
 
 ## Repo contents
 
 - [`docs/framework.md`](docs/framework.md) — full formal spec: execution model, SSR canonical form, authorization/factorization theory, multi-client portability theorem, gating semantics, complexity model.
 - [`docs/differential_testing.md`](docs/differential_testing.md) — the differential testing engine design used to check byte-level convergence between a Geth-side and Reth-side SSR extractor.
 - [`docs/implementation_roadmap.md`](docs/implementation_roadmap.md) — concrete engineering tasks (Phase 1–3) to turn the spec into a working implementation.
+- [`docs/semantic_architecture_spec.md`](docs/semantic_architecture_spec.md) — formal stage contracts (partition → projection → canonicalization → serialization → commitment) with real implementation cross-references.
+- [`docs/hash_specification.md`](docs/hash_specification.md) — normative cryptographic commitment protocol (domain-separated BLAKE3), implemented in `runtime/hash`.
+- [`runtime/`](runtime/) — the Rust reference implementation. See below.
 - Curated test fixtures now live in a separate dataset repo: [`Sahek/kaysentinel-fixtures`](https://huggingface.co/datasets/Sahek/kaysentinel-fixtures).
 - [`scripts/verify_ssr.py`](scripts/verify_ssr.py) — standalone verifier that hashes and byte-diffs two SSZ-encoded SSR outputs.
 - [`tests/transient_storage_case.json`](tests/transient_storage_case.json) — example test vector (EIP-1153 transient storage + reentrancy rollback).
 
+## `runtime/` — Rust reference implementation
+
+A Cargo workspace. Status per crate, honestly:
+
+| Crate | Status |
+| --- | --- |
+| `cse` | **Done.** Canonical Semantic Event ABI: frozen event/payload types, execution context, a sequence/transaction-boundary validator. |
+| `builder` | **In progress, core pipeline works.** Partitions a CSE stream into flat relational tables (`partition.rs`), reduces per-key timelines to terminal transitions (`reduce.rs`), resolves account lifecycle generations (`lifecycle/resolve.rs`, `canonicalize.rs`), and assembles canonical account certificates from real state + generation data (`lifecycle/certificate.rs`, `hydration.rs`). 21 passing unit tests across the workspace. |
+| `hash` | **Core primitive done.** Domain-separated BLAKE3 commitments (`derive_commitment`), per the RC1 spec. 8 passing tests, including real (not hand-typed) pinned vectors — see `runtime/hash/vectors/candidate.json`. Not yet cross-language-verified (no Python/Go implementation exists to check against), so nothing has been promoted to `normative.json`. |
+| `ssr` | Empty stub. |
+| `ssz` | Empty stub — canonical encoding doesn't exist yet, so nothing has real bytes to hash yet either. |
+| `verify` | Empty stub. |
+
+Known open gaps (tracked in `docs/semantic_architecture_spec.md`): no real `AccountSnapshotSource` (prior-block state) implementation; storage roots are always `AwaitingDerivation` (no Phase 5 trie construction); access-list touches aren't tracked; several `TraceProvenance`/generation-chain fields (`frame_ordinal`, `ProvenanceMetadataDivergence`, `MalformedProvenanceChain`) are defined but not yet wired to real detection logic.
+
 ## Roadmap
 
-Nothing below is implemented yet. See [`docs/implementation_roadmap.md`](docs/implementation_roadmap.md) for the full phased task breakdown (SSZ schema, Go/Rust extractors, CI pipeline). Short version:
+See [`docs/implementation_roadmap.md`](docs/implementation_roadmap.md) for the full phased task breakdown. Short version:
 
 **Phase 1 — Canonical type system**
-- [ ] SSZ schema + Go/Rust serialization libraries
+- [x] Canonical Semantic Event ABI (`runtime/cse`)
+- [ ] SSZ schema + serialization (`runtime/ssz` — stub only)
 
 **Phase 2 — Client extractors**
 - [ ] Geth-side extractor (`StateDB` journal hook)
@@ -36,6 +55,17 @@ Nothing below is implemented yet. See [`docs/implementation_roadmap.md`](docs/im
 - [x] Verification harness (`scripts/verify_ssr.py`) — comparison logic only, done
 - [ ] Test runner environment + GitHub Actions CI
 
+**Phase 4 — Builder pipeline (Rust reference implementation)**
+- [x] Partition + terminal projection (`runtime/builder/src/partition.rs`, `ir/timeline.rs`)
+- [x] Lifecycle resolution + canonicalization (`runtime/builder/src/lifecycle/`)
+- [x] Certificate hydration + assembly (`runtime/builder/src/lifecycle/{certificate,hydration}.rs`)
+- [ ] Storage subtree/trie derivation (`StorageRootDeriver` trait exists, no implementation)
+
+**Phase 5 — Cryptographic commitment**
+- [x] Domain-separated BLAKE3 commitment primitive (`runtime/hash`)
+- [ ] Cross-language (Python/Go) differential verification of vectors
+- [ ] Wire real commitments into `VerifiedGeneration.state_table_proof_root` and `CanonicalAccountCertificate.storage_root`
+
 ## License
 
 MIT — see [`LICENSE`](LICENSE).

docs/hash_specification.md

@@ -0,0 +1,99 @@
+# KAYSentinel Hash Specification (RC1)
+
+Normative cryptographic protocol for `kaysentinel-hash`.
+
+**Status:** Release Candidate 1 (RC1). The Rust reference implementation exists and
+is self-consistent (deterministic, domain-separated, regression-pinned by unit
+tests). Cross-language verification (Python/Go) has **not** happened — no
+implementations exist in those languages yet — so vectors in `vectors/candidate.json`
+remain `"status": "candidate"`, not `"normative"`, per the promotion criteria below.
+
+## 1. Terminology
+
+The key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", and
+"MAY" in this document are to be interpreted as described in RFC 2119 and updated by
+RFC 8174.
+
+## 2. Cryptographic Primitive & Configuration
+
+* **Core Algorithm:** The protocol SHALL use the BLAKE3 algorithm. All commitments
+  MUST use the standard unkeyed BLAKE3 hash function. Keyed hashing, `derive_key`
+  mode, and extendable-output mode (XOF) are prohibited.
+* **Commitment Layout:** The resulting digest is an immutable sequence of exactly 32
+  bytes (256 bits). No integer interpretation, byte-swapping, or endianness applies
+  to the final digest sequence.
+* **Security Constraints:** The security architecture relies strictly on the
+  collision resistance and preimage resistance properties of the underlying BLAKE3
+  hash function.
+* **Portability & Determinism:** Given identical `DomainBytes` and `CanonicalBytes`,
+  all conforming implementations SHALL produce identical digest bytes on every
+  platform, host architecture, and execution environment.
+
+## 3. Domain Separation Architecture
+
+```
+HashInput := DomainBytes || CanonicalBytes
+Digest    := BLAKE3(HashInput)
+```
+
+* **DomainBytes**: the raw, fixed byte sequence representing the unique protocol
+  constant.
+* **CanonicalBytes**: the deterministic, byte-stable serialization of the underlying
+  data structure.
+* **||**: strict byte concatenation.
+
+Core invariants:
+
+1. **Structural Ordering:** domain separation SHALL precede all canonical bytes. No
+   protocol structure may insert additional bytes, padding, version flags,
+   delimiters, framing bytes, or metadata between the domain identifier and the
+   canonical serialization.
+2. **Infallibility by Contract:** commitment derivation is total and cannot fail once
+   valid canonical bytes have been produced.
+3. **No Normalization:** domain identifiers SHALL be matched strictly byte-for-byte.
+   Unicode normalization, case folding, locale conversion, whitespace trimming, or
+   character encoding transformations are prohibited.
+
+## 4. Canonical Encoding Separation
+
+The canonical encoding of every protocol structure is defined independently of the
+hashing function. Canonical encoding SHALL be deterministic, injective (no two
+distinct logical objects serialize to identical byte sequences), and entirely
+independent of the runtime environment. The hashing function operates exclusively on
+raw, opaque byte sequences and is not responsible for serialization semantics.
+
+**Status:** no canonical encoding (SSZ) exists yet — `runtime/ssz` is still an empty
+stub crate. Everything hashed so far in tests/vectors is raw test bytes, not real
+canonical-encoded protocol structures.
+
+## 5. Hash Domain Registry (Version: 1)
+
+Future protocol versions MAY append new domain tags to this registry. Existing tags
+SHALL remain permanently immutable, SHALL NOT change their underlying semantic
+meaning, and SHALL NEVER be reused or recycled upon feature retirement. No two
+protocol operations SHALL share the same domain byte sequence.
+
+| Protocol Constant | Normative Value (ASCII) | Context / Usage |
+| --- | --- | --- |
+| `KAY_TRIE_LEAF` | `"KAY_TRIE_LEAF"` | Storage trie leaf nodes |
+| `KAY_TRIE_BRANCH` | `"KAY_TRIE_BRANCH"` | Storage trie branch nodes |
+| `KAY_LIFE_CERT` | `"KAY_LIFE_CERT"` | Verification certificates |
+| `KAY_SSR_ROOT` | `"KAY_SSR_ROOT"` | Serialization Record roots |
+
+## 6. Reference Implementation
+
+`runtime/hash/src/lib.rs` implements this specification: `Digest`, `Domain`,
+`derive_commitment(domain, canonical_bytes) -> Digest`. 8 unit tests cover
+determinism, domain separation, length validation, and pin real (not hand-typed)
+BLAKE3 output for one vector per registered domain — see
+`runtime/hash/vectors/candidate.json`.
+
+## 7. Vector Status & Promotion Criteria
+
+Per the execution lifecycle, a vector is `"candidate"` once a reference
+implementation computes and regression-pins it, and becomes `"normative"` only after
+independent implementations in multiple languages are shown to converge on the same
+digest via automated differential verification. `runtime/hash/vectors/candidate.json`
+holds real, computed, Rust-self-consistent values — but since no Python or Go
+implementation exists yet to check against, none have been promoted to
+`vectors/normative.json`, and that file doesn't exist yet.

docs/implementation_roadmap.md

@@ -1,6 +1,8 @@
 # Implementation Roadmap
 
-Concrete engineering tasks to turn the [framework spec](framework.md) and [differential testing design](differential_testing.md) into working code. Nothing here is implemented yet — see status per phase below.
+Concrete engineering tasks to turn the [framework spec](framework.md) and [differential testing design](differential_testing.md) into working code.
+
+> **Update:** the Rust reference implementation (`runtime/`) now has real, tested code for the canonical event ABI and most of the builder pipeline (Phase 1.2's Rust half, partially) plus the cryptographic commitment primitive (Phase 5). Status per item below has been updated accordingly — everything not explicitly marked done is still not started.
 
 ## Phase 1 — Canonical Type System & Serialization
 
@@ -9,7 +11,20 @@ The serialization layer needs to be settled before client logic begins, to preve
 - [ ] **1.1 Define the strict SSZ schema.** Draft the official SSZ definitions for `CanonicalSSR` and its sub-containers. Enforce little-endian byte ordering for integers and explicit padding rules for `Uint256` (32-byte arrays).
 - [ ] **1.2 Implement serialization libraries.**
   - **Go:** integrate an SSZ library (e.g. [`fastssz`](https://github.com/ferranbt/fastssz)) to generate static encoder/decoder methods for the Go-side SSR types.
-  - **Rust:** configure an SSZ crate (e.g. `ssz` or `lighthouse_types`) to derive encoding logic on the Rust structs.
+  - **Rust:** configure an SSZ crate (e.g. `ssz` or `lighthouse_types`) to derive encoding logic on the Rust structs. **Not started** — `runtime/ssz` is still an empty stub crate. The canonical event *types* that would eventually be serialized do exist (`runtime/cse`), but nothing encodes them to SSZ bytes yet.
+
+## Phase 1.5 — Rust Builder Pipeline (new, not in the original phase breakdown)
+
+The event-to-certificate compiler pipeline that consumes a validated `CanonicalSemanticEvent` stream (from `runtime/cse`) and produces canonical per-account certificates. This sits logically between Phase 1 (types) and Phase 2 (extractors) — it's what a real extractor's output would eventually flow into, but it doesn't extract from a real client itself (see Phase 2 status, unchanged).
+
+- [x] **Canonical Semantic Event ABI** (`runtime/cse`) — frozen event/payload types, execution context, sequence/transaction-boundary validation.
+- [x] **Partition + terminal projection** (`runtime/builder/src/partition.rs`, `ir/timeline.rs`) — flattens an event stream into relational, `CanonicalKey`-keyed tables; reduces per-key timelines to verified terminal transitions.
+- [x] **Lifecycle resolution + canonicalization** (`runtime/builder/src/lifecycle/{resolve,canonicalize}.rs`) — resolves account creation/destruction into identity "generations," with formal invariant verification (uniqueness, temporal well-formedness, chronological adjacency).
+- [x] **Certificate hydration + assembly** (`runtime/builder/src/lifecycle/{certificate,hydration}.rs`) — cross-references real state facts (balance/nonce/code) to resolved generations to build `CanonicalAccountCertificate`s, with a real (if unimplemented) `AccountSnapshotSource`/`StorageRootDeriver` extension point for prior-state and Phase-5 storage-trie data.
+- [ ] Storage subtree/trie derivation — `StorageRootDeriver` trait exists, no implementation. Every certificate's `storage_root` is currently `AwaitingDerivation`.
+- [ ] Access-list tracking — `CsePayload::AccessListTouched` events are parsed but not recorded anywhere in the pipeline.
+
+21 passing unit tests across `runtime/cse` + `runtime/builder`. See `docs/semantic_architecture_spec.md` for the full stage-by-stage contract writeup and honest gap list.
 
 ## Phase 2 — Client Extractor Modules
 
@@ -21,7 +36,7 @@ The serialization layer needs to be settled before client logic begins, to preve
 
 ### Reth extractor (Rust)
 
-- [ ] **3.1 Intercept execution outputs.** Inject the extraction module where `BlockExecutionResult` yields its finalized in-memory `BundleState`.
+- [ ] **3.1 Intercept execution outputs.** Inject the extraction module where `BlockExecutionResult` yields its finalized in-memory `BundleState`. **Not started** — nothing in `runtime/` reads from a real Reth `BundleState` yet; the builder pipeline (Phase 1.5) consumes already-abstracted `CanonicalSemanticEvent`s, which still need to be produced by a real extractor hook.
 - [ ] **3.2 Map BundleState structural diffs.** Map state maps to `AccountMutation` vectors; use `sort_by_key` to enforce the same lexicographic ordering as the Go side over addresses and slots.
 
 ## Phase 3 — Infrastructure & Differential Testing CI
@@ -63,14 +78,28 @@ Depends entirely on Phase 1 and Phase 2 being complete — there's no extractor
 
 See the companion dataset repo: [`Sahek/kaysentinel-fixtures`](https://huggingface.co/datasets/Sahek/kaysentinel-fixtures) for the curated Phase 3 test fixtures that exist today.
 
+## Phase 5 — Cryptographic Commitment (new, not in the original phase breakdown)
+
+- [x] **Domain-separated BLAKE3 commitment primitive** (`runtime/hash`) — `derive_commitment(domain, canonical_bytes) -> Digest`, per `docs/hash_specification.md` (RC1). 8 passing tests, including real computed-and-pinned vectors per domain.
+- [ ] Cross-language (Python/Go) differential verification of vectors — no Python/Go implementation exists yet, so nothing in `runtime/hash/vectors/candidate.json` has been promoted to `normative.json`.
+- [ ] Wire real commitments into `VerifiedGeneration.state_table_proof_root` and `CanonicalAccountCertificate.storage_root` — both are still placeholder/`AwaitingDerivation` values in the builder pipeline.
+
 ## Current status summary
 
 | Phase | Item | Status |
 |---|---|---|
 | 1 | SSZ schema definition | Not started |
 | 1 | Go/Rust serialization libs | Not started |
+| 1.5 | Canonical Semantic Event ABI (`runtime/cse`) | **Done** |
+| 1.5 | Builder pipeline: partition + terminal projection | **Done** |
+| 1.5 | Builder pipeline: lifecycle resolution + canonicalization | **Done** |
+| 1.5 | Builder pipeline: certificate hydration + assembly | **Done** |
+| 1.5 | Storage subtree/trie derivation | Not started (`StorageRootDeriver` trait only) |
 | 2 | Geth extractor | Not started |
 | 2 | Reth extractor | Not started |
 | 3 | Verification harness (`verify_ssr.py`) | Done (comparison logic only — see script docstring) |
 | 3 | Test runner environment | Not started |
 | 3 | CI automation | Not started |
+| 5 | BLAKE3 commitment primitive (`runtime/hash`) | **Done** |
+| 5 | Cross-language vector verification | Not started |
+| 5 | Real commitments wired into builder pipeline | Not started |

runtime/Cargo.lock

@@ -2,9 +2,65 @@
 # It is not intended for manual editing.
 version = 3
 
+[[package]]
+name = "arrayref"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76a2e8124351fda1ef8aaaa3bbd7ebbcb486bbcd4225aca0aa0d84bb2db8fecb"
+
+[[package]]
+name = "arrayvec"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
+
+[[package]]
+name = "blake3"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0231f06152bf547e9c2b5194f247cd97aacf6dcd8b15d8e5ec0663f64580da87"
+dependencies = [
+ "arrayref",
+ "arrayvec",
+ "cc",
+ "cfg-if",
+ "constant_time_eq",
+]
+
+[[package]]
+name = "cc"
+version = "1.2.67"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e17dd265a7d0f31ef544e1b20e03add05d3b45b491b633b10d67145d2acc1a38"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "constant_time_eq"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c74b8349d32d297c9134b8c88677813a227df8f779daa29bfc29c183fe3dca6"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
 [[package]]
 name = "kaysentinel-builder"
 version = "0.1.0"
+dependencies = [
+ "kaysentinel-cse",
+]
 
 [[package]]
 name = "kaysentinel-cse"
@@ -13,6 +69,9 @@ version = "0.1.0"
 [[package]]
 name = "kaysentinel-hash"
 version = "0.1.0"
+dependencies = [
+ "blake3",
+]
 
 [[package]]
 name = "kaysentinel-ssr"
@@ -25,3 +84,9 @@ version = "0.1.0"
 [[package]]
 name = "kaysentinel-verify"
 version = "0.1.0"
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"

runtime/hash/Cargo.toml

@@ -5,3 +5,4 @@ edition.workspace = true
 license.workspace = true
 
 [dependencies]
+blake3 = "=1.5.0"

runtime/hash/src/lib.rs

@@ -1 +1,210 @@
-//! placeholder stub for the hash crate (not yet specified in source doc)
+//! # Kaysentinel Hash
+//!
+//! Reference implementation of `SPECIFICATION.md` (Normative Cryptographic Protocol,
+//! RC1): domain-separated BLAKE3 commitments over canonical byte sequences.
+//!
+//! `Digest := BLAKE3(DomainBytes || CanonicalBytes)` — unkeyed BLAKE3, no
+//! `derive_key` mode, no XOF, no padding or framing bytes between the domain
+//! identifier and the canonical serialization.
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DigestError {
+    InvalidLength,
+}
+
+impl std::fmt::Display for DigestError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::InvalidLength => write!(f, "Invalid digest length: must be exactly 32 bytes"),
+        }
+    }
+}
+
+impl std::error::Error for DigestError {}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Digest([u8; 32]);
+
+impl Digest {
+    /// Creates a Digest wrapper from an explicit 32-byte array.
+    pub const fn from_bytes(bytes: [u8; 32]) -> Self {
+        Self(bytes)
+    }
+
+    /// Returns the raw 32-byte digest.
+    pub const fn to_bytes(&self) -> [u8; 32] {
+        self.0
+    }
+
+    /// Lowercase hex encoding of the digest, matching the vector-file convention.
+    pub fn to_hex(&self) -> String {
+        self.0.iter().map(|b| format!("{:02x}", b)).collect()
+    }
+}
+
+impl AsRef<[u8]> for Digest {
+    fn as_ref(&self) -> &[u8] {
+        &self.0
+    }
+}
+
+impl std::borrow::Borrow<[u8]> for Digest {
+    fn borrow(&self) -> &[u8] {
+        &self.0
+    }
+}
+
+impl From<[u8; 32]> for Digest {
+    fn from(bytes: [u8; 32]) -> Self {
+        Self::from_bytes(bytes)
+    }
+}
+
+impl TryFrom<&[u8]> for Digest {
+    type Error = DigestError;
+
+    fn try_from(slice: &[u8]) -> Result<Self, Self::Error> {
+        if slice.len() == 32 {
+            let mut bytes = [0u8; 32];
+            bytes.copy_from_slice(slice);
+            Ok(Self::from_bytes(bytes))
+        } else {
+            Err(DigestError::InvalidLength)
+        }
+    }
+}
+
+/// Hash Domain Registry (Version: 1). Existing tags are permanently immutable once
+/// published — new domains may be appended, but nothing here may be renamed,
+/// reinterpreted, or recycled.
+#[non_exhaustive]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Domain {
+    TrieLeaf,
+    TrieBranch,
+    LifeCert,
+    SsrRoot,
+}
+
+impl Domain {
+    pub const fn as_bytes(&self) -> &'static [u8] {
+        match self {
+            Domain::TrieLeaf => b"KAY_TRIE_LEAF",
+            Domain::TrieBranch => b"KAY_TRIE_BRANCH",
+            Domain::LifeCert => b"KAY_LIFE_CERT",
+            Domain::SsrRoot => b"KAY_SSR_ROOT",
+        }
+    }
+}
+
+/// Total function that computes the cryptographic commitment per the specification:
+/// BLAKE3(DomainBytes || CanonicalBytes). Infallible once `canonical_bytes` exists —
+/// there is no failure mode once you have valid input bytes.
+pub fn derive_commitment(domain: Domain, canonical_bytes: &[u8]) -> Digest {
+    let mut hasher = blake3::Hasher::new();
+    hasher.update(domain.as_bytes());
+    hasher.update(canonical_bytes);
+    Digest::from_bytes(hasher.finalize().into())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn commitment_is_deterministic() {
+        let bytes = [1u8, 2, 3, 4];
+        let a = derive_commitment(Domain::TrieLeaf, &bytes);
+        let b = derive_commitment(Domain::TrieLeaf, &bytes);
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn different_domains_produce_different_digests() {
+        let bytes = [1u8, 2, 3, 4];
+        let leaf = derive_commitment(Domain::TrieLeaf, &bytes);
+        let branch = derive_commitment(Domain::TrieBranch, &bytes);
+        assert_ne!(leaf, branch);
+    }
+
+    #[test]
+    fn different_canonical_bytes_produce_different_digests() {
+        let a = derive_commitment(Domain::LifeCert, &[1, 2, 3]);
+        let b = derive_commitment(Domain::LifeCert, &[1, 2, 4]);
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn digest_try_from_rejects_wrong_length() {
+        let short = [0u8; 16];
+        assert_eq!(Digest::try_from(&short[..]), Err(DigestError::InvalidLength));
+
+        let exact = [0u8; 32];
+        assert!(Digest::try_from(&exact[..]).is_ok());
+    }
+
+    #[test]
+    fn digest_round_trips_through_bytes() {
+        let bytes = [0xABu8; 32];
+        let digest = Digest::from_bytes(bytes);
+        assert_eq!(digest.to_bytes(), bytes);
+    }
+
+    /// Computes the real BLAKE3 digest for the candidate vector in
+    /// `vectors/candidate.json` (domain = KAY_TRIE_LEAF, canonical_bytes = 01020304)
+    /// and prints it, so the actual output can be copied into `vectors/normative.json`
+    /// rather than trusting a hand-typed value. Run with `cargo test -- --nocapture`.
+    #[test]
+    fn print_candidate_vector_1_digest() {
+        let canonical_bytes = [0x01u8, 0x02, 0x03, 0x04];
+        let digest = derive_commitment(Domain::TrieLeaf, &canonical_bytes);
+        println!("candidate_vector_1 digest_hex = {}", digest.to_hex());
+        // 32 bytes -> 64 hex characters, always.
+        assert_eq!(digest.to_hex().len(), 64);
+    }
+
+    /// Regression pin for candidate_vector_1. The doc that specified this vector
+    /// claimed a digest_hex value that was actually 66 hex characters long — an
+    /// impossible length for a 32-byte BLAKE3 digest, so it was never real. This
+    /// pins the value this implementation actually computes, so any future change
+    /// to the hashing logic (or the blake3 dependency version) that silently
+    /// changes output is caught immediately.
+    #[test]
+    fn candidate_vector_1_matches_pinned_digest() {
+        let canonical_bytes = [0x01u8, 0x02, 0x03, 0x04];
+        let digest = derive_commitment(Domain::TrieLeaf, &canonical_bytes);
+        assert_eq!(
+            digest.to_hex(),
+            "80522501585b8ebf1831439e57add0002d22fe75521120104b000cc707b5a34a"
+        );
+    }
+
+    /// One pinned regression vector per registered domain, all against the same
+    /// canonical bytes — proves domain separation holds and gives every domain a
+    /// real, computed (not hand-typed) reference value.
+    #[test]
+    fn per_domain_vectors_are_pinned_and_distinct() {
+        let canonical_bytes = [0x01u8, 0x02, 0x03, 0x04];
+        let leaf = derive_commitment(Domain::TrieLeaf, &canonical_bytes).to_hex();
+        let branch = derive_commitment(Domain::TrieBranch, &canonical_bytes).to_hex();
+        let cert = derive_commitment(Domain::LifeCert, &canonical_bytes).to_hex();
+        let ssr = derive_commitment(Domain::SsrRoot, &canonical_bytes).to_hex();
+
+        println!("leaf   = {leaf}");
+        println!("branch = {branch}");
+        println!("cert   = {cert}");
+        println!("ssr    = {ssr}");
+
+        assert_eq!(leaf, "80522501585b8ebf1831439e57add0002d22fe75521120104b000cc707b5a34a");
+        assert_eq!(branch, "51614b8a4a5f5a2b5b7b858e626cd19b710d670ebad2e0b9b296bf282b4bfe93");
+        assert_eq!(cert, "59fd735ed0c0923c4316ad197223aed69b6667f6a00a228aae1638a521d1f62f");
+        assert_eq!(ssr, "1007c1368120e75ff7f8a47d6933f1440e1a6e0fd1b5e10f8721329dd5d47617");
+
+        let all = [&leaf, &branch, &cert, &ssr];
+        for i in 0..all.len() {
+            for j in (i + 1)..all.len() {
+                assert_ne!(all[i], all[j], "domain separation violated between vectors {i} and {j}");
+            }
+        }
+    }
+}

runtime/hash/vectors/candidate.json

@@ -0,0 +1,30 @@
+[
+  {
+    "name": "candidate_vector_1",
+    "domain": "KAY_TRIE_LEAF",
+    "canonical_hex": "01020304",
+    "digest_hex": "80522501585b8ebf1831439e57add0002d22fe75521120104b000cc707b5a34a",
+    "status": "candidate"
+  },
+  {
+    "name": "candidate_vector_2",
+    "domain": "KAY_TRIE_BRANCH",
+    "canonical_hex": "01020304",
+    "digest_hex": "51614b8a4a5f5a2b5b7b858e626cd19b710d670ebad2e0b9b296bf282b4bfe93",
+    "status": "candidate"
+  },
+  {
+    "name": "candidate_vector_3",
+    "domain": "KAY_LIFE_CERT",
+    "canonical_hex": "01020304",
+    "digest_hex": "59fd735ed0c0923c4316ad197223aed69b6667f6a00a228aae1638a521d1f62f",
+    "status": "candidate"
+  },
+  {
+    "name": "candidate_vector_4",
+    "domain": "KAY_SSR_ROOT",
+    "canonical_hex": "01020304",
+    "digest_hex": "1007c1368120e75ff7f8a47d6933f1440e1a6e0fd1b5e10f8721329dd5d47617",
+    "status": "candidate"
+  }
+]