Replay Determinism Verification

Version: 1.0.0
Status: Production
Last Updated: 2026-05-23
Editor: Eric Beans, H33.ai, Inc.
Canonical URL: https://h33.ai/verification/replay-determinism/

1. Scope

This walkthrough verifies that the HATS replay engine produces byte-identical output when the same governance bundle is replayed at the same logical timestamp. Deterministic replay is a foundational requirement of the HATS standard: independent verifiers MUST produce identical canonical replay frames and frame hashes for identical inputs.

The test executes 100 replay iterations of the valid bundle from HATS-VW-001, all pinned to timestamp 2026-05-15T14:30:00Z. The expected result is 100/100 iterations producing byte-identical frame hashes (100.0% deterministic).

2. Definitions

Replay: The process of re-executing the verification and frame computation pipeline against a governance bundle at a specified logical timestamp. Replay does not re-sign or re-hash the bundle; it recomputes the canonical replay frame and its digest.
Canonical Replay Frame: The deterministic byte representation of a complete verification pass. The frame includes the bundle ID, session ID, per-node verification results, the frame timestamp, and a SHA3-256 digest of the entire frame. Two verifier implementations producing different frame bytes for the same input are non-conformant.
Frame Hash: The SHA3-256 digest of the canonical replay frame. This single 32-byte value summarizes the entire verification result. If two replay executions produce the same frame hash, the verification results are byte-identical.
Logical Timestamp: The timestamp parameter supplied to the replay command via --at. This timestamp is used to evaluate temporal constraints and is embedded in the canonical replay frame. It does not reflect the wall-clock time of the replay execution.
Environmental Independence: The property that replay output depends only on the input bundle and the logical timestamp, not on the operating system, hardware architecture, timezone, locale, or any other environmental variable.

3. CLI Command

$ hats replay --at "2026-05-15T14:30:00Z" --iterations 100 valid-bundle.json

The --iterations flag instructs the verifier to repeat the replay process the specified number of times and report the determinism result. Each iteration is a complete, independent replay pass.

Flag	Value	Description
`--at`	`2026-05-15T14:30:00Z`	Logical timestamp for the replay (ISO 8601, UTC)
`--iterations`	`100`	Number of independent replay passes
`--format`	`text`	Output format (default)

4. What the Replay Engine Computes

For each iteration, the replay engine:

Loads the governance bundle from disk.
Sets the logical timestamp to the value of --at.
Executes the full verification pipeline (schema, chain, hash, signatures, temporal ordering).
Constructs the canonical replay frame: a fixed-layout byte structure containing the bundle ID (16 bytes), session ID (variable, length-prefixed), logical timestamp (8 bytes, milliseconds since Unix epoch), per-node verification status (1 byte per node), and the overall result (1 byte).
Computes the frame hash: SHA3-256 over the canonical replay frame bytes.
Records the frame hash for comparison against other iterations.

5. Expected Output

stdout

$ hats replay --at "2026-05-15T14:30:00Z" --iterations 100 valid-bundle.json

HATS Replay Engine v1.0.0
Bundle: b8f3c2a1-4e5d-4a6b-9c8d-7e6f5a4b3c2d
Logical timestamp: 2026-05-15T14:30:00.000Z

Running 100 iterations...

Iteration   1: frame_hash = 7b3a9c4d2e1f0a8b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b
Iteration   2: frame_hash = 7b3a9c4d2e1f0a8b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b
Iteration   3: frame_hash = 7b3a9c4d2e1f0a8b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b
  ...
Iteration 100: frame_hash = 7b3a9c4d2e1f0a8b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b

Result: DETERMINISTIC
  Iterations:    100
  Unique hashes: 1
  Match rate:    100.0%
  Frame hash:    7b3a9c4d2e1f0a8b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b
  Duration:      312ms (3.12ms/iteration)

6. JSON Output

{
  "status": "DETERMINISTIC",
  "bundle_id": "b8f3c2a1-4e5d-4a6b-9c8d-7e6f5a4b3c2d",
  "logical_timestamp": "2026-05-15T14:30:00.000Z",
  "iterations": 100,
  "unique_frame_hashes": 1,
  "frame_hash": "7b3a9c4d2e1f0a8b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b",
  "match_rate": 1.0,
  "per_iteration_ms": 3.12,
  "total_duration_ms": 312
}

A match rate of 100.0% confirms that the replay engine is a pure function of its inputs. The frame hash 7b3a9c...4a3b is the conformance test vector for this bundle at this timestamp. Any conformant verifier implementation MUST produce this exact hash.

7. Sources of Non-Determinism

The following are common sources of non-determinism that a conformant implementation MUST avoid:

Source	Problem	Mitigation
Floating-point timestamps	IEEE 754 rounding varies across architectures	Use integer milliseconds since Unix epoch (i64)
JSON key ordering	Hash map iteration order is non-deterministic	Canonical serialization uses fixed field order per schema
String encoding	UTF-8 normalization forms (NFC vs NFD) differ	All strings are NFC-normalized before hashing
Wall-clock time	Embedding current time in the frame	Use only the logical timestamp from `--at`
Random padding	Some serializers add random padding bytes	No padding in canonical serialization
Endianness	Big-endian vs little-endian integer encoding	All integers are little-endian per specification

8. Cross-Platform Verification

To confirm environmental independence, run the replay on multiple platforms and compare frame hashes:

# Linux x86_64 (Graviton4)
$ hats replay --at "2026-05-15T14:30:00Z" valid-bundle.json --format json | jq .frame_hash
"7b3a9c4d2e1f0a8b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b"

# macOS Apple Silicon
$ hats replay --at "2026-05-15T14:30:00Z" valid-bundle.json --format json | jq .frame_hash
"7b3a9c4d2e1f0a8b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b"

# Linux aarch64 (Docker)
$ hats replay --at "2026-05-15T14:30:00Z" valid-bundle.json --format json | jq .frame_hash
"7b3a9c4d2e1f0a8b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b"

All three platforms produce the same frame hash. This is the expected result for a conformant implementation.

9. Failure Scenario: Non-Deterministic Replay

If a verifier produces different frame hashes across iterations, the output would appear as:

Result: NON_DETERMINISTIC
  Iterations:    100
  Unique hashes: 3
  Match rate:    97.0%
  Divergent iterations: [14, 67, 82]

ERROR: Verifier is non-deterministic. 3 of 100 iterations produced
different frame hashes. This implementation is non-conformant.

A non-deterministic result indicates a bug in the implementation (typically one of the sources listed in Section 7). Non-deterministic verifiers MUST NOT be used in production.

10. Conformance

A verifier implementation is conformant with this walkthrough if:

100 iterations of replay at timestamp 2026-05-15T14:30:00Z produce exactly 1 unique frame hash.
The match rate is 100.0%.
The frame hash matches the conformance test vector (given the same cryptographic keys and bundle content).

Conformance test vector ID: HATS-VW-005-REPLAY-DETERMINISM

Related Walkthroughs & Specifications

Verification Index Valid Bundle Tampered Receipt Broken Chain Invalid Signature Conformance Vectors Agent Replay Governance Replay