# Platform Evidence/Status Frontend Contract v1

Status: draft frontend contract (PF-EVIDENCE-FRONTEND-CONTRACT-001)
Owner: Platform Frontend
Last updated: 2026-06-01

## Purpose

Define the V3 frontend contract for platform evidence and status surfaces.

This contract turns the platform evidence/status slice into reviewable pages for
release, UAT, security, architecture, ops, product, and release-owner workflows.
It does not make the frontend the source of truth for evidence. The frontend
renders and filters backend-owned read models, links reviewers to raw artifacts,
and makes missing, stale, partial, or failing evidence visible before release or
production-impacting decisions.

## Source Context

This contract aligns with:

- `Platform_Evidence_Status_Slice_v1.md`;
- `Platform_Evidence_Status_Schema_v1.md`;
- `Platform_Code_And_Deployment_Architecture_v1.md`;
- `Frontend_Surface_Architecture_Work_Plan_v1.md`;
- the current V3 platform evidence/audit surfaces in
  `packages/web/src/components/v3/v3-platform-pages.tsx` and
  `packages/web/src/components/v3/v3-audit-evidence-page.tsx`.

## Frontend Page Family

The evidence/status surfaces belong to the V3 Platform page family. They should
use the existing platform shell and `V3PlatformNav` family navigation until the
frontend architecture restructure creates a more explicit platform module.

Route assumptions:

| Route | Page contract |
|---|---|
| `/platform/evidence` | Evidence landing with release bundle summary, status pivots, audit/tool links, and current attention queue |
| `/platform/evidence/bundles` | Evidence bundle list workbench |
| `/platform/evidence/bundles/{bundle_id}` | Evidence bundle detail and review posture |
| `/platform/evidence/audit` | Existing audit evidence workbench, retained as an investigation subpage |
| `/platform/status` | Platform readiness/status landing when status is split from evidence |
| `/platform/status/components` | Component readiness and health workbench |
| `/platform/status/guards` | Platform-foundation guard report summary workbench |
| `/platform/evidence/devsecops` | DevSecOps control metrics dashboard for scan enforcement, vulnerability SLA, waiver hygiene, supply-chain coverage, risk burn-down, and agent governance |

The first implementation may place status sections on `/platform/evidence` if a
separate `/platform/status` route is not yet wired. The page contract should
still keep evidence bundle, readiness, guard, and component-status panels as
separate page modules so the route can split later without redesigning the data
model.

## Target Personas

| Persona | Primary intent |
|---|---|
| Architecture | Verify that product and platform boundaries, invariants, and guard findings match the approved architecture sequence |
| Ops | See current readiness, component health, stale evidence, incidents, maintenance, and operational pivots |
| Security | Review scan, authz, secrets, audit, residual-risk, and approval evidence |
| Product | Confirm UAT coverage of user-visible launch, connect, release, and failure invariants |
| Release owner | Decide whether a bundle is promotable, blocked, partially approved, or carrying accepted residual risk |
| App developer | Understand whether SDK examples, manifest validation, app launch/connect flows, artifact promotion, and developer-facing failure cases have passing evidence |

## Ownership Boundary

The frontend displays evidence/status; it does not own evidence truth.

Allowed frontend responsibilities:

- fetch typed V3 read models;
- preserve query/filter state in URL parameters where useful;
- render state, freshness, result, owner, artifact, and approval fields;
- link to raw CI, UAT, security, guard, log, trace, deploy, and incident
  artifacts;
- display stale, missing, partial, and failing conditions prominently;
- provide review ergonomics such as filters, pagination, detail drawers, copy
  buttons, and external-tool launch affordances.

Not allowed:

- infer a passing release posture from client-side rules alone;
- rewrite evidence result, gate state, approval, or freshness semantics in the
  browser;
- hide missing evidence by treating null fields as success;
- introduce frontend-only evidence categories that are not backed by the
  platform evidence/status contract;
- treat audit rows as a substitute for release evidence bundles.

## Page Contracts

### Evidence Bundle List

Purpose: let reviewers find release, UAT, security, or production-impacting
evidence bundles as activity grows.

Required content:

