# Sentinel Failure & Warning Code Semantics (v1)

Status: Canonical (protocol surface)

Source of truth: `vaultmesh-orgine-mobile/tools/sentinel_failure_codes.py`

This document freezes the meaning of `failure_code` / `warning` codes emitted by the Sentinel v1 offline verifier(s). Codes are intended to be stable identifiers for automation, audits, and long-term tooling.

## Stability Rules

- Codes MUST NOT be reused. If meaning must change, add a new code and deprecate the old one.
- Codes MUST have stable semantics across verifier implementations.
- Verifiers MUST emit only codes defined in `vaultmesh-orgine-mobile/tools/sentinel_failure_codes.py`.
- Reports SHOULD include `contract_ids` / `violated_contract_ids` to bind findings to the Contract Matrix.

## Severity Model

- `E_*` = verification FAIL (non-zero exit; bundle is not accepted as correct evidence).
- `W_*` = verification WARNING (bundle may PASS). In `--strict` mode, verifiers MAY elevate some `W_*` conditions into `E_*` failures (documented per-code below).

## Failure Codes (`E_*`)

| Code | Meaning (stable) | Typical Triggers | Remediation / Next Actions |
| --- | --- | --- | --- |
| `E_SCHEMA_INVALID` | Any required schema/format/cross-field validation fails, or required JSON cannot be parsed. | Invalid JSONL line; missing required field; unknown `format`; inconsistent manifest fields. | Re-export the bundle from a known-good producer; verify older seals; treat as corruption/tamper evidence if produced artifacts are expected to be immutable. |
| `E_MISSING_REQUIRED_FILE` | A required file is missing from the bundle (or referenced but absent). | `seal.json` missing; `seal.json.files.*` points to absent paths; integrity lists missing file. | Restore the missing artifact from redundancy/WORM copy; re-export the seal; verify an older seal bundle that includes the missing file(s). |
| `E_MANIFEST_HASH_MISMATCH` | A file’s computed digest does not match `integrity.json`. | One-bit flip / truncation; tampering; wrong `hash_algo` used for verification. | Treat as high-confidence tamper/corruption evidence; restore from a known-good copy; compare against earlier seals / out-of-band copies. |
| `E_OVERSIZE_INPUT` | A bundle input exceeds configured maximum bytes (defense against decompression bombs / giant files). | Abnormally large receipts; attacker-supplied oversized file; misconfigured exporter. | Re-export with bounded payload/chunking; raise size limits only with explicit operational override and strong justification. |
| `E_EVENT_HASH_MISMATCH` | `event_hash` does not match recomputation from canonical bytes (with `event_hash` omitted). | Event field mutation; canonicalization drift; wrong `hash_algo`; corruption. | Confirm `canonicalization_version` + `hash_algo`; re-export from canonical source; treat persistent mismatch as tamper evidence. |
| `E_CHAIN_DISCONTINUITY` | `prev_event_hash` chain breaks (tamper/reorder/rollback evidence) or strict linkage invariants fail. | Missing `prev_event_hash`; chain fork; execution without intent; intent without outcome (strict). | Verify earlier bundles; compare to independent copies; treat as rollback/reorder evidence; restore from last-known-good continuity point. |
| `E_SEQ_NON_MONOTONIC` | Duplicate, missing, or non-monotonic `seq` values in the covered range. | Truncation; rollback; forked history; corrupted append order. | Treat as rollback/corruption evidence; restore from earlier seal; reconstruct from raw receipts if available. |
| `E_RANGE_MISMATCH` | Seal declares a range that does not match included events/roots. | `seal.json.range` inconsistent with receipts; `roots.txt` last seq mismatch. | Re-export the seal with correct range; ensure exporter includes complete receipts for the declared range. |
| `E_CANON_VERSION_UNSUPPORTED` | Declared `canonicalization_version` is unknown/unsupported by this verifier. | Newer producer; older verifier; incompatible artifact set. | Use an updated verifier that supports the declared version; keep N-2 verifier compatibility policy enforced. |
| `E_ROOT_MISMATCH` | Recomputed Merkle end root does not match declared/observed root. | Tampering; missing continuation state (strict); wrong hash algorithm; inconsistent leaf definition. | Confirm `hash_algo` and leaf definition; restore missing continuation state (eg. frontier snapshot) or verify a genesis-range seal; treat persistent mismatch as tamper evidence. |
| `E_REVOKED_CAPABILITY_USED` | A revoked capability is used after revoke (violates “revocation is authoritative”). | `action_executed` references `cap_hash` after `cap_revoke`. | Treat as compromise/violation of authority semantics; investigate actor systems; rotate keys/caps; ensure future actions are denied + recorded via `shadow_receipt`. |

## Warning Codes (`W_*`)

| Code | Meaning (stable) | Typical Triggers | Strict Mode Behavior | Remediation / Next Actions |
| --- | --- | --- | --- | --- |
| `W_FILE_NOT_IN_MANIFEST` | A file exists in the bundle but is not listed in `integrity.json` (or recommended files like `seal.json` are not covered). | Extra stray files; incomplete integrity manifest; accidental artifacts (eg. `.DS_Store`). | MAY be elevated to `E_SCHEMA_INVALID` (fail-closed) depending on verifier policy. | Either add the file to `integrity.json` (preferred) or remove it from the bundle; ensure exporters generate complete integrity manifests. |
| `W_RANGE_ROOT_PARTIAL` | Verifier cannot fully verify roots/chain due to missing prior context (non-genesis range). | `since_seq > 0`; first event is not `seq=0`. | MAY be elevated to `E_CHAIN_DISCONTINUITY` or `E_ROOT_MISMATCH` depending on verifier policy. | Provide verifiable continuation state (frontier snapshot) or export a seal that starts at `seq=0`; accept reduced assurance only intentionally (non-strict). |