TenantAtlas/specs/074-verification-checklist/data-model.md

Data Model: Verification Checklist Framework (074)

Overview

This feature introduces a versioned verification report document attached to an existing OperationRun. No new database tables are required for v1.

Existing Entities Used

OperationRun (operation_runs)

Selected fields:

• id
• tenant_id
• user_id
• type (used as the verification flow identifier)
• status (queued | running | completed)
• outcome (pending | succeeded | failed)
• summary_counts (JSONB)
• failure_summary (JSONB)
• context (JSONB)
• started_at, completed_at

Idempotency:

• DB-enforced dedupe for active runs via partial unique index on (tenant_id, run_identity_hash) where status IN ('queued','running').

New Logical Data (stored inside OperationRun context)

VerificationReport (operation_runs.context.verification_report)

• Stored as JSON in context under verification_report.
• Versioned by schema_version.
• Rendered DB-only (no external calls during view).

High-level shape (see contracts/verification-report.schema.json for the canonical contract):

• schema_version
• flow (identifier; for v1 this can align with operation_runs.type)
• identity (scope identifiers such as tenant_id, provider_connection_id, etc.)
• generated_at
• summary (counts, overall state)
• checks[] (check results)

CheckResult (within checks[])

• key, title
• status: pass|fail|warn|skip|running
• severity: info|low|medium|high|critical
• blocking: boolean
• reason_code
• message
• evidence[]: safe pointers only
• next_steps[]: links only in v1

Audit

Verification start and completion are recorded in audit_logs using stable action identifiers (via App\Support\Audit\AuditActionId). Metadata is minimal and sanitized.

Notes / Constraints

• Viewer must be DB-only: rendering the report must not dispatch jobs or perform HTTP.
• Evidence must be redacted/safe: no secrets/tokens/payload dumps in stored or rendered report.