diff --git a/docs/SNAPSHOT_HASH_v1.0.md b/docs/SNAPSHOT_HASH_v1.0.md index 7feaf5b..8184b9d 100644 --- a/docs/SNAPSHOT_HASH_v1.0.md +++ b/docs/SNAPSHOT_HASH_v1.0.md @@ -6,10 +6,46 @@ This document defines the canonical snapshot hashing algorithm used by DigiEmu C Scope: canonical_utf8_without_sha256_comment_line, SHA-256, uppercase hex. -Rules (summary): -- Build an explicit replay state object that contains only the stable kernel state (units, versions, meaning, claims, uncertainty). -- Serialize using `internal/canonicaljson.Marshal` which sorts map keys, preserves array order, and emits compact JSON without extra whitespace. +## Rules + +- Build an explicit replay state object that contains only the stable kernel state. +- Serialize using `internal/canonicaljson.Marshal`. +- Object/map keys MUST be sorted deterministically. +- Array order MUST be preserved. +- Insignificant whitespace MUST NOT affect the canonical bytes. - Compute SHA-256 over the UTF-8 bytes of the canonical JSON. -- Encode the digest as uppercase hexadecimal and record it where specified (e.g. `docs/GENESIS_ANCHOR_v1.0.yaml`), excluding the sha256 comment line from canonical bytes. +- Encode the digest as uppercase hexadecimal. + +## Deterministic hash boundary + +The snapshot hash boundary MUST include only deterministic replay state. + +The following values are considered outside the deterministic hash boundary: + +- timestamps such as `CreatedAtUnix` +- generated or user-facing labels such as version labels +- actor identifiers such as `ActorID` +- audit trace metadata +- verification metadata such as `expected_hash_v1` +- runtime environment data +- build or bundle metadata that does not change reconstructed state + +These values MAY be preserved for auditability, display, traceability, or governance purposes, but they MUST NOT change deterministic state identity unless explicitly included as deterministic replay state by a future versioned specification. + +## Replay and verification metadata + +`expected_hash_v1` MUST be excluded from the hashed replay scope. + +This prevents self-referential hashing and keeps declared verification metadata separate from reconstructed deterministic state. + +## Stability guarantees + +DigiEmu Core v1.x requires the following stability guarantees: + +- same deterministic state -> same canonical JSON -> same SHA-256 hash +- different input key ordering -> same canonical JSON, if logical content is identical +- pretty-printed or compact JSON -> same canonical JSON, if logical content is identical +- replaying the same bundle input -> same reconstructed state hash +- tampered deterministic state -> different hash -> verification FAIL -Ordering constraints and determinism requirements are normative — see `docs/PUBLIC_API_README.md` for links. +Ordering constraints and determinism requirements are normative. See `docs/PUBLIC_API_README.md` and `docs/VERIFY_SPEC_v1.0.md` for related contracts. \ No newline at end of file diff --git a/docs/VERIFY_SPEC_v1.0.md b/docs/VERIFY_SPEC_v1.0.md index 492e093..ef07359 100644 --- a/docs/VERIFY_SPEC_v1.0.md +++ b/docs/VERIFY_SPEC_v1.0.md @@ -158,7 +158,14 @@ Verification success (`ok=true`) MAY still return exit 3 if `--write-expected` i - BOM-safe decode MUST be applied. - Canonical JSON MUST be stable for the same logical content. +- Object/map key ordering MUST NOT affect canonical JSON output. +- Nested object/map key ordering MUST NOT affect canonical JSON output. +- Pretty-printed or compact JSON MUST produce the same canonical JSON if logical content is identical. - Trace ordering MUST be deterministic. +- ReplayV1 MUST be idempotent for the same bundle input. +- `expected_hash_v1` MUST be excluded from replay/hash scope. +- Verification metadata MUST NOT change deterministic reconstructed state identity. +- Tampered deterministic snapshot state MUST result in verification failure. ## 11. Security & Governance Notes