TenantAtlas/specs/267-artifact-lifecycle-retention/data-model.md

# Data Model: Governance Artifact Lifecycle & Retention v1

## Scope

This slice adds one shared derived contract over existing governance artifacts. It does not introduce a generic artifact table, a new browsing console, or a new persistence layer. Any persisted lifecycle or retention markers that v1 truly requires must stay on the existing owning tables or aggregate roots for the concrete artifact families involved.

## Artifact Family Matrix

| Artifact family | Owning record | Current immutable or historical anchors | Current lifecycle anchors | Current retention or access anchors | Current operator surfaces | First-slice adoption |
|---|---|---|---|---|---|---|
| Evidence snapshot | `EvidenceSnapshot` | `id`, `fingerprint`, `generated_at` | `status`, `isCurrent()`, latest vs older snapshot truth in the current artifact presenter | `expires_at`; explicit `expire` mutation via `EvidenceSnapshotService` | `EvidenceSnapshotResource`, linked review and pack detail | Visible contract adoption on existing resource and linked surfaces |
| Review pack | `ReviewPack` | `id`, `fingerprint`, `previous_fingerprint`, `sha256`, `generated_at` | `status`, relation to `tenant_review_id`, `current_export_review_pack_id` through the review | `expires_at`; signed download allowed only when ready, unexpired, and entitled | `ReviewPackResource`, `ReviewPackDownloadController`, `CustomerReviewWorkspace`, tenant review detail | Visible contract adoption on existing resource, download, and workspace-linked surfaces |
| Stored report | `StoredReport` | `id`, `report_type`, `fingerprint`, `previous_fingerprint`, `created_at` | Latest-per-tenant-and-type vs older fingerprint rows is the current or historical distinction | `created_at` plus `tenantpilot.stored_reports.retention_days`; pruning via `PruneStoredReportsCommand` | No dedicated operator resource; evidence sources, widgets, support diagnostics, telemetry | Headless contract adoption only |
| Accepted-risk decision record | `FindingExceptionDecision` inside the `FindingException` aggregate | `id`, `decision_type`, `decided_at`, append-only history, parent `current_decision_id` | Parent exception `status`, `current_validity_state`, and current-vs-historical decision relationship | `expires_at`, `review_due_at`, and current validity on the parent exception; no hold or delete contract today | `DecisionRegister`, `ViewFindingException`, finding-governance projections | Headless contract adoption on aggregate models and current findings-service seams only; current register and detail surfaces stay unchanged in this slice |

`TenantReview` remains a consumer and context surface for linked artifact truth in this slice. Its publication, archive, and successor states must not become retention proxies for the shared contract.

## Shared Derived Contract

### GovernanceArtifactReference

Derived object emitted by the shared lifecycle or truth path.

| Field | Description | Notes |
|---|---|---|
| `family` | One of `evidence_snapshot`, `review_pack`, `stored_report`, `finding_exception_decision` | No synthetic family for a generic registry |
| `workspace_id` | Owning workspace scope | Required for all current families |
| `tenant_id` | Owning tenant scope | Required for all current in-scope artifact families |
| `record_type` | Current model or aggregate owner | Derived from the owning record, not a new registry enum |
| `record_id` | Existing primary key | Stable inside the current family |
| `display_reference` | Human-readable immutable reference shown on current surfaces | Built from family plus existing identifiers already owned by the record |
| `integrity_anchor` | Existing fingerprint, SHA, or append-only decision anchor when available | Nullable; never invent a synthetic hash when the family has no current one |
| `source_context` | Existing related artifact or aggregate context | Examples: evidence snapshot, current export pack, parent finding exception |

Validation rules:

- `workspace_id` and `tenant_id` remain required scope anchors for every current in-scope family.
- The shared contract may normalize display labels, but it must not replace the owning record's real ID or fingerprint.
- A direct-access expiry or hold state must not erase the artifact reference from historical views.

### GovernanceArtifactLifecycleState

Derived state that explains whether the artifact is the current artifact in active circulation or a retained historical record.

| Value | Meaning | Repo-grounded examples |
|---|---|---|
| `current` | Current artifact intended for active operator or customer use | Active evidence snapshot, current export review pack, current decision on the exception aggregate |
| `historical` | Retained historical artifact that remains readable without implying a newer replacement path | Older stored reports by fingerprint, prior evidence snapshots still referenced by later reviews |
| `superseded` | Historical artifact explicitly replaced by a newer current artifact | Prior export review pack after a newer export becomes current, prior decision row after a newer decision becomes current |

Rules:

- `expired_direct_access` is not a lifecycle state in this slice. It belongs to retention.
- `suspended_read_only` is not a lifecycle state in this slice. It remains commercial lifecycle from Spec 251.
- A family may map directly from existing repo truth to `historical` without needing a second new state value.

### GovernanceArtifactRetentionState

Bounded retention state family used by the shared contract.

