TenantAtlas/specs/262-lifecycle-governance-taxonomy/data-model.md

# Data Model: Workspace, Tenant & Managed Object Lifecycle Governance v1

## Overview

This slice introduces no product persistence. Its data model is a governance contract that classifies existing repo-real lifecycle truth and names reserved follow-up values without implementing them.

`contracts/lifecycle-governance-taxonomy.yaml` is the canonical machine-readable source for this package. `docs/product/standards/lifecycle-governance.md` is the reviewer-facing standard that future specs must cite. This document explains the same lifecycle matrix in prose and must stay aligned with both artifacts.

## Entity: LifecycleDimensionDefinition

**Persistence**: none; governance contract only

| Field | Type | Meaning |
|---|---|---|
| `name` | string | One of the six lifecycle dimensions |
| `purpose` | string | What question this dimension answers |
| `authoritative_sources` | list | Repo-real models, commands, config, or specs that currently own the meaning |
| `current_repo_real_values` | list | Values or states already evidenced in the repo |
| `reserved_follow_up_values` | list | Values named for future work but not yet repo-real |
| `forbidden_proxies` | list | Meanings this dimension must not borrow from another dimension |

## Canonical Lifecycle Dimensions

### 1. Local Record Lifecycle

- **Purpose**: whether a local TenantPilot record is active, onboarding, archived, or otherwise locally present/removed.
- **Authoritative sources**:
  - `specs/143-tenant-lifecycle-operability-context-semantics/spec.md`
  - `specs/091-backupschedule-retention-lifecycle/spec.md`
  - `apps/platform/app/Models/Tenant.php`
- **Current repo-real values**:
  - `tenant.draft`
  - `tenant.onboarding`
  - `tenant.active`
  - `tenant.archived`
  - `backup_schedule.active`
  - `backup_schedule.archived`
  - `backup_schedule.force_deleted`
- **Reserved follow-up values**:
  - `locally_removed`
  - `local_purge_scheduled`
  - `locally_purged`
- **Forbidden proxies**:
  - `provider_presence`
  - `commercial_state`
  - `retention_expiry`

### 2. Provider Presence Lifecycle

- **Purpose**: whether a managed object is currently observed in the supported provider-backed result set.
- **Authoritative sources**:
  - `specs/261-provider-missing-policy-visibility/spec.md`
  - `apps/platform/app/Models/Policy.php`
- **Current repo-real values**:
  - `present`
  - `provider_missing`
- **Reserved follow-up values**:
  - `provider_deleted`
  - `provider_reappeared`
- **Forbidden proxies**:
  - `local_delete`
  - `local_suppression`
  - `restoreability`

### 3. Operator Suppression Lifecycle

- **Purpose**: whether an operator intentionally hid or restored visibility for a local record.
- **Authoritative sources**:
  - `specs/261-provider-missing-policy-visibility/spec.md`
  - `apps/platform/app/Models/Policy.php`
- **Current repo-real values**:
  - `visible`
  - `ignored`
  - `restored_to_visibility`
- **Reserved follow-up values**:
  - `scoped_suppression_reason_families`
- **Forbidden proxies**:
  - `provider_missing`
  - `retention`
  - `commercial_state`

### 4. Commercial / Workspace Lifecycle

- **Purpose**: whether a workspace is in trial, active paid use, grace, or suspended read-only posture.
- **Authoritative sources**:
  - `specs/251-commercial-entitlements-billing-state/spec.md`
- **Current repo-real values**:
  - `trial`
  - `active_paid`
  - `grace`
  - `suspended_read_only`
- **Reserved follow-up values**:
  - `closed`
- **Forbidden proxies**:
  - `tenant_archive`
  - `provider_missing`
  - `purge_due`

### 5. Retention / Compliance Lifecycle

- **Purpose**: whether an artifact must be retained, has export requested, is expiring, or is eligible for later purge.
- **Authoritative sources**:
  - `apps/platform/app/Models/ReviewPack.php`
  - `apps/platform/app/Console/Commands/PruneReviewPacksCommand.php`
  - `apps/platform/config/tenantpilot.php`
- **Current repo-real values**:
  - `review_pack.expired`
  - `configured_retention_days`
