# VEX Evidence Playbook (VEX1–VEX10)

Status: Draft · Date: 2025-12-03
Scope: Define deterministic VEX evidence bundles, justification catalog, and verification workflow for reachability evidence chain (Sprint 0401 tasks 62, 64, 65).

## Goals
- Publish signed VEX justification catalog with DSSE predicates and canonical hashes.
- Require entry-point coverage %, negative tests, and config/flag hash enforcement for each justification.
- Provide offline-friendly proof bundle format with CAS paths and DSSE envelopes.

## Bundle schema (draft)
- `proofBundle.schema.json` (to be placed under `docs/benchmarks/vex-evidence-playbook.schema.json`):
  - `id`, `version`, `createdAt`, `createdBy`.
  - `graph_hash` (BLAKE3-256), `graph_dsse` (sha256 of envelope).
  - `entrypoints[]` with `id`, `coverage_percent`, `negative_tests` (bool), `config_hash` (sha256), `flags_hash` (sha256).
  - `justification_id` (must exist in justification catalog), `justification_dsse` (optional hash).
  - `evidence[]` items with `type` (`trace`, `coverage`, `sbom`, `scan`, `policy`), `cas_uri`, `hash`, `dsse` (optional), `expiresAt`.
  - `signatures[]` DSSE/JWS entries with `keyId`, `sig`, `envelopeDigest`.

## Justification catalog
- Canonical JSON, JCS normalized; BLAKE3 + SHA-256 recorded.
- Fields: `id`, `title`, `description`, `applicability` (list of predicates), `required_evidence` (array of types/hashes), `expiry`, `policy_links`.
- Signed with DSSE predicate `stella.ops/vexJustification@v1`.

## Determinism rules
- Canonical JSON with sorted keys; arrays sorted by `id`.
- Timestamps UTC `Z`; strip milliseconds unless non-zero.
- Hashes: primary BLAKE3-256, secondary SHA-256 for interoperability.
- DSSE subject = canonical JSON hash; verifier must check hash + signature.

## Offline verification
- `scripts/vex/verify_proof_bundle.py` (to be authored) validates schema, hashes, DSSE, and CAS availability.
- No network calls; CAS paths resolved locally via `--cas-root`.

## Fixtures (to add)
- `tests/Vex/ProofBundles/sample-proof-bundle.json` with matching DSSE.
- `docs/benchmarks/vex-justifications.catalog.json` with 5 sample justifications (VEX1–VEX5).

## Next steps
- Freeze `proofBundle.schema.json` and justification catalog hashes.
- Implement `verify_proof_bundle.py` and add CI job to run it over fixtures.
- Wire sprint 0401 tasks 62/64/65 to these artifacts; update Decisions & Risks once frozen.