Entrypoint Failure Contracts

Every deterministic vault-ingress entrypoint closes its outer failure boundary (#203). No unexpected exception reaches a caller as a traceback, and no machine-readable command leaves a truncated document on stdout.

Read this when a script exits non-zero and you need to know what state it left behind. It inventories the boundary contract only — each script's normal validation predicates stay in the script (rules/script-as-black-box.md).

The Shared Diagnostic Shape

skills/vault-ingress/scripts/failure_diagnostics.py owns the emitted document. On an unexpected failure the entrypoint writes to stderr, one JSON object on the first line:

{"error": "<entrypoint>_unexpected_failure",
 "error_type": "RuntimeError",
 "origin": ["persist-results.py:412 in merge_return"]}

A human-readable recovery note follows on the next lines.

• error_type is the exception CLASS. The exception MESSAGE never crosses the boundary — no-secrets forbids it, and a FileNotFoundError message embeds the path it could not find.
• origin is basename:line in function, innermost last. Never a full path.
• Mutating entrypoints add commit-position fields; see the table.

CLI Contracts

Every script named below lives in skills/vault-ingress/scripts/.

The three read-only audits and render-markdown-deck.py use exit 3 because argparse already owns exit 2 there; a caller can still tell a malformed invocation from a broken tool. render-markdown-deck.py additionally owns exit 1 for its own verdict — an unreadable deck, an unavailable renderer lane, a renderer that failed — with a plain diagnostic on stderr, not the JSON document above.

preflight-vault.py is the one entrypoint whose failure lands on stdout: a caller gates claiming on its report, and a missing report reads as "preflight never ran". It emits a real report — ok: false, one blocking finding whose keys match every other finding — so a consumer parses it normally.

What an Exit Code Does Not Mean

• Exit 1 is the script's own verdict: a rejected batch, a structurally invalid catalog. The tool worked.
• Exit 2 (or 3) with the JSON document above means the tool FAILED. A read-only command's inputs are unexamined, not clean. Never read it as a pass.
• SystemExit from a documented error path is not caught by these boundaries — those exit codes reach the caller unchanged.

Retrying a Mutating Script

database_written, analyses_written, and output_written state whether the atomic commit landed before the failure:

• true — the write is durable. Re-running re-persists the batch. Re-read the live state before deciding.
• false — every target was rolled back. The batch can be retried as-is.

Never infer commit position from the exit code; read the field.

Worker Protocol Boundaries

pptx_evidence.py, pptx-extraction.py, pdf_evidence.py, local_media_evidence.py, local_media_download.py, and local_media_transcription.py — same directory — run supervised worker children whose stdout is reserved for one authenticated frame. Their boundaries emit a path-neutral <kind> worker failed: <reason> line on stderr and exit 2; the supervisor reads a non-zero child without an authenticated response as a bounded crash.