# V1-AWEB-097 — Evidence, Provenance, Diff & Compare Surface Spec

Implementation spec for the Phase 17.10 redesign of evidence / provenance / diff
/ compare surfaces. Goal: **complex review states remain readable and
trustworthy**.

## Reference: as-is

- Evidence: `ResearchSourceReviewPanel`, `ResearchComparativePromotionPanel`,
  `CitationValidationWorkspacePanel`, `EvidencePack` schemas.
- Provenance: `RightsProvenancePanel`, `WatermarkVerificationPanel`,
  `RightsExportConsentInspectionPanel`, `AdminProvenanceBadge`.
- Diff / compare: comparative-text section of
  `ResearchComparativePromotionPanel` (no formal diff).
- Audit history: `ReviewAuditEventLog`, `ReviewStageHistory`,
  `ReviewHistoryInspector`, per-panel decision-history sections.

### As-is pain points

1. **Evidence rows are dense without hierarchy.** Citations, evidence refs,
   source-set members, copilot evidence refs all render as flat tables.
   Operators cannot tell at a glance which row is the primary citation vs.
   supporting evidence.
2. **Provenance signals scatter.** C2PA attestation, watermark status, consent
   jurisdiction, and rights clearance live in different panels;
   cross-referencing requires visual hopping.
3. **No formal diff surface.** Comparative-text reviews show left/right text in
   two `<textarea>`-shaped cards but do not highlight differences.
4. **Audit history is multi-panel.** Stage history, audit event log, and history
   inspector are separate components even though they share the same underlying
   event stream.
5. **Trust signals are buried.** Provenance "valid / invalid / tampered" status
   renders as muted badges; operators wanted prominent at-a-glance indicators.

## Design principles

1. **Evidence has a hierarchy.** Primary > supporting > contradicting >
   contextual. The hierarchy is reflected in visual weight and reading order.
2. **Provenance is one card.** A canonical `<ProvenanceTrustCard />` aggregates
   C2PA + watermark + rights + consent into one card with severity emphasis.
3. **Diff is highlighted at the segment level.** Comparative text gets red /
   green / unchanged segment highlighting via a shared `<TextDiff left right />`
   component.
4. **Audit history is one timeline.** A canonical `<AuditTimeline />` consumes
   the union of stage history + audit events + history inspector into a single
   chronological timeline.
5. **Trust signals are prominent.** Provenance trust status surfaces at the top
   of every review surface that has provenance data (not buried in a
   sub-section).

## Evidence hierarchy

Each row in an evidence list ships with a `rank` prop:

- `primary` — full row, stripe colour `#38bdf8`, larger title.
- `supporting` — full row, no stripe.
- `contradicting` — full row, stripe colour `#ef4444`, italicised summary.
- `contextual` — collapsed row, click-to-expand.

Existing panels migrate row rendering to use this rank.

## ProvenanceTrustCard

```tsx
<ProvenanceTrustCard
  c2pa={{ status: 'valid' | 'invalid' | 'tampered' | 'absent' }}
  watermark={{ status: 'verified' | 'tampered' | 'absent' }}
  rights={{ status: 'verified' | 'pending' | 'revoked' | ... }}
  consent={{ status: 'verified' | 'pending' | 'expired' | ... }}
  jurisdiction="us" | "eu" | ...
/>
```

Renders a single card with four sub-rows. Card severity is the worst of the
four:

- Any `invalid | tampered | revoked | expired` → critical (red stripe).
- Any `pending` → attention (amber stripe).
- All `valid | verified` → normal (green stripe).
- Mixed `absent` rows → neutral.

Card is mounted at the top of every detail surface that has provenance data
(rights provenance, V1-AWEB-086 grounded report detail, V1-AWEB-088 voice/avatar
consent rows).

## TextDiff

`<TextDiff left right />` renders two columns with synchronised scroll. Per-line
and per-word diff highlighting uses a Myers diff implementation (`diff` npm
package — already in the monorepo). Unchanged segments render in muted text;
insertions in green; deletions in red.

The comparative-text section of `ResearchComparativePromotionPanel` migrates to
use `<TextDiff />` inside the `<AdminCompareView />` wrapper from V1-AWEB-094.

## AuditTimeline

`<AuditTimeline events={...} />` consumes a union event type:

```ts
type AdminAuditTimelineEvent =
  | { kind: 'stage_transition'; ... }
  | { kind: 'audit_event'; ... }
  | { kind: 'decision'; ... }
  | { kind: 'copilot_feedback'; ... }
  | { kind: 'override'; ... };
```

Events render chronologically (newest at top), grouped by day, with an icon per
event kind and a severity stripe driven by event metadata. The
`/review/[reviewId]` page mounts a single `<AuditTimeline />` in place of
`ReviewAuditEventLog` + `ReviewStageHistory` + `ReviewHistoryInspector`.

## Implementation deliverables

1. `apps/oshun/admin/src/components/ProvenanceTrustCard.tsx` + `.module.css`.
2. `apps/oshun/admin/src/components/TextDiff.tsx` + `.module.css` (uses the
   `diff` npm package, already installed).
3. `apps/oshun/admin/src/components/AuditTimeline.tsx` + `.module.css`.
4. Migration: rights/grounded-report/voice/avatar surfaces mount
   `<ProvenanceTrustCard />` at the top.
5. Migration: `ResearchComparativePromotionPanel` comparative section uses
   `<TextDiff />` inside `<AdminCompareView />`.
6. Migration: `/review/[reviewId]` consolidates the three history panels into a
   single `<AuditTimeline />`.
7. Tests: trust card severity test (covers worst-of-four logic), text diff
   component test (insertion + deletion highlighting), audit timeline grouping
   test, Playwright `admin-evidence-provenance.spec.ts`.

## Out of scope

- Streaming audit timeline updates (deferred).
- Per-segment annotations on TextDiff (deferred).
- Provenance trust card multi-jurisdiction overlay (deferred).

## Acceptance criteria

- Every detail surface with provenance data renders a single
  `<ProvenanceTrustCard />` at the top with severity-correct stripe.
- Comparative-text reviews render with per-segment red/green diff highlighting.
- `/review/[reviewId]` shows one consolidated audit timeline instead of three
  separate history panels.
- Evidence rows honour the four-rank hierarchy (primary / supporting /
  contradicting / contextual).
- All component tests + Playwright spec pass; existing tests remain green after
  migration.
