83 lines
2.8 KiB
Markdown
83 lines
2.8 KiB
Markdown
# 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.
|