TenantAtlas/specs/259-compliance-evidence-mapping/data-model.md

Data Model — Compliance Evidence Mapping v1

Spec: spec.md

No new persisted table, report artifact family, or projection store is required for this feature. The implementation reuses current review, section, evidence, finding, accepted-risk, membership, and audit truth, then embeds one bounded interpretation contract inside the existing review payloads.

Source Truth Reused

Workspace / Tenant Entitlement Context

Purpose: Establish the active workspace boundary and entitled tenant set before any workspace row, released-review detail, or supporting evidence route is resolved.

Persisted carriers:

• existing workspace membership rows
• existing tenant membership pivot rows and role assignments
• existing capability registry and role-capability map

Relevant fields / contracts:

• workspace_id
• tenant_id
• workspace membership existence
• tenant membership role
• capability grants derived from ../../apps/platform/app/Support/Auth/Capabilities.php
• remembered tenant context from the existing workspace session model

Validation rules:

• the actor must be a member of the current workspace or the request resolves as not found
• workspace rows and explicit tenant filters may only resolve for entitled tenants in that workspace
• out-of-scope tenant targets remain 404 and must not leak review or evidence presence

CanonicalControlDefinition

Purpose: Existing provider-neutral control identity used as the anchor for every mapped customer-safe control summary.

Carrier: existing ../../apps/platform/config/canonical_controls.php loaded through ../../apps/platform/app/Support/Governance/Controls/CanonicalControlCatalog.php

Relevant fields:

• control_key
• name
• domain_key
• subdomain_key
• summary
• control_class
• evaluation_strategy
• evidence_archetypes
• historical_status

Validation / usage rules:

• canonical controls remain provider-neutral and customer-facing labels must continue to use the catalog's neutral names
• provider-specific Microsoft bindings stay internal resolution inputs only
• the interpretation overlay may add customer-safe readiness meaning, but it must not create a second control taxonomy

Findings Summary Evidence Input

Purpose: Existing per-finding evidence basis that already resolves canonical control references and accepted-risk governance state.

Persisted carriers:

• existing evidence_snapshots
• existing evidence_snapshot_items
• existing findings

Primary producer: ../../apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php

Relevant fields / payload:

• EvidenceSnapshot.id
• EvidenceSnapshot.generated_at
• EvidenceSnapshot.expires_at
• EvidenceSnapshotItem.dimension_key = findings_summary
• summary_payload.entries[].id
• summary_payload.entries[].status
• summary_payload.entries[].severity
• summary_payload.entries[].terminal_outcome
• summary_payload.entries[].canonical_control_resolution
• summary_payload.entries[].governance_state
• summary_payload.entries[].governance_warning
• summary_payload.canonical_controls[]
• summary_payload.risk_acceptance

Validation / usage rules:

• canonical control identity continues to come from the current upstream resolution path only
• the interpretation overlay should consume current governance-state and terminal-outcome values rather than inventing a second status source
• if the current payload is sufficient, upstream evidence collection remains unchanged

FindingException / Accepted Risk Decision

Purpose: Existing accepted-risk and accountability truth that can weaken or qualify a customer-safe control interpretation.

Persisted carrier: existing finding_exceptions rows via ../../apps/platform/app/Models/FindingException.php

Relevant fields / relationships:

• status
• current_validity_state
• owner_user_id
• approved_by_user_id
• request_reason
• review_due_at
• effective_from
• expires_at
• owner
• approver
• currentDecision

Validation / usage rules:

• accepted-risk truth may qualify a control interpretation but must not collapse into a fully positive readiness claim
• missing owner, approver, or review-due truth must surface as explicit partial disclosure rather than fabricated certainty
• this slice remains read-only and does not introduce approval, renewal, or revocation actions

TenantReview

Purpose: Existing released review artifact that anchors the shared interpretation contract for both workspace and detail surfaces.

Persisted carrier: existing tenant_reviews rows via ../../apps/platform/app/Models/TenantReview.php

Relevant fields / relationships:

• id
• workspace_id
• tenant_id
• status
• generated_at
• published_at
• summary
• evidence_snapshot_id
• current_export_review_pack_id
• operation_run_id
• tenant
• evidenceSnapshot
• sections

Planned embedded summary additions inside the existing summary JSON:

• control_interpretation.version
• control_interpretation.display_label
• control_interpretation.non_certification_disclosure
• control_interpretation.controls[]
• control_interpretation.limitations[]

Validation / usage rules:

• only released reviews feed the default customer-safe workspace path
• the shared interpretation version must be carried at compose time so older released reviews preserve the meaning shown at publication time
• the workspace must read the embedded summary contract instead of recomputing the interpretation locally

TenantReviewSection

Purpose: Existing detailed review section carrier used for the per-control explanation surface on the released review detail page.

Persisted carrier: existing tenant_review_sections rows via ../../apps/platform/app/Models/TenantReviewSection.php

Relevant fields:

• section_key
• title
• sort_order
• completeness_state
• summary_payload
• render_payload
• measured_at

Planned usage:

• add one new v1 interpretation section inside the existing section family with the canonical control_interpretation section key
• keep the section near the top of the customer-workspace detail disclosure so mapped-control explanation precedes rawer supporting sections

Planned embedded payload shape:

• summary_payload.version
• summary_payload.mapped_control_count
• summary_payload.follow_up_required_count
• summary_payload.limitation_counts
• render_payload.entries[] containing detailed per-control explanations

