# Spec 337 - Evidence / Review Pack State Contract

Status: prepared
Created: 2026-05-30
Scope: Evidence / Review Pack readiness surfaces

This contract defines what the first screen must show per repo-backed state, without inventing evidence, customer-safe, auditor-ready, or export truth.

## Flow Steps

The Evidence readiness flow uses these fixed steps:

1. Source data selected
2. Evidence snapshot
3. Stored report
4. Review pack
5. Customer-safe output
6. Export / delivery

## Presentation Vocabulary

Presentation states are not a new enum family. They are labels derived from existing model state.

- `Available`
- `Missing`
- `Required`
- `Generating`
- `Failed`
- `Stale`
- `Needs review`
- `Ready`
- `Not ready`
- `Generated`
- `Unavailable`
- `Collapsed`

## Universal Defaults

- Diagnostics default: `Collapsed`.
- Raw JSON / raw payload default: hidden.
- Primary next action: exactly one per state.
- Customer-safe output: `Ready` only when Customer Review Workspace / Environment Review package readiness is repo-backed.
- Export/download: `Available` only when a ready, non-expired review pack has file metadata and the user can access the signed download.
- Operation proof: proof of generation/export is not the same as evidence output or customer-safe readiness.
- External delivery: unavailable unless a repo-backed mechanism is discovered.

## State Contracts

### 1. No Evidence Snapshot

| Field | Contract |
|---|---|
| State | No evidence snapshot |
| Visible status | Evidence snapshot required |
| Reason | No evidence snapshot is available for the selected review scope. |
| Impact | Review pack output cannot be trusted or exported yet. |
| Primary next action | Generate evidence snapshot, only when repo-supported and authorized. Otherwise show unavailable state. |
| Flow gate states | Source data selected: Available or Unavailable (repo-backed); Evidence snapshot: Missing; Stored report: Unavailable; Review pack: Unavailable; Customer-safe output: Not ready; Export / delivery: Unavailable |
| Evidence proof | Snapshot unavailable; source data proof only if repo-backed. |
| Customer-safe state | Not ready. |
| Export state | Unavailable. |
| Diagnostics default | Collapsed; no raw JSON visible. |

### 2. Evidence Snapshot Generating

| Field | Contract |
|---|---|
| State | Evidence snapshot generating |
| Visible status | Evidence generation in progress |
| Reason | Evidence snapshot generation is currently running. |
| Impact | Review pack output is not final yet. |
| Primary next action | View operation progress. |
| Flow gate states | Source data selected: Available or Unavailable; Evidence snapshot: Generating; Stored report: Unavailable; Review pack: Unavailable; Customer-safe output: Not ready; Export / delivery: Unavailable |
| Evidence proof | Linked OperationRun visible when authorized. |
| Customer-safe state | Not ready. |
| Export state | Unavailable. |
| Diagnostics default | Collapsed. |

### 3. Evidence Snapshot Failed

| Field | Contract |
|---|---|
| State | Evidence snapshot failed |
| Visible status | Evidence generation failed |
| Reason | Evidence snapshot generation ended with errors. |
| Impact | Review pack output cannot be generated from this evidence yet. |
| Primary next action | Review evidence operation. |
| Flow gate states | Source data selected: Available or Unavailable; Evidence snapshot: Failed; Stored report: Unavailable; Review pack: Unavailable; Customer-safe output: Not ready; Export / delivery: Unavailable |
| Evidence proof | Failed OperationRun proof visible when authorized. |
| Customer-safe state | Not ready. |
| Export state | Unavailable. |
| Diagnostics default | Collapsed; failure summarized before diagnostics. |

### 4. Evidence Snapshot Stale

| Field | Contract |
|---|---|
| State | Evidence snapshot stale or expired |
| Visible status | Evidence refresh required |
| Reason | Evidence exists, but its freshness is outside the acceptable window or the snapshot is expired/stale. |
| Impact | Review pack output should not be treated as current until evidence is refreshed. |
| Primary next action | Refresh evidence snapshot, only when repo-supported and authorized. |
| Flow gate states | Source data selected: Available or Unavailable; Evidence snapshot: Stale; Stored report: Unavailable or Available (repo-backed); Review pack: Unavailable or Needs review; Customer-safe output: Not ready; Export / delivery: Unavailable |
| Evidence proof | Existing snapshot proof may be shown with stale/expired state. |
| Customer-safe state | Not ready or Needs review; never Ready from stale evidence alone. |
| Export state | Unavailable unless implementation proves a still-valid review-derived pack is independent and repo-backed; default unavailable. |
| Diagnostics default | Collapsed. |

### 5. Evidence Snapshot Available, Stored Report Missing

| Field | Contract |
|---|---|
| State | Evidence snapshot available / stored report missing |
| Visible status | Stored report required |
| Reason | Evidence snapshot exists, but no stored report is available for this review output. |
| Impact | Evidence is present but not yet packaged for consumption. |
| Primary next action | Generate stored report, only if repo-supported and authorized; otherwise Open evidence snapshot or show report unavailable. |
| Flow gate states | Source data selected: Available; Evidence snapshot: Available; Stored report: Missing; Review pack: Unavailable; Customer-safe output: Not ready; Export / delivery: Unavailable |
| Evidence proof | Evidence snapshot proof available. Stored report proof unavailable. |
| Customer-safe state | Not ready. |
| Export state | Unavailable. |
| Diagnostics default | Collapsed. |

### 6. Stored Report Available, Review Pack Required

