# Data Model — Verification Surfaces Unification (Spec 084)

This feature reuses existing persisted entities. The main change is a stronger invariant about `OperationRun.context.verification_report` for blocked verification completions.

## Entities

### OperationRun

Source of truth for observability and verification report storage.

- Table: `operation_runs`
- Key fields (existing):
  - `id` (int)
  - `workspace_id` (int)
  - `tenant_id` (int, nullable for some platform runs; verification is tenant-associated)
  - `type` (string) — verification uses `provider.connection.check`
  - `status` (string) — includes active vs completed
  - `outcome` (string) — includes `succeeded`, `failed`, `blocked`
  - `context` (json/jsonb) — stores `verification_report` and run metadata
  - `failure_summary` (array/json)
  - timestamps: `created_at`, `started_at`, `completed_at`

#### Verification context (provider connection check)

For `OperationRun.type = provider.connection.check`, the context is expected to include:

- `provider` (string)
- `module` (string)
- `provider_connection_id` (int)
- `target_scope` (object):
  - `entra_tenant_id` (string)
  - optionally `entra_tenant_name` (string)
- `verification_report` (object) — see “VerificationReport” below

Additionally, for blocked starts (preflight):

- `reason_code` (string)
- `next_steps` (array of `{label, url}`)
- `verification_report` MUST exist once the run is completed as `blocked`.

### VerificationReport (stored document)

A stored document under `operation_runs.context.verification_report`.

- Schema: `specs/075-verification-v1-5/contracts/verification-report.v1_5.schema.json`
- Key properties:
  - `schema_version`
  - `flow` (aligns with `OperationRun.type`)
  - `generated_at`
  - `fingerprint`
  - `previous_report_id`
  - `summary.overall`, `summary.counts`
  - `checks[]`

#### Invariant introduced by this feature

- If a verification run completes with outcome `blocked`, `verification_report` MUST be present and schema-valid.
- For in-progress runs, `verification_report` may be absent until the job writes it.

### TenantOnboardingSession (existing)

Onboarding stores pointers to the current verification run.

- `state.verification_operation_run_id` (int)
- `state.provider_connection_id` (int)

## Relationships

- `OperationRun` belongs to `Tenant` (tenant-scoped verification)
- `VerificationCheckAcknowledgement` belongs to `OperationRun` (acknowledgements enrich viewer; unchanged)

## State transitions

For `provider.connection.check`:

- `queued/running` → `completed`
- Outcomes:
  - `succeeded` when provider connection is healthy and permission inventory refresh succeeds
  - `failed` when provider check fails (with `failure_summary`)
  - `blocked` when prerequisites prevent starting (preflight), still with a stub report

No database schema migrations are expected for this feature.
