Skip to content

Error model

Contract and ordering

Target API errors are HallmarkError(code: ErrorCode, stage: Stage, retryable: bool), with no raw value, path, exception string or transcript attached. Stage is one of parse, enroll, attest, bind, execute, prove, verify, store. CLI translation follows public API. ErrorCode is exactly the codes in the table below. Unexpected exceptions become INTERNAL_ERROR with a local random diagnostic ID; they never result in an accepted claim.

Check in this order: size/type/schema; external trust/config; registry; request/time; receipt signature; hardware if required; opening/input binding; proof and integer verdict; aggregate policy. Return the first failed stage and a deterministically sorted list of codes within that stage. A proof backend is never called on an input that failed earlier checks. Claim B-only B1 verification may explicitly decline hardware validation, while still requiring enrollment and complete binding/proof checks.

Code Trigger Response and recovery
INPUT_INVALID Duplicate/extra keys, invalid type/UTF-8/version/encoding, malformed signature or digest Reject; create a corrected new artifact
LIMIT_EXCEEDED Size, nesting, unit/chunk count or declared resource bounds exceeded Reject before allocation/work; new admission for a larger profile
TRUST_MISSING No externally enrolled key, model, policy or required hardware root No claim acceptance; enroll through owner-controlled channel
REGISTRY_INVALID Signature threshold, time, sequence, predecessor or entry mismatch Reject; restore trusted snapshot/history, never lower local sequence
ARTIFACT_RETIRED Any required artifact retired by the verification time Reject; retain historical evidence without current acceptance
REQUEST_MISMATCH Nonce/audience/interaction/model/policy differs Reject; never retry under changed expectations
STALE_EVIDENCE Expiry, stale hardware collateral, future issuance Reject; acquire fresh evidence under approved host access
SIGNATURE_INVALID Receipt signature does not verify under epoch key Reject permanently
ATTESTATION_INVALID Invalid chain/TCB/freshness/debug state or missing device binding Reject A and B2; no mock fallback
MEASUREMENT_UNKNOWN Serving image, loader or accelerator measurements not enrolled Reject until independently reviewed enrollment
OPENING_FAILED Byte-exact commitment differs Reject; no normalization repair
INPUT_BINDING_FAILED Tokenizer, length, masks, chunk coverage or input digest differs Reject B; new complete proof required
PROOF_INVALID Proof/key/setup/backend mismatch or verifier false Reject B; preserve failed artifact
VERDICT_MISMATCH Receipt, proof, integer comparison or all-pass result disagree Reject; stop serving and investigate
POLICY_BLOCKED Valid evidence establishes any classifier block Report valid evidence separately; overall accepted is false
PROOF_PENDING Proof absent or unfinished No accepted bundle; explicit later collection
RESOURCE_EXHAUSTED Timeout, OOM or approved job-count cap Kill worker, retain failure, no automatic budget increase
STORAGE_FAILED Disk full, existing output, failed durable write or encryption No release/new complete artifact; preserve prior state
INTERNAL_ERROR Unexpected implementation/backend exception Fail closed; local sanitized diagnostic, manual investigation

State and retry rules

Request/receipt identity is immutable. A failed job may be retried once within its original approved total budget using the same inputs/key/setup; each attempt has a separate record. Invalid evidence, schema, policy and signature failures are never retried automatically. Expired jobs delete their per-receipt encryption keys and cannot return to ready. Duplicate completed requests return the same signed receipt only to the authenticated requester; the ledger does not expose existence to other audiences.

INV-ERROR-PRIVACY: no normal stdout/stderr/event contains raw prompts, responses, tokens, salts, weights, keys, local absolute paths or external provider exception text.

INV-ERROR-TRUTH: unavailable, pending, declined trust, invalid evidence and policy-blocked are distinct states. None is reported as proof failure if no proof was actually checked.

Implemented diagnostic boundary

hallmark.errors exports ErrorCode, Stage, ERROR_CODES, STAGES, HallmarkError, sanitize_exception and first_stage_errors. HallmarkError(code, stage, retryable=False) validates finite metadata; as_dict() emits only schema_id="hallmark/error/1", code, stage, retryable and diagnostic_id. Unexpected failures get a random UUID4 hex ID; normal failures have null IDs. The ID is a correlation handle, not proof that a private traceback or diagnostic file exists.

The CLI applies this boundary to argument parsing and execution. Invalid values/Unicode/schema and absent/non-file input paths produce INPUT_INVALID at parse. Timeouts and memory exhaustion produce RESOURCE_EXHAUSTED; other filesystem failures produce STORAGE_FAILED at store. Unexpected exceptions, including failed child processes, produce INTERNAL_ERROR. Existing typed errors retain their code/stage. External messages, notes, causes and process output never enter the JSON record.

Exit 2 means INPUT_INVALID, LIMIT_EXCEEDED or TRUST_MISSING. Exit 3 means PROOF_PENDING, RESOURCE_EXHAUSTED, STORAGE_FAILED or INTERNAL_ERROR. The other codes exit 1 (rejected claim/policy). No error maps to exit 0. The research CLI does not implement proof/attestation acceptance just because the taxonomy includes those codes.

first_stage_errors accepts 1–64 typed errors and selects the earliest of parse, enroll, attest, bind, execute, prove, verify, store, sorting within that stage by code and retryability. It organizes diagnostics; it does not execute a verifier or replace the detailed check order above.

WireError retains its codec API as a HallmarkError subclass. Internal research helpers still raise their existing exceptions; callers exposing those failures must apply the diagnostic boundary. Existing run files, source/diff snapshots and the legacy two-field failure.json are preserved, not sanitized or rehashed. Versioned local events and immutable attempt/failure records are implemented in hallmark.events; see observability. Decision 0004 records the compatibility change.