- **Reserved follow-up values**:
  - `retained`
  - `export_requested`
  - `deletion_requested`
  - `deletion_scheduled`
  - `legal_hold`
  - `purge_due`
  - `purged`
- **Forbidden proxies**:
  - `workspace_suspension`
  - `local_archive`
  - `provider_missing`

### 6. Restoreability Lifecycle

- **Purpose**: whether historical evidence or backup truth is still restorable and what kind of continuity remains.
- **Authoritative sources**:
  - `specs/261-provider-missing-policy-visibility/spec.md`
  - `apps/platform/app/Models/BackupSet.php`
  - `apps/platform/app/Models/RestoreRun.php`
- **Current repo-real values**:
  - `historical_restore_continuity_available`
- **Reserved follow-up values**:
  - `metadata_only`
  - `blocked_by_dependency`
  - `not_restorable`
  - `expired_by_retention`
- **Forbidden proxies**:
  - `provider_presence`
  - `commercial_state`
  - `local_suppression`

## Entity: TransitionGovernanceRule

**Persistence**: none; governance contract only

| Field | Type | Meaning |
|---|---|---|
| `dimension` | string | Which lifecycle dimension owns the transition |
| `transition` | string | Human-readable transition |
| `transition_owner` | string | Repo authority or future owner class that owns the transition decision |
| `execution_path` | string | Whether the transition stays direct/local, observation-derived, derived/passive, or must use shared `OperationRun` semantics |
| `requires_confirmation` | enum | `never`, `sometimes`, or `always` depending on whether the transition is passive, conditional, or irreversible |
| `requires_audit` | boolean | Whether audit evidence is mandatory |
| `requires_operation_run` | enum | `never`, `sometimes`, or `always` based on transition class |
| `requires_export_precondition` | boolean | Whether export-before-delete or similar preconditions must be satisfied |
| `requires_retention_review` | boolean | Whether retention rules must be resolved first |

## Transition Guidance (v1)

| Dimension | Example transition | Transition owner | Execution path | Confirmation | Audit | OperationRun | Export / Retention Preconditions |
|---|---|---|---|---|---|---|---|
| Local record lifecycle | archive a locally managed record or force-delete a backup schedule | TenantPilot local domain owner | direct local mutation, or shared `OperationRun` when long-running, cross-resource, or externally mediated | always | yes | sometimes; always if long-running or cross-resource | yes before irreversible deletion |
| Provider presence | object becomes provider missing or reappears | provider observation / sync process | observation-derived update | never | yes | no, unless wrapped in a broader long-running reconciliation flow | no |
| Operator suppression | ignore / restore local visibility | TenantPilot local domain owner | direct local mutation | always | yes | no | no |
| Commercial/workspace lifecycle | enter suspended read-only or close workspace | platform workspace/commercial owner | direct local mutation for bounded state changes, or shared `OperationRun` for closure-class / multi-artifact flows | always | yes | sometimes; closure-class flows are likely `always` | yes |
| Retention/compliance lifecycle | mark export requested, delete requested, hold, purge due, or purge | compliance / retention owner | shared `OperationRun` for purge-class automation and long-running/export-coupled flows | always | yes | always for purge-class automation | yes |
| Restoreability lifecycle | mark metadata-only or expired-by-retention | backup / restore / evidence owner | derived status when passive; guarded mutation or shared `OperationRun` when an operator reduces restoreability | sometimes; never for passive derived status, always for irreversible operator action | yes | sometimes | yes |

## Entity: FollowUpSliceBoundary

**Persistence**: none; governance contract only

| Follow-up slice | Why it stays separate |
|---|---|
| Provider-Missing Managed Object Truth v1 | broader provider-presence rollout beyond policies |
| Workspace & Tenant Closure Lifecycle v1 | workspace or tenant close/remove behavior |
| Data Export Before Deletion v1 | customer-owned export workflow that fulfills the reserved `export requested` lifecycle value before irreversible deletion |
| Retention & Purge Governance v1 | retention periods, holds, purge eligibility, irreversible deletion |
| Restoreability Expiry & Evidence Retention v1 | distinction between retained evidence and restorable payload |