Validation / usage rules:

• exactly one interpretation section should exist per review for v1
• the detail surface should read this section instead of deriving a second explanation contract in-page
• this remains part of the existing review artifact and does not create a new section table or entity family

EvidenceSnapshot

Purpose: Existing supporting proof artifact that informs evidence-basis summaries and explicit deeper drilldown.

Persisted carrier: existing evidence_snapshots rows via ../../apps/platform/app/Models/EvidenceSnapshot.php

Relevant fields / relationships:

• id
• workspace_id
• tenant_id
• status
• completeness_state
• generated_at
• expires_at
• summary
• items

Validation / usage rules:

• supporting proof remains optional, lower-priority, and capability-gated
• the overlay may summarize the evidence basis, but raw payloads and unrestricted diagnostics remain outside the default customer-safe path
• supporting evidence access should reuse the existing evidence route and audit action

Audit Log Event Family

Purpose: Existing audit trail used to keep the displayed interpretation and access path traceable.

Persisted carrier: existing audit_logs rows via ../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php

Relevant current action IDs:

• customer_review_workspace.opened
• tenant_review.opened
• evidence_snapshot.opened

Planned shared metadata additions:

• source_surface
• interpretation_version
• review_id when a released review is opened from the workspace
• tenant_filter_id when the workspace is entered with a safe prefilter

Validation / usage rules:

• no new audit store or audit event family is justified
• interpretation-version traceability should be added to shared metadata before introducing any new event concept

Embedded Interpretation Contracts

ControlInterpretationOverlayVersion

Purpose: The explicit version label that states which customer-safe interpretation rules produced the displayed control/readiness summaries.

Persistence: embedded in existing TenantReview.summary and the existing interpretation section payload; echoed in shared audit metadata when relevant

Fields:

• version_key (planned baseline: compliance_evidence_mapping.v1)
• display_label
• non_certification_disclosure

Validation rules:

• exactly one version key is carried for a given released review
• the version must be visible on workspace and detail surfaces whenever mapped control summaries are shown

CustomerControlSummary

Purpose: Compact per-control summary reused by the workspace and as the top-level contract for the detail surface.

Persistence: embedded inside TenantReview.summary['control_interpretation']['controls']

Fields:

• control_key
• control_name
• domain_key
• readiness_bucket
• limitation_flags[]
• customer_summary
• evidence_basis_summary
• accepted_risk_summary (nullable)
• recommended_next_action
• detail_anchor (nullable)
• supporting_finding_ids[]

Validation rules:

• one summary exists per mapped canonical control for the released review
• the summary must stay customer-safe and must not expose provider IDs, raw JSON, or support-only diagnostics
• the same summary meaning must appear on the workspace and detail surfaces for the same released review

CustomerControlExplanation

Purpose: Detailed per-control explanation rendered on the released-review detail surface.

Persistence: embedded inside the interpretation TenantReviewSection.render_payload.entries[]

Fields:

• control_key
• control_name
• readiness_bucket
• limitation_flags[]
• explanation_text
• evidence_basis_items[]
• accepted_risk_context (nullable)
• recommended_next_action
• proof_access_state

Validation rules:

• the detail explanation must be a denser expansion of the compact summary, not a second source of truth
• supporting evidence remains explicit drilldown, not default-visible raw detail
• the explanation must keep non-certification language visible and must not claim legal or framework attestation

CustomerReviewWorkspaceEntry

Purpose: Derived row-level presentation contract for one entitled tenant with a released review on the workspace page.

Persistence: none; derived at request time from the latest released TenantReview and its embedded interpretation contract

Fields:

• workspace_id
• tenant_id
• tenant_name
• latest_published_review_id
• latest_review_published_at
• interpretation_version
• control_summaries[]
• follow_up_summary

Validation rules:

• exactly one derived entry exists per entitled tenant with a released review visible in the current workspace scope
• when no entitled tenant has a released review, the workspace falls back to a page-level empty state rather than emitting partial row contracts without a review
• the one dominant row action remains opening the released review; supporting proof stays secondary and is not a peer primary action on the row

CustomerReviewDetailContext

Purpose: Derived detail-page contract for the existing released-review surface when launched from the workspace.

Persistence: none; derived from the released TenantReview, its interpretation section, and the current customer_workspace query flag

Fields:

• review_id
• tenant_id
• customer_workspace_context (boolean)
• interpretation_version
• controls[]
• non_certification_disclosure
• operator_actions_hidden (boolean)
• supporting_evidence_collapsed_by_default (boolean)

Validation rules:

• the detail page must stay read-only in customer-workspace context
• the same interpretation version and control meaning shown on the workspace must be visible here
• supporting evidence should remain explicit in-body drilldown rather than a new dominant header action

Derived Disclosure States

This feature introduces no new platform-wide lifecycle family. It does require one bounded overlay-local readiness contract and explicit limitation flags.

Primary readiness buckets

• follow_up_required
• review_recommended
• evidence_on_record

Limitation flags

• accepted_risk_influenced
• partial_mapping
• stale_evidence
• supporting_evidence_unavailable
• unmapped

Validation rules:

• limitation flags qualify the customer-safe interpretation and must never be silently collapsed into evidence_on_record
• accepted risk remains a qualifier, not a passing state
• these values stay embedded in the interpretation contract only and do not become a broader platform taxonomy or standalone persistence family