| Field | Contract |
|---|---|
| State | Stored report available / review pack required |
| Visible status | Review pack required |
| Reason | Stored report exists, but a review pack has not been generated. |
| Impact | Customer-safe delivery is not ready yet. |
| Primary next action | Generate review pack, only when authorized and entitlement/evidence requirements allow it. |
| Flow gate states | Source data selected: Available; Evidence snapshot: Available; Stored report: Available; Review pack: Required; Customer-safe output: Not ready; Export / delivery: Unavailable |
| Evidence proof | Evidence snapshot and stored report proof available. |
| Customer-safe state | Not ready. |
| Export state | Unavailable. |
| Diagnostics default | Collapsed. |

### 7. Review Pack Generating

| Field | Contract |
|---|---|
| State | Review pack generating |
| Visible status | Review pack generation in progress |
| Reason | Review pack generation is currently running. |
| Impact | Customer output is not final yet. |
| Primary next action | View operation progress. |
| Flow gate states | Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Generating; Customer-safe output: Not ready; Export / delivery: Unavailable |
| Evidence proof | ReviewPack OperationRun proof visible when authorized. |
| Customer-safe state | Not ready. |
| Export state | Unavailable. |
| Diagnostics default | Collapsed. |

### 8. Review Pack Failed

| Field | Contract |
|---|---|
| State | Review pack failed |
| Visible status | Review pack generation failed |
| Reason | Review pack generation ended with errors. |
| Impact | Customer-safe output cannot be generated from this pack yet. |
| Primary next action | Review review-pack operation. |
| Flow gate states | Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Failed; Customer-safe output: Not ready; Export / delivery: Failed or Unavailable |
| Evidence proof | Failed OperationRun proof visible when authorized. |
| Customer-safe state | Not ready. |
| Export state | Failed or Unavailable, based on repo-backed artifact state. |
| Diagnostics default | Collapsed; failure summarized before diagnostics. |

### 9. Review Pack Available, Customer-Safe Output Needs Review

| Field | Contract |
|---|---|
| State | Review pack available / customer-safe review required |
| Visible status | Customer-safe review required |
| Reason | A review pack exists, but customer-safe output has not been confirmed by repo-backed review/package readiness. |
| Impact | Do not share the pack externally until it has been reviewed. |
| Primary next action | Review customer output. |
| Flow gate states | Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Available; Customer-safe output: Needs review; Export / delivery: Required, Available, or Unavailable based on pack file truth |
| Evidence proof | Review pack proof available; OperationRun proof available when linked. |
| Customer-safe state | Needs review. |
| Export state | Do not show export/share as final customer-ready unless download/package readiness is repo-backed. |
| Diagnostics default | Collapsed. |

### 10. Customer-Safe Output Ready

| Field | Contract |
|---|---|
| State | Customer-safe output ready |
| Visible status | Customer-safe output ready |
| Reason | Review pack output is available for customer/auditor consumption through a repo-backed review/package readiness path. |
| Impact | The pack can be shared or exported according to workspace policy. |
| Primary next action | Export review pack or Download export, only when authorized. |
| Flow gate states | Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Available; Customer-safe output: Ready; Export / delivery: Available, Generated, or Required based on repo-backed artifact state |
| Evidence proof | Linked snapshot/review/pack/operation proof visible when authorized. |
| Customer-safe state | Ready. |
| Export state | Available or Required from review-pack file truth. |
| Diagnostics default | Collapsed. |

### 11. Export Available

| Field | Contract |
|---|---|
| State | Export available |
| Visible status | Review pack export available |
| Reason | A generated export artifact is available. |
| Impact | Evidence package can be downloaded or shared according to capability rules. |
| Primary next action | Download export. |
| Flow gate states | Source data selected: Available; Evidence snapshot: Available; Stored report: Available or Unavailable (repo-backed); Review pack: Available; Customer-safe output: Ready or Needs review based on repo-backed customer-safe state; Export / delivery: Available |
| Evidence proof | Review pack file metadata and OperationRun proof available when authorized. |
| Customer-safe state | Ready only if repo-backed; otherwise Needs review even when download exists. |
| Export state | Available. |
| Diagnostics default | Collapsed. |

### 12. Export Unavailable / External Delivery Not Configured

| Field | Contract |
|---|---|
| State | Export unavailable |
| Visible status | Export unavailable |
| Reason | No generated export artifact is available, the pack is not ready, the file is missing/expired, or external delivery is not configured. |
| Impact | Evidence package cannot be downloaded or delivered from this surface yet. |
| Primary next action | Generate review pack, regenerate export, review operation, or no action, based on repo-backed state and authorization. |
| Flow gate states | Source data selected: repo-backed; Evidence snapshot: repo-backed; Stored report: repo-backed; Review pack: repo-backed; Customer-safe output: repo-backed; Export / delivery: Unavailable |
| Evidence proof | Show available proof rows only. |
| Customer-safe state | Ready, Needs review, Not ready, or Unavailable based on repo truth; never inferred from missing export. |
| Export state | Unavailable. |
| Diagnostics default | Collapsed. |

## Surface-Specific Notes

### Evidence Overview

- Evidence Overview can show internal evidence and artifact proof.
- Evidence Overview must not infer `Customer-safe output ready` unless it links to a repo-backed Customer Review Workspace / Environment Review current export state.
- Raw artifact inventory remains secondary.

### Customer Review Workspace

- This is the safest source for customer-safe package readiness.
- It can show customer-safe output ready only when existing review/package/download readiness methods support that claim.
- Diagnostics remain collapsed and customer-facing default content must hide raw internals.

### Review Pack Resource

- A ready review pack with file metadata supports export/download availability.
- It does not automatically support `auditor-ready` copy.
- The existing expire action remains destructive/confirmed and is not changed by this spec.

### Stored Report

- Stored report `Available` / `Missing` is repo-backed.
- Stored report `Generating` / `Failed` is not repo-backed unless implementation discovers a direct OperationRun relation or existing job/run source.