| Value | Meaning | Repo-grounded anchor or note |
|---|---|---|
| `retained` | Artifact remains retained and readable under normal entitlement rules | Default state for current evidence, packs, stored reports before prune, and historical decisions |
| `hold` | Artifact is retained under an explicit hold and cannot progress into deletion | New v1 mutation state only if current-table persistence can stay bounded |
| `deletion_requested` | Explicit reversible request to remove the artifact from normal circulation later | New v1 mutation state only if current-table persistence can stay bounded |
| `expired_direct_access` | Direct access has expired even though historical reference or audit truth may still remain | Current repo-real pattern for review packs and evidence snapshots with `expires_at` |

Rules:

- `hold` wins over `deletion_requested` for visible truth and progression rules.
- `expired_direct_access` does not imply purge, provider deletion, or removal of the immutable reference.
- `suspended_read_only` must never be used as a retention-state proxy.
- Stored reports may stay `retained` or become effectively unavailable through prune, but prune itself remains a separate retained-history follow-up boundary rather than a generic purge workflow in this spec.

### GovernanceArtifactActionDecision

Derived action contract emitted alongside lifecycle and retention truth.

| Field | Description |
|---|---|
| `may_view` | Whether current entitlement and retention state still allow detail access |
| `may_download` | Whether current entitlement, retention state, and artifact state still allow direct download of an already-generated artifact |
| `may_generate_successor` | Whether a new successor artifact may be generated now |
| `may_mutate_lifecycle` | Whether hold, release-hold, or deletion-request actions may execute now |
| `blocked_reason` | Customer- or operator-readable reason for the blocked action |
| `audit_action` | Stable audit event family for the action or mutation |

Rules:

- `may_generate_successor` remains separate from `may_download`. The repo already proves that a workspace can block new review-pack starts while still allowing ready-pack downloads.
- The shared contract should reuse existing policy and capability checks before adding any family-local lifecycle gating.
- If a family does not pass the bounded current-owner persistence gate in v1, `may_mutate_lifecycle` remains false or blocked while the contract still exposes truthful retention semantics.

## Likely Persistence Touch Points

| Current table or aggregate | Current fields already in repo | Likely v1 additions only if required | Guardrail |
|---|---|---|---|
| `evidence_snapshots` | `status`, `expires_at`, `fingerprint`, `generated_at` | Family-local hold or deletion-request markers and actor or reason metadata | Do not add a generic artifact foreign key |
| `review_packs` | `status`, `expires_at`, `fingerprint`, `previous_fingerprint`, `sha256`, `generated_at` | Family-local hold or deletion-request markers and actor or reason metadata | Keep download truth on the current record and controller path |
| `tenant_reviews` | `status`, `published_at`, `archived_at`, `superseded_by_review_id`, `current_export_review_pack_id` | No new retention state; use only to point review surfaces at linked artifact truth | Review lifecycle remains review-owned context, not a shared artifact engine |
| `stored_reports` | `report_type`, `fingerprint`, `previous_fingerprint`, `created_at`, `payload` | Prefer derived-only in v1; keep pruning command-owned | No new operator UI surface in this slice |
| `finding_exceptions` plus `finding_exception_decisions` | `current_decision_id`, parent `status`, `current_validity_state`, `review_due_at`, `expires_at`, append-only decision rows | If hold or deletion-request semantics are needed, prefer aggregate-level state on `finding_exceptions` rather than mutation of append-only decision history | Do not break append-only history |

## Query and Precedence Rules

- `hold` wins over `deletion_requested` for user-visible truth and action blocking.
- `expired_direct_access` blocks direct download or open actions only where the current family already uses `expires_at` or equivalent access expiry.
- `suspended_read_only` blocks new generation or lifecycle mutation actions, but it does not change lifecycle or retention state by itself.
- `ReviewPackDownloadController` remains the canonical enforcement point for ready-pack direct download: entitlement, ready status, unexpired access, and file existence must all remain true.
- `StoredReport` current-versus-historical selection should prefer latest report per tenant and report type, with older fingerprint rows remaining historical until pruned.
- `FindingExceptionDecision` rows remain historically addressable even when the parent exception points to a newer current decision.

## State Transitions In Scope

### Existing repo-real transitions to preserve

- Evidence snapshot: current active snapshot to expired direct access through `EvidenceSnapshotService::expire(...)`
- Review pack: queued to generating to ready or failed, and ready to expired direct access
- Finding exception decision history: requested to approved or renewed, rejected, or revoked through append-only decision creation on the parent aggregate
- Stored report: retained-by-age to pruned-by-command through `PruneStoredReportsCommand`

### New bounded transitions this slice may add

- `retained` to `hold`
- `hold` to `retained`
- `retained` to `deletion_requested`
- `deletion_requested` to `retained`

Guardrails:

- No transition in this slice may claim purge or irreversible deletion.
- No transition may depend on provider presence or workspace commercial state as its primary meaning.
- If a requested transition needs a cross-family executor, scheduler, or export-before-delete workflow, it belongs to a follow-up spec instead of this slice.
- If no current family can support these transitions without widening scope, v1 stops at read-only lifecycle truth plus existing download audit and does not add new mutation persistence.