- summary KPIs for total bundles, blocked/failing bundles, stale bundles, and
  recently updated bundles;
- table of bundles with `bundle_id`, `source_commit`, `release_branch`,
  `environment_profile`, `product_scope`, `change_summary`, `gate_state`,
  `residual_risk`, `created_at`, and `updated_at`;
- result chips for `pass`, `fail`, `partial`, `blocked`, `missing`, and
  `not_applicable`;
- links to detail view and raw source/artifact pivots when available;
- cursor pagination using backend pagination metadata.

Required filters:

- environment profile;
- product scope;
- gate state;
- source commit or release branch search;
- updated time range;
- owner or approval role once provided by the read model.

### Evidence Bundle Detail

Purpose: show whether one bundle is complete enough for review, approval, or
promotion.

Required sections:

- bundle header with source commit, branch/lane, product scope, environment,
  gate state, created/updated timestamps, and correlation IDs;
- change summary and rollback plan;
- artifact digests with artifact type, digest, and source URI;
- migration status and capacity posture;
- release gate results grouped by gate and owner;
- evidence items grouped by type, producer, result, owner, and freshness;
- UAT invariant coverage;
- approvals and residual risk;
- raw artifact links and observability pivots.

Detail UI should prefer dense sections, tables, and drawers over oversized
cards. A failing or blocked gate should be visible above the fold on desktop
and near the start of the page on mobile.

### UAT Invariant Coverage

Purpose: prove product behavior by named invariant, not by page-load success.

Required invariant fields:

- `invariant_id`;
- `product_area`;
- `result`;
- linked `evidence_item_ids`;
- `missing_reason`.

The UI should group invariants by product area and distinguish:

- covered/pass;
- covered/fail;
- partial or blocked;
- missing with explicit reason;
- not applicable for the selected product scope.

Initial invariant IDs come from `Platform_Evidence_Status_Slice_v1.md`,
including GPUaaS launch/connect/release/capacity, App Platform contract/launch
failure, and platform audit/outbox invariants.

### App Developer Evidence

Purpose: make SDK and app-platform readiness visible without requiring app
developers to read internal CI logs, seed SQL, or backend runtime code.

Required content:

- SDK smoke status by example app and environment;
- manifest validation result by app/version;
- launch, connect, decommission, publish, promotion, and failure-contract
  coverage where available;
- artifact digest and trust/promote status links for app artifacts;
- developer portal links for the relevant app SDK, manifest, quickstart, and
  API reference pages;
- explicit current-state/target-state notes when the app still depends on a
  platform-admin or seed-backed bridge.

This view should be filtered from the same evidence/readiness data, not a
separate developer-owned evidence store.

### Guard Report Summary

Purpose: make platform-foundation boundary guard posture reviewable without
requiring every reviewer to open raw CI artifacts first.

Required content:

- latest guard reports by `guard_id`, mode, source commit, generated time, and
  artifact path;
- mode chip for `report_only`, `warning`, or `blocking`;
- findings table with severity, owner, file, line, rule, and reason;
- allowed debt list;
- graduation criteria;
- link to raw guard artifact.

The guard page should clearly separate report-only allowed debt from blocking
findings. It must not imply that report-only findings are harmless; it should
show them as accepted or pending architectural debt.

### DevSecOps Control Metrics

Purpose: make security/CD control adoption and risk burn-down visible from the
same evidence/status model used for release readiness.

Required content:

- control adoption and enforcement summary by environment, product scope, and
  release branch;
- SAST, secrets, dependency, image, DAST, hardening, contract, and authz gate
  posture by mode and result;
- vulnerability SLA posture: open, overdue, nearing breach, remediated,
  resurfaced, false-positive, invalid, and mean/percentile age;
- waiver posture: active, expiring, expired, deferred, invalid, owner, expiry,
  and release impact;
- supply-chain coverage for SBOM, signature, provenance, digest, artifact
  trust, and runtime image freshness;
- risk arrival, burn-down, survival age, and escape-rate trends;
- Fairway governance metrics for review-domain completion, deploy-run closure,
  stale active sessions, and no-self-approval compliance.

