git.stella-ops.org/docs/product-advisories/archived/23-Dec-2026 - Designing Replayable Verdict Interfaces.md

Here’s a compact, practical plan for surfacing replayable risk verdicts in Stella Ops so users can see input–output determinism and what changed between releases.

---

Why this matters (quick background)

• A verdict = the platform’s signed decision about risk (e.g., “deployable,” “blocked,” “needs review”), computed from inputs (SBOM, reachability, signatures, policies, VEX, env facts).
• Replayable = same inputs → same verdict (byte‑for‑byte), provable via content‑addressed manifests and attestations.
• Users often ask: “What changed since last release?” A delta verdict answers that with a cryptographically signed diff of evidence and policy effects.

---

Minimal UX (MVP) — one view, three panes

1. Header strip

• Artifact@version • Environment • Policy profile • Verdict (badge) • Signature status • “Replay” button • “Export attestations” button.

2. Smart Diff (center)

• Tabs: Evidence, Policies, Impact.

• Each tab shows Delta Objects (diffable cards), each signed:

  • Evidence deltas (SBOM nodes, reachability subgraphs, VEX claims, signatures, runtime facts).
  • Policy deltas (changed rules, thresholds, exceptions).
  • Impact deltas (risk budget movement, affected services, deploy gates).

3. Explainable Triage (right)

• Collapsible causality chain:

  • “Verdict = Blocked” ↳ due to Policy R‑17 (“fail if unknowns>0 in prod”) ↳ because Evidence:E‑UNK‑42 (package libxyz hash H…) ↳ reachable via Subgraph G‑a12 (entry→…→libxyz) ↳ vendor VEX absent for CVE‑2025‑1234

• Each node links back to its Delta Object and raw payload.

Result: Smart Diff + Explainable Triage unified in one screen; diffs tell what changed, the triage rail tells why it changed.

---

Core objects (signed & diffable)

• Verdict (verdict.jsonld):

  • inputs: CIDs for SBOM, Reachability, Policies, VEX sets, Env facts
  • decision: enum + score + rationale hash
  • evidence_refs[]: CIDs of normalized evidence bundles
  • policy_trace[]: ordered rule hits with pre/post states
  • provenance: in‑toto/DSSE, signer, algo (Ed25519 / optional PQ)
  • replay_hint: docker image digests, feed snapshots, clock fence

• Delta Verdict (verdict.delta.jsonld):

  • base_verdict_cid, head_verdict_cid
  • diffs[]: typed ops (add/remove/modify) over normalized graphs
  • risk_budget_delta, gate_effects[] (which gates flipped)
  • signatures[] (platform, optional vendor co‑sign)

All objects stored/content‑addressed in Authority (Postgres SOR; Valkey cache) and attachable to OCI artifacts as attestations.

---

UI interactions (MVP flow)

• Select two runs (e.g., app:payments @ 2025‑12‑20 vs 2025‑12‑23) → Compute/Load Delta Verdict → render cards.
• Click any card → left shows raw JSON, right shows cause chain.
• “Replay” → spins a deterministic runner with frozen inputs (feed pins, policy version, env snapshot) → emits replayed verdict with new timestamp, same content hash expected.

---

Visual design hints

• Keep it diff‑first: green (+), red (–), gray (unchanged).
• Pin trust badges on each card (Signed/Unsigned, Verifier OK/Fail).
• Show unknowns and assumptions as chips (count + hover detail).
• One click to “Open as Evidence Pack” (ZIP with all referenced CIDs).

---

API sketch (internal)

• GET /verdicts/{cid} → full verdict
• POST /verdicts/diff → body: {base: cid, head: cid} → delta verdict
• POST /verdicts/replay → body: {cid} → new run with frozen inputs
• GET /evidence/{cid} → normalized bundle (SBOM, subgraph, VEX, sigs)
• GET /policy-trace/{cid} → ordered rule hits + bindings

---

Normalization & determinism (must‑haves)

• Canonical JSON (JCS), sorted maps/lists, stable IDs.
• Graph hashing (Merkle over node/edge tuples).
• Feed pinning (timestamped snapshots with source checksums).
• DSSE envelopes; Rekor‑compatible log proof (or mirror).

---

Rollout plan (3 sprints)

S1: Canonicalization library, Verdict object, Delta over SBOM+Policies, UI skeleton with diff cards. S2: Reachability subgraph deltas, policy‑trace explainer, signatures & verify badges, export packs. S3: Replay runner with freeze‑frame inputs, gate effects view, OCI attestation attach/read.

---

Acceptance criteria (MVP)

• Given identical inputs, replay reproduces byte‑identical verdict CID.
• Delta view pinpoints exact evidence/policy changes in <2 clicks.
• Each delta object displays signature status and source.
• Exported evidence pack re‑computes the same verdict on air‑gapped node.

---