TenantAtlas/specs/241-support-diagnostic-pack/data-model.md

Data Model — Support Diagnostic Pack

Spec: spec.md

No new persistent tables are required for the first support-diagnostics slice. The bundle is computed at request time from existing canonical records.

Existing Canonical Entities Reused

Workspace (workspaces)

Purpose: Primary admin-plane isolation boundary and audit scope for every support-diagnostic bundle.

Key fields (existing):

• id
• name

Bundle use:

• Supplies the workspace scope label.
• Anchors workspace-membership checks.
• Owns audit-log scope for bundle-open activity.

Tenant (tenants)

Purpose: Tenant-plane scope boundary and the canonical subject for tenant-context support diagnostics.

Key fields (existing):

• id
• workspace_id
• external_id
• name
• status

Bundle use:

• Acts as the primary subject for tenant-context bundles.
• Supplies tenant identity and tenant authorization scope.

OperationRun (operation_runs)

Purpose: Canonical execution truth and the primary subject for operation-context support diagnostics.

Key fields (existing):

• id
• workspace_id
• tenant_id (nullable)
• type
• status
• outcome
• summary_counts
• context
• started_at
• completed_at

Relationships (existing):

• tenant()
• workspace()
• user()

Bundle use:

• Supplies the primary execution summary.
• Carries run-bound reference ids such as provider_connection_id and artifact references in context.
• Reuses existing humanized run explanation and canonical run URLs.

ProviderConnection (provider_connections)

Purpose: Canonical provider readiness and connection state for the tenant or run context.

Key fields (existing):

• id
• workspace_id
• tenant_id
• provider
• connection_type
• consent_status
• verification_status
• last_error_reason_code
• last_error_message
• is_default
• is_enabled
• last_health_check_at

Relationships (existing):

• tenant()
• workspace()
• credential()

Bundle use:

• Supplies provider readiness summary, translated provider failure reasons, and target-scope detail.
• Never contributes raw credential payloads or secrets to the bundle.

Finding (findings)

Purpose: Canonical drift or permission posture issues that may explain current support pressure.

Key fields (existing):

• id
• workspace_id
• tenant_id
• type
• severity
• status
• baseline_operation_run_id
• current_operation_run_id
• due_at
• last_seen_at

Relationships (existing):

• tenant()
• baselineRun()
• currentRun()
• findingException()

Bundle use:

• Supplies prioritized open or recent findings relevant to the current tenant or run.
• Contributes summary and freshness cues only; finding detail remains on canonical pages.

StoredReport (stored_reports)

Purpose: Canonical report/evidence truth for report identity and freshness.

Key fields (existing):

• id
• workspace_id
• tenant_id
• report_type
• fingerprint
• previous_fingerprint
• payload

Relationships (existing):

• workspace()
• tenant()

Bundle use:

• Supplies report identity, report type, and freshness/continuity cues.
• The bundle must not expose the full stored report payload by default.

TenantReview (tenant_reviews)

Purpose: Canonical tenant review state and review-level summary for governance follow-up.

Key fields (existing):

• id
• workspace_id
• tenant_id
• operation_run_id
• status
• completeness_state
• summary
• generated_at
• current_export_review_pack_id

Relationships (existing):

• workspace()
• tenant()
• operationRun()
• reviewPacks()

Bundle use:

• Supplies current review status, completeness, blockers, and canonical review references when review truth is relevant.

ReviewPack (review_packs)

Purpose: Canonical review export/package truth when a tenant review already has a pack.

Key fields (existing):

• id
• workspace_id
• tenant_id
• operation_run_id
• tenant_review_id
• status
• summary
• generated_at
• expires_at
• file_size

Relationships (existing):

• workspace()
• tenant()
• operationRun()
• tenantReview()

Bundle use:

• Supplies pack availability, readiness, and expiry cues.
• The bundle links to the canonical pack viewer instead of reproducing pack content.

AuditLog (audit_logs)

Purpose: Canonical audit trail for workspace-, tenant-, and operation-related events.

Key fields (existing):

• id
• workspace_id
• tenant_id
• action
• resource_type
• resource_id
• target_label
• metadata
• outcome
• operation_run_id
• recorded_at

Relationships (existing):

• tenant()
• workspace()
• operationRun()

Bundle use:

• Supplies the most relevant authorized audit references for the current tenant or run.
• Also records bundle-open activity with redacted metadata only.

Derived Runtime Entities

SupportDiagnosticBundle (computed, not persisted)

Purpose: One machine-readable, redacted support-safe envelope for either a tenant context or an operation-run context.

Proposed shape (runtime array / view-model):

• context_type — tenant or operation_run
• workspace — workspace reference and label
• tenant — tenant reference when applicable
• operation_run — primary run reference when applicable
• headline — dominant support summary
• dominant_issue — translated blocker or issue statement
• freshness_state — derived cue such as fresh, stale, mixed, or missing_context
• redaction_mode — fixed first-slice mode: default-redacted
• sections — ordered list of section payloads
• notes — explicit redaction, completeness, or degradation notes

Relationships:

• 1 workspace
• 0..1 tenant
• 0..1 primary operation run
• 0..1 provider connection section
• 0..n finding references
• 0..n stored report references
• 0..1 tenant review reference
• 0..1 review pack reference
• 0..n audit references

SupportDiagnosticSection (computed, not persisted)

Purpose: One deterministic section inside the bundle.

Proposed shape:

• key — fixed section key such as provider_connection, operation_context, findings, stored_reports, tenant_review, review_pack, audit_history
• label
• availability — derived local status (available, missing, stale, inaccessible, redacted)
• summary
• freshness_at or freshness_note
• references — ordered support references for that section
• redaction_markers — explicit markers when detail is intentionally excluded

Note: these are presentation-contract values only, not new persisted domain state.

SupportDiagnosticReference (computed, not persisted)

Purpose: Stable canonical link/reference metadata for one related record.

Proposed shape:

• type — tenant, operation_run, provider_connection, finding, stored_report, tenant_review, review_pack, or audit_log
• record_id
• label
• action_label
• url (nullable when inaccessible or no viewer exists)
• availability
• freshness_note (nullable)
• access_reason or missing_reason (nullable)

RedactionMarker (computed, not persisted)

Purpose: Make exclusion deterministic and explicit.

Proposed shape:

• path (nullable)
• reason — secret, credential, raw_payload, restricted_log_excerpt, or inaccessible_record
• replacement_text

Derived Rules and Validation

• Bundle generation requires established workspace membership first.
• Tenant-context bundle generation requires tenant entitlement before any tenant-owned section resolves.
• Operation-context bundle generation must first pass OperationRunPolicy::view(...); if the run points at a tenant, tenant entitlement still applies before tenant-owned related records resolve.
• After membership/entitlement is established, missing support_diagnostics.view is a 403 capability denial.
• The bundle must never include secrets, tokens, credentials, unrestricted provider response bodies, or unrestricted stored-report payloads.
• Missing or inaccessible related records must degrade into explicit placeholders or unavailable references, not hard-fail the whole bundle.
• For unchanged authorized input, section order, reference order, and redaction output must remain stable.

Lifecycle and Audit Behavior

• SupportDiagnosticBundle has no persisted lifecycle.
• Opening the bundle writes one audit event with redacted metadata only.
• Opening linked canonical records follows their own existing authorization and audit behavior.