This page must use backend-owned aggregates from
`DevSecOps_Control_Metrics_Dashboard_v1.md`. It must not infer pass/fail from
client-side absence of findings. Missing or stale metric sources render as
`missing` or `stale`, not success.

### Component Readiness/Status

Purpose: answer whether platform and product components are healthy enough for
the selected environment/profile.

Required content:

- component table with `component_id`, `component_type`,
  `environment_profile`, `status`, `freshness_seconds`, `checked_at`, and
  `evidence_href`;
- readiness summary by environment profile and product scope;
- gate state, incidents, maintenance if available, capacity posture, and read
  model freshness;
- stale or unknown components highlighted separately from healthy components.

Component status should cover API, web, billing worker, provisioning worker,
App Platform runtime worker, terminal gateway, node agent, outbox relay, and
future platform-owned services as they appear in the status read model.

### Residual Risk And Approvals

Purpose: let release and security owners understand what has been accepted and
who accepted it.

Required content:

- residual-risk statement, never collapsed into a generic success state;
- approvals table with owner, role, result, approved time, and comment;
- missing approval roles called out as `missing` or `blocked`;
- explicit linkage between approvals, failed/partial gates, and accepted debt
  where provided by the read model.

Approval controls, if added later, are privileged mutations and must follow the
platform API contract, idempotency, audit, and evidence rules. This frontend
contract only requires display until a writer API is explicitly approved.

## API And Read-Model Dependencies

Primary dependencies:

| Endpoint | Purpose |
|---|---|
| `GET /api/v1/v3/platform/evidence/bundles` | bundle list with filters and pagination |
| `GET /api/v1/v3/platform/evidence/bundles/{bundle_id}` | bundle detail |
| `GET /api/v1/v3/platform/status/readiness` | readiness summary for environment/profile/product scope |
| `GET /api/v1/v3/platform/status/components` | component status list |
| `GET /api/v1/v3/platform/status/guards` | guard report summaries |
| `GET /api/v1/v3/platform/evidence/audit` | existing audit evidence investigation table |
| `GET /api/v1/v3/platform/evidence` | existing platform evidence landing/read model until split views are wired |

Candidate fields already present in the evidence/status schema:

| Schema | Candidate frontend fields |
|---|---|
| `V3PlatformEvidenceBundleSummary` | `bundle_id`, `source_commit`, `release_branch`, `environment_profile`, `product_scope`, `change_summary`, `gate_state`, `residual_risk`, `created_at`, `updated_at` |
| `V3PlatformEvidenceBundle` | summary fields plus `artifact_digests`, `migration_status`, `capacity_posture`, `rollback_plan`, `correlation_ids`, `approvals`, `invariants`, `items` |
| `V3PlatformEvidenceItem` | `evidence_item_id`, `evidence_type`, `producer`, `source_uri`, `artifact_path`, `result`, `started_at`, `completed_at`, `correlation_id`, `owner`, `retention_class`, `proves_invariants` |
| `V3PlatformProductInvariantCoverage` | `invariant_id`, `product_area`, `result`, `evidence_item_ids`, `missing_reason` |
| `V3PlatformEvidenceApproval` | `owner`, `role`, `result`, `approved_at`, `comment` |
| `V3PlatformStatusReadinessResponse` | `environment_profile`, `product_scope`, `gate_state`, `gates`, `evidence_freshness`, `incidents`, `capacity_posture`, `meta` |
| `V3PlatformReleaseGateStatus` | `gate_id`, `label`, `result`, `owner`, `evidence_item_ids`, `missing_reason` |
| `V3PlatformEvidenceFreshness` | `evidence_type`, `latest_completed_at`, `max_age_seconds`, `state` |
| `V3PlatformComponentStatus` | `component_id`, `component_type`, `environment_profile`, `status`, `freshness_seconds`, `evidence_href`, `checked_at` |
| `V3PlatformGuardReportSummary` | `guard_id`, `mode`, `source_commit`, `generated_at`, `artifact_path`, `findings`, `allowed_debt`, `graduation_criteria` |

The frontend should use generated OpenAPI types and domain API helpers. It
should not duplicate schema enums in component-local strings except for display
labels and tone mapping.

## Page States

