TenantAtlas/specs/084-verification-surfaces-unification/data-model.md

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.