Eve library

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

Spec

Revision 1

On this page

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.