All pages must handle these states explicitly:

| State | Expected behavior |
|---|---|
| Loading | Use existing V3 loading state with page-specific label; preserve layout stability where possible |
| Empty | Explain that no bundles/status records match the selected scope or filters; provide clear-filter action when filters are active |
| Stale evidence | Show stale freshness chips, latest completion time, max age, and affected evidence type/gate |
| Partial/failing gates | Keep `partial`, `fail`, `blocked`, and `missing` visible in summary and affected rows; do not bury them only in detail drawers |
| Missing permissions | Use V3 restricted/permission-denied state; do not leak raw evidence details |
| API error | Use standard V3 error state and include retry; surface correlation/evidence links through existing error mapping when available |
| Read-model stale cache | Display read-model cache/freshness metadata when provided by `meta` or response headers |

## Tables, Filters, And Pagination

Evidence and status activity will grow. The first implementation must not assume
small in-memory lists.

Expectations:

- backend cursor pagination for bundle lists, audit logs, guard findings when
  they grow, and component lists if component count becomes large;
- page size controls of 25, 50, and 100 where the table is operator-facing;
- URL-addressable filters for investigation handoff, especially environment,
  product scope, gate/result, owner, commit/branch, correlation ID, and time
  range;
- sortable columns where the backend supports sorting, with newest/most severe
  defaults;
- filter chips that make active filters visible and removable;
- detail drawers for row inspection, with full-page detail routes for durable
  release evidence;
- no client-only pagination for canonical evidence bundle lists once backend
  pagination exists.

## Accessibility And Dense Dashboard Expectations

The pages are operational dashboards, not marketing surfaces.

Required expectations:

- semantic tables for tabular evidence, gates, findings, approvals, and
  component status;
- keyboard-reachable filters, pagination, row actions, drawers, and close
  buttons;
- `aria-modal`, labelled drawers/dialogs, and Escape close behavior for drawers;
- result/status conveyed by text plus color, never color alone;
- compact typography appropriate for dense review work, with no viewport-scaled
  fonts;
- stable table and toolbar dimensions to avoid layout shift during loading,
  pagination, or filter changes;
- copy buttons for correlation IDs, bundle IDs, digests, and artifact paths;
- external links labelled by destination or artifact type;
- mobile layout that preserves the failing/blocked summary and primary filters
  before long tables.

## Telemetry And Evidence Pivots

Frontend interactions should preserve investigation handoff:

- correlation IDs should remain copyable and URL-addressable;
- links to logs, traces, CI, UAT, security scans, guard artifacts, deployment
  smoke, and incident records should use backend-provided URIs when available;
- privileged future actions must generate or propagate `X-Request-Id` and
  idempotency keys through existing mutation helpers;
- no auth token or evidence token may be placed in query parameters.

## Review Notes And Open Questions

1. Should `/platform/status` be introduced as a sibling route immediately, or
   should the first slice land status panels under `/platform/evidence` and
   split after the read models stabilize?
2. Which platform roles can view release evidence bundles, guard reports, and
   component readiness: platform ops only, platform admins, architecture,
   security, product reviewers, or a narrower permission set?
3. Are approval mutations in scope for the first frontend slice, or should
   approvals remain read-only until the backend writer and audit contract are
   separately approved?
4. What freshness thresholds should be displayed per evidence type, and are
   they backend policy/read-model fields or static documentation values?
5. Should guard findings support owner reassignment and false-positive review in
   this surface, or should they link to a separate platform-foundation guard
   workflow?
6. Which raw artifact links are internal-only, and which need a mediated
   backend redirect/proxy before they can be exposed in the browser?
7. Does the release owner need export support for a bundle detail, or is the
   evidence API response sufficient as the machine-readable handoff?

## Acceptance Criteria

This contract is ready for implementation when:

- route ownership and page-family placement are reviewed;
- generated schema types are available to the web app;
- list/detail/readiness/guard/component endpoints have agreed permissions;
- stale, missing, partial, failing, and no-permission states are covered in page
  tests;
- table/filter/pagination behavior is included in the frontend task scope;
- the UI is reviewed as a display/read-model surface, not an evidence authority.