Findings Ledger — Runtime Instrumentation UI Integration Requirements

Status: Draft awaiting review — Web UI lead sign-off pending. Sprint reference: SPRINT_20260429_015_FindingsLedger_runtime_documentation task FL-RUNTIME-DOC-006. Follow-up implementation sprint: SPRINT_FUTURE_FE_findings_runtime_panel.
This document is REQUIREMENTS ONLY. UI implementation is out of scope for sprint 015.

1. Goal

Surface runtime instrumentation evidence on the Finding Detail Page so that analysts can answer “is this finding actually being exercised in production?” without leaving the UI.

The wire surface is already shipped (sprint 013); this document specifies what the Web console should render on top of it.

2. User stories

US-RT-1 — Analyst viewing a single finding sees runtime evidence

As a security analyst, when I open a finding’s detail page, I want to see whether the vulnerable code path has been exercised at runtime, so that I can prioritize triage on findings that matter operationally.

Acceptance criteria:

A “Runtime” tab is visible on every Finding Detail Page.
Selecting the tab loads runtime evidence within 500 ms (P50, single GET to /runtime/traces + /runtime/score).
The tab shows three regions: a score gauge, an aggregate table, and a timeline chart.

US-RT-2 — Operator sees explicit “no data yet” empty state

As an operator, when I open a finding for which no runtime traces have been ingested yet, I want to see a friendly hint explaining how to start collecting traces, so that I know whether to wait or to enable instrumentation.

Acceptance criteria:

A 404 from /runtime/traces renders a “no runtime data yet” empty state with a link to the agent setup docs.
A “runtime disabled” empty state is visually distinct: it shows a callout that runtime instrumentation is disabled in this deployment and links to the enable guide.
The two empty states may share a wire response (both 404), so the UI must consult a separate “feature toggle” hint (a small capability endpoint or a session-stored config flag — see Open questions §7).

US-RT-3 — Analyst inspects which functions were hit

As an analyst, I want to see which vulnerable functions were actually invoked, so that I can confirm the finding is not dead-code reachable but operationally invoked.

Acceptance criteria:

The aggregate table lists vulnerable function names, hit counts, first/last seen timestamps, and a “direct path” indicator.
The table is sortable by hits and recent.
Pagination/limit follows the API surface (?limit=, max 200).

US-RT-4 — Analyst inspects activity over time

As an analyst, I want to see the timeline of runtime events for the finding, so that I can correlate spikes with deploys or incidents.

Acceptance criteria:

A line/area chart renders events bucketed by hour over the last 24h (default), with controls to extend to 7d.
Hovering a bucket shows the event count and the dominant kind.

3. Wireframes

3.1 Finding Detail Page — top-level layout

+--------------------------------------------------------------------------+
| [Header: CVE-2026-NNNN — pkg:npm/lodash@4.17.21]                          |
|--------------------------------------------------------------------------|
| [ Overview ] [ Evidence ] [ Policy ] [ ⟶ Runtime ⟵ ] [ Workflow ] [ ... ] |
|--------------------------------------------------------------------------|
|                                                                          |
|   ┌─────────────────────────────┬──────────────────────────────────┐    |
|   │  Runtime Score Gauge        │  Score Breakdown                 │    |
|   │     ┌───────┐               │   - Observation : 0.92           │    |
|   │     │  78   │  /100         │   - Recency     : 0.85           │    |
|   │     └───────┘               │   - Quality     : 0.40           │    |
|   │  Computed 2 min ago         │   [info icon → ADR link]         │    |
|   └─────────────────────────────┴──────────────────────────────────┘    |
|                                                                          |
|   Aggregate table                                                        |
|   ┌─────────────────────────────────────────────────────────────────┐  |
|   │ FUNCTION         HITS  DIRECT  FIRST SEEN          LAST SEEN     │  |
|   │ lodash.merge     1500   yes    2026-04-25 08:00    2 min ago     │  |
|   │ ...                                                              │  |
|   └─────────────────────────────────────────────────────────────────┘  |
|                                                                          |
|   Timeline (24h, hourly buckets)                                         |
|   ┌─────────────────────────────────────────────────────────────────┐  |
|   │     ▁▁▂▃▅▇▆▄▃▂▁                                                  │  |
|   │     └───────────────  04-27  ─────────────────  04-28 (now) ──┘  │  |
|   └─────────────────────────────────────────────────────────────────┘  |
|                                                                          |
+--------------------------------------------------------------------------+

