docs/hash_specification.md

# 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.