# Witness packs

EvoWitness treats a breaking compatibility finding as incomplete until it has a replayable counterexample. A witness pack is the compact artifact that carries those counterexamples across review, CI and regression tests.

## Case model

Each `WitnessCase` contains:

- a stable `EW-...` id derived from report order, rule code and path;
- the rule code, direction and path;
- the JSON payload;
- the contract version that should accept the payload;
- the contract version that should reject the payload;
- a replay assertion and the original reason.

This is intentionally narrower than a data contract governance report. It does not store ownership metadata, lifecycle status, external ticket links or registry state.

## Output formats

- `WitnessPack::to_json()` writes one envelope with all cases;
- `WitnessPack::to_jsonl()` writes one complete case per line for CI fan-out;
- `WitnessPack::to_markdown()` writes a review-friendly evidence document;
- `AnalysisReport::to_witness_jsonl()` is the shortest path from an analysis report to a machine-readable negative-test stream.

The CLI accepts `witness-json`, `witness-jsonl` and `witness-md` as output formats.

## Evidence Scorecard

`AnalysisReport::score_witness_evidence()` checks whether the evidence is strong enough to use in review:

- every breaking finding is covered by a witness;
- case ids keep the deterministic `EW-...` form;
- payloads and contract sides are present;
- repeated payloads are called out for reviewer attention;
- paths or payloads that look secret-bearing are flagged before upload;
- weak reasons are reported so the evidence remains explainable.

The CLI formats `score-json` and `score-md` expose the same witness-specific scorecard without external services.
The scorecard also reports a compact readiness label plus a next action so maintainers can decide whether a pack is ready to replay, needs human review, or is blocked by malformed evidence.

## Replay suite

`AnalysisReport::to_replay_suite()` turns each witness into three steps:

- validate the payload as accepted by the source side;
- validate the same payload as rejected by the target side;
- keep the target rejection as a regression guard.

This keeps EvoWitness different from a governance system: it does not open tickets or own lifecycle state. It emits deterministic replay material that other tools can consume.

## Replay contract

For every case, downstream tools should replay the assertion:

```text
accept under <acceptedBy> and reject under <rejectedBy>
```

The project already verifies generated witnesses through `verify_witness`; the pack makes the same idea portable without requiring EvoWitness to create external tests, issues or dashboards itself.