3.2 Empty states

+----------------------------------+    +----------------------------------+
|  Runtime instrumentation: ON     |    |  Runtime instrumentation: OFF    |
|----------------------------------|    |----------------------------------|
|                                  |    |                                  |
|   No runtime traces yet for      |    |   Runtime instrumentation is     |
|   this finding.                  |    |   disabled in this deployment.   |
|                                  |    |                                  |
|   [Set up an agent →]            |    |   [How to enable →]              |
|                                  |    |                                  |
+----------------------------------+    +----------------------------------+
        (returned 404)                       (returned 404 + capability)

3.3 Mermaid component graph

flowchart TB
    A[Finding Detail Page] --> B[RuntimeTab]
    B --> C[ScoreGauge]
    B --> D[ScoreBreakdownPanel]
    B --> E[AggregateTable]
    B --> F[TimelineChart]
    B --> G[EmptyState]
    G --> G1[NoDataYet]
    G --> G2[RuntimeDisabled]

4. Component list

Component	Purpose
`RuntimeTab`	Container; renders one of `ScoreSection`, `EmptyState`, or error.
`ScoreGauge`	0…100 numeric gauge with computed-at relative timestamp.
`ScoreBreakdownPanel`	Lists `observationScore`, `recencyFactor`, `qualityFactor` with help icons.
`AggregateTable`	Sortable table; columns per US-RT-3.
`TimelineChart`	Bucketed line/area chart per US-RT-4.
`EmptyState.NoDataYet`	“Runtime instrumentation is on but no traces yet” + link to agent docs.
`EmptyState.RuntimeDisabled`	“Runtime instrumentation is disabled” + link to enable guide.

5. API endpoints used

Endpoint	Used by
`GET /api/v1/findings/{id}/runtime/score`	`ScoreGauge`, `ScoreBreakdownPanel`
`GET /api/v1/findings/{id}/runtime/traces`	`AggregateTable`
`GET /api/v1/findings/{id}/runtime-timeline`	`TimelineChart`

Cross-link: runtime-instrumentation-api.md.

6. Empty-state behavior matrix

Score endpoint	Traces endpoint	Timeline endpoint	Render
200	200	200	Full panel
200	200	404	Full panel; timeline shows empty
404	404	404 (capability says enabled)	`EmptyState.NoDataYet`
404	404	404 (capability says disabled)	`EmptyState.RuntimeDisabled`
any 5xx	-	-	Generic error toast + retry button

The toggle state (“enabled / disabled”) is not carried in the read endpoints by design (see ADR-013 Findings Runtime Disabled Mode). The UI needs a separate signal — see Open questions §7.

7. Open questions for the Web UI lead

Capability surface. What’s the right way for the UI to learn whether runtime instrumentation is enabled in this deployment? Options: (a) a new /api/v1/findings/runtime/capabilities endpoint; (b) reuse /platform/envsettings.json; © infer from a 404 with a distinguishing header. Recommend (a) or (b).
Score-as-percentage vs score-as-fraction. The wire returns score.score as a 0…1 fraction; the gauge renders 0…100. Should the UI scale or should we add a server-side scaledScore field?
Timeline default window. 24h is the API default; do analysts want 7d on the page initially? Tuned via UI param, not server.
Pagination of aggregates. API supports limit=200. Should the UI offer pagination beyond that, or is “top 200 hits” always sufficient for triage?
Cross-tab badge. Should the “Runtime” tab show a badge with the current score (e.g. Runtime (78)) when data is present?

8. Out of scope for this requirements doc

Implementation language / framework choice (Angular component structure, RxJS streams, etc.) — defer to the Web UI team.
Visual design / theming.
Per-tenant feature flags beyond the existing global toggle.

9. Cross-references

API: runtime-instrumentation-api.md
Architecture: architecture.md
ADRs:
- ADR-013 Findings Runtime Disabled Mode
- ADR-016 Findings Runtime Score Formula
Follow-up implementation sprint: SPRINT_FUTURE_FE_findings_runtime_panel

Sign-off

Author (Documentation): 2026-04-28
Web UI lead: PENDING — review window 5 working days; if no response, escalate per sprint Decisions & Risks (§5).