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,EvidencePackschemas. - 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#
- 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.
- Provenance signals scatter. C2PA attestation, watermark status, consent jurisdiction, and rights clearance live in different panels; cross-referencing requires visual hopping.
- No formal diff surface. Comparative-text reviews show left/right text in
two
<textarea>-shaped cards but do not highlight differences. - 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.
- Trust signals are buried. Provenance "valid / invalid / tampered" status renders as muted badges; operators wanted prominent at-a-glance indicators.
Design principles#
- Evidence has a hierarchy. Primary > supporting > contradicting > contextual. The hierarchy is reflected in visual weight and reading order.
- Provenance is one card. A canonical
<ProvenanceTrustCard />aggregates C2PA + watermark + rights + consent into one card with severity emphasis. - Diff is highlighted at the segment level. Comparative text gets red /
green / unchanged segment highlighting via a shared
<TextDiff left right />component. - Audit history is one timeline. A canonical
<AuditTimeline />consumes the union of stage history + audit events + history inspector into a single chronological timeline. - 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#
<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
absentrows → 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:
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#
apps/oshun/admin/src/components/ProvenanceTrustCard.tsx+.module.css.apps/oshun/admin/src/components/TextDiff.tsx+.module.css(uses thediffnpm package, already installed).apps/oshun/admin/src/components/AuditTimeline.tsx+.module.css.- Migration: rights/grounded-report/voice/avatar surfaces mount
<ProvenanceTrustCard />at the top. - Migration:
ResearchComparativePromotionPanelcomparative section uses<TextDiff />inside<AdminCompareView />. - Migration:
/review/[reviewId]consolidates the three history panels into a single<AuditTimeline />. - 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.