docs: document deterministic verification guarantees

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.

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