vm-core/spec/SENTINEL_FAILURE_CODE_SEMANTICS.md

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).