# ChronoSeal Debugging & Failure Mode Guide (WHY_IT_FAILS)

This document provides a technical diagnostic reference for developers, operators, and integration security teams. It explains why a client heartbeat or session initialization fails verification, and how to debug desynchronization issues.

---

## 1. Silent Rejections vs. HTTP Failures

To deny attackers a feedback oracle, the ChronoSeal heartbeat endpoint (`POST /hb`) always returns HTTP status `200 OK` with `{"status": "ok"}` on semantic verification failures.

*   **Successful Attestation:** The JSON response contains the rotated next state information: `next_salt`, `next_mutation_step`, and `next_mutation_order_b64`.
*   **Silently Rejected Attestation:** The JSON response *omits* these three fields. The client is expected to roll back the state preview and retry.

---

## 2. Common Verification Failure Modes

### A. Clock Drift (`TimestampDrift`)
*   **Error Cause:** The client machine's local system time differs from the server's time by more than the configured `max_timestamp_drift_ms` (default 30 seconds).
*   **Diagnostic Signal:** The `/hb` response omits next state parameters.
*   **Remediation:** Synchronize both client and server clocks using NTP (Network Time Protocol). On the client, use NTP-synced system clocks or query server timestamp headers during initialization to compute a local clock offset.

### B. Replay Attempts / Out-of-Sequence (`ChainBroken`)
*   **Error Cause:** The request `prev_hash` does not match the server-stored `last_hash` for the session.
*   **Root Causes:**
    1.  The client replayed a previously captured heartbeat payload.
    2.  The client lost the network response containing the rotated next state parameters and retried with stale state.
    3.  A concurrent request succeeded first, updating the session's hash state.
*   **Remediation:** If network issues cause packet loss, the client must discard the session and initiate a new `/init` handshake. Heartbeats cannot be replayed or resumed from a historical state.

### C. Signature Failures (`Signature`)
*   **Error Cause:** The Ed25519 signature over the canonical JSON payload is invalid.
*   **Root Causes:**
    1.  The client signed a payload that differed in ordering or format from the server's canonical serialization. (Ensure key sorting matches alphabetically: `entropyData`, `fingerprint`, `geneCommitment`, `mutationStep`, `prevHash`, `sessionId`, `stackState`, `timestamp`).
    2.  Different platform engines formatted floats or large numbers differently.
    3.  The public key registered during `/init` does not match the signing key.
*   **Remediation:** Ensure both frontend and backend use strict canonical serializations (BTreeMap alphabetically sorted keys).

### D. VM Stack State Mismatch (`VmStackMismatch`)
*   **Error Cause:** The client's submitted `stack_state` (VM stack and instruction pointer `ip`) does not match the server-side re-execution of the session's random math program.
*   **Root Causes:**
    1.  An automated client bypassed the VM bytecode interpreter.
    2.  The client VM interpreter diverged mathematically (e.g. word size wrapping or logical op mismatches).
*   **Remediation:** Check the VM interpreter implementation parity between the client wasm and `shared::vm`.

### E. Mutation Commitment Mismatch (`MutationCommitmentMismatch`)
*   **Error Cause:** The client's computed `gene_commitment` does not match the server-applied gene mutation.
*   **Root Causes:**
    1.  The client used a different number of `mutation_rounds` than the server config.
    2.  The mutation order execution logic diverged.
*   **Remediation:** Verify that the client wasm correctly parsed `mutation_rounds` from `/init` and passed it to the generator.

### F. Rate Limiting (`RateLimiter`)
*   **Error Cause:** The client submitted more requests than allowed by the server's rate-limiting config (e.g., `rate_limit_count` per `rate_limit_window_secs`).
*   **Diagnostic Signal:** The server returns `200 OK` with `{"status": "ok"}` but no next state data.
*   **Remediation:** Reduce heartbeat frequency or adjust rate limit parameters in the daemon configuration.


## Additional v1.0.2 Failure Modes

- Invalid aspect ratio
- Invalid device pixel ratio
- Invalid hardware concurrency
- NaN or infinite fingerprint values
- Entropy event count exceeds 500
- Client IP rate limited