# Platform Evidence/Status Schema v1

Status: draft schema contract (PF-EVIDENCE-SCHEMA-001)
Owner: Platform Backend
Last updated: 2026-06-01

## Purpose

Define the additive platform-owned persistence model for the evidence/status
first slice.

The schema supports the OpenAPI read-model contract in `doc/api/openapi/domains/v3-read-models.yaml`
and the first-slice architecture in `Platform_Evidence_Status_Slice_v1.md`.
It does not rename existing audit, outbox, release, or product tables.

## Tables

| Table | Purpose |
|---|---|
| `platform_evidence_bundles` | One bundle per release candidate, UAT package, security review, or production-impacting change |
| `platform_evidence_items` | Individual CI, UAT, security, guard, smoke, artifact, or operator evidence entries attached to a bundle |
| `platform_release_gate_results` | Gate state for contract drift, UAT, security, capacity, approval, guard, and environment-profile checks |
| `platform_product_invariant_results` | Named product invariant coverage such as launch/connect/release/app failure behavior |
| `platform_status_component_status` | Latest component health/readiness snapshots for Status/Ops read models |
| `platform_guard_report_summaries` | Ingested summaries of report-only/warning/blocking platform-foundation guard reports |

## Design rules

1. All table names are platform-owned and owner-visible.
2. Evidence writes are append-oriented. Existing rows may be superseded by a new
   bundle/item/result, but audit evidence should not be rewritten to erase prior
   release posture.
3. JSONB columns hold external producer payloads and source-specific details,
   not unmodeled ownership boundaries.
4. Product invariants are recorded by stable IDs so UAT evidence proves product
   behavior, not only page-load success.
5. Guard report summaries store the latest classified posture while raw guard
   artifacts remain linked by `artifact_path`.
6. Status read models can be generated from the tables or imported from CI/UAT
   artifacts before a dedicated worker exists.

## API mapping

| API schema | Tables |
|---|---|
| `V3PlatformEvidenceBundleSummary` | `platform_evidence_bundles` |
| `V3PlatformEvidenceBundle` | bundle + items + gate results + invariant results |
| `V3PlatformEvidenceItem` | `platform_evidence_items` |
| `V3PlatformStatusReadinessResponse` | gate results + invariant results + component status + guard summaries |
| `V3PlatformComponentStatus` | `platform_status_component_status` |
| `V3PlatformGuardReportSummary` | `platform_guard_report_summaries` |

## Initial indexes

- bundle lookup by environment/profile/product/update time;
- item lookup by bundle/type/result/completion time;
- gate lookup by bundle/result;
- invariant lookup by bundle/invariant/result;
- component status lookup by environment/component/status;
- guard report lookup by guard/generated time.

## Migration posture

The first migration is additive. It can land before any route implementation
because no existing table or enum is renamed. Early importers may populate
bundles from GitLab/UAT/security artifacts, then API routes can expose the same
shape through platform evidence/status facades.