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